migrate

Documentation

Overview

Package migrate provides a minimal database migration runner. Migrations are read from one or more named Layer instances (each wrapping an fs.FS) and applied in global lexicographic order by filename. Using a date-based filename prefix (e.g. 20060102_description.sql) across all layers gives a natural chronological ordering regardless of which layer a migration comes from.

Applied versions are tracked as "layername/filename" (without .sql) so migrations from different layers with the same filename do not collide in the tracking table.

Database access and dialect differences are abstracted through the DB interface. Use NewDriver to wrap a *sql.DB with a Dialect.

Index

• Variables
• func MapError(err error) error
• type DB
  • func NewDriver(db *sql.DB, dialect Dialect) DB
• type Dialect
• type Layer
• type MigrateResult
• type Migrator
  • func New(db DB, opts ...Option) *Migrator
  • func (m *Migrator) Migrate(ctx context.Context) (*MigrateResult, error)
  • func (m *Migrator) Pending(ctx context.Context) ([]string, error)
• type Option
  • func WithDirectory(dir string) Option
  • func WithLayers(layers ...Layer) Option
  • func WithTable(name string) Option
• type PostgresDialect
  • func (PostgresDialect) CreateTableSQL(table string) string
  • func (PostgresDialect) InsertVersionSQL(table string) string
  • func (PostgresDialect) QueryVersionsSQL(table string) string
• type Rows
• type SQLiteDialect
  • func (SQLiteDialect) CreateTableSQL(table string) string
  • func (SQLiteDialect) InsertVersionSQL(table string) string
  • func (SQLiteDialect) QueryVersionsSQL(table string) string
• type Tx

Variables

var ErrConflict = errors.New("conflict")

ErrConflict is returned when an insert or update violates a uniqueness constraint.

var ErrNotFound = errors.New("not found")

ErrNotFound is returned when a queried record does not exist.

Functions

func MapError

func MapError(err error) error

MapError translates database/sql errors to migrate sentinel errors.

Types

type DB

type DB interface {
	Exec(ctx context.Context, query string, args ...any) error
	Query(ctx context.Context, query string, args ...any) (Rows, error)
	Begin(ctx context.Context) (Tx, error)

	CreateTableSQL(table string) string
	InsertVersionSQL(table string) string
	QueryVersionsSQL(table string) string
}

DB abstracts database operations and dialect-specific SQL. Use NewDriver to create one from a *sql.DB and Dialect.

func NewDriver

func NewDriver(db *sql.DB, dialect Dialect) DB

NewDriver wraps a *sql.DB and Dialect to satisfy the DB interface.

type Dialect

type Dialect interface {
	CreateTableSQL(table string) string
	InsertVersionSQL(table string) string
	QueryVersionsSQL(table string) string
}

Dialect abstracts dialect-specific SQL differences.

type Layer

type Layer struct {
	Name string
	FS   fs.FS
}

Layer associates a name with an fs.FS containing migration files. The name is used to namespace version strings in the tracking table (e.g. "auth/20060102_create_users"), so migrations from different layers with the same filename do not collide.

type MigrateResult

type MigrateResult struct {
	Applied []string // versions applied in this run
	Total   int      // total migrations (applied + already present)
}

MigrateResult contains information about a migration run.

type Migrator

type Migrator struct {
	// contains filtered or unexported fields
}

Migrator runs migrations against a database.

func New

func New(db DB, opts ...Option) *Migrator

New creates a Migrator. Call WithLayers to register migration layers.

func (*Migrator) Migrate

func (m *Migrator) Migrate(ctx context.Context) (*MigrateResult, error)

Migrate applies all pending migrations in sorted order. Each migration runs in its own transaction. Returns the list of newly applied versions.

func (*Migrator) Pending

func (m *Migrator) Pending(ctx context.Context) ([]string, error)

Pending returns the list of migration versions not yet applied.

type Option

type Option func(*Migrator)

Option configures a Migrator.

func WithDirectory

func WithDirectory(dir string) Option

WithDirectory sets the subdirectory within each Layer's FS to read migration files from (default: "migrations"). Use "." to read from the root.

func WithLayers

func WithLayers(layers ...Layer) Option

WithLayers appends one or more Layer values to the migrator. All migrations from all layers are sorted globally by filename before being applied, so date-prefixed filenames (e.g. 20060102_name.sql) produce a correct chronological order across layers.

func WithTable

func WithTable(name string) Option

WithTable sets the migrations tracking table name (default: "schema_migrations").

type PostgresDialect

type PostgresDialect struct{}

PostgresDialect implements Dialect for PostgreSQL databases.

func (PostgresDialect) CreateTableSQL

func (PostgresDialect) CreateTableSQL(table string) string

func (PostgresDialect) InsertVersionSQL

func (PostgresDialect) InsertVersionSQL(table string) string

func (PostgresDialect) QueryVersionsSQL

func (PostgresDialect) QueryVersionsSQL(table string) string

type Rows

type Rows interface {
	Next() bool
	Scan(dest ...any) error
	Err() error
	Close()
}

Rows abstracts result set iteration.

type SQLiteDialect

type SQLiteDialect struct{}

SQLiteDialect implements Dialect for SQLite databases.

func (SQLiteDialect) CreateTableSQL

func (SQLiteDialect) CreateTableSQL(table string) string

func (SQLiteDialect) InsertVersionSQL

func (SQLiteDialect) InsertVersionSQL(table string) string

func (SQLiteDialect) QueryVersionsSQL

func (SQLiteDialect) QueryVersionsSQL(table string) string

type Tx

type Tx interface {
	Exec(ctx context.Context, query string, args ...any) error
	Rollback(ctx context.Context) error
	Commit(ctx context.Context) error
}

Tx abstracts a database transaction.