Go语言需用golang-migrate/migrate等第三方库实现真正数据库迁移,而非GORM的AutoMigrate;推荐用CLI管理,迁移文件按时间戳命名并成对编写up/down SQL,确保可逆与版本追踪。

Go 语言本身不提供数据库迁移(migration)功能,得靠第三方库实现;最常用、最稳的是 migrate(即 golang-migrate/migrate),不是 ORM 自带的迁移(比如 GORM 的 AutoMigrate 不算真正 migration)。
用 migrate CLI 做命令行迁移最可靠
别从 Go 代码里硬调迁移逻辑——容易绕进事务、锁、并发执行等坑。官方推荐方式是用 migrate CLI 管理版本和执行,Go 应用只负责连接数据库,不参与迁移控制。
-
migrate支持 SQLite / PostgreSQL / MySQL / TiDB 等主流驱动,通过 URL 指定数据库,例如:postgres://localhost:5432/mydb?sslmode=disable - 迁移文件必须严格按命名规则:
YYYYMMDDHHIISS_<description>.up.sql</description>和.down.sql成对出现,时间戳保证顺序 - 执行迁移只需两条命令:
migrate -path ./migrations -database "your-db-url" up(升版),down(回退) - CLI 会自动在数据库中建一张
migrations表记录已执行版本,别手动删它,否则下次up会重复执行
GORM 的 AutoMigrate 不是 migration
AutoMigrate 是“结构同步”工具,不是 migration:它只比对当前 struct 和表结构差异,然后 CREATE TABLE IF NOT EXISTS 或加字段,但不会生成或执行 down 步骤,也无法回滚、无法跨环境追踪版本。
- 适合开发初期快速试错,不适合生产环境变更管理
- 字段改名、删字段、拆表、数据迁移等操作,
AutoMigrate完全无能为力 - 如果混用
AutoMigrate和migrate,极可能造成 schema 状态与 migration 记录不一致,后续执行up报错:duplicate column或table already exists
在 Go 应用启动时安全触发迁移
如果非要在代码里触发(比如 FaaS 场景),别直接调 migrate.Up(),而要用带锁和幂等检查的封装:
立即学习“go语言免费学习笔记(深入)”;
- 先用
migrate.NewWithDatabaseInstance()创建实例,传入已初始化的*sql.DB,避免重复开连接 - 调
m.Migrate(1)前,先调m.Version()判断是否已是最新版,避免每次启动都扫一遍迁移文件 - 注意:PostgreSQL 下需确保数据库用户有
CREATE TABLE权限;MySQL 要开innodb_lock_wait_timeout,否则长迁移卡住会导致应用启动失败 - 强烈建议加超时控制:
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second),迁移失败就log.Fatal,别静默跳过
真正的难点不在语法,而在迁移文件内容的设计:SQL 里不能依赖 Go 变量、不能写条件逻辑、down 文件必须能完全逆向 up 的副作用(比如 up 中 INSERT 初始化数据,down 就得 DELETE 对应行)。这些没法靠工具自动推导,得人来想清楚。


















