Documentation
¶
Overview ¶
Package dbmigrate registers a generated project's per-domain migrations, orders them by declared dependencies, and applies pending ones using Bun's migration table for bookkeeping.
Index ¶
- Variables
- func Migrate(ctx context.Context, db *bun.DB, target Target, ...) ([]Migration, []Migration, error)
- func Register(up, down MigrationFunc, opts ...Option)
- type Dependency
- type Migration
- type MigrationFunc
- type Option
- type Registry
- func (r *Registry) Add(m Migration, up, down MigrationFunc, deps ...Dependency) error
- func (r *Registry) Apply(ctx context.Context, db *bun.DB) (applied []Migration, err error)
- func (r *Registry) Migrate(ctx context.Context, db *bun.DB, target Target, ...) (rolledBack, applied []Migration, err error)
- func (r *Registry) Order() ([]Migration, error)
- func (r *Registry) Plan(target Target, applied map[string]bool) (rollback, apply []Migration, err error)
- type Target
Constants ¶
This section is empty.
Variables ¶
var ErrNotConfirmed = errors.New("rollback not confirmed")
ErrNotConfirmed is what Migrate returns when confirm declines a non-empty rollback.
var ErrStateChanged = errors.New("migration state changed since planning; rerun")
ErrStateChanged is returned by Migrate when the applied set changed between planning and locking, so the confirmed plan no longer describes what would run; rerun to plan against the new state.
Functions ¶
func Migrate ¶
func Migrate(ctx context.Context, db *bun.DB, target Target, confirm func(rollback []Migration) bool) ([]Migration, []Migration, error)
Migrate brings target's domain to target.Version, rolling back before applying; confirm is asked before a non-empty rollback and must return true to proceed. It stops at the first failure.
func Register ¶
func Register(up, down MigrationFunc, opts ...Option)
Register records the calling file as a migration. It must be called from init() in a file at backend/<domain>/migrations/<NNNN>_<name>.go; any other path panics.
Types ¶
type Dependency ¶
type Dependency struct {
Domain, Version string
}
Dependency names another domain's migration that must run first.
type Migration ¶
Migration identifies one registered migration.
type MigrationFunc ¶
MigrationFunc is the shape of a migration's up and down functions, matching Bun's own migration signature.
type Option ¶
type Option struct {
// contains filtered or unexported fields
}
Option is what After returns; Register accepts any number.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is the set Register adds to. The package-level default is what Register and Apply use; tests build their own.
func (*Registry) Add ¶
func (r *Registry) Add(m Migration, up, down MigrationFunc, deps ...Dependency) error
Add records m with its up/down functions and cross-domain dependencies. A duplicate (Domain, Version) returns an error.
func (*Registry) Apply ¶
Apply is the Registry-scoped form of the package-level Apply; see its doc comment.
func (*Registry) Migrate ¶
func (r *Registry) Migrate(ctx context.Context, db *bun.DB, target Target, confirm func(rollback []Migration) bool) (rolledBack, applied []Migration, err error)
Migrate is the Registry-scoped form of the package-level Migrate; see its doc comment. It re-plans after locking and returns ErrStateChanged if a concurrent run changed the applied set.
func (*Registry) Order ¶
Order returns every registered migration in dependency order, ties broken by (Domain, Version) so runs are deterministic.
func (*Registry) Plan ¶
func (r *Registry) Plan(target Target, applied map[string]bool) (rollback, apply []Migration, err error)
Plan computes what bringing applied to target requires: rollback to unapply (reverse dependency order) and apply to run (dependency order). Both empty means target is already met.
type Target ¶
type Target struct{ Domain, Version string }
Target names the state one domain should be brought to. Version "zero" means none of the domain's migrations applied.
func ParseTarget ¶
ParseTarget parses "<domain>/<version>" ("<domain>/zero" allowed).