Startup order

depends_on starts the database before the API, but started is not ready: PostgreSQL needs a few seconds before it accepts connections. condition: service_healthy waits until it really does.

How it works

With the short form depends_on: [db], Compose only waits for the db container to start. With the long form and condition: service_healthy, it waits for db's healthcheck to pass. The app should still retry its connection, because a database can restart later too.

What breaks

An API that connects once at start crashes with ECONNREFUSED when it beats the database, and a restart policy only hides it. The order only applies to docker compose up, not to server reboots or to a single service restarting.

In compose.yaml

services:
  api:
    build: ./api
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      retries: 10

See it break, then fix it

Write the Dockerfile or the compose file, type the docker commands, and watch a simulated server run them through reboots, upgrades and traffic. Free to start.

Open the learning path Open the sandbox