You use Docker Compose to start a database and an application, with depends_on defining the dependency between them. Yet the application reports a database connection error. You configured the database to start first, but the application only connects when you restart it a little later.

Compose is following your configuration. When you list only a service name under depends_on, it waits for the database container to start. It does not wait for the database to accept connections.

We’ll use PostgreSQL to see the difference between controlling startup order and waiting until the database can accept connections.

Listing a service under depends_on only controls startup order

Here is a common configuration:

depends_on:
  - db

This starts the db container before the application. The condition used by this form is service_started. Writing that condition explicitly gives you the same startup behavior:

depends_on:
  db:
    condition: service_started

condition specifies the state a dependency must reach before Compose proceeds. service_started means “continue once the container has started.”

Both forms wait only for the container to start, whether or not db has a health check. To wait for a successful health check, you need condition: service_healthy, which we'll use below. The Compose specification defines a service-name-only dependency and service_started as equivalent conditions.

But a running PostgreSQL container is not necessarily ready for connections. On its first start, PostgreSQL takes time to initialize its data directory and run initialization scripts. Recovery may also be needed after a restart. If the application tries to connect while this work is still in progress, the connection fails.

The startup order can be correct while the database is still getting ready. Docker’s documentation makes the same distinction between a running container and a ready service.

To wait for readiness, use healthcheck together with condition: service_healthy. A healthcheck periodically runs a command inside the container and uses its result to assess the container's health. With service_healthy, Compose waits for the dependency to pass that check and become healthy before starting the dependent service. Here, the check tests whether the database accepts connections.

Adding a healthcheck alone is not enough. If depends_on still lists only the service name, Compose continues to wait only for startup. You need both healthcheck and condition: service_healthy.

Try it with a connection test container

There is no need to build an application just to test a database connection. Instead, we’ll use a probe container that runs SELECT 1; and exits.

This example uses PostgreSQL 16. It assumes Docker Engine and the Compose plugin are installed and that you can run docker compose. If you have used docker compose up and down, you can follow along without prior knowledge of health checks. We'll run Compose on a single machine; Docker Swarm, which can distribute containers across multiple machines, is outside the scope of this example.

The example was tested on November 12, 2026, with Ubuntu 26.04.1 LTS on WSL2, Docker Engine 29.9.1, Docker Compose 5.6.0, and PostgreSQL 16.15.

Create a new working directory and save the following as compose.yaml.

We’ll use the project name depends-on-demo. Database data is stored in a named volume, so make sure you do not already have a project with that name. The password is for this experiment only; do not use it in production. The database port is not published to the host.

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: local-demo-only
      POSTGRES_DB: demo
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", 'pg_isready -h 127.0.0.1 -U "$${POSTGRES_USER}" -d "$${POSTGRES_DB}"']
      interval: 2s
      timeout: 3s
      retries: 15
      start_period: 10s

  probe:
    image: postgres:16
    environment:
      PGHOST: db
      PGPORT: "5432"
      PGUSER: demo
      PGPASSWORD: local-demo-only
      PGDATABASE: demo
      PGCONNECT_TIMEOUT: "3"
    depends_on:
      db:
        condition: service_healthy
    command: ["psql", "-w", "-v", "ON_ERROR_STOP=1", "-c", "SELECT 1;"]

volumes:
  db-data:

The db service has a healthcheck, and probe depends on it with condition: service_healthy. Under the Compose specification, startup proceeds as follows:

1. Compose starts the db container.
2. The health check runs repeatedly inside db. Once the database accepts connections, the check succeeds and the container becomes healthy.
3. Compose starts the probe container.
4. probe connects to the database, runs SELECT 1;, and exits.

To make connection and SQL failures visible, the psql command in probe uses -w to avoid waiting for a password prompt and -v ON_ERROR_STOP=1 to stop on SQL errors. The SQL statement to execute follows -c.

Check connection readiness with healthcheck.test

In the configuration above, pg_isready is the command under db → healthcheck → test. It checks whether PostgreSQL accepts connections. If it does, the command returns exit code 0 and the health check succeeds.

The -h 127.0.0.1 option makes the check connect over TCP from inside the database container. -U specifies the user, and -d specifies the database name.

The official PostgreSQL image starts a temporary server during initialization. That server accepts connections through a Unix socket, a local communication endpoint within the container. If pg_isready uses that socket, it can reach the temporary server and pass the health check. The container could then be marked healthy and probe could start before initialization has finished.

Using TCP avoids treating that temporary server as ready. This choice follows the official image’s entrypoint script; it is not a universal rule for every database image. When adapting the check to another container, choose a command and connection method that actually test what “ready” means for that service.

Start the containers

From the directory where you saved the configuration, validate it, start the containers, and inspect their state and logs:

docker compose -p depends-on-demo config -q
docker compose -p depends-on-demo up -d
docker compose -p depends-on-demo ps -a
docker compose -p depends-on-demo logs --timestamps db probe

In the output of docker compose -p depends-on-demo ps -a, look for db to be healthy and probe to show Exited (0), meaning it finished successfully with exit code 0. In the output of logs --timestamps db probe, check that the probe log contains 1 as the result of SELECT 1;.

