depends_on is not enough: PostgreSQL healthcheck in Compose

Why `depends_on` by default fails

The practical consequences of a startup race condition

• connection refused — PostgreSQL's TCP socket is not yet open, the application fails on the first PDO or SQLAlchemy call.
• FATAL: role does not exist — PostgreSQL is listening, but the initialization scripts (docker-entrypoint-initdb.d) have not yet created the role or database.
• FATAL: the database system is starting up — the cluster is recovering from a clean shutdown; connections are temporarily refused.
• Silent crash loop — Docker restart: unless-stopped relaunches the application indefinitely, logs repeat, and the problem looks like an application error.
• False positives in CI — integration tests fail intermittently depending on the runner startup speed.
• Cascading dependencies — an API that depends on an app that depends on the database inherits the same problem if the depends_on chain is not uniformly correct.

Prerequisites: Docker Compose v2 and the official plugin

docker compose version

Configure a reliable PostgreSQL healthcheck, step by step

1. 01

   Understand service_started vs service_healthy

   depends_on accepts three conditions:

   - service_started (default) — waits for the container to simply be started.
   - service_healthy — waits for the container's healthcheck to return healthy.
   - service_completed_successfully — for short-lived containers (jobs, migrations).

   For any database, service_healthy is the only condition that guarantees the service accepts connections.

2. 02

   Write the PostgreSQL healthcheck in the `db` service

   Add the healthcheck block directly in the db service definition:

   services:
     db:
       image: postgres:16
       environment:
         POSTGRES_USER: app
         POSTGRES_PASSWORD: secret
         POSTGRES_DB: appdb
       healthcheck:
         test: ["CMD", "pg_isready", "-U", "app", "-d", "appdb"]
         interval: 5s
         timeout: 5s
         retries: 5
         start_period: 30s

   The test field receives a list: the first element is CMD (Docker executes the command directly), followed by the arguments. pg_isready returns 0 if PostgreSQL is ready to accept connections for the given user and database, and a non-zero code otherwise — which Docker interprets as healthy or unhealthy.

3. 03

   Understand the role of `start_period`

   start_period is the grace window given to the container to initialize before healthcheck failures start counting toward retries. During this window, Docker does run the healthcheck, but a failure does not increment the counter.

   Without start_period, a PostgreSQL that takes 15 seconds to initialize would fail its first 5 checks (interval: 5s × 5 attempts = 25 seconds) and go unhealthy before it was even operational.

   The recommended value is 30 seconds for a standard PostgreSQL: long enough to absorb slow initializations (first start with empty volume, heavy extensions) without unnecessarily delaying startup under normal conditions. interval and start_period are distinct: interval paces checks under normal operation, start_period protects the bootstrap phase.

4. 04

   Write the `depends_on` with `condition: service_healthy`

   In each service that depends on the database, replace the short form of depends_on with the long form with condition:

   services:
     app:
       image: myapp:latest
       depends_on:
         db:
           condition: service_healthy
       environment:
         DATABASE_URL: postgresql://app:secret@db:5432/appdb

   With this configuration, Docker waits for the db service healthcheck to return healthy before starting app. If db goes unhealthy after retries failures, app does not start.

5. 05

   Test with `docker compose up`

   Launch the stack and observe the sequencing:

   docker compose up

   You will see in the logs lines such as:

   db  | database system is ready to accept connections
   app | Waiting for db to be healthy...
   app | Starting application server

   To check the healthcheck state at any time:

   docker inspect <db_container_name> | grep -A 5 '"Health"'

   The output shows Status: healthy, starting or unhealthy, and lists the last check outputs.

6. 06

   Redis use case: adapted healthcheck

   Redis does not have redis-isready, but its equivalent is redis-cli ping:

     redis:
       image: redis:7-alpine
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 3s
         retries: 5
         start_period: 10s

   redis-cli ping returns PONG and exit code 0 if Redis accepts connections. Since Redis starts faster than PostgreSQL, start_period: 10s is generally sufficient.

7. 07

   MySQL / MariaDB use case: `mysqladmin ping`

   For MySQL or MariaDB, use mysqladmin ping:

     mysql:
       image: mariadb:11
       environment:
         MYSQL_ROOT_PASSWORD: secret
         MYSQL_DATABASE: appdb
       healthcheck:
         test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-psecret"]
         interval: 5s
         timeout: 5s
         retries: 5
         start_period: 30s

   Note: the password is concatenated directly to -p with no space (-psecret), which is the expected mysqladmin behavior. This command appears in docker inspect, so prefer a Compose secret or environment variable if confidentiality is a constraint.

8. 08

   Troubleshooting: four common errors

   pg_isready: command not found — you are not using the official postgres image (or a derived image that includes it). Check with docker compose exec db which pg_isready.

   Healthcheck looping, never healthy — the test never returns 0. Test manually: docker compose exec db pg_isready -U app -d appdb. If the command fails, check the POSTGRES_USER and POSTGRES_DB environment variables.

   start_period too short — on a first start with an empty volume, PostgreSQL can take more than 30 seconds. Increase to 60s or observe the logs: database system was shut down at … LOG: database system is ready to accept connections indicates the actual delay.

   Container permanently unhealthy — after retries failures, Docker marks the container unhealthy but does not restart it (that is the role of restart). Check docker inspect to see the output of the last checks and identify the failing command.

Default behavior vs with healthcheck

Scroll the table

Next steps