1. 为什么数据库初始化/更新不能靠“手搓”1.1 从一次线上“炸库”事故说起先说个真实经历。某次我负责一个Go写的内部工单系统开发阶段的数据库表结构每天都在变。当时团队人少大家约定“谁改表结构谁就在群里喊一声然后自己连上测试库执行SQL”。听起来没什么问题是吧直到有一次一位小伙伴在本地库加了一个deleted_at字段群里倒是喊了但生产环境和测试环境执行的细节不一样——测试环境加了DEFAULT NULL生产环境建的是NOT NULL。上线后老数据的deleted_at全部是零值接口直接报错一堆工单查不出来。那次事故之后我就明白了一个道理数据库结构的管理必须和代码一样有版本、有记录、有回滚手段不能依赖人的记性和自觉。尤其是Go项目编译出来就是一个二进制文件部署时数据库变更还得单独拉一份SQL去手工执行这完全违背了“一键部署”的思路。所以我开始认真调研Go生态里做 schema 初始化/更新的方案也在项目里踩了不少坑这篇文章就是把整个过程记录一下。如果你也在写Go服务或者你正在维护一个表结构经常变的小项目这篇文章会比较适合你。文章不会讲太深奥的原理重点是怎么把“初始化数据库”和“后续更新字段/索引”这两件事做得规范、可重复、可回滚。1.2 方案选型三选一背后的取舍逻辑我先花点时间说说方案选型因为很多人一上来就搜“go 数据库迁移”结果被一堆库搞晕。我当时调研了三个主流方向用下来的感受完全不同。第一个是社区讨论度很高的golang-migrate。它支持文件形式的SQL迁移.up.sql和.down.sql也支持直接写Go代码做迁移数据库方面覆盖面很广PostgreSQL、MySQL、SQLite、ClickHouse 这些都支持。更关键的是它支持go:embed可以把迁移文件直接编译进二进制部署的时候不用单独带SQL文件。第二个是dbmate。它更偏向“数据库运维工具”这个定位用起来有点类似 Rails 的 migration 体验支持自动生成迁移文件模板、执行迁移、回滚、查看状态代码量不大也有很多人在用。第三个是GORM AutoMigrate。如果你整个项目就是用 GORM 操作数据库那这个方案最省事——它根据你定义的 model 结构体自动帮你建表、加字段。但它的问题也很明显它只管“向前加”不管“向后缩”。字段改名、删除字段、加复合索引这类操作AutoMigrate 经常没法处理或处理得很隐蔽更别提数据回填了它完全做不了。我当时的选择是golang-migrate原因是它完美契合我下面这几个需求迁移文件是纯SQLreview代码的时候能直接看到数据库到底怎么变支持 down 迁移紧急回滚时有退路迁移记录写到数据库里schema_migrations表多个人、多个环境跑都不会重复执行能go:embed进二进制部署时少一个外部依赖。下表是三个方案在我心中的横向对比方便你按项目情况选对比维度golang-migratedbmateGORM AutoMigrate迁移文件形式SQL或Go代码SQL无根据model生成回滚支持支持down文件支持rollback不支持数据回填自己写SQL自己写SQL不支持嵌入二进制支持go:embed需要在容器中带文件无需文件学习成本中等较低最低适合场景团队协作、多环境、生产环境小团队、快速起步原型项目、单人项目选型这件事我多说一句如果项目刚起步表结构可能天天变用 GORM AutoMigrate 做“开发期的豆腐块工程”可以但上线前一定要换成文件形式的迁移方案。我见过不止一个项目因为依赖 AutoMigrate到了生产环境发现有两张表的字段顺序和测试环境完全不一样查了半天查不出原因最后只能手工改库。到那时你宁可当初多花半天时间把迁移体系搭好。2. 迁移文件的设计与组织2.1 从目录结构到命名规范为什么这么较真用 golang-migrate 这类工具时迁移文件本身就是一个项目的“数据库时间线”。目录结构我习惯这么组织migrations/ ├── 000001_create_users_table.up.sql ├── 000001_create_users_table.down.sql ├── 000002_add_orders_table.up.sql ├── 000002_add_orders_table.down.sql ├── 000003_add_user_email_index.up.sql ├── 000003_add_user_email_index.down.sql └── 000004_seed_initial_configs.up.sql └── 000004_seed_initial_configs.down.sql文件名的格式是固定的{版本号}_{描述}.{up|down}.sql。版本号必须是从000001开始的连续整数前面补零是为了排序时按字符串比较也能得到正确顺序。描述部分是给人看的尽量用能表达意图的短横线拼接短语比如add_orders_table、create_users_table。为什么要这么较真因为迁移文件的执行顺序完全依赖版本号的字典序。如果哪天你写了个000010和000009放一起时字典序会把它排在000002前面到时候顺序就全乱了这是最隐蔽的一个坑。每个迁移文件必须成对出现一个 up执行正向迁移、一个 down回滚。down 不一定是 up 的逆操作它的目的是“把数据库恢复到这一步之前的状态”。比如000002建了 orders 表那down文件就是DROP TABLE IF EXISTS orders;。但如果是给表加字段up 是ALTER TABLE xxx ADD COLUMN yyy ...;down 就是ALTER TABLE xxx DROP COLUMN yyy;。这里有个细节不要把多个逻辑无关的变更塞进同一个迁移文件。比如在000005里同时改了 users 表和 orders 表一旦线上执行失败dirty 状态出现回滚时你脑子里要同时记两件事很容易出错。迁移文件应该保持单一职责一个文件只做一件表结构相关的事情。1.2 版本表数据库如何记住自己“迁移到哪了”golang-migrate 首次运行时会自动创建一张版本表名字默认是schema_migrations。这张表结构很简单核心就两列version迁移版本号和dirty是否脏状态。每次执行迁移时工具会先查询这张表找到当前数据库所处版本然后按顺序把大于当前版本的 up 文件逐个执行。每成功执行一个迁移就把版本号写进版本表。执行 down 时反过来从当前版本开始先执行 down 文件再从版本表里删掉对应版本记录。为什么要特别关注这张表因为dirty状态是工具保护你的一个机制。如果一个迁移脚本执行到一半失败了工具会把版本表里的 dirty 标记为 true下次再跑任何迁移命令时它不会继续往下走而是提示你先处理脏状态。这个时候你不能直接再执行一次 migrate因为不知道上一条 SQL 到底执行到哪一步了重复执行很可能造成副作用比如重复插入数据、重复加索引。处理脏状态的正确姿势是先打开数据库看schema_migrations表里记录的 version 是多少再手动对比迁移文件内容判断失败的那条 SQL 是否已经部分执行。如果只是执行了一半需要手工把剩余 SQL 补齐然后手动把 dirty 标记改成 false或者用工具提供的 force 命令。这一步非常考验细心程度实际生产环境里大部分“迁移卡住”的问题都是这么来的。3. 从零到上线初始化与更新的完整实现3.1 第一步数据库连接与配置项的准备工作在写迁移逻辑之前得先把数据库连接搞定。Go 语言里最底层、最通用的数据库接口是database/sql配合对应数据库的 driver 使用。生产项目里基本不会直接用 ORM 来做连接而是先拿sql.DB再在上面跑迁移。我一般会在项目里单独建一个配置文件比如config.yaml内容大致如下database: host: 127.0.0.1 port: 5432 user: app_user password: ${DB_PASSWORD} dbname: myapp sslmode: require max_open_conns: 50 max_idle_conns: 10 conn_max_lifetime: 1h然后在代码里读取并拼装 DSNData Source Name用sql.Open打开连接。拿 PostgreSQL 举例func openDB(cfg *config.Database) (*sql.DB, error) { dsn : fmt.Sprintf( host%s port%d user%s password%s dbname%s sslmode%s, cfg.Host, cfg.Port, cfg.User, cfg.Password, cfg.DBName, cfg.SSLMode, ) db, err : sql.Open(postgres, dsn) if err ! nil { return nil, err } db.SetMaxOpenConns(cfg.MaxOpenConns) db.SetMaxIdleConns(cfg.MaxIdleConns) db.SetConnMaxLifetime(cfg.ConnMaxLifetime) ctx, cancel : context.WithTimeout(context.Background(), 5*time.Second) defer cancel() if err : db.PingContext(ctx); err ! nil { return nil, err } return db, nil }这里有个经验连接参数不要照抄网上的默认值。MaxOpenConns设置太大数据库连接数一多连接池和数据库端都会出现性能问题设置太小高并发下请求会排队。我这边一个中等流量的服务MaxOpenConns设置在 50 左右MaxIdleConns10压测下来比较稳定。如果你的服务依赖数据库非常频繁需要结合实际压测慢慢调没有一劳永逸的参数。3.2 初始化数据库建库、建表与基础数据一气呵成这里要区分两个概念创建数据库实例本身和创建数据库内部的表结构。golang-migrate 这类工具默认不负责“创建数据库”。比如你要连的库叫myapp但它现在还不存在那连接就失败。所以第一步一般是在代码里先连到一个不会不存在的库比如 PostgreSQL 的postgres库或者template1然后执行CREATE DATABASE myapp;。这一步可以手工执行也可以放到部署脚本里但我不建议用代码自动创建——因为这涉及权限控制生产环境通常不允许应用账号拥有创建数据库的权限。库建好之后再连到myapp库跑迁移把所有表建出来。我的做法是写一个Makefile或 shell 脚本把“建库、迁移、启动服务”串起来。迁移执行的 Go 代码大致长这样import ( log/slog net/url github.com/golang-migrate/migrate/v4 github.com/golang-migrate/migrate/v4/database/postgres _ github.com/golang-migrate/migrate/v4/source/file ) func runMigrations(db *sql.DB, migrationsPath string) error { driver, err : postgres.WithInstance(db, postgres.Config{}) if err ! nil { return err } m, err : migrate.NewWithDatabaseInstance( file://migrationsPath, postgres, driver, ) if err ! nil { return err } if err : m.Up(); err ! nil !errors.Is(err, migrate.ErrNoChange) { return err } slog.Info(database migrations applied) return nil }第一张表的迁移文件我通常这么写000001_create_users_table.up.sqlCREATE TABLE IF NOT EXISTS users ( id BIGSERIAL PRIMARY KEY, username VARCHAR(64) NOT NULL UNIQUE, email VARCHAR(128) NOT NULL UNIQUE, password_hash VARCHAR(255) NOT NULL, status SMALLINT NOT NULL DEFAULT 0, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );对应 down 文件DROP TABLE IF EXISTS users;注意我在 up 文件里写了IF NOT EXISTS这不是必须的工具本身会保证只执行一次但多写这个条件能让你在调试时手工执行文件也不容易误伤已有的表。还有个很容易被忽略的点如果在初始化阶段就要写入一些基础配置数据比如系统默认角色、管理员账号不要直接往第一个建表迁移文件里硬塞 INSERT。把建表和种子数据分开放在后面的迁移文件里比如000004_seed_initial_configs这样如果种子数据有问题你可以单独回滚那一步而不影响前面的表结构。种子数据迁移文件里up 是INSERT ... ON CONFLICT DO NOTHINGdown 则删除这些数据前提是要有明确的筛选条件千万别写无脑的DELETE FROM xxx;。3.3 增量更新的正确姿势加字段、改索引、数据回填项目上线后表结构更新就是常规操作了。大部分“更新”无非三类加字段、加索引、给已有数据做回填。这三类我分开说说具体写法。第一种加字段。up 文件ALTER TABLE users ADD COLUMN nickname VARCHAR(64) NOT NULL DEFAULT ;down 文件ALTER TABLE users DROP COLUMN nickname;这里有一个非常关键的注意点给已有大量数据的表加字段时用NOT NULL DEFAULT会导致全表重写线上会锁表。如果是小表几千行无所谓但如果表里有几百万行这个操作在生产环境可能跑几分钟甚至更久。我处理这种问题的经验是分两步走先加一个允许 NULL 的列ADD COLUMN nickname VARCHAR(64)等业务代码兼容了空值之后再做一次填充和加约束的迁移。第二种加索引。up 文件CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_created_at ON users (created_at);加CONCURRENTLY这个关键字是为了让建索引的过程不阻塞读写。但注意golang-migrate 执行 SQL 时如果开了事务CONCURRENTLY会报错它不能在事务块里执行。好在 golang-migrate 对纯SQL迁移默认就是非事务模式直接跑没问题。如果你用的是其他工具可能需要手动把迁移配置改成非事务。第三种数据回填。比如你给orders表加了total_amount字段需要把order_items汇总出来填进去。这种回填逻辑我建议先写成 SELECT 语句在测试库上反复模拟确认数据没问题再放进迁移文件。up 文件可能长这样UPDATE orders o SET total_amount sub.total FROM ( SELECT order_id, SUM(amount) AS total FROM order_items GROUP BY order_id ) sub WHERE sub.order_id o.id AND o.total_amount IS NULL;down 文件就把total_amount更新回 NULLUPDATE orders SET total_amount NULL WHERE total_amount IS NOT NULL;数据回填类的迁移最怕的是幂等性不好。如果某条 SQL 执行到一半失败重跑时会重复更新结果可能就错了。所以写这类迁移时一定要加一个“只处理目标状态数据”的条件比如上面的AND o.total_amount IS NULL让它能安全地重复执行。3.4 在 Docker/Kubernetes 里跑迁移的注意事项如果你的 Go 服务最终部署在容器里迁移的执行时机很关键。我见过不少团队把迁移逻辑和服务启动放一起进程一启动就执行m.Up()然后才开始接收流量。如果是单副本部署这种方式勉强能跑一旦多副本同时启动多个实例会同时尝试执行迁移虽然工具内部有锁但并发场景下经常出现各种怪异的报错。更推荐的做法是把迁移放到独立的初始化容器Init Container里执行主服务容器等迁移完成后再启动。每次发布新版本时先跑迁移容器再滚动更新业务容器。这样能保证整个发布过程是串行的不会出现业务代码已经更新了但数据库结构还没变的情况。还有一个小细节迁移文件必须打进镜像里。用go:embed是最好的不用留一个外部目录如果项目里不方便 embed也要在 Dockerfile 里显式COPY migrations/ /app/migrations/并且要注意相对路径问题。路径错是迁移执行报错里最常见的原因之一排查看日志很容易忽略。4. 常见问题与排查技巧实录4.1 问题速查表以下是我在实际跑迁移时遇到过的典型问题整理成一张速查表方便你直接对照排查现象可能原因处理方式迁移执行报错No change当前版本已经等于目标版本不要太意外这是正常提示确认目标版本正确即可Dirty database version X上个迁移文件执行中失败版本表 dirty 置为 true先查schema_migrations手工检查已执行了哪些SQL手动修复后 force 版本号Timeout 45s reached某条 DDL 锁表等待过久检查是否有长事务占用锁把 lock_timeout 调大或拆小迁移步骤迁移文件顺序乱了版本号写了不等长数字比如1和10统一补零为 6 位或 8 位数字编号Embedding static files报路径错代码里 embed 目录与实际迁移目录不匹配仔细核对 embed 指令的路径注意 go:embed 不支持父目录引用语句执行成功但版本表未更新工具处于非事务模式时中途失败不会记录版本手动处理剩余语句手工维护版本表记录排障的总原则是不要慌先开个数据库可视化工具看版本表和表结构的实际状态再决定重跑还是手工修。最忌讳的就是不分析原因直接删掉schema_migrations表或者手工把 version 改大那等于放弃了整个迁移体系的信任基础。4.2 亲自踩过的几个典型坑这里多写几段我亲自踩坑的细节给读者一个更具体的参考。坑一回滚脚本写反了。某次我在down文件里本来想删掉刚加的nickname列结果手滑写成了DELETE FROM users WHERE nickname IS NOT NULL;一执行下去差点把整张表的数据全清掉。还好当时是在开发库上测试回滚数据可以随便造。这件事给我的教训是down 文件不等于 up 文件的反向镜像它操作的对象是“数据”写的时候要像写生产 SQL 一样小心翼翼最好先在测试库跑一遍。坑二把业务数据的修复合到了 schema 迁移里。有一次某个线上 bug 需要通过 SQL 修正一批脏数据当时图省事直接在迁移文件里写了修复逻辑。结果后来需要回滚这次版本down 文件只能把表结构调整回去但脏数据修复无法“恢复原样”导致线上数据状态比回滚前更乱。从这个事以后我严格区分两类操作schema 变更走迁移体系数据修复走单独的数据订正脚本数据订正脚本不进版本迁移体系而是用独立工具记录执行状态。坑三建索引没有用CONCURRENTLY导致线上服务抖动。这个是在一个千万级数据量的订单表上发生的当时直接CREATE INDEX idx_orders_user_id ON orders(user_id);这个操作会阻塞表的写入线上业务监控立刻报警接口延迟飙高。从那次之后凡是新建索引只要目标表的数据量可能超过10万行我都默认用CONCURRENTLY并且把超时时间拉长。坑四多实例并发执行迁移出现莫名其妙的脏状态。之前有段时间迁移代码写在服务启动阶段结果发布新版本时同时多个副本实例一起执行迁移就遇到了schema_migrations表被锁、dirty 状态被反复置位的情况。后来把迁移抽成独立的初始化容器这个问题再没出现过。坑五embed 迁移目录后忘记重新编译镜像。这是个很蠢但很容易犯的错误本地测试时迁移文件直接指向本地磁盘目录一切正常部署时改用go:embed后总觉得改一下 SQL 文件代码能自动生效结果忘记重新编译镜像上线时压根没有包含最新的迁移文件。解决方案也没什么高深的就是在 CI 的构建流程里加一步检查确保镜像内的迁移文件 hash 和仓库中最新代码一致。4.3 几个我现在的固定操作习惯写到这里可以聊点我最终沉淀下来的工作习惯。这些习惯谈不上多高明但是能省掉不少救火的时间。第一每次写迁移前先看当前环境的状态。我习惯在本地开发时准备一个Makefile目标make db-status执行后输出当前所有环境本地、测试、生产的版本号。上线前一定先跑一遍确认生产库停在哪个版本再决定发布哪几个新迁移。第二迁移文件提交前先在新环境跑一遍完整流程。我会用一个临时数据库从空的CREATE DATABASE开始把全部迁移文件 up 跑一遍再全部 down 跑一遍确认加了一个新迁移后整个链路是通的。这在多人协作的项目里特别重要因为别人可能已经在上游加了几个迁移文件你不完整跑一遍根本不知道会不会跟自己的变更冲突。第三给迁移文件加一行注释说明变更动机。纯SQL迁移文件本身没有描述字段我习惯在文件开头写两句注释比如-- 原因订单列表页需要按创建时间筛选查询频率高 -- 影响订单表数据量约 500 万行使用 CONCURRENTLY 避免阻塞写入 CREATE INDEX CONCURRENTLY idx_orders_created_at ON orders (created_at);这行注释在两个人同时 review 迁移文件时价值极高能把“这段SQL是谁为了什么加的”这个信息保留下来而不是靠群聊记录去翻。第四迁移版本号尽量保持连续但不强求。如果你的迁移文件版本号是 1、2、3、4突然同事合并进来一个 5你本地可能没有 5这没事。但如果你的本地有一个 4同事也写了一个 4那合并时就麻烦了。所以我现在会尽量让每个人在自己的分支上用“一个足够大的独立区间”来编号比如你这次分支从000020开始他用000030开始冲突概率就小很多。5. 从一次“成功迁移”中学到的心态其实写数据库迁移这个事做到后来会发现技术本身并不难——难的是在出现意外时保持冷静用体系化的方式去处理问题。我现在的固定动作是任何一次迁移成功后都会打开数据库确认三件事版本表里的版本号是否正确、关键表的数据行数是否符合预期、down 文件是否已经验证过。确认完了再考虑发布业务服务。这一步看着笨但确实帮我拦住过好几次“迁移成功但数据不对”的隐性事故。如果你看完这篇记录也打算给自己的Go项目搭一套数据库迁移体系建议第一步别急着写代码先把你当前库里的表结构导出成一份初始化SQL作为第一个迁移文件然后在开发环境里把整个项目从零初始化一遍。跑通了再继续往下加新的迁移。这个过程不需要很复杂但能让你在最开始就建立“数据库有版本”的意识而不是继续依赖记忆和群消息。 
长河君 · 2026/10/21 15:24:47 · 阅读 1.2k Go项目数据库迁移实战：用golang-migrate实现版本控制与安全回滚
1. 为什么数据库初始化/更新不能靠“手搓”1.1 从一次线上“炸库”事故说起先说个真实经历。某次我负责一个Go写的内部工单系统开发阶段的数据库表结构每天都在变。当时团队人少大家约定“谁改表结构谁就在群里喊一声然后自己连上测试库执行SQL”。听起来没什么问题是吧直到有一次一位小伙伴在本地库加了一个deleted_at字段群里倒是喊了但生产环境和测试环境执行的细节不一样——测试环境加了DEFAULT NULL生产环境建的是NOT NULL。上线后老数据的deleted_at全部是零值接口直接报错一堆工单查不出来。那次事故之后我就明白了一个道理数据库结构的管理必须和代码一样有版本、有记录、有回滚手段不能依赖人的记性和自觉。尤其是Go项目编译出来就是一个二进制文件部署时数据库变更还得单独拉一份SQL去手工执行这完全违背了“一键部署”的思路。所以我开始认真调研Go生态里做 schema 初始化/更新的方案也在项目里踩了不少坑这篇文章就是把整个过程记录一下。如果你也在写Go服务或者你正在维护一个表结构经常变的小项目这篇文章会比较适合你。文章不会讲太深奥的原理重点是怎么把“初始化数据库”和“后续更新字段/索引”这两件事做得规范、可重复、可回滚。1.2 方案选型三选一背后的取舍逻辑我先花点时间说说方案选型因为很多人一上来就搜“go 数据库迁移”结果被一堆库搞晕。我当时调研了三个主流方向用下来的感受完全不同。第一个是社区讨论度很高的golang-migrate。它支持文件形式的SQL迁移.up.sql和.down.sql也支持直接写Go代码做迁移数据库方面覆盖面很广PostgreSQL、MySQL、SQLite、ClickHouse 这些都支持。更关键的是它支持go:embed可以把迁移文件直接编译进二进制部署的时候不用单独带SQL文件。第二个是dbmate。它更偏向“数据库运维工具”这个定位用起来有点类似 Rails 的 migration 体验支持自动生成迁移文件模板、执行迁移、回滚、查看状态代码量不大也有很多人在用。第三个是GORM AutoMigrate。如果你整个项目就是用 GORM 操作数据库那这个方案最省事——它根据你定义的 model 结构体自动帮你建表、加字段。但它的问题也很明显它只管“向前加”不管“向后缩”。字段改名、删除字段、加复合索引这类操作AutoMigrate 经常没法处理或处理得很隐蔽更别提数据回填了它完全做不了。我当时的选择是golang-migrate原因是它完美契合我下面这几个需求迁移文件是纯SQLreview代码的时候能直接看到数据库到底怎么变支持 down 迁移紧急回滚时有退路迁移记录写到数据库里schema_migrations表多个人、多个环境跑都不会重复执行能go:embed进二进制部署时少一个外部依赖。下表是三个方案在我心中的横向对比方便你按项目情况选对比维度golang-migratedbmateGORM AutoMigrate迁移文件形式SQL或Go代码SQL无根据model生成回滚支持支持down文件支持rollback不支持数据回填自己写SQL自己写SQL不支持嵌入二进制支持go:embed需要在容器中带文件无需文件学习成本中等较低最低适合场景团队协作、多环境、生产环境小团队、快速起步原型项目、单人项目选型这件事我多说一句如果项目刚起步表结构可能天天变用 GORM AutoMigrate 做“开发期的豆腐块工程”可以但上线前一定要换成文件形式的迁移方案。我见过不止一个项目因为依赖 AutoMigrate到了生产环境发现有两张表的字段顺序和测试环境完全不一样查了半天查不出原因最后只能手工改库。到那时你宁可当初多花半天时间把迁移体系搭好。2. 迁移文件的设计与组织2.1 从目录结构到命名规范为什么这么较真用 golang-migrate 这类工具时迁移文件本身就是一个项目的“数据库时间线”。目录结构我习惯这么组织migrations/ ├── 000001_create_users_table.up.sql ├── 000001_create_users_table.down.sql ├── 000002_add_orders_table.up.sql ├── 000002_add_orders_table.down.sql ├── 000003_add_user_email_index.up.sql ├── 000003_add_user_email_index.down.sql └── 000004_seed_initial_configs.up.sql └── 000004_seed_initial_configs.down.sql文件名的格式是固定的{版本号}_{描述}.{up|down}.sql。版本号必须是从000001开始的连续整数前面补零是为了排序时按字符串比较也能得到正确顺序。描述部分是给人看的尽量用能表达意图的短横线拼接短语比如add_orders_table、create_users_table。为什么要这么较真因为迁移文件的执行顺序完全依赖版本号的字典序。如果哪天你写了个000010和000009放一起时字典序会把它排在000002前面到时候顺序就全乱了这是最隐蔽的一个坑。每个迁移文件必须成对出现一个 up执行正向迁移、一个 down回滚。down 不一定是 up 的逆操作它的目的是“把数据库恢复到这一步之前的状态”。比如000002建了 orders 表那down文件就是DROP TABLE IF EXISTS orders;。但如果是给表加字段up 是ALTER TABLE xxx ADD COLUMN yyy ...;down 就是ALTER TABLE xxx DROP COLUMN yyy;。这里有个细节不要把多个逻辑无关的变更塞进同一个迁移文件。比如在000005里同时改了 users 表和 orders 表一旦线上执行失败dirty 状态出现回滚时你脑子里要同时记两件事很容易出错。迁移文件应该保持单一职责一个文件只做一件表结构相关的事情。1.2 版本表数据库如何记住自己“迁移到哪了”golang-migrate 首次运行时会自动创建一张版本表名字默认是schema_migrations。这张表结构很简单核心就两列version迁移版本号和dirty是否脏状态。每次执行迁移时工具会先查询这张表找到当前数据库所处版本然后按顺序把大于当前版本的 up 文件逐个执行。每成功执行一个迁移就把版本号写进版本表。执行 down 时反过来从当前版本开始先执行 down 文件再从版本表里删掉对应版本记录。为什么要特别关注这张表因为dirty状态是工具保护你的一个机制。如果一个迁移脚本执行到一半失败了工具会把版本表里的 dirty 标记为 true下次再跑任何迁移命令时它不会继续往下走而是提示你先处理脏状态。这个时候你不能直接再执行一次 migrate因为不知道上一条 SQL 到底执行到哪一步了重复执行很可能造成副作用比如重复插入数据、重复加索引。处理脏状态的正确姿势是先打开数据库看schema_migrations表里记录的 version 是多少再手动对比迁移文件内容判断失败的那条 SQL 是否已经部分执行。如果只是执行了一半需要手工把剩余 SQL 补齐然后手动把 dirty 标记改成 false或者用工具提供的 force 命令。这一步非常考验细心程度实际生产环境里大部分“迁移卡住”的问题都是这么来的。3. 从零到上线初始化与更新的完整实现3.1 第一步数据库连接与配置项的准备工作在写迁移逻辑之前得先把数据库连接搞定。Go 语言里最底层、最通用的数据库接口是database/sql配合对应数据库的 driver 使用。生产项目里基本不会直接用 ORM 来做连接而是先拿sql.DB再在上面跑迁移。我一般会在项目里单独建一个配置文件比如config.yaml内容大致如下database: host: 127.0.0.1 port: 5432 user: app_user password: ${DB_PASSWORD} dbname: myapp sslmode: require max_open_conns: 50 max_idle_conns: 10 conn_max_lifetime: 1h然后在代码里读取并拼装 DSNData Source Name用sql.Open打开连接。拿 PostgreSQL 举例func openDB(cfg *config.Database) (*sql.DB, error) { dsn : fmt.Sprintf( host%s port%d user%s password%s dbname%s sslmode%s, cfg.Host, cfg.Port, cfg.User, cfg.Password, cfg.DBName, cfg.SSLMode, ) db, err : sql.Open(postgres, dsn) if err ! nil { return nil, err } db.SetMaxOpenConns(cfg.MaxOpenConns) db.SetMaxIdleConns(cfg.MaxIdleConns) db.SetConnMaxLifetime(cfg.ConnMaxLifetime) ctx, cancel : context.WithTimeout(context.Background(), 5*time.Second) defer cancel() if err : db.PingContext(ctx); err ! nil { return nil, err } return db, nil }这里有个经验连接参数不要照抄网上的默认值。MaxOpenConns设置太大数据库连接数一多连接池和数据库端都会出现性能问题设置太小高并发下请求会排队。我这边一个中等流量的服务MaxOpenConns设置在 50 左右MaxIdleConns10压测下来比较稳定。如果你的服务依赖数据库非常频繁需要结合实际压测慢慢调没有一劳永逸的参数。3.2 初始化数据库建库、建表与基础数据一气呵成这里要区分两个概念创建数据库实例本身和创建数据库内部的表结构。golang-migrate 这类工具默认不负责“创建数据库”。比如你要连的库叫myapp但它现在还不存在那连接就失败。所以第一步一般是在代码里先连到一个不会不存在的库比如 PostgreSQL 的postgres库或者template1然后执行CREATE DATABASE myapp;。这一步可以手工执行也可以放到部署脚本里但我不建议用代码自动创建——因为这涉及权限控制生产环境通常不允许应用账号拥有创建数据库的权限。库建好之后再连到myapp库跑迁移把所有表建出来。我的做法是写一个Makefile或 shell 脚本把“建库、迁移、启动服务”串起来。迁移执行的 Go 代码大致长这样import ( log/slog net/url github.com/golang-migrate/migrate/v4 github.com/golang-migrate/migrate/v4/database/postgres _ github.com/golang-migrate/migrate/v4/source/file ) func runMigrations(db *sql.DB, migrationsPath string) error { driver, err : postgres.WithInstance(db, postgres.Config{}) if err ! nil { return err } m, err : migrate.NewWithDatabaseInstance( file://migrationsPath, postgres, driver, ) if err ! nil { return err } if err : m.Up(); err ! nil !errors.Is(err, migrate.ErrNoChange) { return err } slog.Info(database migrations applied) return nil }第一张表的迁移文件我通常这么写000001_create_users_table.up.sqlCREATE TABLE IF NOT EXISTS users ( id BIGSERIAL PRIMARY KEY, username VARCHAR(64) NOT NULL UNIQUE, email VARCHAR(128) NOT NULL UNIQUE, password_hash VARCHAR(255) NOT NULL, status SMALLINT NOT NULL DEFAULT 0, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );对应 down 文件DROP TABLE IF EXISTS users;注意我在 up 文件里写了IF NOT EXISTS这不是必须的工具本身会保证只执行一次但多写这个条件能让你在调试时手工执行文件也不容易误伤已有的表。还有个很容易被忽略的点如果在初始化阶段就要写入一些基础配置数据比如系统默认角色、管理员账号不要直接往第一个建表迁移文件里硬塞 INSERT。把建表和种子数据分开放在后面的迁移文件里比如000004_seed_initial_configs这样如果种子数据有问题你可以单独回滚那一步而不影响前面的表结构。种子数据迁移文件里up 是INSERT ... ON CONFLICT DO NOTHINGdown 则删除这些数据前提是要有明确的筛选条件千万别写无脑的DELETE FROM xxx;。3.3 增量更新的正确姿势加字段、改索引、数据回填项目上线后表结构更新就是常规操作了。大部分“更新”无非三类加字段、加索引、给已有数据做回填。这三类我分开说说具体写法。第一种加字段。up 文件ALTER TABLE users ADD COLUMN nickname VARCHAR(64) NOT NULL DEFAULT ;down 文件ALTER TABLE users DROP COLUMN nickname;这里有一个非常关键的注意点给已有大量数据的表加字段时用NOT NULL DEFAULT会导致全表重写线上会锁表。如果是小表几千行无所谓但如果表里有几百万行这个操作在生产环境可能跑几分钟甚至更久。我处理这种问题的经验是分两步走先加一个允许 NULL 的列ADD COLUMN nickname VARCHAR(64)等业务代码兼容了空值之后再做一次填充和加约束的迁移。第二种加索引。up 文件CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_created_at ON users (created_at);加CONCURRENTLY这个关键字是为了让建索引的过程不阻塞读写。但注意golang-migrate 执行 SQL 时如果开了事务CONCURRENTLY会报错它不能在事务块里执行。好在 golang-migrate 对纯SQL迁移默认就是非事务模式直接跑没问题。如果你用的是其他工具可能需要手动把迁移配置改成非事务。第三种数据回填。比如你给orders表加了total_amount字段需要把order_items汇总出来填进去。这种回填逻辑我建议先写成 SELECT 语句在测试库上反复模拟确认数据没问题再放进迁移文件。up 文件可能长这样UPDATE orders o SET total_amount sub.total FROM ( SELECT order_id, SUM(amount) AS total FROM order_items GROUP BY order_id ) sub WHERE sub.order_id o.id AND o.total_amount IS NULL;down 文件就把total_amount更新回 NULLUPDATE orders SET total_amount NULL WHERE total_amount IS NOT NULL;数据回填类的迁移最怕的是幂等性不好。如果某条 SQL 执行到一半失败重跑时会重复更新结果可能就错了。所以写这类迁移时一定要加一个“只处理目标状态数据”的条件比如上面的AND o.total_amount IS NULL让它能安全地重复执行。3.4 在 Docker/Kubernetes 里跑迁移的注意事项如果你的 Go 服务最终部署在容器里迁移的执行时机很关键。我见过不少团队把迁移逻辑和服务启动放一起进程一启动就执行m.Up()然后才开始接收流量。如果是单副本部署这种方式勉强能跑一旦多副本同时启动多个实例会同时尝试执行迁移虽然工具内部有锁但并发场景下经常出现各种怪异的报错。更推荐的做法是把迁移放到独立的初始化容器Init Container里执行主服务容器等迁移完成后再启动。每次发布新版本时先跑迁移容器再滚动更新业务容器。这样能保证整个发布过程是串行的不会出现业务代码已经更新了但数据库结构还没变的情况。还有一个小细节迁移文件必须打进镜像里。用go:embed是最好的不用留一个外部目录如果项目里不方便 embed也要在 Dockerfile 里显式COPY migrations/ /app/migrations/并且要注意相对路径问题。路径错是迁移执行报错里最常见的原因之一排查看日志很容易忽略。4. 常见问题与排查技巧实录4.1 问题速查表以下是我在实际跑迁移时遇到过的典型问题整理成一张速查表方便你直接对照排查现象可能原因处理方式迁移执行报错No change当前版本已经等于目标版本不要太意外这是正常提示确认目标版本正确即可Dirty database version X上个迁移文件执行中失败版本表 dirty 置为 true先查schema_migrations手工检查已执行了哪些SQL手动修复后 force 版本号Timeout 45s reached某条 DDL 锁表等待过久检查是否有长事务占用锁把 lock_timeout 调大或拆小迁移步骤迁移文件顺序乱了版本号写了不等长数字比如1和10统一补零为 6 位或 8 位数字编号Embedding static files报路径错代码里 embed 目录与实际迁移目录不匹配仔细核对 embed 指令的路径注意 go:embed 不支持父目录引用语句执行成功但版本表未更新工具处于非事务模式时中途失败不会记录版本手动处理剩余语句手工维护版本表记录排障的总原则是不要慌先开个数据库可视化工具看版本表和表结构的实际状态再决定重跑还是手工修。最忌讳的就是不分析原因直接删掉schema_migrations表或者手工把 version 改大那等于放弃了整个迁移体系的信任基础。4.2 亲自踩过的几个典型坑这里多写几段我亲自踩坑的细节给读者一个更具体的参考。坑一回滚脚本写反了。某次我在down文件里本来想删掉刚加的nickname列结果手滑写成了DELETE FROM users WHERE nickname IS NOT NULL;一执行下去差点把整张表的数据全清掉。还好当时是在开发库上测试回滚数据可以随便造。这件事给我的教训是down 文件不等于 up 文件的反向镜像它操作的对象是“数据”写的时候要像写生产 SQL 一样小心翼翼最好先在测试库跑一遍。坑二把业务数据的修复合到了 schema 迁移里。有一次某个线上 bug 需要通过 SQL 修正一批脏数据当时图省事直接在迁移文件里写了修复逻辑。结果后来需要回滚这次版本down 文件只能把表结构调整回去但脏数据修复无法“恢复原样”导致线上数据状态比回滚前更乱。从这个事以后我严格区分两类操作schema 变更走迁移体系数据修复走单独的数据订正脚本数据订正脚本不进版本迁移体系而是用独立工具记录执行状态。坑三建索引没有用CONCURRENTLY导致线上服务抖动。这个是在一个千万级数据量的订单表上发生的当时直接CREATE INDEX idx_orders_user_id ON orders(user_id);这个操作会阻塞表的写入线上业务监控立刻报警接口延迟飙高。从那次之后凡是新建索引只要目标表的数据量可能超过10万行我都默认用CONCURRENTLY并且把超时时间拉长。坑四多实例并发执行迁移出现莫名其妙的脏状态。之前有段时间迁移代码写在服务启动阶段结果发布新版本时同时多个副本实例一起执行迁移就遇到了schema_migrations表被锁、dirty 状态被反复置位的情况。后来把迁移抽成独立的初始化容器这个问题再没出现过。坑五embed 迁移目录后忘记重新编译镜像。这是个很蠢但很容易犯的错误本地测试时迁移文件直接指向本地磁盘目录一切正常部署时改用go:embed后总觉得改一下 SQL 文件代码能自动生效结果忘记重新编译镜像上线时压根没有包含最新的迁移文件。解决方案也没什么高深的就是在 CI 的构建流程里加一步检查确保镜像内的迁移文件 hash 和仓库中最新代码一致。4.3 几个我现在的固定操作习惯写到这里可以聊点我最终沉淀下来的工作习惯。这些习惯谈不上多高明但是能省掉不少救火的时间。第一每次写迁移前先看当前环境的状态。我习惯在本地开发时准备一个Makefile目标make db-status执行后输出当前所有环境本地、测试、生产的版本号。上线前一定先跑一遍确认生产库停在哪个版本再决定发布哪几个新迁移。第二迁移文件提交前先在新环境跑一遍完整流程。我会用一个临时数据库从空的CREATE DATABASE开始把全部迁移文件 up 跑一遍再全部 down 跑一遍确认加了一个新迁移后整个链路是通的。这在多人协作的项目里特别重要因为别人可能已经在上游加了几个迁移文件你不完整跑一遍根本不知道会不会跟自己的变更冲突。第三给迁移文件加一行注释说明变更动机。纯SQL迁移文件本身没有描述字段我习惯在文件开头写两句注释比如-- 原因订单列表页需要按创建时间筛选查询频率高 -- 影响订单表数据量约 500 万行使用 CONCURRENTLY 避免阻塞写入 CREATE INDEX CONCURRENTLY idx_orders_created_at ON orders (created_at);这行注释在两个人同时 review 迁移文件时价值极高能把“这段SQL是谁为了什么加的”这个信息保留下来而不是靠群聊记录去翻。第四迁移版本号尽量保持连续但不强求。如果你的迁移文件版本号是 1、2、3、4突然同事合并进来一个 5你本地可能没有 5这没事。但如果你的本地有一个 4同事也写了一个 4那合并时就麻烦了。所以我现在会尽量让每个人在自己的分支上用“一个足够大的独立区间”来编号比如你这次分支从000020开始他用000030开始冲突概率就小很多。5. 从一次“成功迁移”中学到的心态其实写数据库迁移这个事做到后来会发现技术本身并不难——难的是在出现意外时保持冷静用体系化的方式去处理问题。我现在的固定动作是任何一次迁移成功后都会打开数据库确认三件事版本表里的版本号是否正确、关键表的数据行数是否符合预期、down 文件是否已经验证过。确认完了再考虑发布业务服务。这一步看着笨但确实帮我拦住过好几次“迁移成功但数据不对”的隐性事故。如果你看完这篇记录也打算给自己的Go项目搭一套数据库迁移体系建议第一步别急着写代码先把你当前库里的表结构导出成一份初始化SQL作为第一个迁移文件然后在开发环境里把整个项目从零初始化一遍。跑通了再继续往下加新的迁移。这个过程不需要很复杂但能让你在最开始就建立“数据库有版本”的意识而不是继续依赖记忆和群消息。