Documentation
¶
Overview ¶
Package migrate provides programmatic access to SQL/Go migrations owned by the consuming application, wrapping pressly/goose v3's Provider API.
Unlike the source repositories' migrate package, this one does not embed or otherwise own any migration files: a shared library has no migrations of its own, only applications do. Every function here takes an fs.FS (typically an application's own go:embed'd directory, or os.DirFS during local development) as an explicit parameter instead of reading a package-level embedded default.
Locking: every operation acquires a PostgreSQL session-level advisory lock (goose's default lock ID, a crc64 hash of "goose") for the duration of the migration run, via goose.WithSessionLocker. This is the fix this package adds over its source: none of the three source repositories locked at all, so two concurrent `migrate up` invocations — two CI jobs against the same database, two init containers racing on pod startup, a manual run overlapping a deploy pipeline — could interleave DDL and corrupt the goose_db_version bookkeeping instead of one simply waiting for the other.
CREATE INDEX CONCURRENTLY: PostgreSQL does not allow CREATE INDEX CONCURRENTLY inside a transaction, and goose runs each migration in its own transaction by default. A migration file that needs it must start with the "-- +goose NO TRANSACTION" annotation (see goose's documentation for "-- +goose NO TRANSACTION") so goose runs it outside of a transaction instead of wrapping it in one that PostgreSQL will reject.
Index ¶
- Variables
- func Down(ctx context.Context, dbURL string, fsys fs.FS, opts ...Options) error
- func Status(ctx context.Context, dbURL string, fsys fs.FS, w io.Writer, opts ...Options) error
- func Up(ctx context.Context, dbURL string, fsys fs.FS, opts ...Options) error
- func UpByOne(ctx context.Context, dbURL string, fsys fs.FS, opts ...Options) error
- func UpTo(ctx context.Context, dbURL string, fsys fs.FS, version int64, opts ...Options) error
- type Options
Constants ¶
This section is empty.
Variables ¶
var ErrNoMigrations = goose.ErrNoMigrations
ErrNoMigrations is returned (via errors.Is) when fsys contains no migration files. Re-exported from goose so callers do not need to import goose themselves just to check this one error.
Functions ¶
func Status ¶
Status writes a human-readable table of migration versions and their applied state to w.
func Up ¶
Up applies all pending migrations found in fsys. It is idempotent: calling Up on a fully migrated database is a no-op that returns nil.
Returns an error if dbURL is unreachable, if fsys contains no migrations (ErrNoMigrations), or if any migration fails.
Types ¶
type Options ¶
type Options struct {
// Logger is the slog logger used for goose output. When nil, slog.Default()
// is used. Pass slog.New(slog.NewTextHandler(io.Discard, nil)) to silence
// goose during tests.
Logger *slog.Logger
// LockID overrides the PostgreSQL advisory lock ID used to serialize
// migration runs. Zero uses goose's default (a crc64 hash of "goose").
// Override this only if a consumer needs distinct locks for distinct
// migration sets running against the same database.
LockID int64
// DisableLock disables the session-level advisory lock. It exists as an
// escape hatch for environments where advisory locks are unavailable
// (e.g. a connection pooler in transaction-pooling mode that does not
// preserve session state); leave it false in every normal deployment.
DisableLock bool
// TableName overrides the name of the goose version table used to track
// which migrations have been applied. Empty uses goose's own default,
// "goose_db_version".
//
// Set this whenever more than one independently-numbered migration set
// runs against the same database — most notably, a library-owned
// migration set (see vogel/audit/migrations) alongside an application's
// own migrations. Both sets start numbering at 001; without separate
// version tables, goose would see the library's "001" as already applied
// once the application's own "001" ran (or vice versa), silently
// skipping one set. This is deliberately a caller-supplied option, not a
// constant hardcoded in this package, since this package owns no
// migrations of its own and has no opinion on what any consumer should
// name their table(s).
TableName string
}
Options configures optional behaviour for migrate operations.