golang-migrate需手动下载预编译二进制并配置PATH,驱动须显式启用(如postgres、sqlite3),MySQL需自编译;迁移文件名含序号决定执行顺序,up/down/fresh行为需明确;Go程序中应使用官方库而非CLI调用,并注意embed.FS路径处理。

golang-migrate 的二进制安装和驱动准备
不装对的 migrate CLI,后续所有命令都会报 command not found 或 no driver for dialect。Go 生态里它不走 go install 主流路径,得手动下载预编译二进制。
直接去 GitHub releases 页面 找对应系统(Linux/macOS/Windows)的最新版 migrate,比如 macOS Intel 下载 migrate.darwin-amd64.tar.gz,解压后把 migrate 二进制丢进 $PATH(如 /usr/local/bin)。
驱动必须显式启用:PostgreSQL 用 postgres,MySQL 用 mysql,SQLite 用 sqlite3。例如 PostgreSQL 连接串必须以 postgres:// 开头,且 CLI 必须能加载 postgres 驱动——这依赖你安装的二进制是否内置该驱动。官方 release 包默认只含 postgres 和 sqlite3;要用 MySQL,得自己编译或找带 mysql 驱动的第三方 build。
- 检查是否就绪:
migrate -version和migrate create -h能正常输出 - 连接串里密码含特殊字符(如
@、/)必须 URL 编码,否则解析失败 - SQLite 路径写绝对路径更稳,比如
sqlite3:///tmp/myapp.db
创建迁移文件:命名、内容与 SQL 规范
migrate create 只生成空文件,不校验 SQL 合法性,也不管你写的是 DDL 还是垃圾注释。名字里的时间戳决定执行顺序,不是随意取的。
运行 migrate create -ext sql -dir ./migrations -seq add_users_table,会生成两个文件:000001_add_users_table.up.sql 和 000002_add_users_table.down.sql。序号自动递增,不能手改;.up.sql 里写正向变更(CREATE TABLE),.down.sql 写逆向操作(DROP TABLE)。二者必须语义可逆,否则 migrate down 会出错或留脏数据。
-
.up.sql中避免写分号结尾(某些驱动不认),但多条语句必须用分号分隔 - PostgreSQL 注意 schema,默认是
public,跨 schema 操作要显式写CREATE TABLE my_schema.users - 不要在迁移里写
INSERT初始化数据——那是 seed 工作,不属于 schema 迁移范畴
执行迁移:up/down/fresh 的实际行为差异
migrate up 不是“执行所有未跑的迁移”,而是“执行到目标版本”;migrate down 也不是“回退全部”,而是“回退指定步数”。搞不清这个,容易误删表。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
典型命令:
migrate -path ./migrations -database "postgres://user:pass@localhost:5432/mydb?sslmode=disable" up
上面命令会查数据库里的 schema_migrations 表(自动建),对比本地 migration 文件序号,只执行缺失的 .up.sql。如果想只执行前 3 个,加 up 3;回退最后 1 个,用 down 1;清空库重来?fresh 先 down 到 0,再 up 全量——但生产环境禁用 fresh。
- 执行失败时,
schema_migrations表不会写入当前版本,下次up会重试,所以 SQL 要幂等(如CREATE TABLE IF NOT EXISTS) -
down命令要求.down.sql存在且语法正确,缺一个就中断,不会跳过 - 网络波动导致迁移中断?检查
schema_migrations表最后一条记录,手动清理或补执行
在 Go 程序中嵌入 migrate:不是调用 CLI,而是用库
很多人以为 os/exec 调 migrate CLI 就算集成,其实官方提供了 Go library:github.com/golang-migrate/migrate/v4,支持 runtime 加载迁移、控制事务、自定义日志。
关键不是“怎么调”,而是“怎么防错”:迁移应在应用启动早期执行,且失败必须 panic 或拒绝启动,不能静默忽略。
import (
"github.com/golang-migrate/migrate/v4"
_ "github.com/golang-migrate/migrate/v4/database/postgres"
_ "github.com/golang-migrate/migrate/v4/source/file"
)
m, err := migrate.New(
"file://./migrations",
"postgres://user:pass@localhost:5432/mydb?sslmode=disable",
)
if err != nil { panic(err) }
if err := m.Up(); err != nil && !errors.Is(err, migrate.ErrNoChange) {
panic(err)
}
- 导入驱动包(如
_ "github.com/golang-migrate/migrate/v4/database/postgres")是为了注册,不能省略下划线 -
m.Up()默认执行全部,加参数如m.Up(2)可控步数;ErrNoChange表示无新迁移,通常可忽略 - 别在 HTTP handler 里调
m.Up()——并发请求可能触发多次迁移,竞争写schema_migrations
最常被忽略的一点:迁移文件路径在 binary 里是相对路径,用 embed.FS 打包进二进制时,必须用 iofs.NewFS 包一层再传给 migrate.New,否则 runtime 找不到文件。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!










