healthcheck

A command Docker runs inside the container on an interval, whose exit status sets the container's state to starting, healthy or unhealthy. In Compose: test: ['CMD-SHELL', 'pg_isready -U app'], with interval: 5s, timeout: 3s, retries: 10. Without one, the only thing Compose can tell you is that the container started, and depends_on: [db] waits for exactly that. PostgreSQL takes a few seconds more to accept connections: the application starts inside that window, fails, and restart: unless-stopped loops it until one attempt lands. The logs then show connection errors that look intermittent and are not. condition: service_healthy under depends_on is what separates started from accepting connections — and only if the test asks the service. A sleep 10 or a port test pass while the database still refuses queries: docker compose ps says healthy and nothing is.