Compose depends_on condition: service_healthy with a healthcheck

A plain depends_on: [db] only waits until the db container has started, not until the database accepts connections. With the long syntax and condition: service_healthy, Compose waits until the dependency's healthcheck reports healthy before it creates the dependent service.

Example

cat > compose.yaml <<'EOF'
name: demo
services:
  web:
    image: nginx:1.29
    depends_on:
      db:
        condition: service_healthy
        restart: true
  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s
EOF
docker-compose config

name: demo
services:
  db:
    image: postgres:18
    networks:
      default: null
    healthcheck:
      test:
        - CMD-SHELL
        - pg_isready -U postgres
      timeout: 3s
      interval: 5s
      retries: 10
      start_period: 10s
  web:
    image: nginx:1.29
    networks:
      default: null
    depends_on:
      db:
        condition: service_healthy
        restart: true
        required: true
networks:
  default:
    name: demo_default

docker compose config prints the resolved configuration, including the defaults Compose fills in (required: true, the default network).

Conditions

Related keys

• restart: true restarts the dependent service when the dependency is restarted by a Compose operation.
• required: false lets the project start when the dependency is not defined (Compose 2.20+).
• The healthcheck command runs inside the dependency's container, so the binary (pg_isready, curl, redis-cli) must exist in that image.