Docker Compose healthchecks: make depends_on actually wait for Postgres

Docker Compose is a tool for defining and running multi-container applications with one YAML file. Its depends_on field is the most misunderstood keyword in that file. If your Compose stack has a bare depends_on: list in front of Postgres, your app has never actually waited for the database.

Here is the fix, in three parts: the healthcheck plus condition: service_healthy setup, the socket trap that makes naive Postgres probes lie, and the two failure modes the gate hides.

In this post:

• What does depends_on actually guarantee?
• How do you wire the gate?
• Where does the socket trap bite?
• What are the two failure modes the gate hides?

You bring a stack up cold. The database container starts, the app container starts a beat later, and the app tries to open a connection before Postgres is finished initializing. The app crashes. This is a known failure class in microservice deployments: when a dependent service is unready, calls to it fail and the app misbehaves until the dependency becomes available (ISSREW 2019, "Avoiding Faults due to Dangling Dependencies by Synchronization in Microservices Applications"). If you set restart: unless-stopped, Compose quietly restarts it a few seconds later, by which point the database happens to be ready, and the stack looks fine. It is not fine. The restart policy papered over a race instead of fixing it, and the same stack can crash-loop the morning the host reboots.

Key Takeaways

• The short depends_on list only orders container start and stop. Compose explicitly "does not wait until a container is 'ready', only until it's running" (Docker docs).
• Waiting for readiness means a healthcheck on the dependency plus condition: service_healthy in the long depends_on form.
• On the official Postgres image, run pg_isready against TCP (-h 127.0.0.1 or the service name), not the default Unix socket, or the probe can pass while the real server is still down (docker-library/postgres issue 146).
• The gate is a startup gate, not a monitor. If Postgres dies or restarts later, your app still needs its own retry logic.

What does depends_on actually guarantee?

The short syntax, the one most quick-start guides show, does exactly two things: Compose creates and starts the dependency container before the dependent one, and removes it in reverse order on shutdown. That is the entire contract. The startup order page in the Compose documentation states it plainly: "does not wait until a container is 'ready', only until it's running" (Docker Compose startup-order docs, 2026). For a database, running and ready are different states separated by seconds of work.

The long form adds a condition per dependency, and there are three to choose from in the compose-file services reference:

• service_started: identical behavior to the short syntax.
• service_healthy: the dependency's healthcheck must report healthy before the dependent service starts. This is the readiness gate.
• service_completed_successfully: the dependency must run to completion with exit code 0, which is what you want in front of a one-shot migration job, not in front of a database.

There is a fourth long-form field people miss: restart: true, which makes Compose restart the dependent service when an explicit Compose operation restarts the dependency, so the app re-establishes its connections instead of pointing at a stale database session.

Why does Postgres race ahead of its own readiness?

The official Postgres image does real work between "container running" and "accepting your queries." On a first boot with an empty data directory, the entrypoint script runs initdb to create the cluster. It then starts a temporary Postgres server to set up roles and run anything you mounted into /docker-entrypoint-initdb.d/. Only after that does it stop the temporary server and exec the real one as PID 1.

The detail that matters for healthchecks: that temporary server is started with listen_addresses='', so it listens on the Unix socket only and not on TCP. The image is designed this way on purpose. Back in 2016, yosifkit put it as: "when it is listening on the network port via its non-loopback interface, it is ready to accept connections." During initialization the container is running, Postgres is running, and nothing on the network will answer. From the outside, the container looks started the whole time, which is exactly the state the short depends_on waits for and then stops waiting.

What I actually ran

To check that the fix works the way the docs describe, I tested this with a real cold start on my own host: Docker Compose v5.1.4, a postgres:16-alpine database with a TCP healthcheck, and an alpine app that prints one line after starting. The app declares depends_on: db: condition: service_healthy. From my testing, the sequence below is what actually happened, in this order.

For example, here is the exact output I watched during the cold start.

 Container compose-test-db-1 Starting
 Container compose-test-db-1 Started
 Container compose-test-db-1 Waiting
 Container compose-test-db-1 Healthy
 Container compose-test-app-1 Starting
 Container compose-test-app-1 Started
app-1  | APP-STARTED-WITH-db-healthy

Note the order: the app container is not even created until db reports Healthy. The diagram below is the same flow the output shows, with the gate drawn in.

