Understand links and depends_on in Docker Compose

depends_on declares service dependencies and startup conditions. links supplies link aliases and also creates an implicit dependency. Modern Compose services on a shared network can normally resolve each other by service name without links, but the current Compose specification still documents links; calling it universally removed or deprecated is inaccurate.

Network access does not require a startup dependency

Services on the default project network can use names such as db to reach the database container's listening port. No host-port publication is needed for that path. The server must still be listening, accepting the connection, and authorizing the client.

Explicit network configuration can separate services. links does not override that separation or connect services that have no shared network. Similarly, depends_on does not attach a service to a network or open a port.

A legacy entry such as links: ["db:database"] may provide an alias the application still uses. Before removing it, replace that name through a network-scoped alias or change the application configuration. Preserve any intended startup dependency explicitly.

Start a dependency before its consumer

Short syntax declares the dependency:

services:
  web:
    image: myapp:1.2
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set a database password}

This example assumes an application image and a supplied password. Starting the database container is not the same as waiting until it accepts application connections.

Wait for a defined health check

services:
  web:
    image: myapp:1.2
    environment:
      DB_HOST: db
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set a database password}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

This is an alternative to the previous configuration. The TCP check avoids treating the image's temporary initialization socket server as the final network server. pg_isready checks connection acceptance, not whether your application's credentials, schema, or migrations are correct. Supply the application's actual database settings separately, and handle authentication securely.

A successful probe can mark the container healthy before all retry attempts elapse. Retries count consecutive failures; they are not a requirement for several successful checks. Persistent failure prevents the healthy dependency condition from being satisfied and may cause startup to fail.

Maintain resilience after startup

service_healthy is a startup gate. It does not pause or restart an already running consumer whenever the database later becomes unhealthy. Applications still need bounded retries, reconnection, useful errors, and safe handling of interrupted writes.

Long-syntax restart: true is also narrower than a universal restart cascade: it concerns explicit Compose-controlled dependency updates or restarts, rather than every runtime crash. Check the installed Compose version before using newer dependency options.

In Kubernetes, readiness checks, application retry behavior, and sometimes a bounded init-container wait serve related purposes. There is no direct general-purpose depends_on equivalent across Deployments; an unbounded init wait can itself stall a rollout.

After migration, compare actual startup connection failures and recovery behavior. Guance log collection can preserve those events once configured; fewer errors in one startup do not prove resilience to later outages.

See Compose links and dependency settings and Compose startup ordering.