README
¶
migrations
migrations is an engine-neutral database migration runtime with a
PostgreSQL backend. It owns migration identity, planning, status, locking,
checksums, baselines, recovery, and the public.go_schema_migrations ledger.
Goose is an internal, pinned SQL execution detail and never appears in the
public API.
Install
go get github.com/faustbrian/golib/pkg/migrations
The supported Go and PostgreSQL versions are documented in compatibility.
Embedded migrations
//go:embed migrations/*.sql
var files embed.FS
source, err := migrations.NewFSSource(files, "migrations")
if err != nil {
return err
}
backend, err := postgres.New(
database,
postgres.WithLockTimeout(30*time.Second),
postgres.WithStatementTimeout(5*time.Minute),
)
if err != nil {
return err
}
runner, err := migrations.NewRunner(source, backend)
if err != nil {
return err
}
plan, err := runner.Plan(ctx)
if err != nil {
return err
}
result, err := runner.Up(ctx)
Run this code in a dedicated deployment job. Do not run it implicitly in every service process.
Service migrate command
migrationsservice.New adapts a caller-constructed Runner to the standard
one-shot service migrate role. The caller loads typed configuration, prepares
only migration dependencies, and explicitly selects the runner operation. The
adapter adds no migration policy, HTTP listener, management server, readiness
check, retries, or long-lived resource ownership.
Migration-only components start before the task and stop in reverse order after
it finishes or fails. A missing runner fails during plan construction. Use a
dedicated deployment job and select Runner.Up, Plan, Status, Down, or
recovery behavior explicitly according to the reviewed operation.
Safety properties
- The complete source and ledger history is validated while an advisory lock is held.
- Applied files cannot be changed, renamed, removed, or reordered.
- Transactional migrations update schema and ledger atomically.
- Explicit no-transaction migrations persist dirty state before executing SQL.
- Dirty outcomes require a checksum-bound operator recovery decision.
- Existing Laravel databases are adopted through an exact reviewed schema
fingerprint without reading or modifying Laravel's
migrationstable. - Status, plans, records, events, and migration values are immutable snapshots.
Read the migration format, operations guide, and Laravel baseline runbook before production use.
Documentation
- Architecture and engine contract
- postgres integration
- Migration format and ledger
- Operations and disaster recovery
- Laravel-to-Go baseline runbook
- Security
- Compatibility
- Hardening evidence
- Benchmark baselines
- Replacing the execution engine
- FAQ
- Contributing
License
migrations is open-source software licensed under the
MIT License.
Ecosystem
Use the Golib documentation portal to choose companion packages, supported stacks, recipes, and operations guidance.
Documentation
¶
Overview ¶
Package migrations provides engine-neutral database migration contracts.
Index ¶
- Variables
- type Action
- type Backend
- type Baseline
- type Checksum
- type Event
- type FSSource
- type Migration
- type Observer
- type Operation
- type Option
- type Phase
- type Plan
- type Record
- type RecordKind
- type Recovery
- type RecoveryAction
- type RecoveryResult
- type Result
- type Runner
- func (runner *Runner) Baseline(ctx context.Context, baseline Baseline) (record Record, err error)
- func (runner *Runner) Down(ctx context.Context, count uint64) (result Result, err error)
- func (runner *Runner) Plan(ctx context.Context) (plan Plan, err error)
- func (runner *Runner) Recover(ctx context.Context, recovery Recovery) (result RecoveryResult, err error)
- func (runner *Runner) Status(ctx context.Context) (status Status, err error)
- func (runner *Runner) Up(ctx context.Context) (result Result, err error)
- type Session
- type Source
- type State
- type Status
- type StatusEntry
- type Step
- type TransactionMode
- type Version
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidBaseline indicates malformed reviewed baseline metadata. ErrInvalidBaseline = errors.New("invalid schema baseline") // ErrBaselineMismatch indicates live schema drift from the reviewed contract. ErrBaselineMismatch = errors.New("schema does not match reviewed baseline") // ErrBaselineExists indicates that owned migration history is not empty. ErrBaselineExists = errors.New("migration baseline already exists") // ErrBaselineVersionConflict indicates Go migrations at or below the // baseline cutoff. ErrBaselineVersionConflict = errors.New("go migration conflicts with baseline version") // ErrBaselineUnsupported indicates a backend without baseline conformance. ErrBaselineUnsupported = errors.New("migration backend does not support baselines") )
var ( // ErrInvalidVersion indicates that a migration version is zero or malformed. ErrInvalidVersion = errors.New("invalid migration version") // ErrInvalidName indicates that a migration name is not canonical snake case. ErrInvalidName = errors.New("invalid migration name") // ErrInvalidTransactionMode indicates an unknown transaction mode. ErrInvalidTransactionMode = errors.New("invalid transaction mode") // ErrEmptyUpSQL indicates that a migration has no forward operation. ErrEmptyUpSQL = errors.New("migration up SQL is empty") // ErrInvalidChecksum indicates malformed or unsupported checksum text. ErrInvalidChecksum = errors.New("invalid migration checksum") )
var ( // ErrInvalidRecord indicates malformed owned-ledger data. ErrInvalidRecord = errors.New("invalid migration record") // ErrDirty indicates an interrupted or partially applied migration. ErrDirty = errors.New("dirty migration history") // ErrChecksumMismatch indicates an applied migration was modified. ErrChecksumMismatch = errors.New("migration checksum mismatch") // ErrRenamedMigration indicates an applied version now has another name. ErrRenamedMigration = errors.New("applied migration was renamed") // ErrDeletedMigration indicates an applied migration is absent from source. ErrDeletedMigration = errors.New("applied migration was deleted") // ErrReorderedHistory indicates non-monotonic or non-prefix history. ErrReorderedHistory = errors.New("migration history was reordered") // ErrInvalidTarget indicates an impossible or ambiguous plan target. ErrInvalidTarget = errors.New("invalid migration target") // ErrIrreversible indicates that rollback SQL was not provided. ErrIrreversible = errors.New("migration is irreversible") )
var ( // ErrInvalidRecovery indicates malformed recovery input. ErrInvalidRecovery = errors.New("invalid dirty migration recovery") // ErrRecoveryMismatch indicates that source identity differs from the // operator-reviewed recovery request. ErrRecoveryMismatch = errors.New("dirty migration recovery identity mismatch") // ErrNoDirtyMigration indicates there is no matching unresolved outcome. ErrNoDirtyMigration = errors.New("dirty migration not found") // ErrRecoveryUnsupported indicates a backend without recovery conformance. ErrRecoveryUnsupported = errors.New("migration backend does not support recovery") // ErrRecoveryConflict indicates more than one dirty migration in the ledger. ErrRecoveryConflict = errors.New("multiple dirty migrations require recovery") )
var ( // ErrInvalidRunner indicates missing or inconsistent runner dependencies. ErrInvalidRunner = errors.New("invalid migration runner") // ErrBackendResult indicates an engine violated the public backend contract. ErrBackendResult = errors.New("invalid migration backend result") )
var ( // ErrInvalidSource indicates an unusable filesystem source configuration. ErrInvalidSource = errors.New("invalid migration source") // ErrInvalidFilename indicates a non-canonical migration filename. ErrInvalidFilename = errors.New("invalid migration filename") // ErrInvalidFormat indicates malformed or ambiguous migration directives. ErrInvalidFormat = errors.New("invalid migration format") // ErrInvalidEncoding indicates non-UTF-8, NUL-containing, or oversized input. ErrInvalidEncoding = errors.New("invalid migration encoding") // ErrUnexpectedSourceEntry indicates a non-migration entry in the source. ErrUnexpectedSourceEntry = errors.New("unexpected migration source entry") // ErrDuplicateVersion indicates that two source files claim one identity. ErrDuplicateVersion = errors.New("duplicate migration version") )
Functions ¶
This section is empty.
Types ¶
type Backend ¶
Backend is the replaceable migration-engine conformance boundary.
Session.Apply must return only after both execution and owned-ledger persistence have reached an explicit recoverable outcome. Implementations must leave a dirty record when non-transactional execution has an uncertain or partial result.
type Baseline ¶
type Baseline struct {
// contains filtered or unexported fields
}
Baseline is an immutable reviewed schema assertion for adopting an existing database without replaying historical migrations.
func NewBaseline ¶
NewBaseline validates a reviewed baseline contract.
func (Baseline) Fingerprint ¶
Fingerprint returns the expected canonical schema digest.
type Checksum ¶
type Checksum struct {
// contains filtered or unexported fields
}
Checksum is the SHA-256 digest of the canonical migration representation.
func ChecksumData ¶
ChecksumData computes the stable SHA-256 representation of canonical bytes. It is intended for package-defined contracts such as schema fingerprints; migration identity uses its stricter built-in canonical representation.
func ParseChecksum ¶
ParseChecksum decodes the stable ledger representation of a checksum.
type Event ¶
type Event struct {
// contains filtered or unexported fields
}
Event is an immutable structured diagnostic suitable for logging and tracing adapters. SQL text is deliberately excluded.
type FSSource ¶
type FSSource struct {
// contains filtered or unexported fields
}
FSSource loads canonical SQL migrations from one fs.FS directory. It works with embed.FS and rejects unrelated entries so packaging mistakes fail closed.
func NewFSSource ¶
NewFSSource constructs a source rooted at a valid fs.FS path.
type Migration ¶
type Migration struct {
// contains filtered or unexported fields
}
Migration is an immutable canonical SQL migration.
Fields are intentionally private so callers and execution engines cannot mutate identity or persisted checksum state after validation.
func NewMigration ¶
func NewMigration( version Version, name string, transactionMode TransactionMode, upSQL string, downSQL string, ) (Migration, error)
NewMigration validates and constructs a canonical migration.
func (Migration) DownSQL ¶
DownSQL returns the canonical rollback SQL, or an empty string when the migration is irreversible.
func (Migration) TransactionMode ¶
func (migration Migration) TransactionMode() TransactionMode
TransactionMode returns the execution transaction policy.
type Operation ¶
type Operation uint8
Operation identifies an observable migration lifecycle operation.
const ( // OperationLock acquires exclusive migration-job ownership. OperationLock Operation = iota + 1 // OperationApply applies one migration and persists its outcome. OperationApply // OperationRollback rolls back one migration and removes its ledger record. OperationRollback // OperationBaseline validates and records one reviewed existing schema. OperationBaseline // OperationRecover resolves one explicitly reviewed dirty outcome. OperationRecover // OperationUnlock releases exclusive migration-job ownership. OperationUnlock )
type Option ¶
Option configures a Runner.
func WithObserver ¶
WithObserver installs a structured event observer. Observer panics are contained so diagnostics cannot change migration outcomes.
func WithUnlockTimeout ¶
WithUnlockTimeout bounds best-effort lock release after the job context is canceled. Release always uses a detached context so cancellation cannot skip cleanup.
type Plan ¶
type Plan struct {
// contains filtered or unexported fields
}
Plan is a deterministic execution plan derived from source and ledger state.
func PlanDown ¶
PlanDown validates the complete persisted history and returns exactly count rollback steps in descending version order. It never crosses a baseline.
type Record ¶
type Record struct {
// contains filtered or unexported fields
}
Record is an immutable entry read from public.go_schema_migrations.
func NewRecord ¶
func NewRecord( kind RecordKind, version Version, name string, checksum Checksum, appliedAt time.Time, duration time.Duration, dirty bool, ) (Record, error)
NewRecord validates data crossing the owned-ledger boundary.
func (Record) Kind ¶
func (record Record) Kind() RecordKind
Kind returns whether this record is a migration or baseline.
type RecordKind ¶
type RecordKind uint8
RecordKind distinguishes an executed migration from an explicit schema baseline in the owned ledger.
const ( // RecordKindMigration is a migration executed by this package. RecordKindMigration RecordKind = iota + 1 // RecordKindBaseline is a reviewed pre-existing schema assertion. RecordKindBaseline )
type Recovery ¶
type Recovery struct {
// contains filtered or unexported fields
}
Recovery is an immutable, checksum-bound operator decision.
func NewRecovery ¶
func NewRecovery(version Version, checksum Checksum, action RecoveryAction) (Recovery, error)
NewRecovery validates an explicit dirty-state resolution request.
func (Recovery) Action ¶
func (recovery Recovery) Action() RecoveryAction
Action returns the operator's verified outcome.
type RecoveryAction ¶
type RecoveryAction uint8
RecoveryAction is an explicit operator assertion about a dirty migration.
const ( // RecoveryMarkApplied certifies that the migration's full up SQL is present. RecoveryMarkApplied RecoveryAction = iota + 1 // RecoveryMarkRolledBack certifies that all partial effects were removed. RecoveryMarkRolledBack )
type RecoveryResult ¶
type RecoveryResult struct {
// contains filtered or unexported fields
}
RecoveryResult is the persisted outcome of resolving one dirty migration.
func (RecoveryResult) Action ¶
func (result RecoveryResult) Action() RecoveryAction
Action returns the applied recovery decision.
func (RecoveryResult) Record ¶
func (result RecoveryResult) Record() Record
Record returns the resolved ledger record. MarkRolledBack returns the dirty record that was removed; MarkApplied returns its new clean representation.
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
Result describes the migrations completed by one runner invocation.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner coordinates source validation, exclusive locking, history revalidation, planning, and backend execution.
func (*Runner) Baseline ¶
Baseline validates and records an existing schema without replaying any historical framework migrations. The owned ledger must be empty, and every Go-owned source migration must have a version strictly above the baseline.
func (*Runner) Down ¶
Down rolls back exactly count applied migrations, newest first. The source and complete ledger history are revalidated while holding the lock.
func (*Runner) Recover ¶
func (runner *Runner) Recover( ctx context.Context, recovery Recovery, ) (result RecoveryResult, err error)
Recover resolves one checksum-matched dirty migration after the operator has verified that its effects are either fully applied or fully removed.
type Session ¶
type Session interface {
Prepare(context.Context) error
Records(context.Context) ([]Record, error)
Apply(context.Context, Migration) (Record, error)
Rollback(context.Context, Migration) (Record, error)
Release(context.Context) error
}
Session represents exclusive migration-job ownership bound to one physical database connection. Ledger preparation, reads, and execution all happen through this value so connection loss and lock loss cannot be separated from execution and a one-connection pool cannot deadlock during preparation.
type State ¶
type State uint8
State is the deterministic relationship between source and owned ledger.
const ( // StateBaseline is the reviewed adoption boundary for an existing schema. StateBaseline State = iota + 1 // StateApplied is a clean, checksum-matched applied migration. StateApplied // StateDirty is an explicitly unresolved partial or uncertain outcome. StateDirty // StatePending is a source migration not yet represented in the ledger. StatePending )
type Status ¶
type Status struct {
// contains filtered or unexported fields
}
Status is an immutable, version-ordered snapshot.
func BuildStatus ¶
BuildStatus validates source and persisted identity while preserving dirty entries as explicit status instead of hiding them behind a generic error.
func (Status) Entries ¶
func (status Status) Entries() []StatusEntry
Entries returns a copy so callers cannot mutate the validated snapshot.
type StatusEntry ¶
type StatusEntry struct {
// contains filtered or unexported fields
}
StatusEntry is one immutable source or ledger status item.
func (StatusEntry) AppliedAt ¶
func (entry StatusEntry) AppliedAt() time.Time
AppliedAt returns the persisted completion time, or zero for pending work.
func (StatusEntry) Checksum ¶
func (entry StatusEntry) Checksum() Checksum
Checksum returns the source checksum or persisted baseline fingerprint.
func (StatusEntry) Duration ¶
func (entry StatusEntry) Duration() time.Duration
Duration returns the persisted execution duration, or zero for pending work.
func (StatusEntry) Name ¶
func (entry StatusEntry) Name() string
Name returns the canonical migration or baseline name.
func (StatusEntry) State ¶
func (entry StatusEntry) State() State
State returns the item's deterministic state.
func (StatusEntry) Version ¶
func (entry StatusEntry) Version() Version
Version returns the migration or baseline version.
type Step ¶
type Step struct {
// contains filtered or unexported fields
}
Step is one immutable action in a deterministic plan.
type TransactionMode ¶
type TransactionMode uint8
TransactionMode controls whether an engine wraps a migration in a database transaction.
const ( // TransactionModeDefault executes the migration atomically. TransactionModeDefault TransactionMode = iota // TransactionModeNone permits operations PostgreSQL cannot run in a // transaction. A failed migration in this mode requires explicit recovery. TransactionModeNone )
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package conformance provides the reusable behavioral test suite every migration backend must pass without depending on its execution engine.
|
Package conformance provides the reusable behavioral test suite every migration backend must pass without depending on its execution engine. |
|
examples
|
|
|
job
command
Command job runs embedded migrations as a dedicated deployment task.
|
Command job runs embedded migrations as a dedicated deployment task. |
|
internal
|
|
|
goose
Package goose contains the replaceable, hidden Goose execution adapter.
|
Package goose contains the replaceable, hidden Goose execution adapter. |
|
Package migrationsservice adapts an explicit migrations.Runner to the standard service migrate command.
|
Package migrationsservice adapts an explicit migrations.Runner to the standard service migrate command. |
|
Package postgres implements the owned PostgreSQL ledger and lock backend.
|
Package postgres implements the owned PostgreSQL ledger and lock backend. |