feat(sql-migrate/examples): add my-todos embedded migration runner

cmd/sql-migrate/examples/my-todos/.gitignore

@@ -0,0 +1,3 @@
+my-todos
+*.db
+.env

cmd/sql-migrate/examples/my-todos/demo.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"context"
+	"crypto/rand"
+	"database/sql"
+	"encoding/hex"
+	"fmt"
+	"strings"
+)
+
+func runAdd(ctx context.Context, db *sql.DB, args []string) error {
+	if len(args) == 0 {
+		return fmt.Errorf("add requires a title")
+	}
+
+	title := strings.Join(args, " ")
+	id := mustRandomHex(4)
+
+	_, err := db.ExecContext(
+		ctx,
+		"INSERT INTO todos (id, title) VALUES (?, ?)",
+		id,
+		title,
+	)
+	if err != nil {
+		return fmt.Errorf("creating todo: %w", err)
+	}
+
+	fmt.Printf("Created: %s  %s\n", id, title)
+	return nil
+}
+
+func runList(ctx context.Context, db *sql.DB, args []string) error {
+	rows, err := db.QueryContext(
+		ctx,
+		"SELECT id, title, status, completed_at, priority FROM todos ORDER BY created_at",
+	)
+	if err != nil {
+		return fmt.Errorf("listing todos: %w", err)
+	}
+	defer func() { _ = rows.Close() }()
+
+	count := 0
+	for rows.Next() {
+		var (
+			id          string
+			title       string
+			status      string
+			completedAt sql.NullTime
+			priority    int32
+		)
+		if err := rows.Scan(&id, &title, &status, &completedAt, &priority); err != nil {
+			return fmt.Errorf("scanning todo: %w", err)
+		}
+
+		displayStatus := status
+		if completedAt.Valid {
+			displayStatus = fmt.Sprintf("done %s", completedAt.Time.Format("2006-01-02"))
+		}
+		pri := ""
+		if priority > 0 {
+			pri = fmt.Sprintf(" [p%d]", priority)
+		}
+		fmt.Printf("  %s  %-10s %s%s\n", id, displayStatus, title, pri)
+		count++
+	}
+	if err := rows.Err(); err != nil {
+		return fmt.Errorf("reading todos: %w", err)
+	}
+
+	if count == 0 {
+		fmt.Println("No todos.")
+	}
+
+	return nil
+}
+
+func runDone(ctx context.Context, db *sql.DB, args []string) error {
+	if len(args) == 0 {
+		return fmt.Errorf("done requires a todo ID")
+	}
+
+	result, err := db.ExecContext(
+		ctx,
+		"UPDATE todos SET status = 'done', completed_at = NOW() WHERE id = ?",
+		args[0],
+	)
+	if err != nil {
+		return fmt.Errorf("marking done: %w", err)
+	}
+
+	n, _ := result.RowsAffected()
+	if n == 0 {
+		return fmt.Errorf("todo %q not found", args[0])
+	}
+
+	fmt.Printf("Done: %s\n", args[0])
+	return nil
+}
+
+func runRm(ctx context.Context, db *sql.DB, args []string) error {
+	if len(args) == 0 {
+		return fmt.Errorf("rm requires a todo ID")
+	}
+
+	result, err := db.ExecContext(
+		ctx,
+		"DELETE FROM todos WHERE id = ?",
+		args[0],
+	)
+	if err != nil {
+		return fmt.Errorf("deleting todo: %w", err)
+	}
+
+	n, _ := result.RowsAffected()
+	if n == 0 {
+		return fmt.Errorf("todo %q not found", args[0])
+	}
+
+	fmt.Printf("Deleted: %s\n", args[0])
+	return nil
+}
+
+func runSeed(ctx context.Context, db *sql.DB) error {
+	type seedTodo struct {
+		ID    string
+		Title string
+	}
+
+	todos := []seedTodo{
+		{ID: "seed0010", Title: "Review Q2 financial reports"},
+		{ID: "seed0011", Title: "Update SSL certificates"},
+		{ID: "seed0020", Title: "Deploy v2.3.1 to staging"},
+		{ID: "seed0021", Title: "Rotate API keys"},
+		{ID: "seed0022", Title: "Audit access logs"},
+	}
+
+	for _, t := range todos {
+		_, err := db.ExecContext(
+			ctx,
+			"INSERT IGNORE INTO todos (id, title) VALUES (?, ?)",
+			t.ID,
+			t.Title,
+		)
+		if err != nil {
+			return fmt.Errorf("seeding todo %q: %w", t.Title, err)
+		}
+		fmt.Printf("  Todo:   %s  %s\n", t.ID, t.Title)
+	}
+
+	// Mark two as done
+	for _, id := range []string{"seed0010", "seed0011"} {
+		_, err := db.ExecContext(
+			ctx,
+			"UPDATE todos SET status = 'done', completed_at = NOW() WHERE id = ? AND status != 'done'",
+			id,
+		)
+		if err != nil {
+			return fmt.Errorf("seeding mark done %s: %w", id, err)
+		}
+	}
+
+	fmt.Println("Seed complete.")
+	return nil
+}
+
+func mustRandomHex(n int) string {
+	b := make([]byte, n)
+	if _, err := rand.Read(b); err != nil {
+		panic(err)
+	}
+	return hex.EncodeToString(b)
+}

