Flyway PostgreSQL Support in Spring Boot 3.3.0

Problem: Unsupported Database Error with PostgreSQL 16

After upgrading to Spring Boot 3.3.0, Flyway fails to connect to PostgreSQL 16 databases, throwing the error:

Caused by: org.flywaydb.core.api.FlywayException: Unsupported Database: PostgreSQL 16.2
    at org.flywaydb.core.internal.database.DatabaseTypeRegister.getDatabaseTypeForConnection(DatabaseTypeRegister.java:105)
    ...

This occurs due to Flyway's new modular architecture introduced in Flyway 9.x, where database-specific support was moved from the core module to separate dependencies. Spring Boot 3.3.0 includes newer versions of Flyway that require explicit PostgreSQL module declaration.

Solution: Add PostgreSQL Database Module

Primary Fix

Add Flyway's PostgreSQL module to your dependencies:

Maven (pom.xml):

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

Gradle (build.gradle):

implementation 'org.flywaydb:flyway-database-postgresql'

Verify Flyway Version

TIP

Spring Boot 3.3.0 manages Flyway versions automatically (flyway-core 10.x). Avoid manual version downgrades unless necessary, as they may cause compatibility issues.

Recommended Configuration

Add standard Flyway configuration to application.yml for full functionality:

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

Why This Works

Flyway restructured its architecture in version 9.0, extracting database support into separate modules:

• flyway-core now contains only core functionality
• Database-specific implementations require dedicated modules (e.g., flyway-database-postgresql)
• Spring Boot dependency management automatically resolves compatible versions

Common Pitfalls to Avoid

1. Downgrading flyway-core

   WARNING

   Avoid downgrading to unsupported versions:

   <!-- Do NOT use this workaround -->
   <version>9.16.3</version>

   This bypasses the root issue and may cause Spring Boot compatibility problems.

2. Missing configuration
   Ensure baseline-on-migrate: true is set if using an existing database schema

3. Incomplete dependency sets
   The flyway-database-postgresql module must coexist with flyway-core - don't remove the core dependency

Troubleshooting Persistent Issues

If the error persists after adding the PostgreSQL module:

1. Verify dependency hierarchy with:

   mvn dependency:tree

2. Ensure no conflicting Flyway versions
3. Check PostgreSQL JDBC driver version (recommended: 42.7.3 or later)
4. Confirm database version in logs matches your PostgreSQL installation

For enterprise setups or complex environments, see Flyway's official PostgreSQL documentation.

Alternative: Manual Flyway Configuration

Explicitly configure Flyway version when needed:

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

TIP

Prefer the Spring-managed version unless you have specific integration requirements. The manual version should always pair with the PostgreSQL module dependency.