Before adding the gate, the same file started both containers at once, and the app's very first connection attempt hit connection refused. In my experience, that is the failure most people blame on "the database being slow" before they find out the ordering was never there. The gate removes this specific race; it cannot remove every failure mode, which is the subject of the last sections.

How do you wire the gate?

healthcheck is a container configuration that makes the runtime probe your service at a fixed interval and report its state as starting, healthy, or unhealthy. service_healthy is the depends_on condition that waits for that state. Here is a runnable Compose file with both:

services:
  app:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
    environment:
      DATABASE_URL: postgres://app:apppassword@db:5432/appdb

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: apppassword
      POSTGRES_DB: appdb
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s

volumes:
  pgdata:

With this file, docker compose up starts db, probes it every 5 seconds, and does not create the app container until the healthcheck passes. The $$ doubling is Compose escaping: a single $ in a Compose file is interpolated by Compose itself, so $$ is what reaches the shell inside the container as a literal $.

pg_isready is the Postgres client's readiness probe; it exits 0 when the server accepts connections. The five timing knobs below use the defaults from the Dockerfile HEALTHCHECK reference. The Compose healthcheck block works the same way:

• interval (default 30s): how often the probe runs once the container is up.
• timeout (default 30s): how long one probe may run before it counts as a failure.
• retries (default 3): consecutive failures needed to mark the container unhealthy.
• start_period (default 0s): grace window where failures don't count toward retries.
• start_interval (default 5s): probe cadence during start_period only, needs Docker Engine 25.0 or later.

For a local dev stack, interval: 5s with start_period: 10s is plenty. In CI on a cold runner, or with a big initdb.d directory, give yourself more headroom: start_period: 30s and retries: 10 is a common starting point. Without a start_period, a database that takes 15 seconds to initialize can burn through its failure budget before it ever had a chance — for example, my own cold start took roughly eight seconds across initdb and the temporary server, inside the 10s window.

Where does the socket trap bite?

Copy-paste healthchecks for Postgres usually look like pg_isready -U postgres. That version can report healthy while the real server is still down, because pg_isready inside the container connects to the Unix socket by default, and the temporary initialization server answers on the Unix socket.

