PostgreSQL "the database system is starting up" in CI
Postgres has bound the port and is answering, but it is still performing crash recovery or initial startup and refuses queries with "the database system is starting up". This is a readiness race that resolves in seconds.
What this error means
A connection made just after the container starts is closed with "FATAL: the database system is starting up". pg_isready returns code 1 ("rejecting connections") during this window.
psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed:
FATAL: the database system is starting upCommon causes
The server is still in startup or recovery
After the postmaster opens the socket it runs recovery before accepting queries. Connections in that gap get this FATAL instead of "Connection refused".
A simple port check passed too early
A TCP-only readiness probe sees the open port and proceeds, but the server is not yet query-ready.
How to fix it
Probe readiness with pg_isready, not a port check
pg_isready distinguishes "accepting connections" (0) from "rejecting" (1) and "no response" (2). Loop until 0.
until pg_isready -h localhost -p 5432 -U postgres -d postgres; do
echo "postgres still starting up"; sleep 1
doneUse a healthcheck that runs a real query
A health command that connects and selects ensures recovery is complete before steps run.
options: >-
--health-cmd "pg_isready -U postgres && psql -U postgres -c 'select 1'"
--health-interval 5s
--health-retries 10How to prevent it
- Gate steps on
pg_isreadyreturning 0, not just an open port. - Give the healthcheck enough retries for recovery on slow runners.
- Avoid mounting a large pre-seeded data dir that lengthens recovery.