feat(migrate): add minimal golang-migrate compatible migration tool

Adds a migrate package that manages database migrations with the same
schema_migrations table layout as golang-migrate (latest version row +
dirty flag), so existing databases can be taken over as-is.

- migrate.Load reads <version>_<name>.up/down.sql files from any fs.FS
- migrate.New returns a Migrator with Up/Down/Drop/Version, serialized
  across processes via GET_LOCK
- migrate.Create generates a timestamped pair of empty migration files
- migrate.Cli is a thin CLI frontend for embedding in a user's main
- cmd/migrate is a ready-made command installable as a Go tool:
  go get -tool github.com/loilo-inc/exql/v3/cmd/migrate

Blank migration files are applied as no-ops, same as golang-migrate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: keroxp

cmd/migrate/main.go

@@ -0,0 +1,55 @@
+// Command migrate is a minimal database migration CLI compatible with
+// golang-migrate, built on the migrate package. Install it as a Go tool
+// and run it with go tool:
+//
+//	go get -tool github.com/loilo-inc/exql/v3/cmd/migrate
+//	go tool migrate -dsn "root:@tcp(127.0.0.1:3306)/app" up
+//	go tool migrate create add_users
+package main
+
+import (
+	"context"
+	"database/sql"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+
+	_ "github.com/go-sql-driver/mysql"
+	"github.com/loilo-inc/exql/v3/migrate"
+)
+
+func main() {
+	if err := run(context.Background(), os.Args[1:], os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(ctx context.Context, args []string, out io.Writer) error {
+	flags := flag.NewFlagSet("migrate", flag.ContinueOnError)
+	flags.SetOutput(out)
+	dsn := flags.String("dsn", "", "MySQL DSN. Append multiStatements=true to run migration files containing multiple statements.")
+	dir := flags.String("dir", "migrations", "directory containing migration files")
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+
+	cli := &migrate.Cli{Dir: *dir, Out: out}
+	cmd := flags.Args()
+	// create only generates files and does not need a database
+	if len(cmd) > 0 && cmd[0] != "create" {
+		if *dsn == "" {
+			return fmt.Errorf("-dsn is required")
+		}
+		db, err := sql.Open("mysql", *dsn)
+		if err != nil {
+			return err
+		}
+		defer db.Close()
+		cli.DB = db
+		cli.FS = os.DirFS(*dir)
+	}
+
+	return cli.Run(ctx, cmd...)
+}

cmd/migrate/main_test.go

@@ -0,0 +1,68 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"os"
+	"path/filepath"
+	"regexp"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRun(t *testing.T) {
+	ctx := context.Background()
+	t.Run("migrates a database from files in -dir", func(t *testing.T) {
+		root, err := sql.Open("mysql", "root:@tcp(127.0.0.1:13326)/")
+		require.NoError(t, err)
+		defer root.Close()
+		_, err = root.Exec("CREATE DATABASE IF NOT EXISTS exql_migrate_main")
+		require.NoError(t, err)
+		defer func() {
+			_, err := root.Exec("DROP DATABASE IF EXISTS exql_migrate_main")
+			require.NoError(t, err)
+		}()
+
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(
+			filepath.Join(dir, "1_create_users.up.sql"),
+			[]byte("create table users (id int not null primary key)"), 0644))
+		dsn := "root:@tcp(127.0.0.1:13326)/exql_migrate_main"
+
+		var out bytes.Buffer
+		assert.NoError(t, run(ctx, []string{"-dsn", dsn, "-dir", dir, "up"}, &out))
+		assert.Equal(t, "applying migration 1_create_users\n", out.String())
+
+		out.Reset()
+		assert.NoError(t, run(ctx, []string{"-dsn", dsn, "-dir", dir, "version"}, &out))
+		assert.Equal(t, "1\n", out.String())
+	})
+	t.Run("create works without -dsn", func(t *testing.T) {
+		dir := t.TempDir()
+		var out bytes.Buffer
+		assert.NoError(t, run(ctx, []string{"-dir", dir, "create", "add_users"}, &out))
+		entries, err := os.ReadDir(dir)
+		require.NoError(t, err)
+		require.Len(t, entries, 2)
+		assert.Regexp(t, regexp.MustCompile(`^\d{14}_add_users\.down\.sql$`), entries[0].Name())
+		assert.Regexp(t, regexp.MustCompile(`^\d{14}_add_users\.up\.sql$`), entries[1].Name())
+	})
+	t.Run("requires -dsn except for create", func(t *testing.T) {
+		var out bytes.Buffer
+		assert.EqualError(t, run(ctx, []string{"up"}, &out), "-dsn is required")
+	})
+	t.Run("rejects an unknown flag", func(t *testing.T) {
+		var out bytes.Buffer
+		err := run(ctx, []string{"-unknown"}, &out)
+		assert.Error(t, err)
+		assert.Contains(t, out.String(), "Usage of migrate:")
+	})
+	t.Run("prints usage without a subcommand", func(t *testing.T) {
+		var out bytes.Buffer
+		err := run(ctx, nil, &out)
+		assert.ErrorContains(t, err, "expects a subcommand")
+	})
+}

migrate/cli.go

@@ -0,0 +1,116 @@
+package migrate
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+)
+
+// Cli is a thin command-line frontend for the migration logic.
+// Embed your migration files and call Run from your main function:
+//
+//	//go:embed migrations/*.sql
+//	var migrationFS embed.FS
+//
+//	func main() {
+//		db, err := sql.Open("mysql", dsn)
+//		...
+//		sub, _ := fs.Sub(migrationFS, "migrations")
+//		cli := &migrate.Cli{DB: db, FS: sub, Dir: "migrations"}
+//		if err := cli.Run(context.Background(), os.Args[1:]...); err != nil {
+//			log.Fatal(err)
+//		}
+//	}
+type Cli struct {
+	// Database to migrate. Not required by the create command.
+	DB *sql.DB
+	// File system containing migration files at its root.
+	// Not required by the create command.
+	FS fs.FS
+	// @default "migrations"
+	// Directory where the create command puts new migration files.
+	Dir string
+	// @default os.Stdout
+	// Destination for command output.
+	Out io.Writer
+	// Options passed to New. Can be nil.
+	Options *Options
+}
+
+const usage = `usage: <command>
+
+commands:
+  up             apply all pending migrations
+  down           revert all applied migrations (destructive)
+  drop           drop all tables in the database (destructive)
+  version        print the current migration version
+  create <name>  create a new pair of migration files
+`
+
+// Run executes a subcommand: up, down, drop, version, or create.
+// The down and drop commands are destructive; guard them by environment
+// in your main function if necessary.
+func (c *Cli) Run(ctx context.Context, args ...string) error {
+	out := c.Out
+	if out == nil {
+		out = os.Stdout
+	}
+	if len(args) == 0 {
+		return fmt.Errorf("expects a subcommand\n%s", usage)
+	}
+
+	if args[0] == "create" {
+		if len(args) != 2 {
+			return fmt.Errorf("usage: create <name>")
+		}
+		dir := c.Dir
+		if dir == "" {
+			dir = "migrations"
+		}
+		paths, err := Create(dir, args[1])
+		if err != nil {
+			return err
+		}
+		for _, p := range paths {
+			fmt.Fprintln(out, p)
+		}
+		return nil
+	}
+
+	migrations, err := Load(c.FS)
+	if err != nil {
+		return err
+	}
+	opts := c.Options
+	if opts == nil {
+		opts = &Options{
+			Log: func(msg string) { fmt.Fprintln(out, msg) },
+		}
+	}
+	m := New(c.DB, migrations, opts)
+
+	switch args[0] {
+	case "up":
+		return m.Up(ctx)
+	case "down":
+		return m.Down(ctx)
+	case "drop":
+		return m.Drop(ctx)
+	case "version":
+		version, dirty, err := m.Version(ctx)
+		if err != nil {
+			return err
+		}
+		if dirty {
+			fmt.Fprintf(out, "%d (dirty)\n", version)
+		} else {
+			fmt.Fprintf(out, "%d\n", version)
+		}
+		return nil
+	default:
+		return fmt.Errorf("unknown command: %s\n%s", args[0], usage)
+	}
+}

