go-migrate
从独立 CLI 运行带版本号的 SQL 迁移,或将运行器嵌入 Go 应用程序。go-migrate 支持 PostgreSQL、MySQL/MariaDB、SQLite、SQL Server、Oracle Database 和 IBM Db2 LUW。先预览 SQL,然后在部署时要求提供其 plan ID,以便在迁移锁下校验计划、数据库和 schema。
go install github.com/go-gen-ecosystem/go-migrate/cmd/gomigrate@latest
为什么选择 go-migrate
该表比较了三个固定版本中的内置能力。破折号表示我们未找到该行的内置对应功能。
| 能力 | go-migrate v1.0.1 | golang-migrate v4.20.1 | goose v3.30.1 |
|---|---|---|---|
| 带版本号的 SQL 迁移 | 是 | 是 | 是 |
| 在同一版本序列中同时使用 SQL 和已注册的 Go 函数 | 库或自定义二进制文件 | — | 库或自定义二进制文件 |
| 乱序应用缺失的版本 | 需显式启用 | — | 需显式启用 |
| SQL 内部替换 | 配置的占位符 | — | 需显式启用 ENVSUB |
| 在标准 CLI 中直接从 Amazon S3 读取迁移 | — | 是 | — |
| Linux amd64 上无需 CGO 的 SQLite | 标准构建 | 使用 sqlite 驱动的自定义构建 | 标准构建 |
| 通过校验和检测对已应用版本化 Up SQL 的修改 | 是 | — | — |
| 当其校验和变化时重复执行 SQL | 是 | — | 无版本模式会在不校验校验和的情况下重新运行文件 |
| 迁移选择 | 上下文、标签、前置条件和回滚标签 | 目标版本或步骤数 | Provider 可排除版本或文件名 |
| Up 运行前后的命名 SQL 回调 | 是 | — | — |
| 要求经过审查且绑定到数据库和 schema 的 SQL 计划 | --expect-plan | — | — |
| 离线 SQL 风险检查 | 规则因方言而异 | — | validate 检查迁移结构 |
| 跨进程锁定 | 因引擎而异,包括针对磁盘 SQLite 的文件锁 | PostgreSQL、MySQL 和 SQL Server 上的原生锁。SQLite 保护是按驱动实例 | 需显式启用的 provider 锁,包括 PostgreSQL 和 MySQL |
| 自动化 | CLI JSON 结果、错误码和捆绑的 MCP 服务器 | 类型化库错误和 logger 接口 | 类型化 provider 结果、部分错误和结构化日志 |
对于 PostgreSQL、SQLite 和 SQL Server 上的事务性 SQL 迁移,go-migrate 和 goose 可以在同一事务中提交变更及其历史记录行。golang-migrate 记录一个脏版本,执行迁移,然后单独将该版本标记为干净。其 force V 命令允许操作员在检查数据库后设置版本并清除脏状态。go-migrate 执行 · golang-migrate 执行与恢复 · goose 事务性 SQL
打包和功能比较使用带标签的源代码和构建配置。golang-migrate 发布驱动 · goose SQL 注解 · goose SQLite 驱动 · goose 发布构建
每 100 次迁移的 SQLite 分配
每个操作构造一个库运行器,并向全新的 SQLite 数据库应用 100 次迁移。每个迁移创建一个表并插入一行。三者均使用相同的 SQL 主体和纯 Go 驱动(modernc.org/sqlite v1.62.0),并启用 WAL 和 synchronous=OFF。该表显示了 Linux/amd64、Go 1.26.11、Intel Core Ultra 9 285HX 上每种配置六次样本的中位数。B/op 是每批次的累计 Go 堆分配。基准测试源
| 库配置 | 每批次分配 | 每批次分配次数 |
|---|---|---|
| go-migrate v1.0.1,默认 | 727.8 KiB | 10,873.5 |
| golang-migrate v4.20.1,默认 | 10.66 MiB | 9,420 |
| goose v3.30.1,默认 | 1.14 MiB | 8,547 |
| golang-migrate v4.20.1,4 KiB 缓冲区 | 892.2 KiB | 9,361 |
在默认设置下,go-migrate 分配的字节数最少,而 goose 的分配次数最少。golang-migrate 的结果对其每次迁移 100,000 字节的缓冲区敏感。第四行仅更改了该设置。更大的 SQL 文件、远程源和持久存储是不同的工作负载。golang-migrate 缓冲区实现
每一列按执行顺序列出六个样本每批次分配的字节数。
| Sample | go-migrate | golang-migrate | goose | golang-migrate, 4 KiB |
|---|---|---|---|---|
| 1 | 754,551 | 11,181,571 | 1,194,601 | 918,816 |
| 2 | 744,524 | 11,180,188 | 1,194,292 | 911,948 |
| 3 | 747,631 | 11,182,817 | 1,194,418 | 913,354 |
| 4 | 742,457 | 11,181,530 | 1,194,792 | 916,509 |
| 5 | 743,558 | 11,180,337 | 1,194,205 | 913,784 |
| 6 | 745,914 | 11,180,937 | 1,194,240 | 912,850 |
从 v1.0.1 的一次性检出开始。Go 1.26.11 需要刷新已打标签的基准测试模块的 go.mod 和 go.sum,因此命令使用了 -mod=mod。
cd benchmarks/compare
GOWORK=off CGO_ENABLED=0 GOTOOLCHAIN=go1.26.11 go test -mod=mod -run '^$' -bench '^BenchmarkUp100_' -benchmem -count=6 .
对于第四行,在该检出中于 BenchmarkUp100_GolangMigrate 开头添加以下行,并用 -bench '^BenchmarkUp100_GolangMigrate$' 重复该命令。
old := gm.DefaultBufferSize
gm.DefaultBufferSize = 4096
defer func() { gm.DefaultBufferSize = old }()
Quick start
gomigrate init # .gomigrate.yaml + migrations/
gomigrate create add_users # migrations/20261116120000_add_users.sql
gomigrate lint # risky SQL? (no database needed)
gomigrate up --sql # dry run: the exact SQL that would run, and its plan ID
gomigrate up --expect-plan <id> # apply exactly the reviewed plan, or fail with plan_changed
gomigrate status # table; -o json for scripts
gomigrate down # roll back the last one (--steps, --to, --to-tag, --all)
-- +migrate Up
CREATE TABLE users (id INTEGER PRIMARY KEY, email VARCHAR(255) NOT NULL UNIQUE);
-- +migrate Down
DROP TABLE users;
Library
//go:embed migrations
var migrations embed.FS
dir, _ := fs.Sub(migrations, "migrations")
m, err := migrate.New(db, "postgres", migrate.WithFS(dir)) // malformed files fail here, not mid-run
if err != nil {
return err
}
_, err = m.Up(ctx)
- Migrator 方法:应用与回滚:Up、UpTo、Down(ctx, migrate.DownTarget{Steps: 1})(或 To: "3",或 Tag: "v1")、Redo;只读:Plan、PlanDown、PlanRepair、PlanID、Statements、Callbacks、Status、Validate、Lint、Migrations;历史管理:Repair(ctx, migrate.RepairTarget{Migration: "3", Action: migrate.RepairClearFailed})、MarkApplied、Baseline、Tag。要接受有意的校验和漂移,请对该版本使用 migrate.RepairAcceptChecksum。裸调用 Repair(ctx) 会返回 ErrInvalidArgument 且不做任何更改。
- 应用与回滚:Up、UpTo、Down(ctx, migrate.DownTarget{Steps: 1})(或 To: "3",或 Tag: "v1")、Redo;
- 只读:Plan、PlanDown、PlanRepair、PlanID、Statements、Callbacks、Status、Validate、Lint、Migrations;
- 历史管理:Repair(ctx, migrate.RepairTarget{Migration: "3", Action: migrate.RepairClearFailed})、MarkApplied、Baseline、Tag。要接受有意的校验和漂移,请对该版本使用 migrate.RepairAcceptChecksum。裸调用 Repair(ctx) 会返回 ErrInvalidArgument 且不做任何更改。
- 已批准的方案:m.Up(ctx, migrate.ExpectPlan(id)) 仅在锁内重新计算的方案仍具有已审核的 ID 时才运行;否则会以 ErrPlanChanged 失败且不运行任何内容。
- 选项:WithFS、WithGoMigrations、WithTable、WithLockWait;WithLogger(halolog);WithPlaceholders、WithContexts、WithLabels、WithBaselineOnMigrate;WithAllowOutOfOrder、WithAllowMissing、WithHooks、WithInstalledBy。
- WithFS、WithGoMigrations、WithTable、WithLockWait;
- WithLogger(halolog);
- WithPlaceholders、WithContexts、WithLabels、WithBaselineOnMigrate;
- WithAllowOutOfOrder、WithAllowMissing、WithHooks、WithInstalledBy。
- 无需数据库:migrate.Lint(dialect, opts...) 在没有连接的情况下分析迁移。
- 错误:每个错误都兼容 errors.Is,且 migrate.ErrorCodes(err) 会给出稳定的错误码。
- 并发性:Migrator 在 New 之后不可变,且可安全地并发使用。
迁移文件
| 文件 | 含义 |
|---|---|
| 001_users.sql , V1.2__index.sql | 带 -- +migrate Up 和 Down 标记的版本化 SQL。也接受 goose 的 Up、Down、StatementBegin、StatementEnd 和 NO TRANSACTION 注解。 |
| 2024…_seed.up.sql + .down.sql | 版本化成对文件(golang-migrate 布局) |
| R__views.sql | 可重复执行:每次变更后重新应用,回滚后也会重新应用 |
| beforeMigrate.sql , afterEachMigrate__x.sql , … | SQL 回调(Flyway 命名) |
-- +migrate Up notransaction -- 例如 CREATE INDEX CONCURRENTLY
-- +migrate Context dev,test -- 仅在 --context dev 或 test 下运行
-- +migrate Labels billing -- 仅在 --label billing 下运行
-- +migrate DBMS postgres -- 仅在 PostgreSQL 上运行
-- +migrate RunAlways -- 可重复:每次 up 都运行
-- +migrate Precondition onFail=MARK_RAN expect=0 SELECT COUNT(*) FROM information_schema.tables WHERE table_name = 'legacy'
-- +migrate Lint ignore=drop-table -- 接受一条已审查的 lint 发现
-- +migrate StatementBegin / StatementEnd -- 将一段代码块保持为单条语句
配套规则:
- 占位符:${name} 会从
--placeholder name=value或placeholders:配置中替换。内置占位符有 ${migrate:dialect}、${migrate:table} 和 ${migrate:user}。
- 版本按数值比较:9 < 10,1.9 < 1.10,001 == 1 == 1.0。
- SQL 校验和覆盖 Up 部分。它们会规范化行尾、开头的 BOM 以及字面量之外无意义的空白,并保留语句块边界。
- 前置条件:HALT 使本次运行失败,MARK_RAN 记录该迁移但不执行它,CONTINUE 使其保持待执行。计划会将此类迁移标记为条件性。
- 回调会出现在
--sql计划中(即使没有待执行的迁移它们也会运行),包含在计划 ID 中,并且会被 lint。
SQL Server
使用 sqlserver 作为方言,或在 GOMIGRATE_DSN 中使用 sqlserver:// URL。库调用方使用由 github.com/microsoft/go-mssqldb 注册的 sqlserver 驱动打开其 *sql.DB。CLI 包含该驱动,并保持 CGO-free。通过 URL 的 database 参数或 YAML 的 database.name 字段选择目标数据库。CLI 默认启用 TLS 并验证服务器证书。通过 URL 或 database.params 提供驱动的 TLS 选项。带自签名证书的一次性本地 fixture 可以设置 trustservercertificate=true。
默认情况下,每个迁移方向作为一个 T-SQL 批处理运行。将 GO 单独放在一行以开始新批处理。允许尾随的 -- 注释。引号标识符、字符串或块注释中的 GO 会保留在 SQL 中。当某条语句(例如 CREATE PROCEDURE)必须位于其批处理首位时,请使用单独的批处理。GO N 重复和诸如 :r 的 SQLCMD 命令不在支持的脚本格式之列。StatementBegin/StatementEnd 也可以设置显式批处理边界。文本 dry run 会在批处理之间打印 GO,JSON 计划会列出每个批处理的精确 payload。
SQL Server 2022 是一致性目标。迁移登录名需要访问所配置的 history schema,并具有在该 schema 中创建和修改 history 及应用程序对象的权限。非限定 history 表使用登录名的默认 schema。请参见 SQL Server 示例。
Oracle Database
使用 oracle 作为方言,或在 GOMIGRATE_DSN 中使用 oracle://user:password@host:port/service URL。YAML 的 database.name 字段标识 Oracle 服务。CLI 捆绑 Oracle 的原生 Go oracledb 驱动,并使用 password 身份验证。该驱动要求 Go 1.26.9,并保持 CLI 为 CGO-free。库调用方可以通过 database/sql 自行注册并打开 oracledb。该驱动依据 Universal Permissive License 1.0 分发。
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。请在回复和工具调用中完全按原样使用它们:它们会在任何内容运行之前被替换为真实值。不要要求验证它们,也不要用示例替换它们。
命令行工具(CLI)默认在端口 2484 上选择 TCPS,并请求证书链与服务器身份验证。根据需要,通过 URL 或 database.params 设置 wallet_location 或 ssl_server_cert_dn。一个隔离的 Oracle Free 测试实例可以使用 protocol=tcp 在端口 1521 上连接。一致性测试夹具在私有网络上通过 TCP 使用 password 认证。它面向 Oracle AI Database 26ai Free,并连接到 FREEPDB1 服务。
未显式指定模式的 history 表使用会话初始的当前模式。该工具会像 Oracle 处理未加引号名称那样,将普通配置的标识符折叠为大写。迁移用户需要具备创建和修改其 history 及应用程序对象的权限,以及 SYS.DBMS_LOCK 上的 EXECUTE 授权。当物理会话结束时,Oracle 会释放迁移锁。请使用在会话丢失时会使运行失败的驱动配置。
普通 SQL 使用分号作为分隔符。将 Oracle PL/SQL 块和存储例程包裹在 -- +migrate StatementBegin 和 -- +migrate StatementEnd 之间。保留结尾的 END;,并省略 SQL*Plus 的斜杠命令。Oracle 的 q'[...]' 和 nq'[...]' 字面量可以包含分号和换行符。参见 Oracle 示例。
IBM Db2 LUW
使用 db2 方言,或在 GOMIGRATE_DSN 中使用 db2://user:password@host:port/database URL。CLI 内置了独立的、MIT 许可的 go-db2 驱动,并且保持无需 CGO。库调用方可以注册 db2 驱动并提供 database/sql 连接池。一致性测试目标是在 Linux x86-64 上、使用默认数据库排序规则的 IBM Db2 Community Edition 12.1.5.0。
CLI 启用经证书验证的 TLS,并默认使用端口 50001。如果使用私有 CA,请提供实例的 TLS 监听端口和 ssl_ca(tls 和 ssl_ca 也可以在 database.params 中设置)。隔离的夹具可以通过 tls=false&allow_plaintext_auth=true 选择使用未加密的 TCP。CLI 支持用户名和 password 认证。
Db2 的 history 标识符对普通未加引号的标识符使用大写名称。未限定模式的 history 表使用初始的当前模式。迁移登录需要具备创建和修改其 history 及应用程序对象的权限,以及 SYSIBMADM.DBMS_LOCK 模块上的 EXECUTE 权限。使用安装了 Db2 原生 DBMS_LOCK 模块的 Db2 LUW 12.1.3 或更新版本。常规模式迁移在事务中运行。对于无法在事务中运行的语句,请使用 notransaction。将 Db2 SQL PL 例程或复合语句包裹在 StatementBegin 和 StatementEnd 中。保留块内的分号,并省略诸如 @ 的 CLP 终止符。参见 Db2 示例。
安全模型
- 锁定:一个作用域为所配置迁移 history 的跨进程锁。PostgreSQL 和 MySQL:pg_advisory_lock / GET_LOCK,进程死亡时由服务器释放。SQL Server:每个数据库一个会话拥有的 sp_getapplock。同一数据库中不同的 history 表共享该锁,因此在不区分大小写或不区分重音的排序规则下,表的别名无法绕过它。Oracle:每个模式和 history 表一个排他的 DBMS_LOCK 会话锁,可在 Oracle DDL 提交后继续存在。Db2:一个由模式和 history 表派生的数值型 SYSIBMADM.DBMS_LOCK 会话锁。Db2 在提交之间保持该锁,并在会话结束时释放它。哈希到同一 ID 的 history 会串行化。SQLite:在数据库文件旁对 <database>.gomigrate-<history-table>.lock 施加一个运行期 OS 锁,并带有一行 fenced lease。所在目录必须允许创建该协调文件,并且每个迁移器都必须能够打开它。在任何迁移器可能使用它时,请将文件保留在原位。内存中的 SQLite 数据库在进程内协调。SQLite 进程退出后,OS 锁会被释放,被遗弃的 lease 在过期后可以回收。在推出 SQLite 锁变更之前,请先排空旧版本,以便所有正在运行的迁移器使用相同的协调协议。十个副本可以在启动时同时运行,而每个迁移仍然只运行一次。
像 {{NAME_ab12cd34}} 这样写入的值是真实值的占位符。请在回复和工具调用中完全按照写入的形式使用它们:它们会在任何内容运行之前被替换为真实值。不要要求验证它们,也不要用示例替换它们。
- PostgreSQL 和 MySQL:pg_advisory_lock / GET_LOCK,进程死亡时服务器会释放该锁。
- SQL Server:每个数据库一个会话拥有的 sp_getapplock。同一数据库中的不同历史表共享该锁,因此在大小写不敏感或重音不敏感排序规则下,表的别名无法绕过它。
- Oracle:每个 schema 和历史表一个独占的 DBMS_LOCK 会话锁,在 Oracle DDL 提交后仍然存活。
- Db2:一个由 schema 和历史表推导出的数字型 SYSIBMADM.DBMS_LOCK 会话锁。Db2 在提交之间保持该锁,并在会话结束时释放它。哈希到相同 ID 的历史记录会串行化。
- SQLite:在数据库文件旁的 <database>.gomigrate-<history-table>.lock 上施加一个运行期 OS 锁,并附带一条带围栏的租约行。所在目录必须允许创建该协调文件,且每个 migrator 都必须能打开它。只要任何 migrator 可能使用它,就要让该文件保持原位。内存中的 SQLite 数据库在进程内进行协调。
- SQLite 进程退出后,OS 锁会被释放,被遗弃的租约在过期后可以被回收。在推出 SQLite 锁变更之前,先排空旧版本,以便所有运行中的 migrator 使用相同的协调协议。
- 十个副本可以在启动时同时拉起,每个迁移仍然只运行一次。
- 每次运行一个连接。所有语句都在锁的连接上运行,因此单连接池也能工作。如果会话丢失,本次运行会失败,而不是在无保护的情况下继续。历史写入使用运行前选定的 schema。SQL Server 还会用起始数据库限定它们,因此迁移中的 SET search_path 或 USE 无法重定向历史写入。会话锁连接随后被丢弃,绝不归还到连接池。
- 所有语句都在锁的连接上运行,因此单连接池也能工作。
- 如果会话丢失,本次运行会失败,而不是在无保护的情况下继续。
- 历史写入使用运行前选定的 schema。SQL Server 还会用起始数据库限定它们,因此迁移中的 SET search_path 或 USE 无法重定向历史写入。
- 会话锁连接随后被丢弃,绝不归还到连接池。
- 原子性。PostgreSQL、SQLite、SQL Server 和 Db2 通常将每个迁移与其历史行一起提交。将需要自动提交的 SQL Server 语句(例如 CREATE DATABASE)标记为 notransaction。MySQL、Oracle 以及标记为 notransaction 的迁移会先提交一行脏行。Oracle DDL 会隐式提交。部分失败会阻止后续运行。手动恢复 schema,然后如果你撤销了变更,使用 repair MIGRATION --clear-failed;如果你完成了版本化迁移,使用 mark-applied VERSION。运行级 SQL 回调(beforeMigrate、afterMigrate、afterMigrateError)在迁移所在的同一会话上运行,但在它们的事务之外。在第一个回调运行之前,go-migrate 会提交一个恢复标记。只有当整个运行成功后,它才会清除该标记。即使没有待处理的迁移,被中断的运行也可能留下已提交的回调副作用。当标记仍然存在时,status 会将 callback_recovery_required 与迁移行分开报告,并且 validate、up、down 和 redo 都会报告需要恢复。成功的运行可以在下一次 up 时再次运行这些回调。
- PostgreSQL、SQLite、SQL Server 和 Db2 通常将每个迁移与其历史行一起提交。将需要自动提交的 SQL Server 语句(例如 CREATE DATABASE)标记为 notransaction。
- MySQL、Oracle 以及标记为 notransaction 的迁移会先提交一行脏行。Oracle DDL 会隐式提交。部分失败会阻止后续运行。手动恢复 schema,然后如果你撤销了变更,使用 repair MIGRATION --clear-failed;如果你完成了版本化迁移,使用 mark-applied VERSION。
文章标题:Go-migrate – 面向 AI agent 的一次性审批 SQL 迁移
正文:
- 运行级 SQL 回调(beforeMigrate、afterMigrate、afterMigrateError)在与迁移相同的会话上执行,位于其事务之外。在第一个回调运行之前,go-migrate 会提交一个恢复标记。只有在整个运行成功后,它才会清除该标记。被中断的运行即使没有待执行的迁移,也可能留下已提交的回调效果。在标记仍然存在期间,status 会将 callback_recovery_required 与迁移行分开报告,validate、up、down 和 redo 会报告需要恢复。成功的运行可以在下一次 up 时再次运行回调。
- 执行前校验:漂移、缺失和乱序的迁移、未知目标、基线下限以及不可逆回滚,都会在任何 SQL 运行之前检查。
- 审批将执行绑定到目标:CLI 和 MCP 的 plan ID 覆盖解析后的数据库、历史表、活动 schema 或搜索路径,以及确切的计划(包括回调和任何自动基线)。--expect-plan(CLI)和 plan_id(MCP)会在更改历史或运行迁移 SQL 之前,在迁移锁下检查审批。请重新签发旧版本中的 ID。库调用方可以通过 PlanWithID 或 PlanDownWithID 以及 ExpectTargetPlan 选择启用相同的检查;PlanID 和 ExpectPlan 仍然只检查计划内容。
- 审批范围:ID 使用来自活动会话的元数据和配置的网络路由。PostgreSQL 重启后需要新的计划。SQLite 绑定规范文件路径和有序的附件名称;它无法检测同一路径下被替换的文件。替换文件后请重新计划。内存或临时 SQLite 目标无法获得目标绑定的 ID。
- 只读就意味着只读:status、validate、lint 和 dry run 绝不会创建表。
- 输出中不含连接机密:DSN 和密码绝不会出现在错误或日志中。占位符值确实会出现在 --sql 计划和 SQL 摘录中,因为它们是 SQL 的一部分;不要将机密放入占位符中。
Lint
gomigrate lint 不需要数据库。其发现的问题及规则 ID:
| 严重级别 | 规则 ID |
|---|---|
| error | add-not-null-without-default , concurrently-in-transaction , sqlite-unsupported-alter |
| 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 |
| info | missing-lock-timeout , irreversible |
工作原理:
- 规则知道方言。
- ALTER TABLE 会被拆分为其各个动作,因此 ADD a int DEFAULT 0, ADD b int NOT NULL 会按列进行判断。
- Serial、identity 和生成列算作有默认值;带引号和带 schema 限定的名称会被匹配。
- 它们忽略字符串和注释内的文本。
- 它们跳过在同一迁移中创建的表。
- -o github 会把发现的问题转换为拉取请求注解。
- --fail-on error|warning|info|never 以代码 3 退出。
AI agents(MCP)
claude mcp add gomigrate -- gomigrate mcp
- 只读工具:status、validate、plan(带 SQL)和 lint。
- create_migration:写入一个迁移文件并对其进行校验和 lint。使用类型化的 no_transaction 和 sequential 输入。嵌入的 -- +migrate 和 -- +goose 指令会被拒绝。
默认情况下,apply 和 rollback 可以预览计划。在操作员的受信任环境中,针对预期的数据库预览预期的变更(例如 gomigrate -o json up --sql)。审查 SQL、回调和目标,然后将该预览的 plan_id 传递给使用相同配置和相应操作的新 MCP 服务器:
gomigrate mcp --approve-apply "$REVIEWED_PLAN_ID"
gomigrate mcp --approve-rollback "$REVIEWED_ROLLBACK_PLAN_ID"
客户端必须提供 confirm: true 和匹配的 plan_id。匹配的请求会在打开数据库连接之前消耗该授权,即使尝试失败或被取消也是如此。runner 还会在迁移锁下检查当前目标和计划。覆盖 lint 错误需要操作员的 --allow-lint-errors 出现在 apply 授权上,以及客户端的 allow_lint_errors: true。
launcher 控制谁可以授予批准。将其配置和数据库凭据置于 agent 的控制之外,并在那里记录审查内容,如果你需要审计批准者的话。每次进程启动都会发放新的授权,因此执行时请使用一次性启动。保持常驻的规划服务器不带有批准标志。在中断的尝试之后,先检查数据库并审查新的计划,然后再重新启动。
CI/CD
# Pull requests: annotate risky SQL, fail on errors
- uses: go-gen-ecosystem/go-migrate@v1
with: { command: lint, driver: postgres }
# Deploy: show the plan, then apply exactly that plan
- uses: go-gen-ecosystem/go-migrate@v1
with: { command: up --sql, dsn: "${{ secrets.DATABASE_URL }}" }
- uses: go-gen-ecosystem/go-migrate@v1
with: { command: "up --expect-plan ${{ vars.APPROVED_PLAN_ID }}", dsn: "${{ secrets.DATABASE_URL }}" }
- JSON envelope:每个命令都接受 -o json 并打印一个 envelope,{ok, command, data | error{code, codes, message}}。部分失败的运行仍会在 data 中报告它应用了什么。
| Code | Meaning |
|---|---|
| 0 | ok |
| 1 | error |
| 2 | pending migrations ( status --fail-on-pending ) |
| 3 | lint findings at the --fail-on level |
- 容器镜像:docker build -t gomigrate . 会生成一个 27 MB 的 distroless 镜像。
Configuration
.gomigrate.yaml,其中值可以使用 ${ENV} 或 ${ENV:-default}:
database:
driver: postgres # inferred from the DSN when omitted
dsn: ${DATABASE_URL} # or host, port, name, user, password, sslmode, params
migrations:
dir: migrations
table: gomigrate_history # or schema.table
lock_timeout: 5m
contexts: [prod]
placeholders: { owner: app_owner }
baseline_on_migrate: "" # e.g. "5" to adopt an existing schema
allow_out_of_order: false
allow_missing: false
设置按以下优先级顺序应用:
- GOMIGRATE_DSN / GOMIGRATE_DRIVER;
- DATABASE_URL;
- 配置文件;
附加规则:
- 覆盖文件的 DSN 会自带其驱动程序。
- 显式的 --config 必须存在,且 DATABASE_URL 永远不会重定向它。
- 凭据优先使用环境变量而非 --dsn,因为命令行对其他进程可见。
Commands
| Command | Purpose |
|---|---|
| init | 写入配置和 migrations/ |
| create NAME [--seq] [--pair] | 创建迁移 |
| lint [--fail-on LEVEL] | 静态风险分析 |
| up [--to V] [--dry-run │ --sql] [--expect-plan ID] | 应用待处理的迁移 |
| down [--steps N │ --to V │ --to-tag T │ --all] [--dry-run │ --sql] [--expect-plan ID] | 回滚 |
| redo | 回滚并重新应用最后一个迁移 |
| status [--fail-on-pending] | 显示状态;兼作 CI 门禁 |
| validate | 检查漂移、缺失、乱序和失败的迁移,以及回调恢复 |
| repair MIGRATION (--clear-failed │ --accept-checksum) [--dry-run] | 预览或更改一行历史记录 |
| mark-applied V | 将 V 记录为已应用而不运行它 |
| baseline --version V | 接管现有数据库 |
| tag NAME | 为当前版本打标签 |
| mcp | 通过 Model Context Protocol 为 AI agent 提供服务 |
以 {{NAME_ab12cd34}} 形式写入的值是真实值的占位符。在回复和工具调用中都请完全按照书写的方式使用它们:它们会在任何内容运行之前被填充为真实值。不要要求验证它们,也不要用示例替换它们。
文章标题:Go-migrate – 为 AI 代理提供带一次性审批的 SQL 迁移
正文: repair 42 --clear-failed 会在你撤销 version 42 的部分更改后,移除其失败的历史记录行。对于失败的 repeatable,请传入 status 中的 label,例如 repair 'R__refresh views' --clear-failed。对于 run-level 回调,检查哪些效果已提交并进行协调,以使其可以安全地再次运行这些回调。使用 repair C:run-callbacks --clear-failed --dry-run 预览标记移除,然后省略 --dry-run 以仅移除该标记。请单独修复任何失败的迁移。在 finalization 期间连接丢失后,重试前请检查 status 和回调效果:数据库可能已经提交了标记移除。repair 42 --accept-checksum 仅接受 version 42 的 drift;优先恢复已应用的文件并编写新的迁移。已更改的 repeatable 会在 up 时重新运行,而不是通过 repair 接受 checksum。添加 --dry-run 可预览所选行,并且对于 checksum 更改,比较其存储的 checksum 和拟议的 checksum。Repair 会在迁移锁下重新检查所选行,并在事务中更新历史记录。它不运行任何迁移 SQL。
全局标志:
| 用途 | 标志 |
|---|---|
| 连接 | --config , --dsn , --driver |
| 迁移 | --dir , --table , --context , --label , --placeholder , --baseline-on-migrate |
| 输出 | -o text│json |
| 日志 | --log-level , --log-format |
开发
make check # lint + tests + govulncheck
make test-race # 竞态检测器(需要 cgo)
make test-integration # 在真实 PostgreSQL 17 和 MySQL 8.4 上的合规性测试(Docker)
make bench # 基准测试;另见 benchmarks/compare
要将 SQL Server 纳入常规测试套件,请将 GOMIGRATE_TEST_SQLSERVER_DSN 设置为一个隔离的测试实例,该实例需具有创建和删除一次性数据库的权限,然后运行 go test ./.... 设置 GOMIGRATE_TEST_SQLSERVER_SELF_SIGNED=1 以使用自签名 fixture,从而同时验证默认证书拒绝。仓库所有者可以在接受 Microsoft 针对该 CI 服务的许可条款后,将 GOMIGRATE_CI_SQLSERVER_ACCEPT_EULA 设置为 Y 以启用 SQL Server Developer Edition CI 作业。
设置 GOMIGRATE_TEST_ORACLE_DSN 以将 Oracle 纳入 go test ./.... 使用一个隔离的 Oracle Database Free PDB,并配备一个 fixture 管理员,该管理员可以创建和删除一次性用户,并授予 SYS.DBMS_LOCK 上的 EXECUTE 权限。测试用户仅获得测试套件所需的 schema 权限,并在每个用例后被删除。
设置 GOMIGRATE_TEST_DB2_DSN 为一个隔离的 Db2 fixture 管理员 URL,该 URL 可以创建和删除临时 schema,并刷新 fixture 的动态包缓存。该 fixture 需要 SYSTOOLSPACE 表空间以用于 SYSPROC.ADMIN_DROP_SCHEMA。将 GOMIGRATE_TEST_DB2_APP_DSN 设置为同一数据库上低权限迁移用户的 URL。若要同时运行 TLS 拒绝检查,请使用由其自己的 CA 签名的 fixture 证书,并将 GOMIGRATE_TEST_DB2_TLS_MISMATCH_HOST 设置为一个解析到该 fixture 且不在其证书中的别名。
依据 Apache-2.0 许可。