migrate

Documentation

Overview

Package migrate applies versioned SQL migrations to a SQL database, safely.

Migrations are SQL files named NNNN_description.sql (the leading integer is the version). Each is applied once, in ascending order, in its own transaction, and recorded in a schema_migrations table. The design refuses to corrupt a store:

• Atomic: each migration runs in a transaction, so a failure leaves zero partial state (SQLite and Postgres both roll back DDL).
• Fail-closed: the first failure stops the run at the last good version.
• Forward-only: there are no down-migrations to run destructively in prod.
• Drift-detected: a SHA-256 of every applied migration is stored; if an already-applied file is later edited, the next run refuses to proceed.
• Order-checked: a new migration whose version sits below the latest applied one (an out-of-order insertion) is rejected rather than silently skipped.

The schema_migrations table is portable, so the same runner serves SQLite and (later) Postgres. Concurrency is guarded by the version primary key: two racing runs cannot both record the same migration; the loser fails safely.

Index

• func Run(ctx context.Context, db *sql.DB, fsys fs.FS) error
• type IncompatibleSchemaError
  • func (e *IncompatibleSchemaError) Error() string

Functions

func Run

func Run(ctx context.Context, db *sql.DB, fsys fs.FS) error

Run applies every migration in fsys not yet recorded in schema_migrations, in ascending version order, after verifying the integrity of those already applied. It is idempotent: once up to date, a re-run does nothing.

Types

type IncompatibleSchemaError

type IncompatibleSchemaError struct {
	Migration string // the offending migration file
	Reason    string // what is wrong with it
}

IncompatibleSchemaError reports that the database was created by a build whose migrations differ from this one's: an already-applied migration's bytes changed, or a new migration sorts below one already applied. The database cannot be migrated forward in place (migrations are immutable), so it must be recreated or a different data directory used. It is a distinct type so a caller can recognise this case and guide the user to recovery rather than surface a raw error.

func (*IncompatibleSchemaError) Error

func (e *IncompatibleSchemaError) Error() string