cmd/sql-migrate/examples/my-todos/go.mod

@@ -0,0 +1,12 @@
+module github.com/therootcompany/golib/cmd/sql-migrate/examples/my-todos
+
+go 1.26.1
+
+require (
+	github.com/go-sql-driver/mysql v1.9.3
+	github.com/joho/godotenv v1.5.1
+	github.com/therootcompany/golib/database/sqlmigrate v1.0.2
+	github.com/therootcompany/golib/database/sqlmigrate/mymigrate v1.0.2
+)
+
+require filippo.io/edwards25519 v1.1.0 // indirect

cmd/sql-migrate/examples/my-todos/go.sum

@@ -0,0 +1,10 @@
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo=
+github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
+github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
+github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+github.com/therootcompany/golib/database/sqlmigrate v1.0.2 h1:hcmhYyUFVj/GqyChP+0Ry2WZCHnoruFMbsy+2KVzsfA=
+github.com/therootcompany/golib/database/sqlmigrate v1.0.2/go.mod h1:7PQUjwT78Hx+SftcIKI2PH4zSFlrSO0V9h618PJqC38=
+github.com/therootcompany/golib/database/sqlmigrate/mymigrate v1.0.2 h1:VLJbyDrACQYISfFLMZHn5b8Q8ywVjswtDjy+8Et8HBY=
+github.com/therootcompany/golib/database/sqlmigrate/mymigrate v1.0.2/go.mod h1:zr+08WaGE+2V1dgrDUzrST7EuiJ4L+0XNNyMpqdl9CE=

cmd/sql-migrate/examples/my-todos/main.go

