{"slug": "go-migrate-sql-migrations-with-one-use-approvals-for-ai-agents", "title": "Go-migrate – SQL migrations with one-use approvals for AI agents", "summary": "Go-Gen-Ecosystem released go-migrate v1.0.1, a standalone CLI and embeddable Go library for versioned SQL migrations that adds an `--expect-plan` flag requiring a reviewed SQL plan ID, bound to the database and schema, before deployment. In the project's benchmark of 100 migrations against a fresh SQLite database using `modernc.org/sqlite v1.62.0`, go-migrate allocated 727.8 KiB per batch versus 10.66 MiB for golang-migrate v4.20.1 and 1.14 MiB for goose v3.30.1. The release supports PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Oracle Database and IBM Db2 LUW, and bundles an MCP server for automation.", "body_md": "Run versioned SQL migrations from a standalone CLI, or embed the runner in a Go application. go-migrate supports PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Oracle Database and IBM Db2 LUW. Preview the SQL, then require its plan ID at deployment to check the plan, database and schema under the migration lock.\n\n```\ngo install github.com/go-gen-ecosystem/go-migrate/cmd/gomigrate@latest\n```\n\nThe table compares built-in capabilities in three pinned releases. A dash means we found no built-in equivalent for that row.\n\n| Capability | go-migrate v1.0.1 | golang-migrate v4.20.1 | goose v3.30.1 | \n|---|---|---|---|\n| Versioned SQL migrations | Yes | Yes | Yes | \n| SQL and registered Go functions in one version sequence | Library or custom binary | — | Library or custom binary | \n| Apply missing versions out of order | Opt-in | — | Opt-in | \n| Substitution inside SQL | Configured placeholders | — | Opt-in `ENVSUB` | \n| Read migrations directly from Amazon S3 in the stock CLI | — | Yes | — | \n| SQLite without CGO on Linux amd64 | Stock build | Custom build with the `sqlite` driver | Stock build | \n| Detect edits to applied versioned Up SQL by checksum | Yes | — | — | \n| Repeat SQL when its checksum changes | Yes | — | Unversioned mode reruns files without a checksum check | \n| Migration selection | Contexts, labels, preconditions and rollback tags | Target version or step count | Provider can exclude versions or filenames | \n| Named SQL callbacks around an Up run | Yes | — | — | \n| Require a reviewed SQL plan bound to the database and schema | `--expect-plan` | — | — | \n| Offline SQL risk linting | Rules vary by dialect | — | `validate` checks migration structure | \n| Cross-process locking | Engine-specific, including a file lock for disk-backed SQLite | Native locks on PostgreSQL, MySQL and SQL Server. SQLite guard is per driver instance | Opt-in provider locks, including PostgreSQL and MySQL | \n| Automation | CLI JSON results, error codes and bundled MCP server | Typed library errors and logger interface | Typed provider results, partial errors and structured logging | \n\nFor transactional SQL migrations on PostgreSQL, SQLite and SQL Server, go-migrate and goose can commit the change and its history row in the same transaction. golang-migrate records a dirty version, executes the migration, then marks the version clean separately. Its `force V` command lets an operator set the version and clear dirty state after checking the database. [go-migrate execution](https://github.com/Go-Gen-Ecosystem/go-migrate/blob/v1.0.1/apply.go) · [golang-migrate execution and recovery](https://github.com/golang-migrate/migrate/blob/v4.20.1/migrate.go) · [goose transactional SQL](https://github.com/pressly/goose/blob/v3.30.1/migration_sql.go)\n\nPackaging and feature comparisons use the tagged source and build configuration. [golang-migrate release drivers](https://github.com/golang-migrate/migrate/blob/v4.20.1/Makefile) · [goose SQL annotations](https://github.com/pressly/goose/blob/v3.30.1/README.md) · [goose SQLite driver](https://github.com/pressly/goose/blob/v3.30.1/cmd/goose/driver_sqlite3.go) · [goose release build](https://github.com/pressly/goose/blob/v3.30.1/.goreleaser.yaml)\n\nEach operation constructs a library runner and applies 100 migrations to a fresh SQLite database. Each migration creates a table and inserts one row. All three use the same SQL bodies and pure-Go driver (`modernc.org/sqlite v1.62.0`), with WAL and `synchronous=OFF`. The table shows medians of six samples per configuration on Linux/amd64, Go 1.26.11, Intel Core Ultra 9 285HX. B/op is cumulative Go heap allocation per batch. [Benchmark source](https://github.com/Go-Gen-Ecosystem/go-migrate/blob/v1.0.1/benchmarks/compare/compare_test.go)\n\n| Library configuration | Allocated per batch | Allocations per batch | \n|---|---|---|\n| go-migrate v1.0.1, default | 727.8 KiB | 10,873.5 | \n| golang-migrate v4.20.1, default | 10.66 MiB | 9,420 | \n| goose v3.30.1, default | 1.14 MiB | 8,547 | \n| golang-migrate v4.20.1, 4 KiB buffer | 892.2 KiB | 9,361 | \n\nAt defaults, go-migrate allocated the fewest bytes and goose made the fewest allocations. The golang-migrate result was sensitive to its 100,000-byte buffer per migration. The fourth row changes only that setting. Larger SQL files, remote sources and durable storage are different workloads. [golang-migrate buffer implementation](https://github.com/golang-migrate/migrate/blob/v4.20.1/migration.go)\n\n## Samples and reproduction\n\nEach column lists bytes allocated per batch for the six samples, in execution order.\n\n| Sample | go-migrate | golang-migrate | goose | golang-migrate, 4 KiB | \n|---|---|---|---|---|\n| 1 | 754,551 | 11,181,571 | 1,194,601 | 918,816 | \n| 2 | 744,524 | 11,180,188 | 1,194,292 | 911,948 | \n| 3 | 747,631 | 11,182,817 | 1,194,418 | 913,354 | \n| 4 | 742,457 | 11,181,530 | 1,194,792 | 916,509 | \n| 5 | 743,558 | 11,180,337 | 1,194,205 | 913,784 | \n| 6 | 745,914 | 11,180,937 | 1,194,240 | 912,850 | \n\nStart in a disposable checkout of `v1.0.1`. Go 1.26.11 needs to refresh the tagged benchmark module's `go.mod` and `go.sum`, which is why the command uses `-mod=mod`.\n\n```\ncd benchmarks/compare\nGOWORK=off CGO_ENABLED=0 GOTOOLCHAIN=go1.26.11 go test -mod=mod -run '^$' -bench '^BenchmarkUp100_' -benchmem -count=6 .\n```\n\nFor the fourth row, add these lines at the start of `BenchmarkUp100_GolangMigrate` in that checkout and repeat the command with `-bench '^BenchmarkUp100_GolangMigrate$'`.\n\n```\nold := gm.DefaultBufferSize\ngm.DefaultBufferSize = 4096\ndefer func() { gm.DefaultBufferSize = old }()\ngomigrate init                       # .gomigrate.yaml + migrations/\ngomigrate create add_users           # migrations/20261116120000_add_users.sql\ngomigrate lint                       # risky SQL? (no database needed)\ngomigrate up --sql                   # dry run: the exact SQL that would run, and its plan ID\ngomigrate up --expect-plan <id>      # apply exactly the reviewed plan, or fail with plan_changed\ngomigrate status                     # table; -o json for scripts\ngomigrate down                       # roll back the last one (--steps, --to, --to-tag, --all)\n-- +migrate Up\nCREATE TABLE users (id INTEGER PRIMARY KEY, email VARCHAR(255) NOT NULL UNIQUE);\n\n-- +migrate Down\nDROP TABLE users;\njs\n//go:embed migrations\nvar migrations embed.FS\n\ndir, _ := fs.Sub(migrations, \"migrations\")\nm, err := migrate.New(db, \"postgres\", migrate.WithFS(dir)) // malformed files fail here, not mid-run\nif err != nil {\n\treturn err\n}\n_, err = m.Up(ctx)\n```\n\n- **Migrator methods:**  - apply and roll back: `Up` ,`UpTo` ,`Down(ctx, migrate.DownTarget{Steps: 1})` (or`To: \"3\"` , or`Tag: \"v1\"` ),`Redo` ;\n  - read-only: `Plan` ,`PlanDown` ,`PlanRepair` ,`PlanID` ,`Statements` ,`Callbacks` ,`Status` ,`Validate` ,`Lint` ,`Migrations` ;\n  - history administration: `Repair(ctx, migrate.RepairTarget{Migration: \"3\", Action: migrate.RepairClearFailed})` ,`MarkApplied` ,`Baseline` ,`Tag` . To accept deliberate checksum drift, use`migrate.RepairAcceptChecksum` for that version. Bare`Repair(ctx)` returns`ErrInvalidArgument` and changes nothing.\n- apply and roll back: \n- **Approved plans:**`m.Up(ctx, migrate.ExpectPlan(id))` runs only if the plan, computed again under the lock, still has the ID that was reviewed; otherwise it fails with`ErrPlanChanged` and runs nothing.\n- **Options:**  - `WithFS` ,`WithGoMigrations` ,`WithTable` ,`WithLockWait` ;\n  - `WithLogger` ([halolog](https://github.com/go-gen-ecosystem/halolog) );\n  - `WithPlaceholders` ,`WithContexts` ,`WithLabels` ,`WithBaselineOnMigrate` ;\n  - `WithAllowOutOfOrder` ,`WithAllowMissing` ,`WithHooks` ,`WithInstalledBy` .\n- **Without a database:**`migrate.Lint(dialect, opts...)` analyzes migrations with no connection.\n- **Errors:** every error works with`errors.Is` , and`migrate.ErrorCodes(err)` gives stable codes.\n- **Concurrency:** a`Migrator` is immutable after`New` and safe for concurrent use.\n\n| File | Meaning | \n|---|---|\n| `001_users.sql` ,`V1.2__index.sql` | Versioned SQL with `-- +migrate Up` and`Down` markers. Also accepts goose`Up` ,`Down` ,`StatementBegin` ,`StatementEnd` and`NO TRANSACTION` annotations. | \n| `2024…_seed.up.sql` +`.down.sql` | versioned pair (golang-migrate layout) | \n| `R__views.sql` | repeatable: re-applied whenever it changes, and after rollbacks | \n| `beforeMigrate.sql` ,`afterEachMigrate__x.sql` , … | SQL callbacks (Flyway names) | \n\nDirectives:\n\n```\n-- +migrate Up notransaction                   -- e.g. CREATE INDEX CONCURRENTLY\n-- +migrate Context dev,test                   -- run only with --context dev or test\n-- +migrate Labels billing                     -- run only with --label billing\n-- +migrate DBMS postgres                      -- run only on PostgreSQL\n-- +migrate RunAlways                          -- repeatable: run on every up\n-- +migrate Precondition onFail=MARK_RAN expect=0 SELECT COUNT(*) FROM information_schema.tables WHERE table_name = 'legacy'\n-- +migrate Lint ignore=drop-table             -- accept a reviewed lint finding\n-- +migrate StatementBegin / StatementEnd      -- keep a block as one statement\n```\n\nSupporting rules:\n\n- **Placeholders:**`${name}` is replaced from`--placeholder name=value` or the`placeholders:` config. Built-ins are`${migrate:dialect}` ,`${migrate:table}` and`${migrate:user}` .\n- **Versions** compare numerically:`9 < 10` ,`1.9 < 1.10` ,`001 == 1 == 1.0` .\n- **SQL checksums** cover the Up section. They normalize line endings, a leading BOM and insignificant whitespace outside literals, and preserve statement-block boundaries.\n- **Preconditions:**`HALT` fails the run,`MARK_RAN` records the migration without running it, and`CONTINUE` leaves it pending. Plans flag such migrations as`conditional` .\n- **Callbacks** appear in`--sql` plans (they run even when nothing is pending), are covered by the plan ID and are linted.\n\nUse `sqlserver` as the dialect or a `sqlserver://` URL in `GOMIGRATE_DSN`. A library\ncaller opens its `*sql.DB` using the `sqlserver` driver registered by\n`github.com/microsoft/go-mssqldb`. The CLI includes that driver and remains CGO-free.\nChoose the target database with the URL's `database` parameter or the YAML\n`database.name` field. The CLI enables TLS and verifies the server certificate by\ndefault. Supply driver TLS options via the URL or `database.params`. A disposable\nlocal fixture with a self-signed certificate can set `trustservercertificate=true`.\n\nEach migration direction runs as a T-SQL batch by default. Put `GO` on its own\nline to begin a new batch. A trailing `--` comment is allowed. `GO` inside a\nquoted identifier, string, or block comment stays in the SQL. Use separate\nbatches when a statement such as `CREATE PROCEDURE` must be first in its batch.\n`GO N` repetition and SQLCMD commands such as `:r` are outside the supported\nscript format. `StatementBegin`/` StatementEnd` can also set explicit batch\nboundaries. The text dry run prints `GO` between batches and the JSON plan lists\nthe exact payload of each batch.\n\nSQL Server 2022 is the conformance target. The migration login needs access to\nthe configured history schema and permission to create and modify history and\napplication objects there. An unqualified history table uses the login's default\nschema. See [the SQL Server example](https://github.com/Go-Gen-Ecosystem/go-migrate/blob/main/examples/sqlserver).\n\nUse the `oracle` dialect or an `oracle://user:password@host:port/service` URL in\n`GOMIGRATE_DSN`. The YAML `database.name` field identifies the Oracle service.\nThe CLI bundles Oracle's native-Go `oracledb` driver and uses password\nauthentication. The driver requires Go 1.26.9 and keeps the CLI CGO-free.\nLibrary callers can register and open `oracledb` themselves through `database/sql`.\nThe driver is distributed under the [Universal Permissive License 1.0](https://github.com/oracle/go-oracledb/blob/v26.4.0/LICENSE.txt).\n\nThe CLI selects TCPS on port 2484 by default and requests certificate-chain and\nserver-identity verification. Set `wallet_location` or `ssl_server_cert_dn` as\nneeded through the URL or `database.params`. An isolated Oracle Free test instance\ncan use `protocol=tcp` to connect on port 1521. The conformance fixture uses\npassword authentication over TCP on a private network. It targets Oracle AI\nDatabase 26ai Free and connects to the `FREEPDB1` service.\n\nA history table with no explicit schema uses the session's initial current\nschema. The tool folds ordinary configured identifiers to uppercase as Oracle\ndoes for unquoted names. The migration user needs permission to create and\nmodify its history and application objects and an `EXECUTE` grant on\n`SYS.DBMS_LOCK`. Oracle releases the migration lock when the physical session\nends. Use a driver configuration that fails the run on session loss.\n\nOrdinary SQL uses semicolon separators. Wrap Oracle PL/SQL blocks and stored\nroutines in `-- +migrate StatementBegin` and `-- +migrate StatementEnd`. Keep the\nfinal `END;` and omit the SQL*Plus slash command. Oracle `q'[...]'` and `nq'[...]'`\nliterals can contain semicolons and newlines. See [the Oracle example](https://github.com/Go-Gen-Ecosystem/go-migrate/blob/main/examples/oracle).\n\nUse the `db2` dialect or a `db2://user:password@host:port/database` URL in\n`GOMIGRATE_DSN`. The CLI bundles the independent, MIT-licensed\n[go-db2 driver](https://github.com/go-db2/go-db2) and remains CGO-free. Library\ncallers can register the `db2` driver and supply a `database/sql` pool. The\nconformance target is IBM Db2 Community Edition 12.1.5.0 on Linux x86-64\nwith the default database collation.\n\nThe CLI enables certificate-verified TLS and defaults to port 50001. Provide\nthe instance's TLS listener port and `ssl_ca` if you use a private CA (`tls` and\n`ssl_ca` can also be set in `database.params`). An isolated fixture can opt in to\nunencrypted TCP with `tls=false&allow_plaintext_auth=true`. The CLI supports\nusername and password authentication.\n\nDb2 history identifiers use uppercase names for ordinary unquoted identifiers.\nAn unqualified history table uses the initial current schema. The migration\nlogin needs permission to create and modify its history and application objects\nand `EXECUTE` on the `SYSIBMADM.DBMS_LOCK` module. Use Db2 LUW 12.1.3 or newer\nwith the Db2 native `DBMS_LOCK` module installed. Regular schema migrations run\nin a transaction. Use `notransaction` for statements that cannot run in one.\nWrap Db2 SQL PL routines or compound statements in `StatementBegin` and\n`StatementEnd`. Keep the semicolons inside the block and omit CLP terminators\nsuch as `@`. See [the Db2 example](https://github.com/Go-Gen-Ecosystem/go-migrate/blob/main/examples/db2).\n\n- **Locking:** a cross-process lock scoped to the configured migration history.\n  - PostgreSQL and MySQL: `pg_advisory_lock` /`GET_LOCK` , which the server releases if the process dies.\n  - SQL Server: a session-owned `sp_getapplock` per database. Distinct history tables in the same database share that lock so aliases of a table under a case-insensitive or accent-insensitive collation cannot bypass it.\n  - Oracle: an exclusive `DBMS_LOCK` session lock per schema and history table that survives Oracle DDL commits.\n  - Db2: a numeric `SYSIBMADM.DBMS_LOCK` session lock derived from the schema and history table. Db2 keeps the lock across commits and releases it when the session ends. Histories that hash to the same ID serialize.\n  - SQLite: a run-lifetime OS lock on `<database>.gomigrate-<history-table>.lock` beside the database file, with a fenced lease row. The containing directory must allow creation of that coordination file, and each migrator must be able to open it. Keep the file in place while any migrator might use it. In-memory SQLite databases coordinate within the process.\n  - After a SQLite process exits, the OS lock is released and an abandoned lease can be reclaimed once it expires. Drain older versions before rolling out the SQLite lock change so all running migrators use the same coordination protocol.\n  - Ten replicas can run `up` at boot, and each migration still runs exactly once.\n- PostgreSQL and MySQL: \n- **One connection per run.**  - All statements run on the lock's connection, so one-connection pools work.\n  - If the session is lost, the run fails instead of continuing unprotected.\n  - History writes use the schema selected before the run. SQL Server also qualifies them with the starting database, so `SET search_path` or`USE` in a migration cannot redirect history writes.\n  - Session-lock connections are discarded afterwards, never returned to the pool.\n- **Atomicity.**  - PostgreSQL, SQLite, SQL Server and Db2 normally commit each migration with its history row. Mark SQL Server statements that require autocommit, such as `CREATE DATABASE` , with`notransaction` .\n  - MySQL, Oracle, and migrations marked `notransaction` commit a dirty row first. Oracle DDL commits implicitly. A partial failure blocks further runs. Restore the schema by hand, then use`repair MIGRATION --clear-failed` if you undid the change, or`mark-applied VERSION` if you completed the versioned migration.\n  - Run-level SQL callbacks (`beforeMigrate` ,`afterMigrate` ,`afterMigrateError` ) run on the same session as the migrations, outside their transactions. Before the first callback runs, go-migrate commits a recovery marker. It clears the marker only after the whole run succeeds. An interrupted run can leave committed callback effects even if no migrations were pending. While the marker remains,`status` reports`callback_recovery_required` separately from migration rows, and`validate` ,`up` ,`down` and`redo` report that recovery is required. Successful runs can run the callbacks again on the next`up` .\n- PostgreSQL, SQLite, SQL Server and Db2 normally commit each migration with its history row. Mark SQL Server statements that require autocommit, such as \n- **Validation before execution:** drift, missing and out-of-order migrations, unknown targets, the baseline floor and irreversible rollbacks are all checked before any SQL runs.\n- **Approval binds execution to the target:** CLI and MCP plan IDs cover the resolved database, history table, active schema or search path, and the exact plan (including callbacks and any automatic baseline).`--expect-plan` (CLI) and`plan_id` (MCP) check the approval under the migration lock before changing history or running migration SQL. Reissue IDs from older releases. Library callers can opt into the same check with`PlanWithID` or`PlanDownWithID` and`ExpectTargetPlan` ;`PlanID` and`ExpectPlan` still check plan content only.\n- **Approval scope:** IDs use metadata from the live session and the configured network route. A PostgreSQL restart requires a fresh plan. SQLite binds canonical file paths and ordered attachment names; it cannot detect a file replaced at the same path. Re-plan after replacing a file. In-memory or temporary SQLite targets cannot receive a target-bound ID.\n- **Read-only means read-only:**`status` ,`validate` ,`lint` and dry runs never create tables.\n- **No connection secrets in output:** DSNs and passwords never appear in errors or logs. Placeholder values do appear in`--sql` plans and SQL excerpts, as they are part of the SQL; do not put secrets in placeholders.\n\n`gomigrate lint` needs no database. Its findings, with the rule IDs:\n\n| Severity | Rule IDs | \n|---|---|\n| error | `add-not-null-without-default` ,`concurrently-in-transaction` ,`sqlite-unsupported-alter` | \n| warning | `index-not-concurrent` ,`column-type-change` ,`foreign-key-not-valid` ,`check-not-valid` ,`set-not-null` ,`rename` ,`drop-table` ,`drop-schema` ,`drop-column` ,`truncate` ,`unbounded-write` ,`full-table-rewrite` | \n| info | `missing-lock-timeout` ,`irreversible` | \n\nHow it works:\n\n- Rules know the dialect.\n- `ALTER TABLE` is split into its actions, so`ADD a int DEFAULT 0, ADD b int NOT NULL` is judged per column.\n- Serial, identity and generated columns count as defaulted; quoted and schema-qualified names are matched.\n- They ignore text inside strings and comments.\n- They skip tables created in the same migration.\n- `-o github` turns findings into pull-request annotations.\n- `--fail-on error|warning|info|never` exits with code 3.\n\n```\nclaude mcp add gomigrate -- gomigrate mcp\n```\n\n- **Read-only tools:**`status` ,`validate` ,`plan` (with SQL) and`lint` .\n- **`create_migration`:** writes a migration file and validates and lints it. Use the typed`no_transaction` and`sequential` inputs. Embedded`-- +migrate` and`-- +goose` directives are rejected.\n\nBy default, `apply` and `rollback` can preview a plan. In the operator's\ntrusted environment, preview the intended change against the intended\ndatabase (for example, `gomigrate -o json up --sql`). Review the SQL, callbacks\nand destination, then pass that preview's `plan_id` to a new MCP server using\nthe same configuration and the corresponding operation:\n\n```\ngomigrate mcp --approve-apply \"$REVIEWED_PLAN_ID\"\ngomigrate mcp --approve-rollback \"$REVIEWED_ROLLBACK_PLAN_ID\"\n```\n\nThe client must supply `confirm: true` and the matching `plan_id`. A matching\nrequest consumes the grant before it opens a database connection, even if the\nattempt fails or is cancelled. The runner also checks the current target and\nplan under the migration lock. Overriding lint errors requires both the\noperator's `--allow-lint-errors` on an apply grant and the client's\n`allow_lint_errors: true`.\n\nThe launcher controls who can grant approval. Keep its configuration and database credentials outside the agent's control and record the review there if you need an audit of the approver. Each process start issues a new grant, so use a one-shot launch for execution. Keep the persistent planning server free of approval flags. After an interrupted attempt, inspect the database and review a fresh plan before launching again.\n\n```\n# Pull requests: annotate risky SQL, fail on errors\n- uses: go-gen-ecosystem/go-migrate@v1\n  with: { command: lint, driver: postgres }\n\n# Deploy: show the plan, then apply exactly that plan\n- uses: go-gen-ecosystem/go-migrate@v1\n  with: { command: up --sql, dsn: \"${{ secrets.DATABASE_URL }}\" }\n- uses: go-gen-ecosystem/go-migrate@v1\n  with: { command: \"up --expect-plan ${{ vars.APPROVED_PLAN_ID }}\", dsn: \"${{ secrets.DATABASE_URL }}\" }\n```\n\n- **JSON envelope:** every command accepts`-o json` and prints one envelope,`{ok, command, data | error{code, codes, message}}` . A run that fails part-way still reports what it applied in`data` .\n- **Exit codes:**\n\n| Code | Meaning | \n|---|---|\n| `0` | ok | \n| `1` | error | \n| `2` | pending migrations ( `status --fail-on-pending` ) | \n| `3` | lint findings at the `--fail-on` level | \n\n- **Container image:**`docker build -t gomigrate .` produces a 27 MB distroless image.\n\n`.gomigrate.yaml`, where values may use `${ENV}` or `${ENV:-default}`:\n\n```\ndatabase:\n  driver: postgres            # inferred from the DSN when omitted\n  dsn: ${DATABASE_URL}        # or host, port, name, user, password, sslmode, params\nmigrations:\n  dir: migrations\n  table: gomigrate_history    # or schema.table\n  lock_timeout: 5m\n  contexts: [prod]\n  placeholders: { owner: app_owner }\n  baseline_on_migrate: \"\"     # e.g. \"5\" to adopt an existing schema\n  allow_out_of_order: false\n  allow_missing: false\n```\n\nSettings are applied in this order of precedence:\n\n1. flags;\n2. `GOMIGRATE_DSN` /`GOMIGRATE_DRIVER` ;\n3. `DATABASE_URL` ;\n4. the config file;\n5. defaults.\n\nAdditional rules:\n\n- A DSN that overrides the file brings its own driver.\n- An explicit `--config` must exist, and`DATABASE_URL` never retargets it.\n- Prefer the environment over `--dsn` for credentials, because command lines are visible to other processes.\n\n| Command | Purpose | \n|---|---|\n| `init` | write a config and `migrations/` | \n| `create NAME [--seq] [--pair]` | create a migration | \n| `lint [--fail-on LEVEL]` | static risk analysis | \n| `up [--to V] [--dry-run \\| --sql] [--expect-plan ID]` | apply pending migrations | \n| `down [--steps N \\| --to V \\| --to-tag T \\| --all] [--dry-run \\| --sql] [--expect-plan ID]` | roll back | \n| `redo` | roll back and re-apply the last migration | \n| `status [--fail-on-pending]` | show state; doubles as a CI gate | \n| `validate` | check drift, missing, out-of-order and failed migrations, and callback recovery | \n| `repair MIGRATION (--clear-failed \\| --accept-checksum) [--dry-run]` | preview or change one history row | \n| `mark-applied V` | record V as applied without running it | \n| `baseline --version V` | adopt an existing database | \n| `tag NAME` | tag the current version | \n| `mcp` | serve AI agents over the Model Context Protocol | \n\n`repair 42 --clear-failed` removes version 42's failed history row after you\nundo its partial changes. For a failed repeatable, pass the label from\n`status`, for example `repair 'R__refresh views' --clear-failed`.\nFor run-level callbacks, inspect which effects committed and reconcile them\nso that it is safe to run the callbacks again. Preview the marker removal\nwith `repair C:run-callbacks --clear-failed --dry-run`, then omit `--dry-run`\nto remove only that marker. Repair any failed migrations separately. After\na connection loss during finalization, check `status` and callback effects\nbefore retrying: the database may already have committed the marker removal.\n`repair 42 --accept-checksum` accepts drift for version 42 only; prefer\nrestoring the applied file and writing a new migration. Changed repeatables\nrun again on `up` rather than accepting a checksum through repair.\nAdd `--dry-run` to preview the selected row and, for checksum changes, compare\nits stored and proposed checksums. Repair rechecks the selected row under the\nmigration lock and updates history in a transaction. It runs no migration SQL.\n\nGlobal flags:\n\n| Purpose | Flags | \n|---|---|\n| Connection | `--config` ,`--dsn` ,`--driver` | \n| Migrations | `--dir` ,`--table` ,`--context` ,`--label` ,`--placeholder` ,`--baseline-on-migrate` | \n| Output | `-o text\\|json` | \n| Logging | `--log-level` ,`--log-format` | \n\n```\nmake check             # lint + tests + govulncheck\nmake test-race         # race detector (needs cgo)\nmake test-integration  # conformance on real PostgreSQL 17 and MySQL 8.4 (Docker)\nmake bench             # benchmarks; see also benchmarks/compare\n```\n\nTo include SQL Server in the normal suite, set `GOMIGRATE_TEST_SQLSERVER_DSN`\nto an isolated test instance with permission to create and drop disposable\ndatabases, then run `go test ./...`. Set `GOMIGRATE_TEST_SQLSERVER_SELF_SIGNED=1`\nfor a self-signed fixture to also verify the default certificate rejection.\nRepository owners can enable the SQL Server Developer Edition CI job by setting\n`GOMIGRATE_CI_SQLSERVER_ACCEPT_EULA` to `Y` after accepting Microsoft's license\nterms for that CI service.\n\nSet `GOMIGRATE_TEST_ORACLE_DSN` to include Oracle in `go test ./...`. Use an\nisolated Oracle Database Free PDB with a fixture administrator that can create\nand drop disposable users and grant `EXECUTE` on `SYS.DBMS_LOCK`. Test users\nreceive only the schema privileges needed by the suite and are dropped after\neach case.\n\nSet `GOMIGRATE_TEST_DB2_DSN` to an isolated Db2 fixture administrator URL that\ncan create and drop temporary schemas and flush the fixture's dynamic package\ncache. The fixture needs the `SYSTOOLSPACE` tablespace for\n`SYSPROC.ADMIN_DROP_SCHEMA`. Set `GOMIGRATE_TEST_DB2_APP_DSN` to\nthe low-privilege migration user's URL on the same database. To also run the TLS\nrejection checks, use a fixture certificate signed by its own CA and set\n`GOMIGRATE_TEST_DB2_TLS_MISMATCH_HOST` to an alias that resolves to the fixture\nand is absent from its certificate.\n\nLicensed under [Apache-2.0](https://github.com/Go-Gen-Ecosystem/go-migrate/blob/main/LICENSE).", "url": "https://wpnews.pro/news/go-migrate-sql-migrations-with-one-use-approvals-for-ai-agents", "canonical_source": "https://github.com/Go-Gen-Ecosystem/go-migrate", "published_at": "2026-11-19 11:42:32+00:00", "updated_at": "2026-11-19 11:46:36.623016+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["go-migrate", "Go-Gen-Ecosystem", "golang-migrate", "goose", "PostgreSQL", "SQLite", "modernc.org/sqlite"], "also_reported_by": [], "takeaway": "go-migrate v1.0.1's `--expect-plan` flag requires the reviewed plan ID at deploy time and re-checks the plan, database and schema under the migration lock, and its benchmark of 100 SQLite migrations allocated 727.8 KiB per batch versus 10.66 MiB for golang-migrate v4.20.1.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/go-migrate-sql-migrations-with-one-use-approvals-for-ai-agents", "markdown": "https://wpnews.pro/news/go-migrate-sql-migrations-with-one-use-approvals-for-ai-agents.md", "text": "https://wpnews.pro/news/go-migrate-sql-migrations-with-one-use-approvals-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/go-migrate-sql-migrations-with-one-use-approvals-for-ai-agents.jsonld"}}