Spring Boot 3.3.0 中 Flyway 连接 PostgreSQL 16 的兼容问题解决

问题描述

升级 Spring Boot 从 3.2.3 到 3.3.0 版本后，Flyway 无法连接 PostgreSQL 16 数据库，出现以下错误：

Caused by: org.flywaydb.core.api.FlywayException: Unsupported Database: PostgreSQL 16.2
    at org.flywaydb.core.internal.database.DatabaseTypeRegister.getDatabaseTypeForConnection(DatabaseTypeRegister.java:105)
    at org.flywaydb.core.internal.jdbc.JdbcConnectionFactory.<init>(JdbcConnectionFactory.java:73)
    at org.flywaydb.core.FlywayExecutor.execute(FlywayExecutor.java:134)
    at org.flywaydb.core.Flyway.migrate(Flyway.java:147)

此问题核心在于 Flyway 未能识别 PostgreSQL 16.x 数据库版本，导致数据库迁移失败。

问题根源

在 Flyway 的架构调整中（官方 Issue #3780），从 Flyway 9.x 版本开始数据库驱动支持被从核心模块分离：

• flyway-core 不再包含具体数据库驱动
• PostgreSQL 支持需要单独添加 flyway-database-postgresql 依赖
• Spring Boot 3.3.0 默认使用 Flyway 10.x+ 版本，需显式添加该依赖支持

解决方案

方法一：添加 PostgreSQL 驱动依赖（推荐）

在项目 pom.xml 中添加 Flyway 的 PostgreSQL 专用驱动：

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

此方案是 Flyway 官方推荐做法，不指定版本号可自动继承 Spring Boot 的依赖管理。添加后 Flyway 即可正确识别 PostgreSQL 16.x。

方法二：额外配置 Flyway 参数（可选增强）

结合驱动依赖添加 Flyway 基础配置到 application.yml：

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration # 迁移脚本路径
    baseline-on-migrate: true # 自动初始化基线版本

不推荐方案

降级 Flyway 版本：

<!-- 避免使用此方案 -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>9.16.3</version>
</dependency>

此方法会强制降级 Flyway，可能导致兼容性问题，且无法利用新版功能优化。

技术原理

Flyway 架构变更后的模块关系：

• 分离设计：数据库支持变为可插拔模块
• 版本要求：Flyway ≥ 9.16.0 才支持 PostgreSQL 16
• 自动识别：添加依赖后无需额外配置，Flyway 自动加载驱动

验证步骤

1. 添加依赖后启动应用
2. 观察日志输出正确版本信息：

Flyway Community Edition 10.15.2 by Redgate
Database: jdbc:postgresql://localhost:5432/mydb (PostgreSQL 16.2)
Successfully validated 8 migrations (execution time 00:00.021)

最佳实践建议

1. 保持版本同步：勿手动指定版本号，利用 Spring Boot 依赖管理
2. 多环境验证：开发/测试/生产环境使用相同 PostgreSQL 主版本
3. 迁移脚本规范：

   -- V1__initial_schema.sql
   CREATE TABLE users (
     id SERIAL PRIMARY KEY,
     name VARCHAR(100) NOT NULL
   );

4. 持续集成中增加 Flyway 检查：

   ./mvnw flyway:validate

至此已完成 Flyway 与 PostgreSQL 16 的兼容性修复，应用可正常运行数据库迁移流程。