Flyway Unsupported Database: PostgreSQL 17

Problem Statement

When attempting database migrations with Flyway on PostgreSQL 17, users encounter the "Unsupported Database" error. This issue persists even when upgrading to Flyway 10.20.1 (the latest version at the time of writing) and occurs because Flyway requires additional configuration to recognize PostgreSQL versions beyond its initial support range. Key observations:

• Error appears as Unsupported Database: PostgreSQL 17.0
• Occurs despite updating Flyway and PostgreSQL dependencies
• Affects migration workflows in both new and existing projects
• Often stems from missing PostgreSQL-specific Flyway modules

Solution: Add PostgreSQL-Specific Dependency

The primary solution requires adding Flyway's PostgreSQL database module to your dependencies. This module contains the necessary drivers and version compatibility logic for Flyway to recognize PostgreSQL 17.

Step 1: Add Required Dependencies

Include both flyway-core and flyway-database-postgresql in your build configuration. The PostgreSQL-specific module is essential for compatibility.

Maven (pom.xml):

<dependencies>
    <!-- Existing dependencies -->
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-core</artifactId>
        <version>10.20.1</version>
    </dependency>
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-database-postgresql</artifactId>
        <version>10.20.1</version> <!-- Match Flyway core version -->
    </dependency>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>42.7.2</version> <!-- Official PostgreSQL JDBC driver -->
    </dependency>
</dependencies>

Gradle (build.gradle / build.gradle.kts):

dependencies {
    implementation("org.flywaydb:flyway-core:10.20.1")
    implementation("org.flywaydb:flyway-database-postgresql:10.20.1")
    implementation("org.postgresql:postgresql:42.7.2")
}

Step 2: Verify Configuration

Ensure proper Flyway configuration in your settings:

YAML

# application.yml
flyway:
  enabled: true
  baseline-on-migrate: true
  baseline-version: 1
  # locations: classpath:db/migration # Uncomment if needed

Properties

# application.properties
flyway.enabled=true
flyway.baseline-on-migrate=true
flyway.baseline-version=1
# flyway.locations=classpath:db/migration

Step 3: Validate Database Connection

Confirm your database URL includes the correct PostgreSQL syntax:

jdbc:postgresql://localhost:5432/your_database

Temporary Workaround: Downgrade PostgreSQL

If the dependency solution doesn't resolve the issue immediately:

1. Downgrade to PostgreSQL 16.6 (the last fully compatible version before 17)
2. Continue using Flyway 10.20.1
3. Monitor Flyway's PostgreSQL support page for version 17 updates
4. Upgrade to PostgreSQL 17 when Flyway releases official support

Explanation

• Why this happens: Flyway treats PostgreSQL as "unsupported" until you add the flyway-database-postgresql module. This module contains database-specific logic not present in the core package.
• Version matching: Keep Flyway core and PostgreSQL module versions identical to avoid compatibility conflicts
• JDBC requirement: PostgreSQL JDBC driver (version 42.7.2+) provides essential database communication
• Baseline configuration: baseline-on-migrate allows initializing new databases without version conflicts

Beta Support Notice

While flyway-database-postgresql:10.20.1 adds PostgreSQL 17 recognition, full feature parity might not be guaranteed until an explicit version support announcement appears in Flyway's changelog. Test migrations thoroughly before production deployment.

Best Practices

1. Always include both flyway-core and database-specific modules
2. Verify JDBC driver compatibility with your PostgreSQL version
3. Use spring-boot-dependencies BOM for automatic version management
4. Check Flyway's Release Notes for PostgreSQL support updates