The maintainers' guidance is to force TCP. tianon's comment on the long-running readiness issue: "Simply adding -h 127.0.0.1 to the pg_isready command line should be enough to detect readiness correctly." (docker-library/postgres issue #146.) The docker-library healthcheck script does the same thing in a heavier form: it resolves the container's own hostname and connects with psql, explicitly "to not use the local unix socket."

Probe shape	What it detects	When it lies	Best for
pg_isready -U postgres (socket)	The Unix socket answers	During init: the temp server answers while the real one is down	Nothing in a multi-container app
pg_isready -h 127.0.0.1 -U ... (TCP, loopback)	TCP port 5432 accepts connections	Never on readiness; still blind to init scripts	The default choice
pg_isready -h db -U ... (TCP, service name)	The exact address other containers use	Never on readiness; still blind to init scripts	When you want the probe to mirror app traffic
psql -c "SELECT 1" (real login)	A role and database actually answer	Can fail for reasons unrelated to readiness (connection limits, pg_hba.conf)	When you need objects from initdb.d to exist first

One nuance from the same issue threads: pg_isready confirms the server accepts connections. It does not confirm that a role or database created by an init script exists yet. If your app needs objects created in /docker-entrypoint-initdb.d/, a TCP probe says "Postgres is up" while those scripts may still be running.

What are the two failure modes the gate hides?

Adding a readiness gate converts one vague failure (intermittent connection refused) into two specific ones. Knowing both is the difference between a five minute fix and an afternoon of log spelunking.

Failure mode one: "dependency failed to start: container db is unhealthy"

Your healthcheck runs, exhausts its retries, and Compose gives up on the whole chain instead of starting the app against a database it knows is not ready. It looks like the gate broke your stack. It didn't. This is the gate doing its job, loudly, at a point where you would otherwise be reading crash-loop logs from the app.

Debug it in this order:

1. docker inspect --format '{{json .State.Health}}' <container> — the Engine stores the last few probe results, stdout and stderr included, so you can see the actual command output that failed.
2. docker compose logs db — the usual suspects: the probe binary does not exist in the image (curl on an image that ships wget), a typo'd user or database name, or timing values too tight for a cold start.
3. If the error instead says the dependency "didn't complete successfully" or the container never leaves starting, check that the dependency actually defines a healthcheck. condition: service_healthy with no healthcheck defined means the condition can never be satisfied and the dependent service is never created.

Failure mode two: the gate passes, the app still crashes

service_healthy is evaluated once, at startup. It is not a runtime monitor. If Postgres restarts two hours later, or the bridge network hiccups under load, Compose does not restart your app to re-run the gate. The app still needs to handle a connection that drops mid-session.

This one-shot behavior is not unique to Compose. Orchestration research on Kubernetes health monitoring shows that how and how often you probe matters: a 2025 study of poll-based container monitoring found it "requires careful tuning," can erroneously detect failures, and that erroneous detections alone reduced service availability by 4% compared with signal-based monitoring (arXiv:2507.02158). The practical reading for a Compose stack: treat the startup gate as your first line, and build the retry into the application, because nobody re-probes for you later.

The belt-and-braces pattern is a retry with backoff at connection time, something like:

import time

def connect_with_retry(connect, attempts=10, base_delay=1.0):
    for attempt in range(1, attempts + 1):
        try:
            return connect()
        except Exception:
            if attempt == attempts:
                raise
            time.sleep(base_delay * attempt)

The healthcheck removes the common cold-start race. Only the application can ride out a dependency that blips later, after docker compose up has long finished and moved on.

How do you verify the gate works?

Watch the health column during a cold start (the exact sequence is above):

docker compose up -d
docker compose ps

You want to see db sit in a starting health state briefly, flip to healthy, and only then see the app container appear. If app starts at the same moment as db, the condition is not wired: check for a typo in the YAML or a missing healthcheck block on the target service.

Two commands worth memorizing for the moment something goes sideways:

docker inspect --format '{{json .State.Health}}' db
docker compose logs db

And for CI pipelines that need a hard wait without writing your own polling loop, docker compose up --wait blocks until every service with a healthcheck reports healthy or the timeout hits. It is a much cleaner signal than grepping logs for a "ready" string.

FAQ

Why does my app still crash if I copied the healthcheck from a tutorial?
The tutorial probably missed condition: service_healthy in the long depends_on form. Or its probe talks to the Unix socket instead of TCP. Both are covered above; the table in "Where does the socket trap bite?" is the quick checklist.

Does depends_on wait for the database by itself?
No. The short list only orders container startup. Readiness requires a healthcheck plus condition: service_healthy.

Is pg_isready -h 127.0.0.1 enough, or do I need psql?
For "is Postgres accepting connections", pg_isready over TCP is enough and is what the image maintainers recommend. Use a psql login probe only when you also need init scripts to have finished.

Will the healthcheck protect the app if Postgres restarts later?
No. service_healthy runs once at startup. The application needs its own connection retry logic for post-startup failures.

What should I use in CI instead of polling?
docker compose up --wait blocks until healthy services report healthy, which replaces hand-rolled polling loops.

What are the five lines that matter?

Strip the whole article down and this is what ships: a healthcheck on the database that probes TCP readiness, and a depends_on with condition: service_healthy on the app. Everything else is tuning. Start with interval: 5s, retries: 5, start_period: 10s locally, loosen them for CI, and add app-level retries because the gate only protects the startup sequence, not the runtime.

If your current compose file has a bare depends_on: list in front of Postgres, that is the line to change today. It was never waiting for the database, and the first cold boot on a slow disk will be the one that reminds you.

Verified against Docker Compose v5.1.4 and the compose-spec reference on 2026-10-25, and fact-checked against every linked source (docs.docker.com, docker-library/postgres issue #146, the Dockerfile reference and the compose-file reference). I flag anything I could not reproduce.

Sources

Every claim above traces to these primary sources. Where I could not verify something hands-on, the post says so.

• ISSREW 2019, "Avoiding Faults due to Dangling Dependencies by Synchronization in Microserv
• Docker docs
• docker-library/postgres issue 146
• compose-file services reference
• entrypoint script
• Green container passing through an open gate at a busy container port at dusk
• Anatomy of the readiness gate: the app waits while pg_isready probes Postgres; the socket
• Dockerfile HEALTHCHECK reference
• works the same way
• docker-library healthcheck script
• Two probe paths out of the Postgres container: the socket probe answers during init, the T
• The two failure modes: an unhealthy gate blocks the app loudly (left), a passed gate still
• arXiv:2507.02158
• compose-spec reference
• GitHub

About the author

Kunal Das writes operations engineering notes as he learns them, always against primary sources. Contact: GitHub and Dev.to. Follow the Docker tag for the next posts in this series.