migrate

Documentation

Overview

Package migrate provides a minimal database migration runner. Migrations are read from an fs.FS (typically embed.FS) and applied in lexicographic order. Applied versions are tracked in a configurable table.

Database access and dialect differences are abstracted through the DB interface. Use NewDriver to wrap a *sql.DB with a Dialect, or the pgxmigrate sub-package for native pgx support.

Index

• type DB
  • func NewDriver(db *sql.DB, dialect Dialect) DB
• type Dialect
• type MigrateResult
• type Migrator
  • func New(db DB, fsys fs.FS, 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 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

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, or implement this interface for other database libraries such as pgx.

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 MigrateResult

type MigrateResult struct {
	Applied []string // versions that were 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, fsys fs.FS, opts ...Option) *Migrator

New creates a Migrator. The fs should contain .sql files named with a sortable prefix (e.g. 0001_initial.sql, 0002_add_users.sql).

func (*Migrator) Migrate

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

Migrate applies all pending migrations in lexicographic 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 that have not yet been applied.

type Option

type Option func(*Migrator)

Option configures a Migrator.

func WithDirectory

func WithDirectory(dir string) Option

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

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.