Documentation
¶
Overview ¶
Package migrations implements a Laravel-style migration engine. A migration is any type that implements the Migration interface; the engine applies them in lexical name order (timestamp-prefixed by convention) and records each application in a repository table.
Migrations interact with the database through schema.Definition values returned via the Context API, so they remain driver-agnostic.
Index ¶
- Variables
- func Checksum(conn *database.Connection, m Migration) (string, error)
- func Register(m Migration)
- type Context
- type FuncMigration
- type Lock
- type Migration
- type Migrator
- func (m *Migrator) Fresh(ctx context.Context) ([]string, error)
- func (m *Migrator) Refresh(ctx context.Context) ([]string, error)
- func (m *Migrator) Reset(ctx context.Context) ([]string, error)
- func (m *Migrator) Rollback(ctx context.Context, step int) ([]string, error)
- func (m *Migrator) Status(ctx context.Context) ([]StatusRow, error)
- func (m *Migrator) Step(ctx context.Context, n int) ([]string, error)
- func (m *Migrator) Up(ctx context.Context) ([]string, error)
- type Options
- type Record
- type Registry
- type Repository
- func (r *Repository) All(ctx context.Context) ([]Record, error)
- func (r *Repository) Delete(ctx context.Context, exec database.Executor, name string) error
- func (r *Repository) Ensure(ctx context.Context) error
- func (r *Repository) Insert(ctx context.Context, exec database.Executor, rec Record) error
- func (r *Repository) LastBatch(ctx context.Context) (int, error)
- func (r *Repository) Names(ctx context.Context) (map[string]Record, error)
- type StatusRow
Constants ¶
This section is empty.
Variables ¶
var Default = NewRegistry()
Default is the process-wide registry.
var ErrChecksumMismatch = errors.New("migrations: checksum mismatch — migration source changed after being applied")
ErrChecksumMismatch is returned when a recorded migration's checksum disagrees with the one computed from current source.
var Now = func() time.Time { return time.Now().UTC() }
Now returns the current wall clock; abstracted so tests can stub it.
Functions ¶
Types ¶
type Context ¶
type Context struct {
Conn *database.Connection
Tx *database.Tx
Ctx context.Context
// contains filtered or unexported fields
}
Context is the value passed to migration callbacks. It exposes the underlying connection plus convenience helpers for applying schema definitions and executing raw SQL.
func (*Context) CollectedSQL ¶
CollectedSQL returns the SQL accumulated during a preview run.
func (*Context) Executor ¶
Executor returns the active executor (transaction if open, else connection).
type FuncMigration ¶
FuncMigration adapts up/down callbacks into a Migration. It is the most common way to declare a migration in user code.
func (*FuncMigration) Down ¶
func (m *FuncMigration) Down(ctx *Context) error
Down runs the down callback.
type Lock ¶
type Lock struct {
Conn *database.Connection
Table string
HolderID string
// contains filtered or unexported fields
}
Lock prevents two migrators from running concurrently against the same database. The implementation uses a row in a dedicated `migrations_lock` table; on databases that support advisory locks (Postgres) we use those instead transparently.
func NewLock ¶
func NewLock(conn *database.Connection, holder string) *Lock
NewLock builds a Lock against conn.
type Migration ¶
Migration is the canonical interface migrations implement. The Name() must be globally unique within a registry and is the migration's primary identifier in the migrations table.
type Migrator ¶
type Migrator struct {
Conn *database.Connection
Registry *Registry
Opts Options
Repo *Repository
}
Migrator orchestrates migrations against a connection.
func New ¶
func New(conn *database.Connection, registry *Registry, opts Options) *Migrator
New creates a Migrator. registry may be nil to use the package Default.
func (*Migrator) Fresh ¶
Fresh drops all tables and re-applies all migrations from scratch. The list of tables is enumerated from each driver — sqlite_master / information_schema / pg_catalog — and excludes the migrations table.
func (*Migrator) Rollback ¶
Rollback reverses the last batch of migrations (or step) and returns the names reverted in application order.
type Options ¶
type Options struct {
// Table overrides the migrations record table (default "migrations").
Table string
// Pretend renders SQL but does not execute it.
Pretend bool
// AllowOutOfOrder permits applying migrations whose names sort before a
// previously applied migration. Off by default to mirror Laravel.
AllowOutOfOrder bool
// EnforceChecksums causes the migrator to refuse to run when a recorded
// migration's checksum has drifted from current source.
EnforceChecksums bool
// LockTimeout for acquiring the migrations lock.
LockTimeout time.Duration
// Logger receives status messages.
Logger *logger.Logger
}
Options configures Migrator behavior.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry collects migrations and returns them in deterministic order. Applications normally have one global registry (Default) that migration files populate via Register() in their init().
type Repository ¶
type Repository struct {
Conn *database.Connection
Table string
}
Repository persists migration history.
func NewRepository ¶
func NewRepository(conn *database.Connection, table string) *Repository
NewRepository builds a Repository targeting the given table.
func (*Repository) All ¶
func (r *Repository) All(ctx context.Context) ([]Record, error)
All returns every record sorted by application order (batch asc, migration asc).
func (*Repository) Ensure ¶
func (r *Repository) Ensure(ctx context.Context) error
Ensure creates the migrations table if it does not already exist.
Source Files