本文说明数据库结构的版本化管理与落地方式。持久层框架与事务边界见 持久层:JDBC、连接池与事务,DBA 视角的变更方案与线上在线 DDL 见 mysql: Schema 变更与运维,分片环境下的变更差异见 分库分表与全局 ID,应用启动与配置管理见 Spring Boot 实践,流水线中的执行位置见 Gradle 与 CI 流水线。
一、起源
1.1 手工执行 SQL 带来的三类问题
在引入迁移工具之前,结构变更通常由人工在数据库客户端执行脚本,问题集中在三处:
| 问题 | 表现 | 后果 |
|---|---|---|
| 无记录 | 无法确定某个环境当前处于哪个结构版本 | 发布前需要人工比对,遗漏必然发生 |
| 无顺序保证 | 多个环境的执行顺序与内容不一致 | 测试环境通过而生产失败,且失败点难以复现 |
| 无校验 | 同一版本的文件被修改后无人察觉 | 已执行过的脚本被再次执行或执行了变更后的内容 |
根本原因是:应用代码有版本控制与流水线,数据库结构只有一堆散落的 SQL 文件。
1.2 需要被管理的内容
| 内容 | 是否适合版本化 | 说明 |
|---|---|---|
| 表与列的定义 | 适合 | 结构变更的主体 |
| 索引与约束 | 适合 | 与结构同源 |
| 视图与存储过程 | 适合 | 用可重复脚本表达 |
| 基础字典数据 | 适合 | 需要稳定主键的枚举类数据 |
| 业务数据修补 | 有限适合 | 应拆成独立的一次性脚本,避免与结构变更混在一起 |
| 分区与权限 | 视环境而定 | 通常由 DBA 与环境配置管理,不进入应用迁移 |
1.3 取舍
- 由应用启动时自动迁移:部署简单、环境一致,风险是把结构变更与发布强绑定,长耗时的表变更会拖长启动时间甚至导致启动失败。
- 由流水线在发布前单独执行:可控、可观测,代价是流水线需要数据库凭据与网络权限,且必须处理"代码已发布但结构未变更"的顺序问题。
- 结论:小变更随应用启动执行,大表变更与需要停机窗口的变更走单独的变更流程,并在应用启动前完成。
二、原理
2.1 版本化迁移的基本模型
所有迁移工具遵循同一模型:
- 迁移文件按版本号排序,文件名中包含版本与描述。
- 数据库中维护一张版本表,记录已执行版本、执行时间、执行者与校验和。
- 每次启动或执行时,先读取版本表,再计算待执行集合,按顺序执行并写回记录。
- 执行前校验已应用文件的校验和,不一致时报错而不是继续执行。
模型带来的两个保证:已执行的版本不会重复执行(除非被标记为可重复),以及文件的任意修改都会被检测到。
2.2 Flyway 的工作方式
| 脚本类型 | 命名形式 | 执行时机 | 适用 |
|---|---|---|---|
| 版本化脚本 | V1__create_order.sql | 按版本号升序,每个只执行一次 | 表结构变更、一次性数据变更 |
| 可重复脚本 | R__order_view.sql | 在全部版本化脚本之后执行,校验和变化时重新执行 | 视图、存储过程、函数 |
| 撤销脚本 | U1__create_order.sql | 需商业版本支持 | 回滚上一个版本 |
关键机制:
- 版本号支持点分形式(
V1.1、V1.2.3),实际使用时建议只使用递增整数,避免版本比较规则带来的歧义。 - 版本表默认名为
flyway_schema_history,记录每条迁移的校验和与执行结果。 baselineOnMigrate:面对已有数据的库时,先用基线版本标记当前位置,使迁移从基线之后开始,避免把历史结构重复创建。outOfOrder:允许执行版本号低于当前最大版本的迁移,仅在多人并行开发且分支合并顺序混乱时开启,生产环境应保持关闭。- 并发保护:迁移过程会对版本表加锁,多个实例同时启动时只有一个执行迁移,其余等待。这是多副本部署下必须依赖的机制。
2.3 Liquibase 的工作方式
Liquibase 以 changeset 为最小单元,用 changelog 文件组织。
- 每个 changeset 由
id与author唯一标识,执行记录写入DATABASECHANGELOG,锁记录写入DATABASECHANGELOGLOCK。 - 变更用抽象语法描述(
addColumn、createIndex),由工具生成目标数据库的方言 SQL,因此同一份 changelog 可以作用在多种数据库上。 - 支持
contexts与labels按环境或标签选择性执行,支持preconditions在变更前声明前置条件(如"表不存在时才创建")。 - 原生支持回滚:
rollback块显式声明回滚动作,也支持按标签或数量回滚。 - 提供
diff与generateChangeLog,可以把现有库结构与 changelog 做差异比较。
2.4 两者对比与选型
| 维度 | Flyway | Liquibase |
|---|---|---|
| 变更表达 | 原生 SQL 为主,贴近数据库实际行为 | 抽象语法为主,可生成方言 SQL |
| 多数据库支持 | 需要为不同数据库分别编写 SQL | 一份 changelog 适配多种数据库 |
| 回滚 | 撤销脚本需商业版本 | 原生支持 |
| 学习成本 | 低,会写 SQL 即可上手 | 较高,需要理解 changelog 结构与抽象语法 |
| 可控性 | 高,执行的就是手写的 SQL | 中,需确认生成的 SQL 是否符合预期 |
| 适用 | 数据库类型单一、团队熟悉 SQL 的场景 | 需要多数据库适配或强依赖回滚能力的场景 |
选型依据:多数 Java 项目只使用一种数据库,直接用原生 SQL 表达变更的确定性更高,因此 Flyway 更常见;只有在确实需要多数据库适配时才值得承担抽象语法带来的间接性。
2.5 与 ORM 的关系
ORM 的自动建表能力(如 ddl-auto=update)不能替代迁移工具:
| 问题 | 说明 |
|---|---|
| 不可审计 | 生成的结构变更没有记录,无法预先评审 |
| 不可预知 | 生成策略随版本变化,变更内容不受控制 |
| 不会删除 | 多数情况下只增不减,遗留字段持续累积 |
| 无法表达数据变更 | 数据回填与清洗不在其能力范围 |
| 无顺序保证 | 多实例并发启动时可能同时执行 DDL |
生产环境的正确设置是把自动建表关闭,改为启动时校验实体与结构是否一致(ddl-auto=validate),不一致时直接启动失败,使问题在发布阶段暴露。
2.6 并发执行与多实例
- 多副本部署时,多个实例会同时尝试迁移。工具通过版本表上的锁保证只有一个执行,其余实例等待锁释放后再检查。
- 因此迁移时间会成为启动时间的一部分:长耗时的表变更会让等待的实例启动超时,被编排系统判定为启动失败并反复重启。
- 处理方式:把耗时变更从启动路径中移出,改为流水线中的独立步骤;或临时把副本数调为 1 完成变更后再恢复。
2.7 不可回滚的变更
部分变更在技术上无法通过反向 SQL 恢复:
| 变更 | 为什么不可回滚 | 处理方式 |
|---|---|---|
| 删除列 | 数据已丢失 | 先停止写入并观察,确认无依赖后再删除,删除本身作为独立发布 |
| 修改列类型 | 精度或范围可能已被截断 | 新增列并回填,切换读写后再删除旧列 |
| 数据清理与合并 | 原始数据被覆盖 | 变更前保留备份表或导出快照 |
| 修改字符集或排序规则 | 索引与比较行为变化 | 在影子表上完成变更后切换 |
原则:结构变更优先使用"新增、回填、切换、清理"四步,而不是就地修改;只有确认无数据风险的变更才允许直接改。
2.8 大表变更与在线 DDL
- 部分 DDL 在数据库内可以原位完成(不重建表),部分必须重建表并复制数据,后者在大表上会长时间持锁。
- MySQL 支持通过
ALGORITHM与LOCK子句声明期望的执行方式,若无法按声明方式执行则直接报错,使风险提前暴露而不是在线上长时间锁表。 - 必须重建表的场景应使用在线变更工具(影子表加触发器或基于日志的复制方式),先建影子表、增量同步、切换表名。具体方案与工具见 mysql: Schema 变更与运维。
- 变更前必须确认的三件事:预计行数、预计耗时、变更期间是否阻塞写入,并准备回退方案。
2.9 滚动发布下的扩展与收缩
滚动发布期间新旧版本代码同时运行,结构变更必须让两个版本的代码都能工作,因此采用扩展与收缩模式:
| 阶段 | 结构变更 | 代码状态 |
|---|---|---|
| 1 扩展 | 新增列或表,允许为空,建立索引 | 新代码双写(旧列与新列都写),读取仍用旧列 |
| 2 回填 | 批量迁移历史数据,分批提交并控制速率 | 代码不变 |
| 3 切换 | 无结构变更 | 新代码改为读新列,仍双写 |
| 4 收缩 | 停止写入旧列,确认无引用后删除 | 只写新列 |
四个阶段之间需要各自的发布与观察窗口,不能合并为一次发布。回填阶段必须分批并限制速率,否则会与线上写入争抢资源。
三、实现
3.1 Flyway 配置与脚本组织
spring:
flyway:
enabled: true
locations: classpath:db/migration # 迁移脚本位置
baseline-on-migrate: true # 已有数据的库首次接入时建立基线
baseline-version: 0
validate-on-migrate: true # 执行前校验校验和
out-of-order: false # 生产环境禁止乱序执行
clean-disabled: true # 禁止清库操作
table: flyway_schema_history
src/main/resources/db/migration/
├── V1__create_user_table.sql
├── V2__create_order_table.sql
├── V2.1__add_order_index.sql
├── V3__add_order_remark_column.sql
├── V4__backfill_order_status.sql # 一次性数据回填
└── R__order_summary_view.sql # 视图,校验和变化时重建
-- V3__add_order_remark_column.sql
-- 扩展阶段:新增列允许为空,保证旧版本代码仍可写入
ALTER TABLE `order`
ADD COLUMN `remark` VARCHAR(255) NULL COMMENT '订单备注',
ALGORITHM = INPLACE,
LOCK = NONE;
-- V4__backfill_order_status.sql
-- 回填阶段:分批更新,避免长事务与主从延迟
-- 注意:迁移脚本应幂等,重复执行不产生副作用
UPDATE `order`
SET `status` = 'CREATED'
WHERE `status` IS NULL
LIMIT 1000;
-- R__order_summary_view.sql
-- 可重复脚本:视图重建
CREATE OR REPLACE VIEW `v_order_summary` AS
SELECT o.id, o.status, o.amount, u.name AS user_name
FROM `order` o
JOIN `user` u ON u.id = o.user_id;
脚本编写规范:
- 一个脚本只做一件事,便于定位失败点与单独处理。
- 结构变更与数据变更分开,避免失败后无法区分已生效部分。
- 数据回填分批执行,禁止无条件全表更新。
- 变更前判断是否存在(对可重复脚本使用
CREATE OR REPLACE,对结构变更依赖版本号保证只执行一次)。 - 不使用工具方言之外的事务控制语句,MySQL 的 DDL 会隐式提交,事务包裹无法保证整体成功或失败。
3.2 关闭 ORM 自动建表
spring:
jpa:
hibernate:
ddl-auto: validate # 只校验,不一致时启动失败
properties:
hibernate:
globally_quoted_identifiers: true
# 校验实体与数据库结构是否一致:启动应用即可,不一致时抛出 SchemaManagementException
# 若需要人工确认差异,可临时使用该属性输出生成的 DDL 进行比对(仅用于比对,不用于执行)
# spring.jpa.properties.jakarta.persistence.schema-generation.scripts.action=create
3.3 流水线中的执行位置
# 方式一:应用启动时自动执行(适合小变更)
# 直接发布,Flyway 在应用启动阶段完成迁移
# 方式二:流水线中单独执行(适合大表变更与需要人工确认的变更)
mvn -q flyway:migrate -Dflyway.url="$DB_URL" -Dflyway.user="$DB_USER" -Dflyway.password="$DB_PASSWORD"
# 只预览将要执行的语句,不实际执行
mvn -q flyway:migrate -Dflyway.url="$DB_URL" -Dflyway.user="$DB_USER" -Dflyway.password="$DB_PASSWORD" -Dflyway.dryRunOutput=-
# 校验已执行脚本与文件是否一致
mvn -q flyway:validate -Dflyway.url="$DB_URL" -Dflyway.user="$DB_USER" -Dflyway.password="$DB_PASSWORD"
# 查看当前版本与执行历史
mvn -q flyway:info -Dflyway.url="$DB_URL" -Dflyway.user="$DB_USER" -Dflyway.password="$DB_PASSWORD"
# 修复版本表(如本地开发环境删除过脚本导致校验失败,仅在确认无结构风险时使用)
mvn -q flyway:repair -Dflyway.url="$DB_URL" -Dflyway.user="$DB_USER" -Dflyway.password="$DB_PASSWORD"
执行顺序约定的三种方案:
| 方案 | 顺序 | 适用 | 风险 |
|---|---|---|---|
| 先结构后代码 | 迁移、再发布 | 扩展阶段(新增列、新增表) | 代码未发布期间结构已变,旧代码需能容忍 |
| 先代码后结构 | 发布、再迁移 | 代码已容忍旧结构(如可空字段) | 依赖代码对新旧结构都兼容 |
| 同步执行 | 启动时迁移 | 小变更 | 迁移耗时计入启动时间 |
3.4 回滚与恢复
| 场景 | 处理方式 |
|---|---|
| 结构变更失败但未产生数据影响 | 修复脚本后重新执行,必要时先 repair 修正版本表记录 |
| 已成功但业务异常 | 优先向前修复(新增一个版本化脚本),而不是回退结构 |
| 必须回退结构 | 使用数据库备份恢复,或在变更前保留影子结构与数据快照 |
| 数据被错误修改 | 从备份或导出快照恢复,恢复范围应控制在受影响的表 |
判断依据:能否在不恢复数据的前提下通过新增脚本修正。多数线上问题属于此类,因此回滚能力的价值主要体现在变更前的准备(备份与快照),而不是变更后的自动回退。
3.5 验证与排查
# 确认当前结构版本与预期一致
mysql -h "$DB_HOST" -u "$DB_USER" -p"$DB_PASSWORD" -e \
"SELECT installed_rank, version, description, success, installed_on FROM flyway_schema_history ORDER BY installed_rank;"
# 确认是否存在失败记录
mysql -h "$DB_HOST" -u "$DB_USER" -p"$DB_PASSWORD" -e \
"SELECT version, description, success FROM flyway_schema_history WHERE success = 0;"
# 确认目标结构是否已生效
mysql -h "$DB_HOST" -u "$DB_USER" -p"$DB_PASSWORD" -e "SHOW CREATE TABLE \`order\`\G"
# 确认索引是否存在
mysql -h "$DB_HOST" -u "$DB_USER" -p"$DB_PASSWORD" -e "SHOW INDEX FROM \`order\`;"
# 确认多实例启动时只有一个实例执行迁移(观察启动日志)
# 关键字:Successfully applied、Database lock acquired、waiting for lock
3.6 常见问题对照
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 启动报校验和错误 | 已执行的迁移文件被修改 | 确认文件历史,恢复原内容或使用新版本脚本表达变更 |
| 启动报版本冲突 | 版本号重复或低于当前最大版本 | 统一版本号分配规则,禁止乱序提交 |
| 迁移执行到一半失败且结构已变化 | MySQL 的 DDL 隐式提交,无法整体回滚 | 人工核对已生效部分,编写针对性脚本补齐 |
| 多实例启动时部分实例启动失败 | 迁移耗时超过启动探针超时 | 把耗时迁移移出启动路径,或临时降低副本数 |
| 首次接入已有数据库时重复建表 | 未设置基线 | 使用 baseline-on-migrate 与 baseline-version |
| 滚动发布期间新旧代码报错 | 结构变更未按扩展与收缩模式拆分 | 拆分为多阶段发布 |
| 回填脚本执行时间过长 | 未分批或批量过大 | 按主键分批并限制速率,观察主从延迟 |
| 大表加索引导致写入阻塞 | 触发了表重建 | 改用在线变更工具,变更前核对执行方式 |
| 删除列后无法恢复数据 | 变更前未备份 | 删除前导出该列数据并保留观察窗口 |
四、总结
- 数据库结构需要与代码同等对待:有版本、有顺序、有校验、有执行记录,否则多环境一致性无法保证。
- 版本化迁移的基本模型是迁移文件加版本表加校验和,由此获得"已执行不重复"与"文件修改可检测"两个保证。
- Flyway 以原生 SQL 表达变更,确定性高、上手快,撤销脚本属于商业能力;Liquibase 以抽象语法表达变更,可适配多数据库且原生支持回滚,代价是间接性。
- ORM 自动建表不可用于生产,正确做法是关闭自动建表并启用启动时结构校验。
- 多实例并发迁移依赖版本表上的锁,迁移耗时会计入启动时间,长耗时变更必须移出启动路径。
- MySQL 的 DDL 隐式提交使一个脚本无法保证整体成功或失败,脚本因此需要拆小并保持可重复执行。
- 结构变更优先采用"新增、回填、切换、清理"四步,就地修改与删除列属于不可回滚操作,必须保留观察窗口与数据快照。
- 滚动发布要求结构变更按扩展与收缩模式拆成多个阶段,使新旧版本代码在同一结构上都能工作。
- 回滚能力的价值主要在变更前的准备,多数线上问题的正确处置是向前修复而不是回退结构。
- 迁移脚本、版本表内容与目标结构三者需要定期核对,避免"流水线成功但结构未生效"的隐性偏差。