migrate

Documentation

Overview

Package migrate applies SQLite schema migrations tracked in a database's PRAGMA user_version. Migration files are named NNNN_description.sql and are applied in ascending numeric order, starting after the current version. Each migration runs inside its own transaction: a failure rolls back that migration's statements and leaves user_version untouched, so a partially applied migration never appears successful.

Index

• Variables
• func Apply(ctx context.Context, db *sql.DB, source fs.FS) error
• func LatestVersion(source fs.FS) (int, error)

Variables

var ErrNoMigrations = errors.New("migrate: no migration files found")

ErrNoMigrations reports that source holds no migration files to apply.

Functions

func Apply

func Apply(ctx context.Context, db *sql.DB, source fs.FS) error

Apply loads the NNNN_description.sql migrations in source and runs every one whose version is greater than db's current user_version, in ascending order. Each migration commits its statements and the resulting user_version together, so a failure partway through leaves db exactly as it was before that migration started.

source must contain a migrations/ directory holding the .sql files; a source with no migrations/ directory, or one where it is empty, is an error (ErrNoMigrations) rather than a no-op. Any .sql file inside migrations/ whose name is not prefixed with a numeric NNNN version, or two files that share a version, fails the whole run.

The context bounds the whole run. A canceled context fails the run closed: the transaction of the migration in flight rolls back, so a canceled run never leaves a partially applied migration committed.

func LatestVersion

func LatestVersion(source fs.FS) (int, error)

LatestVersion returns the highest version among the migrations in source, so a consumer can assert the schema state it should land on without re-parsing the NNNN prefixes itself. It fails for the same reasons Apply does: no migration files, a malformed name, an unparsable version prefix, a duplicate version, or an unreadable file.