@@ -0,0 +1,226 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"embed"
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"strconv"
+
+	_ "github.com/go-sql-driver/mysql"
+	"github.com/joho/godotenv"
+
+	"github.com/therootcompany/golib/database/sqlmigrate"
+	"github.com/therootcompany/golib/database/sqlmigrate/mymigrate"
+)
+
+const version = "0.1.0"
+
+//go:embed sql/migrations/*.sql
+var migrationsFS embed.FS
+
+func main() {
+	_ = godotenv.Load()
+
+	if len(os.Args) > 1 {
+		switch os.Args[1] {
+		case "-V", "-version", "--version", "version":
+			printVersion(os.Stdout)
+			os.Exit(0)
+		case "help", "-help", "--help":
+			printVersion(os.Stdout)
+			fmt.Fprintln(os.Stdout, "")
+			printUsage(os.Stdout)
+			os.Exit(0)
+		}
+	}
+
+	fs := flag.NewFlagSet("my-todos", flag.ContinueOnError)
+	fs.Usage = func() { printUsage(os.Stderr) }
+	if err := fs.Parse(os.Args[1:]); err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			os.Exit(0)
+		}
+		os.Exit(1)
+	}
+
+	args := fs.Args()
+	if len(args) == 0 {
+		printVersion(os.Stdout)
+		fmt.Fprintln(os.Stdout, "")
+		printUsage(os.Stdout)
+		os.Exit(0)
+	}
+
+	ctx := context.Background()
+
+	myURL := os.Getenv("MY_URL")
+	if myURL == "" {
+		fmt.Fprintf(os.Stderr, "Error: MY_URL environment variable is required\n")
+		os.Exit(1)
+	}
+
+	db, err := sql.Open("mysql", myURL)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: connecting to database: %v\n", err)
+		os.Exit(1)
+	}
+	defer func() { _ = db.Close() }()
+
+	migrations := mustCollectMigrations()
+	runner := mymigrate.New(db)
+
+	subcmd := args[0]
+	subArgs := args[1:]
+
+	switch subcmd {
+	case "migrate":
+		err = runMigrate(ctx, runner, migrations, subArgs)
+	case "add":
+		autoMigrate(ctx, runner, migrations)
+		err = runAdd(ctx, db, subArgs)
+	case "list":
+		autoMigrate(ctx, runner, migrations)
+		err = runList(ctx, db, subArgs)
+	case "done":
+		autoMigrate(ctx, runner, migrations)
+		err = runDone(ctx, db, subArgs)
+	case "rm":
+		autoMigrate(ctx, runner, migrations)
+		err = runRm(ctx, db, subArgs)
+	case "seed":
+		autoMigrate(ctx, runner, migrations)
+		err = runSeed(ctx, db)
+	default:
+		fmt.Fprintf(os.Stderr, "Unknown command: %s\n\n", subcmd)
+		printUsage(os.Stderr)
+		os.Exit(1)
+	}
+
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func mustCollectMigrations() []sqlmigrate.Script {
+	migrations, err := sqlmigrate.Collect(migrationsFS, "sql/migrations")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: collecting migrations: %v\n", err)
+		os.Exit(1)
+	}
+	return migrations
+}
+
+func autoMigrate(ctx context.Context, runner sqlmigrate.Migrator, migrations []sqlmigrate.Script) {
+	if _, err := sqlmigrate.Latest(ctx, runner, migrations); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: auto-migrate: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func printVersion(w *os.File) {
+	fmt.Fprintf(w, "my-todos v%s\n", version)
+}
+
+func printUsage(w *os.File) {
+	fmt.Fprintln(w, `USAGE
+   my-todos <command> [args]
+
+COMMANDS
+   migrate up [n]      apply pending migrations (all by default)
+   migrate down [n]    roll back migrations (1 by default)
+   migrate status      show applied and pending migrations
+   migrate reset       drop all tables (rollback all migrations)
+
+   seed                insert deterministic test data (idempotent)
+
+   add <title>         create a new todo
+   list                list todos
+   done <id>           mark a todo as done
+   rm <id>             delete a todo
+
+ENVIRONMENT
+   MY_URL              MySQL/MariaDB DSN (loaded from .env)`)
+}
+
+func runMigrate(ctx context.Context, runner sqlmigrate.Migrator, migrations []sqlmigrate.Script, args []string) error {
+	if len(args) == 0 {
+		return fmt.Errorf("migrate requires a subcommand: up, down, status, or reset")
+	}
+
+	switch args[0] {
+	case "up":
+		n := -1
+		if len(args) > 1 {
+			var err error
+			n, err = strconv.Atoi(args[1])
+			if err != nil || n < 0 {
+				return fmt.Errorf("%q is not a valid count", args[1])
+			}
+		}
+		applied, err := sqlmigrate.Up(ctx, runner, migrations, n)
+		if len(applied) == 0 && err == nil {
+			fmt.Println("Already up-to-date.")
+		} else if err == nil {
+			fmt.Printf("Applied %d migration(s).\n", len(applied))
+			for _, m := range applied {
+				fmt.Printf("   %s\n", m.Name)
+			}
+		}
+		return err
+
+	case "down":
+		n := 1
+		if len(args) > 1 {
+			var err error
+			n, err = strconv.Atoi(args[1])
+			if err != nil || n < 0 {
+				return fmt.Errorf("%q is not a valid count", args[1])
+			}
+		}
+		rolled, err := sqlmigrate.Down(ctx, runner, migrations, n)
+		if len(rolled) == 0 && err == nil {
+			fmt.Println("No migrations to roll back.")
+		} else if err == nil {
+			fmt.Printf("Rolled back %d migration(s).\n", len(rolled))
+			for _, m := range rolled {
+				fmt.Printf("   %s\n", m.Name)
+			}
+		}
+		return err
+
+	case "status":
+		status, err := sqlmigrate.GetStatus(ctx, runner, migrations)
+		if err != nil {
+			return err
+		}
+		fmt.Printf("Applied: %d\n", len(status.Applied))
+		for _, m := range status.Applied {
+			fmt.Printf("   %s\n", m.Name)
+		}
+		fmt.Printf("\nPending: %d\n", len(status.Pending))
+		for _, m := range status.Pending {
+			fmt.Printf("   %s\n", m.Name)
+		}
+		return nil
+
+	case "reset":
+		rolled, err := sqlmigrate.Drop(ctx, runner, migrations)
+		if len(rolled) == 0 && err == nil {
+			fmt.Println("Nothing to reset.")
+		} else if err == nil {
+			fmt.Printf("Reset: rolled back %d migration(s).\n", len(rolled))
+			for _, m := range rolled {
+				fmt.Printf("   %s\n", m.Name)
+			}
+		}
+		return err
+
+	default:
+		return fmt.Errorf("unknown migrate subcommand: %s (use up, down, status, or reset)", args[0])
+	}
+}

cmd/sql-migrate/examples/my-todos/sql/migrations/0001-01-01-001000_init-migrations.down.sql

@@ -0,0 +1,5 @@
+-- init-migrations (down)
+
+DELETE FROM _migrations WHERE id = '00000001';
+
+DROP TABLE IF EXISTS _migrations;

cmd/sql-migrate/examples/my-todos/sql/migrations/0001-01-01-001000_init-migrations.up.sql

@@ -0,0 +1,10 @@
+-- init-migrations (up)
+
+CREATE TABLE IF NOT EXISTS _migrations (
+   id CHAR(8) PRIMARY KEY,
+   name VARCHAR(80) NULL UNIQUE,
+   applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- leave this as the last line
+INSERT INTO _migrations (name, id) VALUES ('0001-01-01-001000_init-migrations', '00000001');

cmd/sql-migrate/examples/my-todos/sql/migrations/2026-04-05-001000_create-todos.down.sql

@@ -0,0 +1,6 @@
+-- create-todos (down)
+
+DROP TABLE IF EXISTS todos;
+
+-- leave this as the last line
+DELETE FROM _migrations WHERE id = 'a1b2c3d4';

cmd/sql-migrate/examples/my-todos/sql/migrations/2026-04-05-001000_create-todos.up.sql

@@ -0,0 +1,12 @@
+-- create-todos (up)
+
+CREATE TABLE todos (
+   id CHAR(8) PRIMARY KEY,
+   title VARCHAR(255) NOT NULL,
+   status VARCHAR(20) NOT NULL DEFAULT 'pending',
+   created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+   updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+-- leave this as the last line
+INSERT INTO _migrations (name, id) VALUES ('2026-04-05-001000_create-todos', 'a1b2c3d4');

cmd/sql-migrate/examples/my-todos/sql/migrations/2026-04-05-002000_add-todo-fields.down.sql

@@ -0,0 +1,7 @@
+-- add-todo-fields (down)
+
+ALTER TABLE todos DROP COLUMN priority;
+ALTER TABLE todos DROP COLUMN completed_at;
+
+-- leave this as the last line
+DELETE FROM _migrations WHERE id = 'd4e5f6a7';

cmd/sql-migrate/examples/my-todos/sql/migrations/2026-04-05-002000_add-todo-fields.up.sql

@@ -0,0 +1,7 @@
+-- add-todo-fields (up)
+
+ALTER TABLE todos ADD COLUMN completed_at TIMESTAMP NULL DEFAULT NULL;
+ALTER TABLE todos ADD COLUMN priority INTEGER NOT NULL DEFAULT 0;
+
+-- leave this as the last line
+INSERT INTO _migrations (name, id) VALUES ('2026-04-05-002000_add-todo-fields', 'd4e5f6a7');