migrator

Documentation

Overview

Package migrator provides a thin wrapper around golang-migrate for paper-board services. Each service ships a ~30-line cmd/migrator/main.go that calls Run with a Config carrying the embedded migrations.

Advisory locking is driver-managed via golang-migrate's pgx/v5 driver, which derives a CRC32 lock id from database+schema. Schema-per-service (ADR-0002) guarantees hash isolation across services — no manual lock id needed.

Usage:

cfg := migrator.Config{
    DBURL:     os.Getenv("MIGRATION_DB_URL"),
    Schema:    "identity",
    EmbedFS:   migrations.SchemaFS,
    EmbedRoot: "schema",
}
migrator.Run(context.Background(), cfg, os.Args[1:])

Index

• Variables
• func Run(ctx context.Context, cfg Config, args []string) error
• type Config

Variables

var (
	ErrMissingEnv     = errors.New("MIGRATION_DB_URL env not set")
	ErrDirty          = errors.New("schema is dirty; run 'migrator force <prev_version>' after fixing")
	ErrLockTimeout    = errors.New("advisory lock acquisition timed out (another migrator running?)")
	ErrDropProduction = errors.New("'drop' is dev-only; set MIGRATOR_ENV=dev to enable")
)

Sentinel errors. Callers may use errors.Is to detect specific failure modes.

Functions

func Run

func Run(ctx context.Context, cfg Config, args []string) error

Run is the binary entry point. It parses args, connects to Postgres, acquires the advisory lock, and dispatches to the appropriate subcommand.

Returns nil on success, error otherwise. Callers typically:

if err := migrator.Run(ctx, cfg, os.Args[1:]); err != nil {
    log.Fatal(err)
}

Types

type Config

type Config struct {
	// DBURL is MIGRATION_DB_URL — direct Postgres on port 5432, NOT PgBouncer.
	// Advisory locks require session-mode connections; PgBouncer transaction
	// pooling breaks them.
	DBURL string

	// Schema is the Postgres schema this service owns (e.g., "identity").
	// Migrations run with search_path=<Schema>,public.
	Schema string

	// EmbedFS is the embedded migration filesystem from the service repo.
	// Convention: //go:embed schema/*.sql
	EmbedFS embed.FS

	// EmbedRoot is the directory inside EmbedFS containing migration files.
	// Typically "schema".
	EmbedRoot string
}

Config carries everything Run needs. All fields required.