Why doesn't depends_on wait for my database in Docker Compose?

Because plain depends_on waits for the database's container to start, not for the database inside it to accept connections. Compose's own documentation says what it guarantees: it "always starts and stops containers in dependency order". Order is all you get. To make the app wait, switch to the long syntax with condition: service_healthy and give the database a healthcheck. For Postgres that check has to go over TCP, pg_isready -h 127.0.0.1, and it needs start_interval set, or the fix either lets the app in too early or makes every start 30 seconds slower.

Two answers circulate, and the second one is only half right#

The first answer is "add depends_on: [db]". It is in nearly every compose file, and it often appears to work, which is why it survives. It is the service_started condition, which the compose reference describes as the default and as "an equivalent of the short syntax". The database container is running, the database is not.

The second answer is "use condition: service_healthy with pg_isready -U postgres". That is the right mechanism with a check that can pass before Postgres accepts the app's connections. It is the same shape as the healthcheck in Docker's own startup-order example, which also leaves out -h. On a first boot with an init script, our app got past it and then had its connections refused for 14.5 seconds. The reason is in the Postgres image's entrypoint, covered below.

What each setup did, measured#

We ran each case on Docker Engine 28.1.1 with Compose 2.35.1, using the official postgres:18-alpine image (PostgreSQL 18.6). The "app" was a second container that tried psql -h db -c 'select 1' over TCP every 0.1 seconds from the moment it started, and counted failures.

Plain depends_on with existing data won the race on every run, against a small database on an idle server. That is why the bug is so often reported as "only on first install" or "only after a reboot": the race is lost when the database is slow to start, which is exactly when it is doing crash recovery, replaying a large write-ahead log, or initializing for the first time.

The 30.7-second row is the cost of the defaults. The fifth row is the trap.

The pg_isready trap: healthy before it is ready#

On first boot, the official Postgres image does not start the real server straight away. Its docker-entrypoint.sh runs initdb, then starts a temporary server with -c listen_addresses='', creates the database, runs every script in /docker-entrypoint-initdb.d, stops the temporary server, and only then execs the real one. An empty listen_addresses means the temporary server listens on the Unix socket and on no TCP port at all.

pg_isready -U postgres with no -h connects through that socket. The PostgreSQL documentation gives exit status 0 when "the server is accepting connections normally", and the temporary server is. In our run, the first health log entry, 1.17 seconds after the container started, read /var/run/postgresql:5432 - accepting connections. Compose released the app, the app connected over the network to a server with no TCP listener, and it got Connection refused until the real server came up at the end of the 15-second script.

Add -h 127.0.0.1 and the same check goes over TCP, where the temporary server is invisible. Our app then started 17.7 seconds after the database, after the real server logged database system is ready to accept connections, and connected first time.

Without an init script the window is short: on our runs the temporary server lived for about 0.1 seconds, so a socket check rarely lands inside it. Restoring a dump on first boot, or any app whose image ships init scripts, makes it long. The -h costs nothing, so use it everywhere.

The healthcheck that works#

services:
  db:
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U app -d app"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s
      start_interval: 1s

  app:
    image: example/app:2.3.1
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
        restart: true

What each timing does, from the Dockerfile reference:

The pairing that matters is start_period with start_interval. During startup the check runs every second, so the app starts about a second after the database is ready, and failures in that window are not counted against retries. After the first success, checks slow to interval, so a steady-state check every 30 seconds costs almost nothing. Size start_period to the slowest first boot you expect, including any restore in an init script. It is a ceiling on how long failures are forgiven, not a delay.

What the error looks like when the check never passes#

If the database's healthcheck fails retries times in a row, Compose stops waiting:

 Container stack-db-1  Waiting
 Container stack-db-1  Error
dependency failed to start: container stack-db-1 is unhealthy

docker compose up -d exited with status 1, and the app container was left in Created. It stays there. Moby's restore code only restarts containers that have a restart policy and HasBeenStartedBefore, so a container that never ran is not started on the next boot either. Fix the cause and run docker compose up -d again.

The cause is usually the check, not the database. Read what the check printed:

docker inspect -f '{{range .State.Health.Log}}{{.ExitCode}} {{.Output}}{{end}}' stack-db-1

A check that calls a tool the image does not ship fails forever. On alpine, a curl -f http://localhost/ check went unhealthy with the output /bin/sh: curl: not found, and from docker compose ps that looks exactly like a broken service. Use whatever the image ships: pg_isready in Postgres images, wget in many Alpine-based ones.

What restart: true does, and what it does not#

restart: true under a dependency is a Compose feature, added in 2.17.0. Docker's documentation says it restarts the dependent service "if db is updated or restarted due to an explicit Compose operation, for example docker compose restart". We tested both ways of restarting the database:

Anything that bypasses Compose bypasses restart: true, and a reboot, covered next, bypasses Compose. It is worth setting for apps that keep a connection pool and never reconnect, but it is not a recovery mechanism.

After a reboot, depends_on does nothing#

This is what most guides leave out. depends_on is read by Compose, the client. When the host reboots, Compose is not running, and the Docker daemon starts the containers on its own, according to each one's restart policy.

Moby's daemon/daemon.go shows how. On startup it collects every container with a restart policy and starts them in parallel goroutines. The only ordering is a "best effort to wait for children": legacy links in 28.1.1, and links or a container whose network namespace is shared in docker-v29.9.1. Even then it waits for the other container's start to complete, not for it to be healthy, and gives up after 5 seconds. Compose does not create links for depends_on: our app container's HostConfig.Links was empty.

So after a reboot, your app and your database start side by side, with nothing holding the app back. Three defenses, in the order we would use them:

1. Let the app retry. If the app retries its database connection on startup, a reboot costs nothing. If it exits instead, restart: unless-stopped brings it back until it connects. That is a crash loop, but a short one.
2. Bring the stacks up with Compose after boot. A systemd unit that runs docker compose up -d in each stack's directory after docker.service re-applies the conditions on every boot. The cost: those services need restart: "no", or the daemon starts them first anyway, and then nothing restarts them if they crash later.
3. Use systemd ordering instead. Podman with Quadlet turns containers into units with real dependencies; Docker vs Podman covers what that costs you on the Compose side.

Updates are the other moment a stack restarts, often with a schema migration in the new image. An update strategy that does not lose data covers why to take a backup first.

When this answer stops applying#

• Compose and Engine versions. start_interval needs Engine 25.0 or later, restart: under depends_on needs Compose 2.17.0, and required: false needs 2.20.0. On anything older, the field is rejected or ignored.
• podman-compose. It handles service_healthy inconsistently; Docker vs Podman has the detail. Nothing here was tested on it.
• A database on another host or a shared instance. depends_on only sees services in the same project. A single Postgres serving several stacks, which One shared Postgres or one per app argues against, gives each app nothing to wait on.
• A 137 or a crash loop that is not about the database. If the app is dying for another reason, What Docker exit code 137 means covers how to tell an out-of-memory kill from a stop timeout.

What to do next#

Search your compose files for pg_isready without -h and add -h 127.0.0.1. Add start_period and start_interval: 1s to every database healthcheck, and switch every depends_on: [db] to condition: service_healthy. Then reboot the server once, deliberately, and watch which containers crash-loop: those are the ones that do not retry, and no compose setting will save them on the next unplanned restart. The per-stack layout these snippets fit into is in Docker Compose conventions, and Docker Engine lists the Engine and Compose versions the fields above need.