Spring Boot 3.4.x 整合 Flyway 时 PostgreSQL 兼容性问题解析

问题背景

在 Spring Boot 3.4.3 版本中，开发者升级现有应用时发现 Flyway 与 PostgreSQL 出现兼容性报错。典型错误信息为 Unsupported Database: PostgreSQL 15.12，即使升级到 PostgreSQL 16/17 版本仍无法解决。该问题源于依赖配置缺失，但现象容易误导开发者认为是版本不兼容问题。

核心原因

Flyway 自 9.0 版本起采用模块化设计，对不同数据库的支持拆分为独立模块。Spring Boot 3.3.x 开始同步此变更，要求：

1. 必须显式引入对应数据库的 Flyway 插件模块
2. 基础依赖 flyway-core 仅提供核心功能，不包含任何数据库驱动

对于 PostgreSQL 项目，需要额外添加：

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
</dependency>

解决方案

标准配置方案

1. 在现有依赖基础上补充 PostgreSQL 插件：

<dependencies>
    <!-- 原有依赖 -->
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-core</artifactId>
    </dependency>
    <!-- 新增插件 -->
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-database-postgresql</artifactId>
    </dependency>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
    </dependency>
</dependencies>

2. 通过 start.spring.io 创建项目时：

• 勾选 "Flyway Migration" 和 "PostgreSQL" 选项
• 生成的项目会自动包含正确依赖

技术原理

Flyway 的模块化设计带来以下优势：

1. 减小包体积：避免携带未使用的数据库驱动
2. 灵活升级：各数据库插件可独立更新
3. 明确依赖：通过 POM 文件即可确认支持的数据库类型

Spring Boot 3.3+ 版本严格遵循这一设计，不再自动传递数据库特定依赖，需要开发者显式声明。

最佳实践

1. 版本对齐：保持 flyway-core 和 flyway-database-postgresql 版本一致
2. 依赖检查：使用 mvn dependency:tree 验证依赖树
3. 升级路径：
   • 从 Spring Boot 2.x 升级时需注意此变更
   • 参考各版本的 Release Notes 获取兼容性说明

常见误区

1. 误判为版本冲突：实际是缺少必要模块而非版本不匹配
2. 过度升级数据库：无需因为此错误升级 PostgreSQL 实例
3. 混淆 JPA 与 Flyway 依赖：两者需要分别配置数据库连接

通过正确理解 Flyway 的模块化架构，可以避免此类配置问题，确保数据库迁移流程顺利执行。