本文说明数据库结构的版本化管理与落地方式。持久层框架与事务边界见 持久层:JDBC、连接池与事务,DBA 视角的变更方案与线上在线 DDL 见 mysql: Schema 变更与运维,分片环境下的变更差异见 分库分表与全局 ID,应用启动与配置管理见 Spring Boot 实践,流水线中的执行位置见 Gradle 与 CI 流水线。

一、起源

1.1 手工执行 SQL 带来的三类问题

在引入迁移工具之前,结构变更通常由人工在数据库客户端执行脚本,问题集中在三处:

问题 表现 后果
无记录 无法确定某个环境当前处于哪个结构版本 发布前需要人工比对,遗漏必然发生
无顺序保证 多个环境的执行顺序与内容不一致 测试环境通过而生产失败,且失败点难以复现
无校验 同一版本的文件被修改后无人察觉 已执行过的脚本被再次执行或执行了变更后的内容

根本原因是:应用代码有版本控制与流水线,数据库结构只有一堆散落的 SQL 文件。

1.2 需要被管理的内容

内容 是否适合版本化 说明
表与列的定义 适合 结构变更的主体
索引与约束 适合 与结构同源
视图与存储过程 适合 用可重复脚本表达
基础字典数据 适合 需要稳定主键的枚举类数据
业务数据修补 有限适合 应拆成独立的一次性脚本,避免与结构变更混在一起
分区与权限 视环境而定 通常由 DBA 与环境配置管理,不进入应用迁移

1.3 取舍

  • 由应用启动时自动迁移:部署简单、环境一致,风险是把结构变更与发布强绑定,长耗时的表变更会拖长启动时间甚至导致启动失败。
  • 由流水线在发布前单独执行:可控、可观测,代价是流水线需要数据库凭据与网络权限,且必须处理"代码已发布但结构未变更"的顺序问题。
  • 结论:小变更随应用启动执行,大表变更与需要停机窗口的变更走单独的变更流程,并在应用启动前完成。

二、原理

2.1 版本化迁移的基本模型

所有迁移工具遵循同一模型:

  1. 迁移文件按版本号排序,文件名中包含版本与描述。
  2. 数据库中维护一张版本表,记录已执行版本、执行时间、执行者与校验和。
  3. 每次启动或执行时,先读取版本表,再计算待执行集合,按顺序执行并写回记录。
  4. 执行前校验已应用文件的校验和,不一致时报错而不是继续执行。

模型带来的两个保证:已执行的版本不会重复执行(除非被标记为可重复),以及文件的任意修改都会被检测到。

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
滚动发布期间新旧代码报错 结构变更未按扩展与收缩模式拆分 拆分为多阶段发布
回填脚本执行时间过长 未分批或批量过大 按主键分批并限制速率,观察主从延迟
大表加索引导致写入阻塞 触发了表重建 改用在线变更工具,变更前核对执行方式
删除列后无法恢复数据 变更前未备份 删除前导出该列数据并保留观察窗口

四、总结

  1. 数据库结构需要与代码同等对待:有版本、有顺序、有校验、有执行记录,否则多环境一致性无法保证。
  2. 版本化迁移的基本模型是迁移文件加版本表加校验和,由此获得"已执行不重复"与"文件修改可检测"两个保证。
  3. Flyway 以原生 SQL 表达变更,确定性高、上手快,撤销脚本属于商业能力;Liquibase 以抽象语法表达变更,可适配多数据库且原生支持回滚,代价是间接性。
  4. ORM 自动建表不可用于生产,正确做法是关闭自动建表并启用启动时结构校验。
  5. 多实例并发迁移依赖版本表上的锁,迁移耗时会计入启动时间,长耗时变更必须移出启动路径。
  6. MySQL 的 DDL 隐式提交使一个脚本无法保证整体成功或失败,脚本因此需要拆小并保持可重复执行。
  7. 结构变更优先采用"新增、回填、切换、清理"四步,就地修改与删除列属于不可回滚操作,必须保留观察窗口与数据快照。
  8. 滚动发布要求结构变更按扩展与收缩模式拆成多个阶段,使新旧版本代码在同一结构上都能工作。
  9. 回滚能力的价值主要在变更前的准备,多数线上问题的正确处置是向前修复而不是回退结构。
  10. 迁移脚本、版本表内容与目标结构三者需要定期核对,避免"流水线成功但结构未生效"的隐性偏差。