正确做法是使用golang-migrate cli + go sdk实现版本化迁移，而非手写sql.exec；需按序号命名迁移文件（如001_init.up.sql）、依赖migrations表追踪版本、支持up/down双向操作，并在代码中通过m.version()校验后谨慎调用m.up(1)避免并发重复执行。
用 golang-migrate 做迁移，别自己手写 SQL 执行器
直接写 sql.Exec 跑 SQL 文件是错的——没版本追踪、没依赖顺序、回滚时容易漏语句。主流方案是用 migrate CLI + Go SDK，它把 migration 文件按序号命名、自动记录 migrations 表、支持 up/down 双向操作。
安装命令：go install -tags 'postgres sqlite3' github.com/golang-migrate/migrate/v4/cmd/migrate@latest（根据实际数据库选 tag）；Go 代码里引入：github.com/golang-migrate/migrate/v4 和对应驱动，比如 github.com/golang-migrate/migrate/v4/database/postgres。
- 迁移文件必须以
001_init.up.sql/001_init.down.sql格式命名，序号决定执行顺序 -
.up.sql里只放 DDL/DML 增量变更（如ALTER TABLE），别写事务控制（BEGIN/COMMIT）——migrate自动包裹事务 - 回滚时
migrate.Down()会找最近一次成功 up 对应的.down.sql，不是按文件名倒序执行
在框架启动时自动触发迁移，但得避开重复执行
很多项目把 migrate.Up() 放在 main() 开头，结果服务重启就又跑一遍——报错 dirty database version 或重复建表。关键不是“要不要自动”，而是“怎么判断该不该跑”。
正确做法：先调用 m.Version() 拿当前库版本，再和目标版本比对；或者更稳妥地，用 m.Up(1) 每次只执行一个版本，配合启动前检查状态。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 不要在 HTTP handler 里调
m.Up()——并发请求可能同时触发，导致锁表或冲突 - PostgreSQL 下若用
pgx连接池，传给migrate.New的*sql.DB必须是单例，否则连接泄漏 - SQLite 路径要用绝对路径（
file:///full/path/db.sqlite），相对路径在不同工作目录下会找不到
down 失败常见原因：down SQL 不幂等或字段已被删
执行 m.Down() 报错 column "xxx" does not exist 很常见——说明 .down.sql 试图删一个在上一轮 down 后已不存在的字段。根本问题在于 down 操作不是“撤销上一步”，而是“回到指定版本”，中间若跳过某些 down，状态就断了。
- 每个
.down.sql必须能安全重复执行（加IF EXISTS判断，如DROP TABLE IF EXISTS users;） - 避免在 down 里做数据清理（如
DELETE FROM）——万一 rollback 失败，数据丢了没法补 - 生产环境慎用
m.Down()，优先用m.Force()强制设版本号，再人工校验
测试迁移脚本时，别共用开发库
本地跑 migrate -database "..." -path ./migrations up 直接连开发库，改错一次就得手动修表。应该为测试单独起临时 DB 实例：
例如 PostgreSQL：docker run -d --rm -p 5433:5432 -e POSTGRES_PASSWORD=pass postgres:15，然后用 postgres://localhost:5433/test?sslmode=disable 测试；SQLite 更简单：sqlite3 /tmp/test.db 。
- CI 中建议用
migrate status输出当前版本号，作为 pipeline 的检查点 - Go 单元测试里可以用
github.com/mattn/go-sqlite3内存模式（file::memory:?cache=shared）快速验证 migration 逻辑 - 别把
.env里的数据库密码 commit 到 Git——迁移脚本里用os.Getenv("DB_URL")，CI 通过 secret 注入
迁移不是“写完 SQL 就完事”，版本号、执行顺序、失败恢复路径，每一步都得在数据库层面可验证。尤其 down 操作，宁可多写几行 IF EXISTS，也别信“我刚写的肯定没问题”。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
