feat(mymigrate): add MySQL/MariaDB backend for sqlmigrate

database/sqlmigrate/mymigrate/go.mod

@@ -0,0 +1,10 @@
+module github.com/therootcompany/golib/database/sqlmigrate/mymigrate
+
+go 1.26.1
+
+require (
+	github.com/go-sql-driver/mysql v1.9.3
+	github.com/therootcompany/golib/database/sqlmigrate v1.0.0
+)
+
+require filippo.io/edwards25519 v1.1.0 // indirect

database/sqlmigrate/mymigrate/go.sum

@@ -0,0 +1,6 @@
+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/therootcompany/golib/database/sqlmigrate v1.0.0 h1:vehFGUBdv/su0jDzSNxYN7N7i1KE3l2QJDf4x9LXhwQ=
+github.com/therootcompany/golib/database/sqlmigrate v1.0.0/go.mod h1:7PQUjwT78Hx+SftcIKI2PH4zSFlrSO0V9h618PJqC38=

database/sqlmigrate/mymigrate/mymigrate.go

@@ -0,0 +1,101 @@
+// Package mymigrate implements sqlmigrate.Migrator for MySQL and MariaDB
+// using database/sql with github.com/go-sql-driver/mysql.
+//
+// The *sql.DB must be opened with multiStatements=true in the DSN;
+// without it, multi-statement migration files will fail. New returns
+// an error if multi-statement support is not detected:
+//
+//	db, err := sql.Open("mysql", "user:pass@tcp(host:3306)/dbname?multiStatements=true")
+//
+// MySQL and MariaDB do not support transactional DDL. Statements like
+// CREATE TABLE and ALTER TABLE cause an implicit commit, so if a migration
+// fails partway through, earlier DDL statements in that migration will
+// already be committed. DML-only migrations are fully transactional.
+package mymigrate
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+
+	"github.com/go-sql-driver/mysql"
+
+	"github.com/therootcompany/golib/database/sqlmigrate"
+)
+
+// Migrator implements sqlmigrate.Migrator using a *sql.DB with MySQL/MariaDB.
+type Migrator struct {
+	DB *sql.DB
+}
+
+// New creates a Migrator from the given database handle.
+// Returns an error if the connection does not support multi-statement
+// queries (multiStatements=true must be set in the DSN).
+func New(db *sql.DB) (*Migrator, error) {
+	// Probe for multi-statement support. Without it, migration files
+	// that contain more than one statement silently execute only the first.
+	if _, err := db.Exec("DO 1; DO 1"); err != nil {
+		return nil, fmt.Errorf("mymigrate: connection requires multiStatements=true in DSN: %w", err)
+	}
+	return &Migrator{DB: db}, nil
+}
+
+var _ sqlmigrate.Migrator = (*Migrator)(nil)
+
+// ExecUp runs the up migration SQL in a transaction. DDL statements
+// (CREATE, ALTER, DROP) are implicitly committed by MySQL; see package docs.
+func (m *Migrator) ExecUp(ctx context.Context, mig sqlmigrate.Migration) error {
+	return m.exec(ctx, mig.Up)
+}
+
+// ExecDown runs the down migration SQL in a transaction. DDL statements
+// (CREATE, ALTER, DROP) are implicitly committed by MySQL; see package docs.
+func (m *Migrator) ExecDown(ctx context.Context, mig sqlmigrate.Migration) error {
+	return m.exec(ctx, mig.Down)
+}
+
+func (m *Migrator) exec(ctx context.Context, sqlStr string) error {
+	tx, err := m.DB.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("%w: begin: %w", sqlmigrate.ErrExecFailed, err)
+	}
+	defer tx.Rollback() //nolint:errcheck
+
+	if _, err := tx.ExecContext(ctx, sqlStr); err != nil {
+		return fmt.Errorf("%w: exec: %w", sqlmigrate.ErrExecFailed, err)
+	}
+
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("%w: commit: %w", sqlmigrate.ErrExecFailed, err)
+	}
+
+	return nil
+}
+
+// Applied returns all applied migrations from the _migrations table.
+// Returns an empty slice if the table does not exist (MySQL error 1146).
+func (m *Migrator) Applied(ctx context.Context) ([]sqlmigrate.AppliedMigration, error) {
+	rows, err := m.DB.QueryContext(ctx, "SELECT id, name FROM _migrations ORDER BY name")
+	if err != nil {
+		if mysqlErr, ok := errors.AsType[*mysql.MySQLError](err); ok && mysqlErr.Number == 1146 {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("%w: %w", sqlmigrate.ErrQueryApplied, err)
+	}
+	defer rows.Close()
+
+	var applied []sqlmigrate.AppliedMigration
+	for rows.Next() {
+		var a sqlmigrate.AppliedMigration
+		if err := rows.Scan(&a.ID, &a.Name); err != nil {
+			return nil, fmt.Errorf("%w: scanning row: %w", sqlmigrate.ErrQueryApplied, err)
+		}
+		applied = append(applied, a)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("%w: reading rows: %w", sqlmigrate.ErrQueryApplied, err)
+	}
+
+	return applied, nil
+}

database/sqlmigrate/sqlmigrate.go

@@ -50,10 +50,15 @@ type Status struct {
 
 // Migrator executes migrations. Implementations handle the
 // database-specific or output-specific details.
+//
+// Database backends should wrap each migration in a transaction when the
+// database supports transactional DDL (e.g. PostgreSQL). For databases
+// that do not (e.g. MySQL), the transaction provides atomicity for DML
+// only — DDL statements are implicitly committed by the engine.
 type Migrator interface {
 	// ExecUp runs the up migration. For database migrators this executes
-	// m.Up in a transaction. For shell migrators this outputs a command
+	// m.Up in a transaction (see package docs for DDL caveats). For shell
-	// referencing the .up.sql file.
+	// migrators this outputs a command referencing the .up.sql file.
 	ExecUp(ctx context.Context, m Migration) error
 
 	// ExecDown runs the down migration.