如何从Flyway 3.x直接升级至5.x（跳过4.x中间版本）

嘿，我之前帮客户处理过类似的Spring Boot + Flyway跨版本升级问题，完全可以跳过Flyway 4.x直接从3.x升到5.x，给你梳理下具体步骤和注意事项：

核心前提 #

Flyway 5.x本身是支持从3.x直接迁移的，官方虽然推荐逐步升级，但只要处理好兼容性问题，完全可以一步到位，不用让客户走中间的4.x过渡版本。

具体操作步骤 #

1. 先检查并修复迁移脚本的兼容性 #

Flyway 3.x到5.x有一些细节变化，先把现有脚本在测试环境验证一遍：

• 脚本命名规范：5.x对脚本名称的特殊字符（比如空格、中文、特殊符号）处理更严格，确保所有脚本都是V<版本号>__<描述>.sql的标准格式，避免识别失败。
• SQL语法兼容性：某些数据库的SQL语法在Flyway 5.x下可能有变化（比如MySQL的时间类型、PostgreSQL的序列），跑一遍现有脚本，看有没有报错，提前修正。
• 废弃API检查：如果你的代码里直接调用了Flyway的旧API（比如new Flyway().setDataSource(...)），要换成5.x的新构建方式：

  Flyway flyway = Flyway.configure()
      .dataSource(dataSource)
      .locations("classpath:db/migration")
      .load();
  flyway.migrate();
  

2. 调整Spring Boot依赖配置 #

升级Spring Boot到2.0.x时，默认会引入兼容的Flyway 5.x版本，你只需要：

• 移除pom.xml/build.gradle中显式指定的Flyway 3.x版本号（如果有的话），让Spring Boot的依赖管理自动引入对应版本；
• 如果需要指定具体版本，选择Spring Boot 2.0.x兼容的5.x版本（比如5.2.4，避免选太新的版本导致兼容问题）。

举个Maven的例子，之前的依赖：

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>3.2.1</version>
</dependency>

现在改成：

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

3. 处理Flyway历史表的自动迁移 #

Flyway 5.x会自动识别旧的schema_version表（3.x用的表名），并在第一次运行时自动把它迁移成5.x的flyway_schema_history表，不需要手动修改结构，但要注意：

• 确保客户的数据库用户有ALTER TABLE权限，不然会报错；
• 如果历史表中有失败的迁移记录，Flyway会阻止后续操作，所以要先在测试环境清理失败记录，或者临时配置flyway.clean-disabled=false（生产环境慎用clean，优先修复失败迁移）。

4. 全流程测试验证 #

一定要在测试环境模拟客户的生产场景验证：

1. 用Flyway 3.x初始化一个带有历史记录的数据库；
2. 升级Spring Boot到2.0.x，替换Flyway为5.x；
3. 启动应用，观察Flyway是否自动完成历史表迁移，然后执行新的迁移脚本（如果有的话）；
4. 检查数据库结构、数据完整性，以及应用功能是否正常。

5. 给客户的升级建议 #

给客户的升级指导要简单明了：

• 升级前必须全量备份数据库，防止意外；
• 先在预生产环境跑一遍升级流程，验证没问题再动生产；
• 确认数据库用户有足够的权限修改Flyway历史表。

常见问题处理 #

• 如果遇到报错Found non-empty schema(s) without schema history table：可以配置flyway.baseline-on-migrate=true，让Flyway以当前数据库状态为基线，但要确保当前结构和预期的基线完全一致，避免后续迁移冲突。
• 如果Spring Boot自动配置有问题：可以显式配置Flyway的参数，比如在application.properties里指定：

  spring.flyway.locations=classpath:db/migration
  spring.flyway.baseline-on-migrate=true
  

内容的提问来源于stack exchange，提问作者Dylan Roberts