Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Flyway cannot handle the PostgreSQL URL after upgrading to Flyway 10 or newer

ErrorNo Flyway database plugin found to handle: jdbc:foo://localhost:port

Short answer

Since Flyway 10, each database has its own module. Flyway core alone cannot open a jdbc:postgresql URL. Add the flyway-database-postgresql module next to flyway-core (and in the buildscript block if you use the Gradle plugin), then check that the URL has the jdbc:postgresql://host:port/database form.

  • Applies to Flyway 10 and newer, PostgreSQL 16, Spring Boot 3, Maven 3.9, Gradle 8
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which Flyway artifacts your build resolves. If flyway-core is listed but flyway-database-postgresql is not, that is the whole problem.

    mvn dependency:tree | grep -i flyway
    # Gradle:
    ./gradlew dependencies --configuration runtimeClasspath | grep -i flyway
  2. 2Match what you see, then jump to its fix

    1. 1The error appears only after the Flyway version moved to 10 or newer, with an unchanged URLThe PostgreSQL module is not a dependencyFix
    2. 2Application runs, but the flywayMigrate Gradle task still failsThe Gradle plugin cannot see the moduleFix
    3. 3Error when you run the flyway command, not the applicationThe command line is missing the module in its lib folderFix
    4. 4The module is on the classpath but Flyway still finds no matchThe JDBC URL is not in the PostgreSQL formatFix

What does the error look like?

  • No Flyway database plugin found to handle: jdbc:foo://localhost:port
  • No database found to handle jdbc:postgresql://localhost:5432/app

Cause 1 of 4

The PostgreSQL module is not a dependency

1Check

Flyway 10 split database support into separate modules. Redgate's PostgreSQL page states that PostgreSQL is found within the flyway-database-postgresql plugin module, and the troubleshooting page says database modules must be added as dependencies when you use the API.

grep -n "flyway" pom.xml build.gradle build.gradle.kts 2>/dev/null

2Fix

Add the module with the same version as flyway-core (the version is an example).

<!-- pom.xml -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
    <version>10.20.1</version>
</dependency>

// build.gradle
implementation 'org.flywaydb:flyway-database-postgresql:10.20.1'

3Verify

Start the application or run the migration again; the plugin error is gone and the migration runs.

mvn spring-boot:run

Confirmed by documentation.red-gate.com

Did this fix it?

Cause 2 of 4

The Gradle plugin cannot see the module

1Check

Redgate's PostgreSQL page shows the dependency declared inside the buildscript block for Gradle. The Gradle plugin reads its own classpath, so declare the module there.

grep -n -A8 "buildscript" build.gradle

2Fix

Declare the module in buildscript as well.

buildscript {
    dependencies {
        classpath 'org.flywaydb:flyway-database-postgresql:10.20.1'
    }
}

3Verify

Run the task again.

./gradlew flywayInfo

Confirmed by documentation.red-gate.com

Did this fix it?

Cause 3 of 4

The command line is missing the module in its lib folder

1Check

For the CLI, the troubleshooting page says the plugin may be missing from the lib/flyway folder and that the individual modules can be found on Maven or in a fresh CLI installation.

ls <flyway-install-dir>/lib/flyway | grep -i postgres

2Fix

Use a complete CLI download, or copy flyway-database-postgresql into lib/flyway.

cp flyway-database-postgresql-10.20.1.jar <flyway-install-dir>/lib/flyway/

3Verify

Run info against the database.

flyway -url=jdbc:postgresql://localhost:5432/app -user=app -password=secret info

Confirmed by documentation.red-gate.com

Did this fix it?

Cause 4 of 4

The JDBC URL is not in the PostgreSQL format

1Check

The troubleshooting page asks you to check that the URL is formatted correctly. The PostgreSQL format is jdbc:postgresql://host:port/database.

grep -rn "jdbc:" src/main/resources/

2Fix

Use the documented form, without extra quotes around the value.

spring.flyway.url=jdbc:postgresql://localhost:5432/app

3Verify

Start the application.

mvn spring-boot:run

Confirmed by documentation.red-gate.com

Did this fix it?

How do I stop it coming back?

  • When you bump Flyway across a major version, read the release notes for modules before building.
  • Keep flyway-core and the database module on the same version.
  • Read the Flyway release notes before moving to a new major version.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.