go/migrate

migrate

go.auvem.com/corestack/migrate sets the house configuration for Goose's Provider API. It returns *goose.Provider directly: Goose owns execution, version tracking, status, and errors. There is no lifecycle dependency or background work.

Use the standalone corestack-goose development tool for SQL and Go creation and timestamp-to-sequential reconciliation. Its generated Go migrations work unchanged with this package's provider-local registration:

go install go.auvem.com/corestack/cmd/corestack-goose@<release>
mkdir -p migrations
cd migrations
corestack-goose create create_events sql
corestack-goose fix
corestack-goose create populate_events go
corestack-goose fix
# Or use the version selected by your consumer module:
go run go.auvem.com/corestack/cmd/corestack-goose create add_index sql

Both commands default to the current working directory; use --dir <dir> to select another existing directory. Paths must have no symlink components (on macOS use /private/tmp, rather than /tmp), and migration files must be regular. Names are lowercase ASCII words separated by underscores. Templates are stock Goose SQL or transactional Go. The Go suffix <version>_<name>_migration.go keeps names such as test, create_test and windows buildable on every platform. Edit up/down bodies; leave factories and generated register.go intact. Its GoMigrations() returns fresh registrations, even for SQL-only sets.

Versions must be unique across SQL and Go. Goose timestamps have second resolution: fix each new migration before creating another in the same second, or wait for a distinct timestamp. fix preserves sequential IDs and migration bodies, allocates timestamps after the highest sequential ID with at least five-digit padding, and updates filenames and registration literals together. Preflight rejects unsafe paths, collisions, unsupported Go layouts, edited aggregates, duplicate versions/factories, overflow and lexical/numeric order disagreement. Stock Goose Go output uses an incompatible global init registry. For concepts, see Goose's hybrid versioning and SQL annotations.

Before fix, commit or separately back up the complete source set, including untracked migrations and tracked edits. Use one authoring process without concurrent editor changes. New destinations are exclusive; staged destinations are fully published before old sources are removed. This is not an atomic multi-file operation: interruption can leave duplicates, aggregate drift or staging files, with no automatic rollback or journal. On failure inspect the reported completed, partial/current and outstanding paths, then restore the complete source set and aggregate from backup before retrying. Ordinary Git restore cannot recover untracked files or unsaved edits.

Source reconciliation never rewrites database history. Use it before those IDs reach a shared database; preserve deployed IDs and add migrations afterward. The tool cannot determine deployment history.

The standalone tool needs no database or build tags. Production imports migrate and optionally migrate/lifecycle; neither imports authoring code. Generated migrations import only Goose and the standard library. Artifact tests verify the runtime dependency and executable boundary for the tested build.

Embed migrations in the application's binary and run them before serving traffic:

package app

import (
    "context"
    "database/sql"
    "embed"
    "log/slog"

    "github.com/pressly/goose/v3"
    "go.auvem.com/corestack/migrate"
)

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

func migrateDatabase(ctx context.Context, db *sql.DB, logger *slog.Logger) error {
    provider, err := migrate.New(db, goose.DialectPostgres, migrations, "migrations", logger)
    if err != nil {
        return err
    }
    _, err = provider.Up(ctx)
    return err
}

The caller opens and closes db, selects a matching database driver and dialect, supplies a nonnil logger, and controls the operation context/deadline. Construction is offline; SQL is parsed lazily by Goose. Provider.Close also closes db, so do not defer it when sharing the pool with the application. Use "." for SQL files at the embedded root. Files in the selected directory are discovered directly, without recursively searching subdirectories.

Preserve the tool's creator/fix filenames and ship the complete migration history. The pinned Goose SQL-only provider relies on lexical filename order matching numeric version order. Timestamp versions and gaps are supported; never derive versions from file counts. For operations and errors, use the Provider API.

For generated Go functions, import the consumer's migration package and pass migrations.GoMigrations()... as the trailing arguments to migrate.New. Embed the complete directory with //go:embed migrations (and use a different variable name, such as migrationFiles, from the imported package). The directory must exist even for Go-only sets. Global registration is disabled; never share mutable registration objects across providers. See Goose's provider-local registration.

Lifecycle startup and native commands

go.auvem.com/corestack/migrate/lifecycle is a thin adapter; migrate itself has no lifecycle dependency. Alias it migratelifecycle to distinguish the core lifecycle package. Its resolver runs after the caller's database setup and should construct a fresh provider with fresh registrations:

resolve := func(ctx context.Context) (*goose.Provider, error) {
    return migrate.New(db, goose.DialectPostgres, migrationFiles,
        "migrations", logger, migrations.GoMigrations()...)
}
startup, err := migratelifecycle.Module("migrations", migratelifecycle.Require, resolve)
if err != nil {
    return err
}
root := &urfavecli.Command{Name: "app", Commands: []*urfavecli.Command{
    {Name: "serve", Action: cli.Serve(cfg, []lifecycle.Module{database, startup, server})},
    migratelifecycle.Commands(cfg, []lifecycle.Module{database}, resolve),
}}
code, err := cli.Run(ctx, root, args) // args includes argv[0]; caller owns process exit.

Here database.Setup opens db and cleans up its partial acquisition on failure; database.Teardown closes it. Construct the tree and captured resource bindings fresh for independent invocations. Declaration does no work. Select Apply to run Up during setup, or Require to fail before later setup/services when migrations are pending. Require is a point-in-time check without a deployment lock. It and status may initialize Goose's version table; neither promises read-only DB access. The migration module never closes the provider or shared database.

The native group supplies migrate up, up-to <version> (inclusive), down (one migration), down-to <version> and status (version/state/source table). Pass exactly the database modules, excluding the startup migration module and unrelated modules. Services are suppressed; the existing lifecycle/cli.Action owns signals, cancellation, errors and reverse cleanup. Help and invalid arguments never run setup. Target versions must be nonnegative decimal int64 values, with no extra arguments; malformed usage returns exit 2 through cli.Run. Zero follows Goose: down-to 0 rolls everything back; up-to 0 succeeds if nothing is pending, but returns a runtime error when pending work reaches Goose's version validation. Resolver/Goose/cleanup and status Writer failures return runtime errors (exit 1). Supply the native command Writer and configured Goose logger for output.

Postgres providers automatically use Goose's default session advisory locker. Concurrent startup calls from separate providers/processes serialize migration execution and recheck applied versions under the lock. The default lock ID serializes Goose migrations throughout the same database, including different schemas. Use a direct connection or a session-pooling proxy: transaction pooling cannot preserve session locks. RunDB Go migrations need spare pool connections while the locked session is held; avoid a one-connection pool for them.

Other dialects have no cross-provider/process lock configured by this package. Serialize migration runs externally, for example with a single deployment job. SQLite tests validate the SQL convention, not concurrent daemon startup safety.

Run the integration suite against an existing Postgres database with schema creation privileges:

MIGRATE_POSTGRES_DSN='postgres://user:password@localhost/testdb?sslmode=disable' go test -race ./migrate

Tests create and clean only random schemas they own. Without a DSN, Postgres tests skip locally; in CI a missing DSN fails, and the CI job supplies a Postgres service. SQLite tests always run in process using temporary databases.