go无内置migrate命令，需用第三方库；migrate支持cli和sdk但行为不同，文件名须严格为14位时间戳+下划线+描述+.sql，ci/cd中须防重复执行与脏状态。
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。
立即学习“go语言免费学习笔记（深入）”；
常见踩坑点：
- 用空格或中文命名（
添加用户表.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 初始化逻辑，都会让这套机制在关键节点失灵。
