migrate

Goose migrations as app modules.

Install

go get gitea.auvem.com/go-toolkit/migrate

Quick start

//go:embed migrations/*.sql
var migrations embed.FS

mod, err := migrate.ModuleMigrations(&migrate.MigrationOpts{
    SQLO:     dbx.SQLO,
    Dialect:  goose.DialectMySQL,
    FS:       migrations,
    BasePath: "migrations",
})

Applying pending migrations

ApplyPendingMigrations(ctx, pendingCount) returns the number of migrations successfully applied, including empty migrations. A count of 0 applies none, a negative count applies all pending migrations, and a positive count applies at most that many. Reaching the end of pending migrations is successful, even when fewer migrations remain than the positive cap. A failure returns the successful count so far and the migration/provider error.

Migration versions are identifiers: contiguous numbers, gaps, timestamps, and mixed numbering all work without treating a version difference as a count. AutoMigrate applies all pending migrations when enabled, retains per-migration and completion logs with actual version identifiers and successful counts, and returns ErrPendingMigrations when disabled and newer migrations exist. Already-current databases are a no-op in either mode.

CLI

Use migrate/cli with appcli — not the removed migrate/cmd package.

Production notes

Require a goose zero-version migration for empty databases
Do not run ModuleMigrateBlank in production
When auto-migration is disabled, pending migrations return ErrPendingMigrations

Breaking changes (V1)

Before	After
`migrate.Migration` global	`migrate.Provider()`
`ModuleMigrations(cfg) *Module` (panic)	`ModuleMigrations(cfg) (*Module, error)` + `MustModuleMigrations`
`ModuleMigrateUp` var	`ModuleMigrateUp()` factory
`MigrationsConfig() *MigrationOpts`	`MigrationsConfig() MigrationOpts` (copy)
`migrate/cmd`	removed — use `migrate/cli`

2.1 KiB Raw Blame History