migrate

Documentation

Overview

Package migrate provides dialect-aware, transactional SQL migrations on top of database/sql.

Index

• func HandleCommand(ctx context.Context, args []string, runner *Runner, migrations []Migration, ...) (handled bool, err error)
• func IsCommand(command string) bool
• type AppliedMigration
• type Dialect
  • func DialectForDriver(driverName string) (Dialect, error)
  • func MySQL() Dialect
  • func PostgreSQL() Dialect
  • func SQLite() Dialect
  • func (d Dialect) Name() string
• type Migration
  • func LoadFS(filesystem fs.FS, directory string) ([]Migration, error)
  • func ValidateMigrations(migrations []Migration) ([]Migration, error)
• type Option
  • func WithTable(table string) Option
• type Runner
  • func New(db *sql.DB, dialect Dialect, options ...Option) (*Runner, error)
  • func (r *Runner) Down(ctx context.Context, migrations []Migration, steps int) (count int, err error)
  • func (r *Runner) Statuses(ctx context.Context, migrations []Migration) ([]Status, error)
  • func (r *Runner) Up(ctx context.Context, migrations []Migration, limit int) (count int, err error)
• type Status

Functions

func HandleCommand

func HandleCommand(
	ctx context.Context,
	args []string,
	runner *Runner,
	migrations []Migration,
	output io.Writer,
) (handled bool, err error)

HandleCommand executes a migration command from application arguments.

Supported commands are migrate, migrate:rollback, and migrate:status. It returns handled=false for arguments that belong to another application command.

func IsCommand

func IsCommand(command string) bool

IsCommand reports whether command is handled by HandleCommand.

Applications can use it to avoid opening a database connection for unrelated application commands.

Types

type AppliedMigration

type AppliedMigration struct {
	Version   int64
	Name      string
	AppliedAt time.Time
}

AppliedMigration is a migration recorded in the database.

type Dialect

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

Dialect describes the small amount of SQL syntax required by the migration metadata table.

func DialectForDriver

func DialectForDriver(driverName string) (Dialect, error)

DialectForDriver maps common database/sql driver names to a migration dialect.

func MySQL

func MySQL() Dialect

MySQL returns the MySQL migration dialect.

func PostgreSQL

func PostgreSQL() Dialect

PostgreSQL returns the PostgreSQL migration dialect.

func SQLite

func SQLite() Dialect

SQLite returns the SQLite migration dialect.

func (Dialect) Name

func (d Dialect) Name() string

Name returns the dialect's stable name.

type Migration

type Migration struct {
	Version int64
	Name    string
	Up      []string
	Down    []string
}

Migration is one ordered database schema change.

func LoadFS

func LoadFS(filesystem fs.FS, directory string) ([]Migration, error)

LoadFS loads paired .up.sql and .down.sql migrations from directory.

File names use VERSION_NAME.up.sql and VERSION_NAME.down.sql. Multiple SQL statements are separated by a line containing "-- kora:split".

func ValidateMigrations

func ValidateMigrations(migrations []Migration) ([]Migration, error)

ValidateMigrations validates and sorts migrations by ascending version.

type Option

type Option func(*Runner) error

Option configures a Runner.

func WithTable

func WithTable(table string) Option

WithTable changes the migration metadata table.

type Runner

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

Runner applies migrations through a database/sql pool.

func New

func New(db *sql.DB, dialect Dialect, options ...Option) (*Runner, error)

New creates a migration runner.

func (*Runner) Down

func (r *Runner) Down(ctx context.Context, migrations []Migration, steps int) (count int, err error)

Down rolls back the most recently applied migrations.

func (*Runner) Statuses

func (r *Runner) Statuses(ctx context.Context, migrations []Migration) ([]Status, error)

Statuses returns local migrations and their database state.

func (*Runner) Up

func (r *Runner) Up(ctx context.Context, migrations []Migration, limit int) (count int, err error)

Up applies pending migrations in ascending version order. A limit of zero applies every pending migration.

type Status

type Status struct {
	Version   int64
	Name      string
	Applied   bool
	AppliedAt time.Time
}

Status describes whether a local migration is applied.