The bug

postgres' docker-entrypoint runs a temporary server reachable only over the Unix socket (listen_addresses='') once initdb has finished, so it can create the database and run docker-entrypoint-initdb.d.

A pg_isready healthcheck without -h talks to that socket. So it reports "accepting connections" while no TCP listener exists at all — compose marks the service healthy, depends_on: condition: service_healthy releases the dependent, and the dependent connects straight into ECONNREFUSED.

It only bites on a fresh volume, because a populated one skips initdb and the temporary server entirely. That is why it surfaces as a rare flake rather than a consistent failure.

Evidence

From the CI failure this was diagnosed from (enterprise umami-linux, a matrix cell that creates its volume):

compose logged Container umami_db Waiting → Container umami_app Started, then the app died with Can't reach database server at 172.78.0.10:5432, while the db showed Up 11 seconds (healthy).

Verification

Reproduced and mutation-tested locally with a compose mirroring the depends_on: service_healthy shape:

Directly measured the false-healthy window against the patched file: the old check reports healthy from t=2s while TCP is refused until t=8s; the patched check holds starting and only goes healthy once TCP is genuinely up. Reproduced on postgres 13.3, 15 and 16.

Why -h 127.0.0.1

The stock images ship listen_addresses = '*', so the real server binds 0.0.0.0 — one bind() covers loopback and the container IP, and the static ipv4_address is configured before PID 1 runs, so there is no phase where loopback works and the network IP does not. During startup/recovery pg_isready reports rejecting connections, so the probe correctly keeps failing until the server can actually serve. localhost would be the wrong literal (it may resolve ::1 first).

Note on pg_isready semantics

pg_isready is a liveness probe: it exits 0 even for a nonexistent role/database, and even when pg_hba.conf rejects the connection. The -U/-d flags here are effectively decorative. That is fine for this fix — the real listener only starts after initdb created the role and database — but it does mean the probe is not a substitute for an application-level readiness check.