Documentation
¶
Overview ¶
Package migrate provides a PostgreSQL migration loader and a Migrator that applies, reverts, and reports the status of versioned SQL migrations.
Index ¶
- func Migrate(ctx context.Context, db DBTX, sources ...fs.FS) error
- type AppliedMigration
- type DBTX
- type Migration
- type Migrator
- func (m *Migrator) Applied(ctx context.Context) ([]AppliedMigration, error)
- func (m *Migrator) Down(ctx context.Context, n int) error
- func (m *Migrator) Pending(ctx context.Context) ([]Migration, error)
- func (m *Migrator) Status(ctx context.Context) (Status, error)
- func (m *Migrator) To(ctx context.Context, version string) error
- func (m *Migrator) Up(ctx context.Context) error
- type Option
- type Status
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Migrate ¶
Migrate loads migrations from one or more filesystems (merged, then sorted by version) and applies all pending ones. It is intended for service startup, e.g.:
//go:embed migrations/*.sql
var migrationsFS embed.FS
if err := migrate.Migrate(ctx, pool, migrationsFS); err != nil { ... }
*pgxpool.Pool satisfies DBTX. Duplicate versions across the merged sources are an error. With no sources Migrate is a no-op and returns nil.
Types ¶
type AppliedMigration ¶
AppliedMigration is a row recorded in the bookkeeping table.
type DBTX ¶
type DBTX interface {
Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
Begin(ctx context.Context) (pgx.Tx, error)
}
DBTX is the database handle the Migrator runs against. *pgxpool.Pool satisfies it, as does a *pgx.Conn wrapper that exposes Begin.
type Migration ¶
type Migration struct {
Version string
Name string
UpSQL string
DownSQL string
Checksum string // sha256 hex of the raw file bytes
}
Migration is a single versioned SQL migration loaded from a file.
A migration file is named "<version>_<name>.sql". Its body may contain "-- sqld:up" and "-- sqld:down" markers that split the up and down sections; when no markers are present the whole file is the up section.
func Load ¶
Load reads all *.sql migrations from an OS directory and returns them sorted by version. It delegates to LoadFS over os.DirFS(dir).
Each filename is parsed as "<version>_<name>.sql": everything up to the first '_' is the version, the remainder (minus the .sql extension) is the name. The file body is split into up/down sections on the "-- sqld:up" / "-- sqld:down" markers (case-insensitive, whole-line); with no markers the whole file is up. Checksum is the sha256 hex of the raw file bytes.
func LoadFS ¶
LoadFS reads all *.sql migrations from an fs.FS (e.g. an embed.FS) and returns them sorted by version.
It walks the filesystem recursively, so an `//go:embed migrations` directive (whose files live under "migrations/") works without the caller doing fs.Sub. Each base filename is parsed as "<version>_<name>.sql"; the body is split on the "-- sqld:up" / "-- sqld:down" markers (with no markers the whole file is up); Checksum is the sha256 hex of the raw file bytes. Non-.sql files are skipped.
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator applies, reverts, and reports the status of a set of migrations.
func New ¶
New creates a Migrator over db using the given migrations. The migrations are kept in version order regardless of input order.
func (*Migrator) Applied ¶
func (m *Migrator) Applied(ctx context.Context) ([]AppliedMigration, error)
Applied returns the recorded migrations in ascending version order.
func (*Migrator) Down ¶
Down reverts the last n applied migrations (descending version order), running each migration's DownSQL in its own transaction. It is an error to revert a migration with no DownSQL.
type Status ¶
type Status struct {
Applied []AppliedMigration
Pending []Migration
Drift []string
}
Status summarizes the migration state of a database.
Applied lists the rows recorded in the bookkeeping table (version order). Pending lists loaded migrations not yet applied (version order). Drift lists versions whose recorded checksum differs from the loaded migration's checksum — i.e. a migration file changed after being applied.
Source Files