migrate 快速上手指南：用 CLI 与 Golang 库管理数据库迁移的全流程-北京尧图网络

数据库开发工具CLI【免费下载链接】migrateDatabase migrations. CLI and Golang library.项目地址https://gitcode.com/gh_mirrors/mi/migrate点击查看免费下载这篇指南以 GETTING_STARTED.md 为主体系统讲解 golang-migrate即 migrate从零开始的完整使用流程创建迁移文件、填充内容、执行迁移、测试回滚以及处理失败迁移留下的脏dirty状态。读者学完后将掌握 migrate CLI 的核心命令与参数、up/down 迁移文件规范并能结合源码理解底层版本记录与加锁机制直接用于实际项目。开始之前理解 up/down 迁移概念在动手之前首先要理解数据库迁移中两个基础方向forward / up将数据库从当前版本迁移到更新版本通常执行CREATE TABLE、ALTER TABLE等变更reverse / down将数据库回退到之前的版本通常执行DROP TABLE等反向操作。migrate 的核心模型是一个逻辑迁移由一对文件表示——.up文件前进、.down文件回退二者共享同一个版本号。例如仓库中的真实示例 1085649617_create_users_table.up.sql 与 1085649617_create_users_table.down.sqlup 文件创建users表down 文件则负责删除它。这一一对文件设计的具体规范可参考 MIGRATIONS.md。其次为你的应用配置好一个数据库并确认所使用的数据库驱动已被支持。migrate 的驱动列表维护在 README.md覆盖 PostgreSQL、PGXv4/v5、Redshift、MySQL/MariaDB、SQLite/SQLite3/SQLCipher、Cassandra/ScyllaDB、ClickHouse、CockroachDB、YugabyteDB、MongoDB、Neo4j、SQL Server、Spanner、Firebird、rqlite 等众多数据库。数据库连接串统一使用 URL 形式dbdriver://username:passwordhost:port/dbname?param1trueparam2falseURL 中的保留字符如!、#、$、%、、?等需要先做百分号编码Percent-Encoding。创建迁移文件使用 migrate CLI 的create子命令创建迁移。官方示例migrate create -ext sql -dir db/migrations -seq create_users_table该命令会在db/migrations目录下生成一对以 6 位序列号开头的文件000001_create_users_table.up.sql 000001_create_users_table.down.sql创建后你只需要向这两个文件中填充 SQL 内容即可。迁移文件名规范create生成的文件名遵循 migrate 全局解析规则。在 source/parse.go 中定义了文件名正则Regex regexp.MustCompile(^([0-9])_(.*)\.(up|down)\.(.*)$)即文件名必须是{version}_{title}.{up|down}.{extension}形式版本号任意 64 位无符号整数、标题仅作可读性不参与逻辑、方向up/down、扩展名如.sql。所有迁移按版本号升序执行 up降序执行 down。从源码结构看Parse函数会提取Version、Identifier、Direction字段供后续调度使用。序列号模式与时间戳模式create支持两种版本生成策略见 internal/cli/main.go 与 internal/cli/commands.go 的实现序列模式-seq默认 6 位数字-digits N可自定义位数自动取目录中已存在的最大序号并加 1nextSeqVersion逻辑。当序号位数不足时会报错提示。时间戳模式默认默认使用 Go 时间格式20060102150405即YYYYMMDDHHMMSS可通过-format指定其他 Go 时间格式或使用特殊值unix/unixNano时区默认 UTC可用-tz指定。若两个迁移落在同一时间戳createCmd会检测到duplicate migration version错误并拒绝生成。create的完整参数为-ext E扩展名必填、-dir D目录默认当前工作目录、-seq、-digits N默认 6、-format时间格式、-tz时区。此外create使用O_EXCL独占模式创建文件防止覆盖已存在的迁移。填充迁移内容幂等性与事务创建文件之后重点在于如何写出健壮的迁移内容。官方文档给出了三条关键建议1. 关注多开发者协作下的迁移一致性IMPORTANT在多人开发的项目中存在迁移不一致的风险——例如两位开发者创建了冲突的迁移而后创建迁移的那位开发者反而先合入仓库。开发团队应在代码评审时特别留意这类情况。这是真实世界的工程问题migrate 官方 issue 中有过详细讨论与总结建议团队制定明确的迁移命名与合入纪律如约定合入前检查db/migrations目录的版本冲突。2. 尽量让迁移幂等考虑让迁移具备幂等性——即同一段 SQL 连续执行两次应得到相同结果这会让迁移更健壮。但幂等也有代价它削弱了对数据库 schema 的控制。文档中的经典例子假设你忘记在 down 迁移中DROP TABLE执行 down 迁移后表仍然存在再次执行 up 迁移时普通CREATE TABLE会报错——这反而帮助你发现了 down 迁移中的问题而如果用了CREATE TABLE IF NOT EXISTS则不会报错问题被悄悄掩盖。因此是否幂等要权衡使用在确保 down 迁移正确清理的前提下再考虑用IF NOT EXISTS等幂等写法增强健壮性。3. 多条命令请用事务包裹如果一次迁移中包含多条命令/查询应将其包裹在事务中前提是你的数据库支持事务 DDL。这样一旦其中某条命令失败整个数据库保持原状避免半途而废的脏状态。从源码角度看每个数据库驱动都实现了Run等接口来执行迁移事务行为由驱动各自处理因此是否支持事务 DDL例如 PostgreSQL 支持、而某些数据库不支持取决于所选数据库。运行迁移创建并填充好迁移后通过 CLI 或你的应用来执行迁移并检查预期变更是否生效。CLI 的基本用法migrate -database YOUR_DATABASE_URL -path PATH_TO_YOUR_MIGRATIONS up-path是-sourcefile://path的简写见 internal/cli/main.go 的翻译逻辑两者等价。migrate 将迁移源本地文件系统、io/fs、GitHub、GitLab、S3、GCS 等见 README.md与数据库驱动解耦源码从 source 读取按序应用到 database。常用命令一览migrate CLI 提供的完整命令集源码见 internal/cli/main.go命令作用create ...创建一对 up/down 迁移文件goto V迁移到指定版本 Vup [N]应用全部或 N 个up 迁移down [N] [-all]应用 N 个 down 迁移-all应用全部默认需要 y/N 确认drop [-f]清空数据库全部内容默认需要确认-f跳过force V直接设置版本 V 而不执行迁移忽略 dirty 状态version打印当前迁移版本常用全局选项-source、-path、-database、-prefetch N预读迁移数默认 10、-lock-timeout N获取数据库锁的超时秒数默认 15、-verbose、-version、-help。例如只执行前两个迁移migrate -source file://path/to/migrations -database postgres://localhost:5432/database up 2若迁移托管在远程仓库source 换成对应驱动即可例如-source github://mattes:personal-access-tokenmattes/migrate_test。CLI 收到 SIGINTCtrlC时会在安全断点优雅停止通过Migrate.GracefulStop通道实现若需立即终止可发送 SIGKILL。CLI 安装方式预编译二进制、Homebrew、scoop、deb 包、go install详见 cmd/migrate/README.md。在应用代码中使用migrate 同时是 Golang 库只需把代码加进你的应用即可运行。最简单的用法源码见 README.mdimport ( github.com/golang-migrate/migrate/v4 _ github.com/golang-migrate/migrate/v4/database/postgres _ github.com/golang-migrate/migrate/v4/source/file ) func main() { m, err : migrate.New( file:///migrations, postgres://localhost:5432/database?sslmodeenable) if err ! nil { // 处理错误 } m.Up() // 或 m.Steps(2) 显式指定执行条数 }底层Migrate对象migrate.go提供了Up()、Down()、Steps(n)、Migrate(version)、Force(version)、Version()、Drop()等方法并支持PrefetchMigrations预读与LockTimeout加锁超时配置还自带优雅停止与线程安全设计。若你已有数据库连接*sql.DB可改用migrate.NewWithDatabaseInstance配合WithInstance构造驱动实例。提交前的验证流程在提交迁移之前官方建议执行完整的往返验证运行 up 迁移运行 down 迁移再次运行 up 迁移。这能确认迁移双向都正常工作。例如如果 up 迁移创建了表而对应的 down 迁移没有删除它那么再次执行 up 时就会遇到错误问题在提交前就会被发现。同时建议在独立的容器化环境中验证迁移例如结合 Docker 测试工具 dktest、dockertest 等在隔离容器里跑真实的数据库实例做冒烟测试避免污染本地开发环境。多实例部署必须使用支持锁定的数据库IMPORTANT如果要在不同机器上运行应用的多个实例务必使用支持迁移锁定的数据库否则多个实例并发执行迁移可能引发问题。这一建议与源码设计一致Migrate在执行前会调用lock()获取数据库锁DefaultLockTimeout为 15 秒超时返回ErrLockTimeout并在执行结束后释放。以 PostgreSQL 驱动为例database/postgres/postgres.go驱动会维护一张schema_migrations表version bigint not null primary key, dirty boolean not null通过SetVersion记录版本与脏标记从而为并发安全提供基础。处理失败的迁移force 命令与 dirty 状态当某条迁移执行出错时migrate 会阻止你在同一数据库上继续执行其他迁移。你会看到形如Dirty database version 1. Fix and force version的错误——这正是 migrate.go 中ErrDirty的原始文案意味着数据库已被标记为dirty脏。此时你需要调查迁移错误判断这次失败的迁移是部分应用了还是完全没应用用force命令修正版本记录使其反映数据库的真实状态migrate -path PATH_TO_YOUR_MIGRATIONS -database YOUR_DATABASE_URL force VERSION例如若错误迁移完全没执行就force回它之前的版本若它已部分执行如表已建好则force到该版本本身。修复迁移内容后再force到正确版本数据库即恢复 clean可以继续迁移。force的底层实现是Migrate.Force(version)migrate.go它直接调用驱动的SetVersion(version, false)写入版本并把 dirty 标记重置为 false不检查当前版本、不执行任何迁移因此也能忽略 dirty 状态使用。CLI 层面force V要求参数V -1-1 表示无迁移的初始版本。官方 issue 中也有针对 force 用法与示例的详细讨论可作参考。进一步阅读PostgreSQL 实战教程以 PostgreSQL 为例的完整演练迁移最佳实践文件名格式、内容格式、可逆性等深入规范FAQ常见问题解答如为什么每个迁移要分 up/down 两个文件CockroachDB 实战教程仓库源码CLI 实现见 internal/cli/main.go 与 internal/cli/commands.go核心库逻辑见 migrate.go 与 migration.go文件名解析见 source/parse.go。赞分享数据库开发工具CLI【免费下载链接】migrateDatabase migrations. CLI and Golang library.项目地址https://gitcode.com/gh_mirrors/mi/migrate点击查看免费下载相关推荐OptiScaler 错误排查指南7 类高频故障按时间轴的修复方法OptiScaler 错误排查指南7 类高频故障按时间轴的修复方法 OptiScaler 出问题时九成是配置问题而不是工具本身。本文按启动前 → 启动时图形学游戏开发树莓派上的数据库迁移使用golang-migrate/migrate管理Raspbian数据树莓派上的数据库迁移使用golang migrate/migrate管理Raspbian数据在树莓派Raspbian上开发应用时数据库结构的变更管理常数据库开发工具CLIPyfolio完整指南5个技巧掌握Python投资组合分析工具Pyfolio完整指南5个技巧掌握Python投资组合分析工具 Pyfolio是Python生态中专业的投资组合风险分析工具为投资经理和量化分析师提供全面的金融科技数据分析上一篇如何给AI助手写自定义技能OpenClaw中文社区版openclaw-cn技能开发从零到一教程下一篇为什么VS Code连续10年霸榜IDEElectronMonaco双引擎架构完全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

migrate 快速上手指南：用 CLI 与 Golang 库管理数据库迁移的全流程

相关推荐

电商进销存软件怎么用出效果？2026年多平台商家的库存数据管理实战指南

广州GEO优化公司哪家专业？2026三家服务广州AI品牌推广服务商盘点

电冷板叠片机：工业机器人协同视觉检测的叠片自动化方案

更多资讯

32位Windows 7运行Steam游戏的完整解决方案

RK3566 AIoT边缘网关：轻量智能场景选型与落地实践

具身智能协同演化动力学（37）：隐空间中的多体网络与级联动力学推演

ISCC 2023 Pwn方向实战解析：从栈溢出到堆利用的CTF进阶之路

AI应用底座：企业AI落地的关键基础设施

Handy 完全离线语音转文字：3 步装好，按快捷键说话文字直接进输入框

今日更新

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？