migrate

go-evolutionary-migrate

Lightweight SQLite migration runner that applies SQL files in lexicographic order and tracks progress using PRAGMA user_version.

Overview

A tiny, predictable migration runner for SQLite projects that prefer plain SQL files over full-featured migration tools.

It keeps ordering simple (lexicographic filenames) and tracks progress using SQLite's built-in PRAGMA user_version.

Inspiration

Evolutionary Database Design by Pramod Sadalage and Martin Fowler.

Usage

Imagine that you have SQL files for your migrations here:

your-module/
  migrations/
    001_init.sql
    002_add_users.sql

Embedded migrations (recommended)

The simplest way to store your migrations are within the Go binary itself. Run assumes that your *.sql files are at the root of the filesystem.

//go:embed migrations/*.sql
var embeddedMigrations embed.FS

migrationsFS, err := fs.Sub(embeddedMigrations, "migrations")
if err != nil {
  return err
}
if err := migrate.Run(ctx, db, migrationsFS); err != nil {
  return err
}

Path-based semantics

migrationsFS := os.DirFS("/path/to/migrations")
if err := migrate.Run(ctx, db, migrationsFS); err != nil {
  return err
}

Behavior

• Each file is executed as a single SQL statement.
• Files are applied in lexicographic order by filename.
• PRAGMA user_version is set to the 1-based index of the last applied migration.