Flyway "Unable to obtain connection from database" in CI

By Daniel Zoghalchali·Latchkey

Flyway could not open a JDBC connection to the database. The driver never reached a usable server - a connectivity, readiness, or URL problem, not a migration-content problem.

What this error means

flyway migrate/info fails up front with "Unable to obtain connection from database", wrapping a JDBC "Connection refused" or timeout. It frequently passes on retry once a database service finishes starting.

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

Diagnose it: connectivity, then migration state

Migration failures in CI are usually the database not being ready rather than the migration being wrong. A service container accepts TCP connections before it is ready to serve queries, so a migration started too early fails in confusing ways.

# wait for readiness, not just for the port to open
until pg_isready -h localhost -p 5432; do sleep 1; done

# then inspect what the tool believes has been applied
<migrate-tool> status

Common causes

Database service not ready

A database service container is still starting when Flyway runs, so the JDBC connection is refused. This is transient and clears once the service is up.

Wrong JDBC URL or credentials

An incorrect host/port in the JDBC URL, or wrong user/password, prevents the connection from being established at all.

Transient network blip

A brief connectivity drop to a remote database can cause an intermittent connection failure that succeeds when retried.

How to fix it

Wait for the database, then migrate

Block on readiness so Flyway does not race the database boot.

until pg_isready -h db -p 5432; do sleep 1; done
flyway -url=jdbc:postgresql://db:5432/app migrate

Verify the JDBC URL and credentials

1. Confirm host, port, and database name in the JDBC URL match the reachable service.
2. Check the user/password against the database service env.
3. Use connectRetries so Flyway waits for a briefly-unavailable database.

Let Flyway retry the connection

flyway -connectRetries=10 -connectRetriesInterval=5 migrate

How to prevent it

• Use connectRetries so Flyway tolerates a slow-starting database.
• Gate Flyway on a readiness check or service healthcheck.
• Keep the JDBC URL and credentials in sync with the CI network.

Frequently asked questions

Related guides

References

• GitHub Actions documentation