Documentation
¶
Overview ¶
Package bunmigrate runs schema migrations for github.com/uptrace/bun.
Runner wraps bun's github.com/uptrace/bun/migrate.Migrator with the workflow a command-line migration tool needs: applying pending migrations one at a time, stamping them without running them, rolling back the last one, and listing their status. Subpackage clicmd turns a Runner into a urfave/cli command; this package itself depends on bun and the standard library only.
The migration set stays with the caller. Keeping github.com/uptrace/bun/migrate.Migrations, its //go:embed directive and its Discover call in the consuming module is what makes the embedded migration files resolve against that module rather than this one.
Index ¶
- Variables
- func EnsureSQLiteFile(dsn string) error
- type MigrateOptions
- type RollbackOptions
- type Runner
- func (r *Runner) CreateGo(ctx context.Context, name string) (*migrate.MigrationFile, error)
- func (r *Runner) CreateSQL(ctx context.Context, name string) ([]*migrate.MigrationFile, error)
- func (r *Runner) Init(ctx context.Context) error
- func (r *Runner) Lock(ctx context.Context) error
- func (r *Runner) Migrate(ctx context.Context, opts MigrateOptions) (migrate.MigrationSlice, error)
- func (r *Runner) Migrator() *migrate.Migrator
- func (r *Runner) Rollback(ctx context.Context, opts RollbackOptions) (migrate.MigrationSlice, error)
- func (r *Runner) Status(ctx context.Context) (migrate.MigrationSlice, error)
- func (r *Runner) Unlock(ctx context.Context) error
Constants ¶
This section is empty.
Variables ¶
ErrCountWithGroup is returned by Runner.Migrate when MigrateOptions asks for a limited run and a single group at the same time. The two are mutually exclusive: a group is applied by bun in one step, with no place to stop.
Functions ¶
func EnsureSQLiteFile ¶
EnsureSQLiteFile creates the database file named by a SQLite "file:" DSN, along with the directories leading to it.
SQLite creates a missing database file on its own, but not the directory it sits in, so the first run of an application that keeps its database under, say, "file:instance/app.sqlite" fails with "unable to open database file" until something creates "instance". This is that something, meant to be called from the function that opens the database, before migrations run.
Anything that does not name a file on disk is left alone: DSNs without the "file:" prefix, ":memory:" and "mode=memory". The file is created with mode 0600 and its directories with 0700, since a database rarely wants to be world-readable; an existing file keeps its own permissions.
Types ¶
type MigrateOptions ¶
type MigrateOptions struct {
// Group applies all pending migrations as a single group, the way bun does
// it, instead of one group per migration. A later rollback then undoes the
// whole group at once.
Group bool
// Stamp records the migrations as applied without running them. Use it to
// adopt a database whose schema already matches.
Stamp bool
// Count applies at most this many migrations, oldest first. Zero applies
// all of them. It cannot be combined with Group.
Count int
}
MigrateOptions configures Runner.Migrate.
type RollbackOptions ¶
type RollbackOptions struct {
// Group rolls back the whole last migration group instead of the single
// last applied migration.
Group bool
// Stamp records the migrations as unapplied without running their down
// migrations.
Stamp bool
}
RollbackOptions configures Runner.Rollback.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner applies, rolls back and inspects a set of migrations.
Where bun's migrate.Migrator applies every pending migration as one group, a Runner applies them one at a time, each in a group of its own, so that a rollback undoes a single migration and a run can stop after a given number of them. Setting Group in MigrateOptions or RollbackOptions asks for bun's whole-group behaviour instead.
A Runner is a thin wrapper: it holds no state of its own beyond the migrator, and it is safe for concurrent use to the same extent bun's migrator is.
func New ¶
func New(db *bun.DB, migrations *migrate.Migrations, opts ...migrate.MigratorOption) *Runner
New returns a Runner that migrates db with the given migration set.
migrate.WithMarkAppliedOnSuccess is enabled ahead of opts, so a migration that fails partway through is not left recorded as applied. Pass migrate.WithMarkAppliedOnSuccess(false) in opts to restore bun's default.
func (*Runner) CreateGo ¶
CreateGo writes a Go migration file into the migrations directory. The generated file registers itself with the migration set of the package it lands in, so it compiles only once that package declares one.
func (*Runner) CreateSQL ¶
CreateSQL writes an up and a down SQL migration file into the migrations directory and returns both.
func (*Runner) Init ¶
Init creates the migration bookkeeping tables. It is safe to call against a database that already has them.
func (*Runner) Lock ¶
Lock takes the migration lock, so that a second process cannot migrate the same database at the same time. Runner.Migrate and Runner.Rollback do this themselves; call it directly only to hold the lock across processes, which is what a "lock" subcommand is for.
The lock is a row in the locks table, not a database session lock: it outlives the process that took it and is released only by Runner.Unlock.
func (*Runner) Migrate ¶
func (r *Runner) Migrate(ctx context.Context, opts MigrateOptions) (migrate.MigrationSlice, error)
Migrate applies pending migrations, oldest first, and returns those it applied.
Each migration lands in a group of its own unless MigrateOptions.Group is set. The database is locked for the duration.
The returned slice holds the migrations that were applied even when the error is non-nil, so a partial run can still be reported.
func (*Runner) Migrator ¶
Migrator returns the migrator underneath, for the operations this package does not wrap: migrate.Migrator.Reset, migrate.Migrator.MissingMigrations and the rest of bun's API.
func (*Runner) Rollback ¶
func (r *Runner) Rollback(ctx context.Context, opts RollbackOptions) (migrate.MigrationSlice, error)
Rollback undoes the last applied migration and returns it, or nothing when the database is already at its initial state.
With RollbackOptions.Group the whole last group is undone, newest migration first. The database is locked for the duration.
The returned slice holds the migrations that were rolled back even when the error is non-nil.
func (*Runner) Status ¶
Status returns every known migration, applied or not, oldest first.
Source Files
¶
- doc.go
- runner.go
- sqlite.go