--timestamps adds a timestamp to each log line; it does not sort logs from different containers into chronological order. The probe logs may appear before the db logs. Compare the timestamps on the lines rather than their position in the output to determine which event happened first.

up -d does not wait for probe to finish. If probe is still running, wait briefly and run the same ps -a and log commands again.

Since probe runs just one SQL statement, an exited container is expected.

Command options

Here is a quick reference for the options above. If you already know them, skip ahead.

OptionPurpose-p depends-on-demoSets the Compose project name. This -p does not specify a portconfig -qValidates the configuration without printing it on successup -dStarts the containers in the backgroundps -aIncludes exited containers in the listinglogs --timestampsAdds a timestamp to each log line

Compare with a configuration that only waits for startup

Here is the full configuration for comparison. It keeps the healthcheck on db and changes only probe's depends_on to the service-name-only form.

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: local-demo-only
      POSTGRES_DB: demo
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", 'pg_isready -h 127.0.0.1 -U "$${POSTGRES_USER}" -d "$${POSTGRES_DB}"']
      interval: 2s
      timeout: 3s
      retries: 15
      start_period: 10s

  probe:
    image: postgres:16
    environment:
      PGHOST: db
      PGPORT: "5432"
      PGUSER: demo
      PGPASSWORD: local-demo-only
      PGDATABASE: demo
      PGCONNECT_TIMEOUT: "3"
    depends_on:
      - db
    command: ["psql", "-w", "-v", "ON_ERROR_STOP=1", "-c", "SELECT 1;"]

volumes:
  db-data:

Create a separate working directory for this comparison and save the configuration there as compose.yaml. From that directory, start it with a different project name. This creates a fresh volume for initialization, keeping it separate from the data used in the first experiment.

docker compose -p depends-on-short-demo up -d
docker compose -p depends-on-short-demo ps -a
docker compose -p depends-on-short-demo logs --timestamps db probe

The health check still runs, but Compose starts probe without waiting for it to pass.

This does not mean the connection will always fail. If PostgreSQL initializes quickly, it may be ready by the time probe connects. The same can happen with an already initialized volume.

Even if the query succeeds, Compose did not wait for the database to become ready.

Does healthy mean the connection will succeed?

A database can accept connections and still reject an incorrect username or password. pg_isready checks whether the server accepts connections; it does not verify the application's credentials.

The PostgreSQL documentation notes that a correct username or password is not required to determine the server’s status.

That is why this example runs SELECT 1; from probe as a separate check. The query tests service-name resolution, a connection over the network, authentication, and SQL execution. The options used here are documented in the psql reference.

Even a successful SELECT 1; does not establish that the application's tables or required permissions are in place. If the application needs database migrations, check that they have finished as well. Compose also provides service_completed_successfully, a condition that waits for another service to finish successfully.

Being able to connect to the database and being able to perform the application’s work are separate checks.

If you get an error

Startup timing is only one possible cause of a connection error. Use the error message to decide what to check.

SymptomWhat to checkConnection refusedDatabase state, listening address, and destination portHostname cannot be resolvedService name and the networks the containers belong toPassword authentication failedCredentials and database authentication settingsTable does not existTarget database, schema, and migrations

These are starting points for investigation. A symptom does not always map to a single cause.

Also check the connection address. In this example, probe connects to db:5432. If you use localhost, it tries to connect to probe itself rather than the database container.

Containers on the same Compose network use the service name and the container-side port. As Docker’s networking documentation explains, you do not need to publish the database port to the host. Publishing a port will not fix an incorrect connection address.

Connection failures after startup need a separate solution

service_healthy handles readiness at startup. It does not make Compose manage application connections if they break later.

For example, a database restart can invalidate connections the application is holding. The application needs a way to reconnect.

Check the behavior of your database driver and connection pool. For temporary failures, retry with a defined interval and a limit on attempts or total time. Do not retry indefinitely when the error is persistent, such as an incorrect password.

Reconnecting and retrying a SQL statement are different operations. If the connection drops just after a write, you may not know whether the transaction was committed. Consider whether repeating that write could create duplicate data.

In Compose 2.17.0 and later, you can set restart: true under db in the application's depends_on configuration. This lets Compose restart the dependent application when it updates or explicitly restarts the database, for example with docker compose restart db. It does not apply when a crashed container is automatically restarted, and it does not replace application-level reconnection logic.

You can also add sleep 10 before starting an application. That may work in some environments, but the connection will fail again if the database needs more than ten seconds. The condition to wait for is the database accepting connections, rather than a fixed amount of elapsed time.

Clean up

When you finish, choose one of the following commands depending on whether you want to keep the database data. Run it from the directory where you saved the configuration.

To keep the data, remove only the containers and network:

docker compose -p depends-on-demo down

If you no longer need the experiment’s database data, run down -v instead of the plain down above. This removes the database volume along with the containers and network.

down -v deletes the data in the volume. Check that you are in the experiment's working directory and using its project name before running it.

docker compose -p depends-on-demo down -v

