🐳 Your App Container Starts Before the Database It Depends On Is Actually Ready
A `docker-compose.yml` lists the database as a `depends_on` dependency of the app service, and the app still fails on startup trying to connect to a database that’s technically running but not yet ready to accept connections – because Compose’s `depends_on` by default only waits for the dependency’s CONTAINER to start, not for whatever’s running inside it to actually finish its own startup and become ready.
🔎 The Problem
services:
app:
build: .
depends_on:
- db # only waits for the db CONTAINER to start
db:
image: postgres:16
# Postgres'"'"'s container process starts almost immediately, but the
# actual database engine inside it still takes a few seconds to
# initialize before it'"'"'s ready to accept connections. `depends_on`
# in this basic form only guarantees START ORDER of the containers -
# it says nothing about whether the service inside db is actually
# ready to be talked to yet.
✅ Fix: Use a Healthcheck-Based Condition
- Add a `healthcheck` to the dependency service, and use the `condition: service_healthy` form of `depends_on` on the dependent service – this makes Compose actually wait for the healthcheck to pass (i.e., the database confirms it’s ready) before starting the app, not just for the container process to exist.
- For Postgres specifically, a healthcheck using `pg_isready` (`test: [“CMD-SHELL”, “pg_isready -U postgres”]`) is the standard, reliable way to detect real readiness – equivalent readiness checks exist for MySQL, Redis, and most common dependency images.
⚠️ The Belt-and-Suspenders Approach
- Even with a proper healthcheck-based `depends_on`, it’s still good practice for the app itself to implement its own retry-with-backoff logic on startup for its database connection – this protects against the healthcheck itself being imperfect, and against the SAME issue happening later if the database restarts independently while the app keeps running.
depends_on getting the container running isn’t the same as the service inside it being ready to talk – those are two different moments, and only one of them is what your app actually needs to wait for.
