migrate

Documentation

Overview

Package migrate is liteorm's thin, driver-free migration runner. It applies ordered migrations against any liteorm.Session, tracking state in a single-row (version, dirty) ledger table (the golang-migrate model) created dialect-aware so it works on SQLite/Postgres/MySQL/MSSQL. It does NOT generate DDL — that is orm.AutoMigrate / orm.GenerateMigration; this runs the SQL you (or the generator) wrote. Load reads three on-disk formats (see source.go). A failed migration leaves the ledger dirty; the next run refuses until Force.

Index

• func WritePair(dir string, version uint64, name, up, down string) (upPath, downPath string, err error)
• type DirtyError
  • func (e *DirtyError) Error() string
• type Migration
  • func Load(fsys fs.FS) ([]Migration, error)
• type Migrator
  • func New(sess liteorm.Session, opts ...Option) *Migrator
  • func (m *Migrator) Down(ctx context.Context, migs []Migration) error
  • func (m *Migrator) DownTo(ctx context.Context, migs []Migration, target uint64) error
  • func (m *Migrator) Force(ctx context.Context, version uint64) error
  • func (m *Migrator) Status(ctx context.Context, migs []Migration) ([]Status, error)
  • func (m *Migrator) Up(ctx context.Context, migs []Migration) (int, error)
  • func (m *Migrator) UpTo(ctx context.Context, migs []Migration, target uint64) (int, error)
  • func (m *Migrator) Version(ctx context.Context) (uint64, bool, error)
• type Option
  • func WithTable(name string) Option
• type Status

Functions

func WritePair

func WritePair(dir string, version uint64, name, up, down string) (upPath, downPath string, err error)

WritePair writes a golang-migrate-style migration pair into dir:

<version>_<slug>.up.sql
<version>_<slug>.down.sql

version is zero-padded to at least six digits; slug is name lowercased with runs of non-alphanumeric characters collapsed to single underscores. The files are exactly the split format Load reads back, so a migration generated from a model diff (orm.GenerateMigration) drops straight into the runner an adopter already uses. dir is created if missing.

An empty up is an error. An empty down is written as a single comment so the step is explicitly irreversible rather than silently empty — Migrator.Down then reports it as irreversible instead of treating "no statements" as success.

Types

type DirtyError

type DirtyError struct{ Version uint64 }

DirtyError is returned when the ledger is dirty (a previous migration failed part-way). Resolve the database manually, then Force to the correct version.

func (*DirtyError) Error

func (e *DirtyError) Error() string

type Migration

type Migration struct {
	Version uint64
	Name    string
	Up      string
	Down    string
}

Migration is one versioned step. Down may be empty (irreversible).

func Load

func Load(fsys fs.FS) ([]Migration, error)

Load reads migrations from the root of fsys (e.g. an embed.FS subtree). It auto-detects three on-disk formats so adopters keep their history:

• golang-migrate split: NNN_name.up.sql / NNN_name.down.sql
• goose-annotated single file: -- +goose Up / -- +goose Down
• plain numbered single file: NNN_name.sql (up-only)

Returned migrations are sorted by version.

type Migrator

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

Migrator applies migrations against a session.

func New

func New(sess liteorm.Session, opts ...Option) *Migrator

New constructs a Migrator bound to sess.

func (*Migrator) Down

func (m *Migrator) Down(ctx context.Context, migs []Migration) error

Down rolls back the most recently applied migration (one step).

func (*Migrator) DownTo

func (m *Migrator) DownTo(ctx context.Context, migs []Migration, target uint64) error

DownTo rolls back every migration with version greater than target.

func (*Migrator) Force

func (m *Migrator) Force(ctx context.Context, version uint64) error

Force sets the ledger to version and clears the dirty flag (recovery).

func (*Migrator) Status

func (m *Migrator) Status(ctx context.Context, migs []Migration) ([]Status, error)

Status reports each migration and whether it has been applied.

func (*Migrator) Up

func (m *Migrator) Up(ctx context.Context, migs []Migration) (int, error)

Up applies every pending migration in version order.

func (*Migrator) UpTo

func (m *Migrator) UpTo(ctx context.Context, migs []Migration, target uint64) (int, error)

UpTo applies pending migrations up to and including target.

func (*Migrator) Version

func (m *Migrator) Version(ctx context.Context) (uint64, bool, error)

Version returns the current applied version and whether the ledger is dirty.

type Option

type Option func(*Migrator)

Option configures a Migrator.

func WithTable

func WithTable(name string) Option

WithTable overrides the ledger table name (default "schema_migrations").

type Status

type Status struct {
	Version uint64
	Name    string
	Applied bool
}

Status is a migration plus whether it has been applied.