Docker Compose Startup Order: Wait for Database Readiness with healthcheck

If an application fails to connect to its database immediately after Docker Compose starts it, distinguish a running container from a database that is ready to accept connections. Basic depends_on orders startup but does not wait for readiness. Add a suitable healthcheck to the dependency and use condition: service_healthy to wait for it during initial startup. The application still needs its own reconnection logic for later failures.

A generated conceptual illustration of one service waiting for another to become ready. It is not a Docker screenshot.

Documentation checked: November 3, 2026. The configuration below is an illustrative example based on the official documentation. Docker was unavailable in this environment, so it was not executed and the failure was not reproduced.

Running is not the same as ready

Compose creates and starts services in dependency order. The short form depends_on: [db], however, does not verify that the database has completed initialization and accepts connections. An application that connects first may fail depending on timing. Docker startup order

In the long form, service_started waits for startup; service_healthy waits for the dependency's health check to pass. service_completed_successfully is useful when a one-off job must finish successfully before another service starts. Compose services reference

Example: wait for PostgreSQL

This minimal example uses a PostgreSQL client in place of a real application to attempt one connection. Save it as compose.yaml in an empty working directory. The password is for local demonstration only and must not be reused in production.

pg_isready checks whether the server is accepting connections. It does not guarantee that the application's account has the required permissions, tables exist, or migrations have completed. The health-check command must exist inside the image; design the check around the real service's readiness requirements. PostgreSQL pg_isready

interval, timeout, retries, and start_period control the check interval, execution timeout, tolerated failures, and initialization grace period. These are example values; adjust them to actual startup times and failure-detection goals. The dependent app does not start before the check passes, and a failed health status can block startup. Docker healthcheck reference

Check the configuration and status

Run these commands in an isolated local practice project. Pulling images requires network access and a Docker Engine.

config shows the configuration interpreted by Compose. Its output may include environment variables or secrets, so inspect it before sharing. During up, check that db becomes healthy before the one-off app runs SELECT 1 and exits. Output varies by environment; this example was not run here.

In another terminal, use docker compose ps -a to inspect containers and health, and docker compose logs db app to distinguish failed checks from application connection errors. A successful exit of the one-off app does not test a continuously running web server. When finished, run docker compose down from the practice directory. Do not run cleanup against an existing project or its data. Compose CLI

Handle failures after startup separately

service_healthy coordinates initial dependency startup. It does not guarantee that the app will recover its connection if the database restarts later or the network fails. Design connection timeouts, bounded retries with backoff, reconnection, and failure observability in the app. Avoid indiscriminate retries of non-idempotent operations.

The long-form depends_on option restart: true relates to explicit Compose updates or restarts of a dependency. It is not a monitor for every automatic restart by the container runtime, nor is it equivalent to application reconnection logic. Official reference

Choose a check that approximates what the app needs rather than merely checking whether a process exists, but do not assume a single readiness check proves all runtime behavior. Migrations can be modeled as a separate one-off service with a successful-completion condition, with additional checks for the actual app account's schema and permissions. This article did not execute a migration or failure-recovery test.

한국어 버전: Docker Compose에서 DB 준비 전에 앱이 시작될 때: depends_on과 healthcheck