Liquibase "Connection could not be created to ... JDBC" in CI

By Kaveh Alemi·Latchkey

Liquibase could not establish a JDBC connection to the database. The driver never reached a usable server - a connectivity, readiness, URL, or driver problem. When it is a not-ready service or a blip, it is transient.

What this error means

liquibase update/status fails with "Connection could not be created to <jdbc-url> with driver ...", wrapping a "Connection refused" or timeout. It frequently passes on retry once the database service is up.

Unexpected error running Liquibase: Connection could not be created to
jdbc:postgresql://db:5432/app with driver org.postgresql.Driver.
Connection to db:5432 refused.

Common causes

Database service not ready

A database service container is still starting when Liquibase runs, so the JDBC connection is refused. Transient.

Wrong JDBC URL, credentials, or driver

An incorrect host/port, wrong user/password, or a missing/mismatched JDBC driver prevents the connection.

Transient network blip

A brief connectivity drop to a remote database can fail a connection that succeeds on retry.

How to fix it

Wait for the database, then run Liquibase

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

Verify URL, credentials, and driver

1. Confirm the JDBC host/port/database match the reachable service.
2. Check the user/password against the service env.
3. Ensure the correct JDBC driver is on the classpath for your database.

How to prevent it

• Gate Liquibase on a readiness check or service healthcheck.
• Keep the JDBC URL, credentials, and driver aligned with the CI setup.
• On managed runners (Latchkey), self-healing auto-retries transient failures such as a database slow to accept connections.

Frequently asked questions

Related guides

References

• GitHub Actions documentation