If you also ran the comparison, clean it up from its own working directory using the same cleanup command with the project name changed to depends-on-short-demo.

When depends_on does not resolve a database connection error, first check whether it waits only for startup or for the database to become healthy. Authentication errors, missing schema, and disconnections after startup each need their own diagnosis and response.

Originally published at https://practicalsyslab.substack.com on November 11, 2026.

Ask an AI a question, and it can explain how to write a program or troubleshoot a computer problem. Does that mean we no longer need technical knowledge?

I think the knowledge we need to work out what to ask has become more important than before. AI can quickly suggest possibilities, but when we use a chat that cannot inspect our computer directly, we need to tell it what is happening.

Suppose we ask, “My computer has been slow lately. How do I fix it?”

The AI might suggest restarting it, removing unnecessary applications, or checking the available storage space. These are all reasonable starting points, but the cause is still unknown.

Now add some observations:

Everyday tasks work normally, but copying a large file to an external USB drive takes a long time. I don’t know when the transfers became slow.

If we know that the destination and connection can affect file transfer speed, we can recognize why we need to mention the external USB drive. Making the question more specific helps narrow down what to investigate. Still, this alone does not establish that a faulty drive is the cause. The connection, available space, and condition of the hardware need further checking.

Dealing with a problem involves at least three stages:

1. Observe: What happened, when, and under what conditions?
2. Isolate: Does changing a condition change the behavior?
3. Act: Test a possible cause before making a change to address it.

AI is good at expanding the range of possible checks and remedies. The user still has a role in accurately observing the actual situation and deciding how much may be changed.

For example, if we ask an AI for help tidying up and it says, “You can throw this document away,” we would check whether we might need it later before discarding it. Even when a suggestion sounds plausible, we need to consider what it affects and what could happen before acting on it.

Basic knowledge helps us put names to possible causes. Even thoughts such as “It might be a connection problem,” “It might involve the destination drive,” or “Authentication might be failing” can change the quality of our questions.

That knowledge also helps us check AI-generated answers. An explanation may sound plausible, yet depend on different conditions or a different software version, making it unsuitable for our situation. We can compare it with the software’s official instructions. If we do not understand the effects of a change or how to undo it, we should check with an administrator or someone knowledgeable before proceeding.

Knowledge helps us remember answers, but it also helps us explain what we have checked and what we still do not understand.

The knowledge that helps here is not limited to expertise gained at work. Learning a broad range of subjects throughout our school years also gives us a foundation for reading AI-generated answers and thinking for ourselves.

For example, understanding ratios and percentages lets us respond to “Sales doubled” with “What was the starting amount?” Sales rising from $100 to $200 and from $10,000 to $20,000 have both doubled, but the amounts gained are different. Both statements are correct, but the difference in scale matters.

Learning to keep experimental conditions consistent in science lessons can help us recognize that, if we change several computer settings at once and the problem disappears, we still do not know which change worked. Learning to distinguish claims from supporting evidence in reading and writing classes also helps us check whether an AI’s explanation has reasons behind it or contradicts itself along the way.

In an unfamiliar field, it can be hard even to notice which parts of an explanation to question or what to ask next. That is why I think there is value in encountering a broad range of knowledge, including things whose immediate use is unclear. We do not have to remember every lesson forever. Remembering that a way of thinking exists can give us a starting point for looking into it again.

Suppose an AI tells us to restart a computer, and the symptoms improve. We may decide that’s enough for now. But knowing a little about memory and running applications can lead to further questions: “Why did restarting help?” or “What should I check if it happens again?”

Learning how one thing works through an AI’s answer can help us notice more for ourselves the next time we ask for help. We do not need to be knowledgeable from the start. Understanding unfamiliar terms one by one as we encounter problems is also a way of building knowledge.

Return to the external drive example. Suppose the AI says, “The USB connection speed is causing the slowdown.” A fluent explanation can make us feel as though the cause has been found. But knowing that the connection can affect copying speed is different from knowing that it is the cause of this particular slowdown.

A little knowledge lets us ask, “What information led to that conclusion?” or “What should we check to distinguish it from other possible causes?” If we encounter an unfamiliar term, we can start by looking up its meaning and considering whether the explanation applies to our situation.

Asking the AI for its reasons does not mean the explanation itself is correct. We need to check whether there is evidence behind it, by comparing it with official documentation or examining the actual situation. Here, too, knowledge helps us work out what to compare and what results would conflict with the explanation.

When sharing information for these checks, avoid casually pasting passwords, private keys, personal data, or confidential company documents into an AI chat. Error messages also need checking for credentials or personal information.

It is convenient to get an answer from AI straight away. But being able to judge whether to act on that answer affects the outcome. What we learned at school and what we have picked up through everyday questions both help us make that judgment.

The next time something goes wrong, try writing one line about “what I know so far” and another about “what I have not checked yet” before asking for a solution. Even that can make the conversation with AI more specific.

This article discusses general problem-solving habits. Before making changes to a real system, check what the changes involve and how to recover if something goes wrong.

Originally published at https://practicalsyslab.substack.com on November 10, 2026.