migrate/cli_test.go

@@ -0,0 +1,84 @@
+package migrate
+
+import (
+	"bytes"
+	"context"
+	"path/filepath"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+var testCliFS = fstest.MapFS{
+	"1_create_users.up.sql":   {Data: []byte("create table users (id int not null primary key)")},
+	"1_create_users.down.sql": {Data: []byte("drop table users")},
+}
+
+func TestCli_Run(t *testing.T) {
+	ctx := context.Background()
+	t.Run("up, version, down and drop", func(t *testing.T) {
+		db := testDB(t, "exql_migrate_cli")
+		var out bytes.Buffer
+		cli := &Cli{DB: db, FS: testCliFS, Out: &out}
+
+		assert.NoError(t, cli.Run(ctx, "up"))
+		assert.Equal(t, "applying migration 1_create_users\n", out.String())
+		assert.Equal(t, []string{"schema_migrations", "users"}, tableNames(t, db))
+
+		out.Reset()
+		assert.NoError(t, cli.Run(ctx, "version"))
+		assert.Equal(t, "1\n", out.String())
+
+		assert.NoError(t, cli.Run(ctx, "down"))
+		assert.Equal(t, []string{"schema_migrations"}, tableNames(t, db))
+
+		assert.NoError(t, cli.Run(ctx, "drop"))
+		assert.Empty(t, tableNames(t, db))
+	})
+	t.Run("version reports dirty state", func(t *testing.T) {
+		db := testDB(t, "exql_migrate_cli_dirty")
+		broken := fstest.MapFS{
+			"1_broken.up.sql": {Data: []byte("alter table nonexistent add x int")},
+		}
+		var out bytes.Buffer
+		cli := &Cli{DB: db, FS: broken, Out: &out}
+		assert.ErrorContains(t, cli.Run(ctx, "up"), "migration 1_broken failed")
+
+		out.Reset()
+		assert.NoError(t, cli.Run(ctx, "version"))
+		assert.Equal(t, "1 (dirty)\n", out.String())
+	})
+	t.Run("create", func(t *testing.T) {
+		stubTimeNow(t, time.Date(2026, 7, 6, 12, 34, 56, 0, time.UTC))
+		dir := t.TempDir()
+		var out bytes.Buffer
+		// create does not require DB nor FS
+		cli := &Cli{Dir: dir, Out: &out}
+		assert.NoError(t, cli.Run(ctx, "create", "add_age"))
+		assert.Equal(t,
+			filepath.Join(dir, "20260706123456_add_age.up.sql")+"\n"+
+				filepath.Join(dir, "20260706123456_add_age.down.sql")+"\n",
+			out.String())
+
+		assert.EqualError(t, cli.Run(ctx, "create"), "usage: create <name>")
+		assert.EqualError(t, cli.Run(ctx, "create", "a", "b"), "usage: create <name>")
+	})
+	t.Run("create defaults to the migrations directory", func(t *testing.T) {
+		stubTimeNow(t, time.Date(2026, 7, 6, 12, 34, 56, 0, time.UTC))
+		dir := t.TempDir()
+		t.Chdir(dir)
+		require.NoError(t, (&Cli{Out: &bytes.Buffer{}}).Run(ctx, "create", "add_age"))
+		assert.FileExists(t, filepath.Join(dir, "migrations", "20260706123456_add_age.up.sql"))
+	})
+	t.Run("errors", func(t *testing.T) {
+		cli := &Cli{FS: testCliFS, Out: &bytes.Buffer{}}
+		assert.ErrorContains(t, cli.Run(ctx), "expects a subcommand")
+		assert.ErrorContains(t, cli.Run(ctx, "unknown"), "unknown command: unknown")
+
+		broken := &Cli{FS: fstest.MapFS{"1_a.down.sql": {Data: []byte("x")}}, Out: &bytes.Buffer{}}
+		assert.EqualError(t, broken.Run(ctx, "up"), "missing up migration for 1_a")
+	})
+}

migrate/create.go

@@ -0,0 +1,40 @@
+package migrate
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// for stubbing in tests
+var timeNow = time.Now
+
+// Create makes an empty pair of up/down migration files in dir, named
+// with the current timestamp as the version, and returns their paths.
+// dir is created if it does not exist. It fails if a file with the
+// same name already exists.
+func Create(dir string, name string) ([]string, error) {
+	if name == "" || filepath.Base(name) != name {
+		return nil, fmt.Errorf("invalid migration name: %q", name)
+	}
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return nil, err
+	}
+
+	version := timeNow().UTC().Format("20060102150405")
+	var paths []string
+	for _, direction := range []string{"up", "down"} {
+		path := filepath.Join(dir, fmt.Sprintf("%s_%s.%s.sql", version, name, direction))
+		f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644)
+		if err != nil {
+			return nil, err
+		}
+		if err := f.Close(); err != nil {
+			return nil, err
+		}
+		paths = append(paths, path)
+	}
+
+	return paths, nil
+}