migrate

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 30, 2026 License: MIT Imports: 11 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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 Down

func Down(ctx context.Context, dbURL string, fsys fs.FS, opts ...Options) error

Down reverts the most recently applied migration.

func Status

func Status(ctx context.Context, dbURL string, fsys fs.FS, w io.Writer, opts ...Options) error

Status writes a human-readable table of migration versions and their applied state to w.

func Up

func Up(ctx context.Context, dbURL string, fsys fs.FS, opts ...Options) error

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.

func UpByOne

func UpByOne(ctx context.Context, dbURL string, fsys fs.FS, opts ...Options) error

UpByOne applies exactly one pending migration. Returns goose.ErrNoNextVersion if every migration has already been applied.

func UpTo

func UpTo(ctx context.Context, dbURL string, fsys fs.FS, version int64, opts ...Options) error

UpTo applies all pending migrations up to and including the given version.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL