SQL Flyway 的 baseline migration 与遗留系统版本初始化

baseline migration 是为遗留数据库建立可信起点，声明“当前库=指定版本”，需清空 schema_history 表后执行 flyway baseline 命令，并严格确保后续迁移版本号大于 baselineversion，且必须人工核对结构、数据并验证重建流程。

当把 Flyway 引入一个已有数据库的遗留系统时，baseline migration 是最关键的一步——它不是“跳过旧迁移”，而是为已有数据库状态建立一个可信的、可追踪的起点。

baseline 的本质：声明“当前库 = 版本 X”

Flyway 默认要求从 V1__init.sql 开始执行所有迁移。但遗留库往往已存在表结构、基础数据，甚至混杂了手工 SQL 修改。直接运行 Flyway 会报错“schema_history 表不存在”或“校验失败”。
此时 baseline 不是绕过规则，而是明确告诉 Flyway：“别管之前发生了什么，我确认此刻数据库的状态，等价于你执行完 V1.0（或任意指定版本）后的结果。”

操作上，需手动设置：

• 确保数据库中 没有 flyway_schema_history 表（若有，先清空或重命名）
• 执行 flyway baseline -baselineVersion=1.0 -baselineDescription="legacy_state"
• Flyway 会创建 flyway_schema_history 表，并插入一条记录：
  installed_rank=1, version='1.0', description='legacy_state', type='BASELINE', installed_on=xxx

baselineVersion 怎么选？关键看后续迁移编号

这个值决定了你第一个自管理迁移脚本的版本号必须严格大于它。例如：

• 设 -baselineVersion=1.0 → 下一个脚本必须是 V1.1__add_user_status.sql 或更高（如 V2.0__refactor_orders.sql）
• 设 -baselineVersion=0 → 下一个脚本可从 V1__init.sql 开始（推荐用于极简场景）
• 设 -baselineVersion=1.5.0 → 下一个脚本需为 V1.5.1__... 或 V1.6__...

建议选整数主版本（如 1.0），避免小版本嵌套带来的维护困惑；若遗留库本身有模糊的“v1.2”发布记录，也可用 1.2 作为 baseline，增强语义对应。

baseline 后必须验证：三件事不能少

baseline 只是元数据写入，不校验实际结构是否真匹配。上线前务必人工核对：

• 比对表结构：用 flyway info 查看当前状态，再导出现有库 DDL，与你设想的 “V1.0 迁移应产出的结构” 对照（可用工具 diff，或重点检查索引、约束、默认值）
• 检查基础数据：比如字典表 status_type 是否已有预期的几条初始化记录；若缺失，需补一个 V1.0.1__insert_initial_data.sql
• 跑一次 clean + migrate（仅测试环境）：确认从空库出发，执行全部迁移（含 baseline 后的第一批脚本）能重建出等效结构

遗留系统常踩的坑：baseline 不是万能胶

它解决的是“版本起点”问题，但掩盖不了历史技术债：

• 不修复手工改库：如果某张表曾被 dba 手动加过字段但没留脚本，baseline 后这个字段就变成“幽灵列”——Flyway 不知道它存在，未来 DDL 脚本可能冲突
• 不替代文档整理：baseline 描述里写 “legacy_state” 毫无信息量；应写明 “based on prod dump 2023-08-15, includes payment_v2 schema and seed data for countries”
• 不跳过逻辑一致性检查：比如订单表有 status_id 外键，但 status 表为空 —— baseline 不会报错，但应用会崩