libmigrate

README

libmigrate

A library for managing and running database migrations. For a command-line tool, see:

• psql-migrate for PostgreSQL
• sqlite-migrate for SQLite3

This library has a few goals:

• Production-friendly: Transactional DDL by default, with per-migration overrides
• Safe: Strict validation of migration files, for gaps or conflicts with the database
• Minimal: Bring your own database driver

Usage

If you want to use libmigrate directly as a library, look at psql-migrate or sqlite-migrate.

Migration files can be marked to run without a transaction with a prefix comment:

-- migrate: no-transaction

Documentation

Index

• Constants
• Variables
• type DB
• type Migrator
  • func New(db DB, migrationDir string, paramType ParamType) Migrator
  • func NewFs(db DB, fs fs.FS, paramType ParamType) Migrator
• type ParamType

Constants

const NoTransactionPrefix = "-- migrate: no-transaction\n"

If your migration must run outside a transaction, the first line must match this constant. (Useful for migrations like PostgreSQL "CREATE INDEX CONCURRENTLY" statements.)

Variables

var (
	ErrFsNotWriteable = fmt.Errorf("Migration filesystem not writeable")
)

Types

type DB

type DB interface {
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
	BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)
}

New() accepts a *database/sql.DB or equivalent.

type Migrator

type Migrator interface {
	MigrateLatest(ctx context.Context) error
	MigrateTo(ctx context.Context, version int) error
	GetVersion(ctx context.Context) (int, error)
	HasPending(ctx context.Context) (bool, error)
	Create(ctx context.Context, name string) error

	SetTableName(name string)
	// If set, "table" becomes schema."table"
	SetTableSchema(schema string)

	// Set to nil to disable output. Default: os.Stdout
	SetOutputWriter(io.Writer)
}

func New

func New(db DB, migrationDir string, paramType ParamType) Migrator

func NewFs

func NewFs(db DB, fs fs.FS, paramType ParamType) Migrator

type ParamType

type ParamType int

Different databases use different syntax for indicating parameter values. Since jmoiron/sqlx hasn't found a better way than naming each one, we probably won't either. Leave it to the caller.

const (
	ParamTypeQuestionMark ParamType = iota
	ParamTypeDollarSign
)