如何在 Go 中使用 Golang-Migrate 管理微服务的数据库版本迁移-Golang-PHP中文网

最稳生产方案是用golang-migrate/migrate cli + sql文件，禁用gorm automigrate；因其不记录历史、无法回滚、字段重命名会丢数据，且不支持多环境版本追踪与审计。

如何在 go 中使用 golang-migrate 管理微服务的数据库版本迁移

常见原因是迁移文件路径没被正确识别，migrate 默认只认当前目录下的 ./migrations，而微服务项目结构往往把迁移文件放在 ./db/migrations 或 ./internal/db/migrations。不显式指定路径，它就找不到 SQL 文件。

实操建议：

Golang Spf13 Viper

Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。

下载

用 -path 参数明确指向迁移目录，例如：migrate -path ./db/migrations -database "postgres://..." up
确保路径是相对于执行命令的当前工作目录（不是相对于 go.mod），建议在 CI/CD 或启动脚本中用 cd $(dirname $0)/.. 切到项目根再运行
SQL 文件名必须严格遵循 数字_描述.up.sql / 数字_描述.down.sql 格式，比如 1598765432_add_users_table.up.sql；时间戳不合法或缺少 .up.sql 后缀都会导致 “no such file” 类似误报

不同服务可能共享同一数据库（如用户中心和订单服务共用 auth 库），但各自有独立迁移需求。直接共用 migrations 目录会导致版本号碰撞、down 操作互相干扰。

实操建议：

每个服务维护自己独立的迁移目录（如 ./user-service/db/migrations、./order-service/db/migrations），用不同 -path 参数隔离
数据库层面用 schema_migrations 表前缀区分：通过 -table 参数指定表名，例如 -table user_service_migrations，避免多服务写同一张元数据表
不要跨服务复用同一组 migration ID（即时间戳）；哪怕逻辑相同，也应生成新时间戳——否则 migrate status 会因重复 ID 报错

硬编码 exec.Command("migrate", ...) 在容器或 Windows 环境下容易失败（路径、权限、二进制缺失）。更可靠的方式是直接集成 github.com/golang-migrate/migrate/v4 的 Go SDK。

实操建议：

用 migrate.New 加载本地文件系统驱动：migrate.New("file://db/migrations", "postgres://...")，注意 URL 中的 file:// 是固定协议，路径是相对或绝对路径
调用 m.Up() 前务必检查 m.Version() 是否为 nil，否则说明数据库还没初始化，需先 m.Up(1) 或允许空迁移
生产环境启动时加 defer m.Close()，否则连接泄漏；同时捕获 migrate.ErrNoChange（无新迁移）作为正常情况，别当错误 panic

PostgreSQL 在已有数据的表上添加 NOT NULL 字段时，即使指定了 DEFAULT，也会报错 “column cannot be marked NOT NULL without a default value”，因为默认值只对新插入生效，老行仍为空。

实操建议：

分三步写 .up.sql：ALTER TABLE x ADD COLUMN y TEXT; → UPDATE x SET y = 'default' WHERE y IS NULL; → ALTER TABLE x ALTER COLUMN y SET NOT NULL;
避免在单条 ADD COLUMN 语句里混用 NOT NULL DEFAULT，PostgreSQL 12+ 虽支持，但旧版不兼容，且部分驱动解析异常
如果用 down.sql 回滚，记得先 DROP COLUMN 再删约束，顺序反了会报 “cannot drop column used in constraint”