Spring Boot 3.3.0 と 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.2 をデフォルトでサポートしていないため発生する互換性問題です。Flyway はバージョン 10.0.0 以降、データベース固有の実装をflyway-coreから分離し、別モジュールとして提供するアーキテクチャ変更を実施しました。

エラー発生の背景

• PostgreSQL 16が公式サポートされるFlywayバージョンは10.10.0以降（Flyway GitHub Issue #3780）
• Spring Boot 3.3.0デフォルトのFlywayがPostgreSQL 16を認識できない

---

推奨解決策

依存関係の追加

pom.xml に以下の PostgreSQL モジュールを追加してください:

<dependencies>
    <!-- 他の依存関係はそのまま -->
    
    <!-- Flyway PostgreSQL モジュール -->
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-database-postgresql</artifactId>
    </dependency>
</dependencies>

バージョン管理について

• flyway-coreはSpring BootのBOM（Bill of Materials）で管理されるので明示的なバージョン指定は不要
• Spring Boot 3.3.0のデフォルトFlywayバージョン：10.x系（10.11.0時点）

設定ファイルの例

application.yml に最小構成を追加：

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration  # マイグレーションスクリプトの場所
    baseline-on-migrate: true          # 既存DBのベースライン化を許可

---

代替案（非推奨）

古いFlywayバージョンへのダウングレードは互換性問題を招くため、緊急時のみ適用：

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>9.16.3</version> <!-- 10.x未満はPostgreSQL 16を非サポート -->
</dependency>

ダウングレードのリスク

• PostgreSQL 16の新機能が利用不可に
• Spring Boot 3.3.xとFlyway 9.xの非互換性が予測困難
• セキュリティ更新が適用されない

---

根本原因と解決の仕組み

Flywayはバージョン10でモジュール設計を刷新し、データベース固有のロジックを分割しました。flyway-database-postgresqlモジュールが提供するPostgreSQLDatabaseType実装によって：

1. PostgreSQL 16の認識可能化
2. バージョンスキーマの正しい解釈
3. PostgreSQL固有のSQL構文サポート

が可能になります。Spring Bootの依存管理が最新版を自動選択するため、追加だけで機能が有効化されます。

---

検証手順

1. mvn dependency:treeでモジュールが存在することを確認：

   [INFO] +- org.flywaydb:flyway-database-postgresql:jar:10.11.0:compile
   [INFO] +- org.flywaydb:flyway-core:jar:10.11.0:compile

2. アプリケーション再起動後、Flywayログで正常動作を確認：

   PostgreSQL 16.2 接続成功
   DBマイグレーション完了（実行スクリプト数: X）

:::success 最終確認ポイント

• PostgreSQL 16.2以上を使用すること
• Spring Boot 3.3.0のドキュメント記載のFlywayサポートバージョンを参照 :::