migrate

Documentation

Index

• Variables
• func Apply(ctx context.Context, conn TxStarter, fsys fs.FS, opts ...Option) error
• func ParseVersion(name string) (string, error)
• type FileMigration
  • func Discover(ctx context.Context, fsys fs.FS, dir string) ([]FileMigration, error)
  • func Rollback(ctx context.Context, conn TxStarter, fsys fs.FS, opts ...Option) (FileMigration, error)
• type MigrationType
  • func (mt MigrationType) String() string
• type Option
  • func WithAdvisoryLock(id int64) Option
  • func WithBatchSize(size int) Option
  • func WithDirectory(dir string) Option
• type Options
• type PlanResult
  • func Plan(ctx context.Context, conn TxStarter, fsys fs.FS, opts ...Option) (PlanResult, error)
• type SchemaDriftError
  • func (e SchemaDriftError) Error() string
• type TxStarter

Variables

var ErrNoAppliedMigrations = errors.New("migrate: no applied migrations to rollback")

ErrNoAppliedMigrations indicates that rollback could not run because no migrations have been recorded in erm_schema_migrations.

Functions

func Apply

func Apply(ctx context.Context, conn TxStarter, fsys fs.FS, opts ...Option) error

Apply discovers SQL migration files in fsys, executes unapplied migrations, and records them in erm_schema_migrations. All work occurs inside a single transaction protected by pg_advisory_xact_lock.

func ParseVersion

func ParseVersion(name string) (string, error)

ParseVersion extracts the version identifier from a migration filename. The identifier is derived from the portion of the name that precedes the first "__", "_", or "-" separator, falling back to the stem when none are present.

Types

type FileMigration

type FileMigration struct {
	// Version is the parsed migration identifier recorded in erm_schema_migrations.
	Version string
	// Name is the base filename (e.g. 0001_init.sql).
	Name string
	// Path is the path relative to the root of the provided fs.FS.
	Path string
	// Type identifies whether the migration is an up (forward) or down (rollback) script.
	Type MigrationType
}

FileMigration represents a single SQL migration discovered on disk.

func Discover

func Discover(ctx context.Context, fsys fs.FS, dir string) ([]FileMigration, error)

Discover locates .sql migrations within dir and returns them in lexical order. A missing directory results in an empty slice.

func Rollback

func Rollback(ctx context.Context, conn TxStarter, fsys fs.FS, opts ...Option) (FileMigration, error)

Rollback executes the rollback script for the most recently applied migration and removes the corresponding version from erm_schema_migrations.

type MigrationType

type MigrationType int

MigrationType differentiates forward (up) migrations from rollback (down) scripts.

const (
	// MigrationTypeUp represents a forward migration that applies schema changes.
	MigrationTypeUp MigrationType = iota
	// MigrationTypeDown represents a rollback script that reverts a previously applied migration.
	MigrationTypeDown
)

func (MigrationType) String

func (mt MigrationType) String() string

String implements fmt.Stringer.

type Option

type Option func(*Options)

Option mutates Options.

func WithAdvisoryLock

func WithAdvisoryLock(id int64) Option

WithAdvisoryLock overrides the advisory lock identifier used to serialize migration runs.

func WithBatchSize

func WithBatchSize(size int) Option

WithBatchSize limits the number of unapplied migrations executed per Apply invocation.

func WithDirectory

func WithDirectory(dir string) Option

WithDirectory instructs Apply to look for migration files under dir.

type Options

type Options struct {
	// Directory indicates the root within the supplied fs.FS that contains the
	// migration files. Defaults to "migrations".
	Directory string
	// BatchSize controls how many unapplied migrations are executed in a single
	// invocation. Zero means all pending migrations run in one transaction.
	BatchSize int
	// AdvisoryLockID overrides the pg_advisory_xact_lock key that guards
	// migrations. Defaults to a deterministic key derived from the project
	// prefix.
	AdvisoryLockID int64
}

Options configures how migrations are discovered and applied.

type PlanResult

type PlanResult struct {
	// Pending lists unapplied up migrations in execution order.
	Pending []FileMigration
	// Applied lists versions recorded in erm_schema_migrations.
	Applied []string
}

PlanResult summarises the outcome of inspecting migrations without executing them.

func Plan

func Plan(ctx context.Context, conn TxStarter, fsys fs.FS, opts ...Option) (PlanResult, error)

Plan inspects the migrations directory and erm_schema_migrations to determine which forward migrations remain unapplied. It performs validation to ensure recorded migrations still exist on disk.

type SchemaDriftError

type SchemaDriftError struct {
	Missing []string
}

SchemaDriftError signals that the database has recorded migrations whose SQL files are no longer present in the migrations directory.

func (SchemaDriftError) Error

func (e SchemaDriftError) Error() string

type TxStarter

type TxStarter interface {
	BeginTx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error)
}

TxStarter abstracts pgx connections capable of starting a transaction.