Flyway "Unable to obtain connection from database" in CI

By Kaveh Alemi·Latchkey

Flyway tried to open a JDBC connection to the configured URL and the driver could not establish it. In CI this is almost always a database that is not ready yet, or a wrong JDBC URL, user, or driver.

What this error means

flyway migrate fails with "Unable to obtain connection from database (jdbc:postgresql://...): Connection refused" before reading any migrations.

ERROR: Unable to obtain connection from database (jdbc:postgresql://localhost:5432/app)
for user 'app': Connection to localhost:5432 refused.
SQL State  : 08001

Common causes

The database is not accepting connections yet

Flyway runs before the database service container is ready, so the JDBC connection is refused.

Wrong JDBC URL, credentials, or missing driver

The flyway.url, user, or password is incorrect, or the JDBC driver for the database is not on the classpath.

How to fix it

Wait for the database before running Flyway

Use a health check so migrate starts only when the database is listening.

services:
  postgres:
    image: postgres:16
    env: { POSTGRES_PASSWORD: postgres }
    options: >-
      --health-cmd "pg_isready -U postgres"
      --health-interval 5s --health-retries 10

Verify the JDBC URL and credentials

1. Confirm flyway.url host and port match the running database.
2. Check the user and password are correct and the database exists.
3. Ensure the right JDBC driver is available to Flyway.

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

How to prevent it

• Gate Flyway behind a database health check.
• Source the JDBC URL and credentials from CI config consistently.
• Make sure the database driver is on the classpath.

Frequently asked questions

Related guides

References

• GitHub Actions documentation