在对已经运行一段时间的遗留系统引入Flyway进行数据库版本管理时，系统中已经存在大量历史表结构和数据，直接执行Flyway的迁移流程会导致重复执行已有的建表、加字段等操作，引发错误。此时使用baseline migration功能可以标记当前数据库的状态为初始基准版本，让Flyway跳过这部分已有的历史变更，只处理后续的增量迁移。
baseline migration 核心概念
baseline migration是Flyway提供的一种特殊迁移类型，它的作用是告诉Flyway当前数据库已经处于某个版本的状态，后续只需要从这个版本之后开始执行迁移即可。它不会实际执行任何数据库变更操作，只会在Flyway的元数据表flyway_schema_history中插入一条基准版本记录。
与普通的迁移文件不同，baseline migration的文件命名有固定规则，格式为V[版本号]__[描述].sql，其中版本号需要比所有已有的遗留系统变更对应的版本号低，或者设置为你希望作为基准的版本号。
遗留系统版本初始化步骤
1. 确认遗留系统当前状态
首先需要梳理遗留系统当前已经存在的所有数据库变更，确定你希望作为基准的版本号，比如遗留系统已经运行了多个迭代，你可以将基准版本设置为V1，后续的所有新变更从V2开始。
2. 创建 baseline migration 文件
在Flyway的迁移脚本目录下创建对应的baseline migration文件，比如设置为V1版本作为基准，文件名为V1__baseline.sql。这个文件可以是空文件，也可以包含一些注释说明基准版本对应的系统状态，不需要写实际的变更SQL。
-- 该文件为遗留系统数据库基准版本标记 -- 对应遗留系统2024年第一版上线时的数据库状态 -- 后续所有迁移从V2版本开始执行
3. 执行 baseline 命令
使用Flyway的命令行工具或者API执行baseline操作，标记当前数据库为基准版本。如果使用命令行，配置好Flyway的连接信息后执行以下命令：
flyway -url=jdbc:mysql://127.0.0.1:3306/legacy_db -user=root -password=123456 baseline
执行完成后，Flyway会自动在flyway_schema_history表中插入一条版本为1的记录，类型为BASELINE，表示该版本是基准版本。
4. 后续迁移文件编写
基准版本设置完成后，所有新的数据库变更都从V2版本开始编写迁移文件，比如新增用户表的扩展字段，文件名为V2__add_user_phone_column.sql，内容如下：
ALTER TABLE user ADD COLUMN phone VARCHAR(20) COMMENT '用户手机号';
5. 执行迁移验证
执行Flyway的migrate命令，此时Flyway会跳过V1的基准版本，只执行V2及之后的迁移文件，不会重复处理遗留系统已有的表结构。
flyway -url=jdbc:mysql://127.0.0.1:3306/legacy_db -user=root -password=123456 migrate
常见注意事项
- baseline的版本号必须小于等于你后续第一个迁移文件的版本号，否则后续迁移会被跳过。
- 如果遗留系统已经存在
flyway_schema_history表，需要先清空表内容再执行baseline操作，避免版本冲突。 - baseline操作只需要执行一次，后续团队其他成员拉取代码后，直接执行migrate命令即可，不需要重复执行baseline。
- 如果后续需要对基准版本之前的内容做调整，不建议修改基准版本文件，而是新增更高版本的迁移文件来处理。
问题排查示例
如果执行baseline后migrate时出现版本冲突错误，可以先查询flyway_schema_history表的内容，确认基准版本是否正确插入：
SELECT * FROM flyway_schema_history;
如果表中没有基准版本记录，检查Flyway的配置是否正确，数据库连接是否指向遗留系统的数据库，是否有权限操作flyway_schema_history表。
Flywaybaseline_migrationSQL遗留系统版本初始化修改时间：2026-07-07 21:39:14