depends_on is not enough: PostgreSQL healthcheck in Compose

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.

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.

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.

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.

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.

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.

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.

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.