如何在Golang中实现数据库迁移_Golang数据库迁移与版本控制-Golang-PHP中文网

Go无内置migrate命令，需用第三方库；migrate支持CLI和SDK但行为不同，文件名须严格为14位时间戳+下划线+描述+.sql，CI/CD中须防重复执行与脏状态。

如何在golang中实现数据库迁移_golang数据库迁移与版本控制

Go 里没有内置的 migrate 命令，得靠第三方库

Go 标准库不提供数据库迁移能力，database/sql 只负责执行 SQL，不管理版本、顺序或回滚。你必须选一个迁移工具，主流是 migrate（golang-migrate/migrate）和 gorm/gorm 自带的 AutoMigrate —— 但后者不是真正意义的迁移：它只同步结构，不记录版本、不支持 down、无法跨环境复现变更。

如果你需要可重复、可审计、可回退的部署流程，必须用 migrate 这类外部迁移器。

migrate CLI 和 Go SDK 的调用方式差异很大

migrate 提供命令行工具和 Go SDK 两种使用路径，行为不完全一致：

CLI 默认从当前目录找 ./migrations，用 migrate -path ./migrations -database "sqlite:///db.sqlite" up 执行；
Go SDK 需手动构造 migrate.Migrate 实例，传入 io/fs.FS（如 os.DirFS("migrations")），再调用 Up() 或 Down()；
CLI 会自动创建 migrations 表（默认名 schema_migrations），SDK 不会自动建表，需确保目标库已存在该表，或提前执行 m.Migrate("up", 0) 初始化；
CLI 支持 -verbose 查看每步 SQL，SDK 需自己包装日志钩子。

迁移文件命名必须严格匹配时间戳+下划线+描述

migrate 要求文件名格式为 YYYYMMDDHHIISS_XXX.sql（如 20240512142301_add_users_table.sql），否则解析失败并报错：no migration files found 或 invalid version format。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

常见踩坑点：

用空格或中文命名（添加用户表.sql → 不识别）；
时间戳非 14 位（少一位、多一位、含字母）；
后缀不是 .sql（如 .txt 或 .SQL，区分大小写）；
文件放在子目录里（migrate 默认不递归扫描，需显式指定路径或改用 embed.FS + 自定义 io/fs.FS）。

在 CI/CD 中执行迁移要防重复和脏状态

生产环境跑 migrate up 最怕的是：同一份迁移被多次执行（比如部署脚本重试）、或部分失败后残留中间状态。关键控制点：

始终用 migrate -database "$DSN" -path ./migrations up 1 指定步数，而非无参数的 up，避免一次把所有未执行的全跑完；
加锁：PostgreSQL 可用 pg_advisory_lock，MySQL 用 GET_LOCK，SQLite 本身串行，但要注意 WAL 模式下的竞争；
迁移前先查 SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1，确认当前最新版本，避免盲目执行；
down 操作慎用：生产环境几乎不该执行 down，应通过新增 migration 来修复，否则可能丢数据。

迁移不是“写完 SQL 就完事”，它本质是数据库 schema 的版本控制 —— 文件名即 commit hash，执行顺序即 merge history，失败回滚即 revert。漏掉时间戳校验、跳过状态检查、混用 CLI 与 SDK 初始化逻辑，都会让这套机制在关键节点失灵。