PostgreSQL Connection Refused in Docker Compose? Diagnose Hostnames, Ports, Listening Addresses, and Access Rules in Order

A PostgreSQL connection problem becomes much easier to fix when you separate three different failures: the server cannot be reached, the server is reached but rejects the login, or the server is under connection pressure. Do not treat every error as a password problem or expose the database to the internet as a quick test.

For an application running in the same Docker Compose project as PostgreSQL, the usual connection target is the database service name and PostgreSQL’s container port: for example, db:5432. It is normally not localhost, and it is not the port published for your host machine. Compose services on the same network can discover each other by service name; Docker also notes that container IP addresses may change when containers are recreated. Docker’s Compose networking documentation describes this service-to-service model.

Start with the wording of the error

Error patternWhat it usually meansFirst layer to inspect
Connection refusedThe target address responded, but no PostgreSQL server is listening on that address and port, or the connection was rejected before PostgreSQL authentication.Hostname, port, running container, listening address
Connection timed outThe client did not get a response within its timeout period.Network path, firewall rules, wrong address, routing
FATAL: password authentication failed, no pg_hba.conf entry, or database/role errorsThe PostgreSQL server was contacted and returned a PostgreSQL-level response.Database name, role, password, TLS mode, access rules
Intermittent connection failures under loadThe connection path may work, but available sessions or another shared resource may be constrained.Active sessions, application pooling, server resources

“Connection refused” is a useful clue, not a diagnosis. PostgreSQL’s documentation identifies a server that is not listening at the attempted address or socket as a common cause; a timeout can instead point to a wider network or firewall problem. See the PostgreSQL server startup documentation for that distinction.

Locate the client before choosing a hostname

Where the client runsTypical hostTypical port
Another service in the same Compose networkdb (the database service name)5432 (the container port)
Your host machinelocalhost or 127.0.0.1The published host port
A container on a different networkDepends on deliberate network configurationDepends on the reachable target

Consider this illustrative Compose mapping: "15432:5432". A database tool on the host connects to localhost:15432. An api container in the same Compose network connects to db:5432. If that API uses localhost:15432, localhost means the API container itself, not the database container or your host.

The host and container connection targets differ: host access uses the published port, while Compose services use the database service name and container port.
The host and container connection targets differ: host access uses the published port, while Compose services use the database service name and container port.

Check Compose networking before editing PostgreSQL

First, confirm that the application and database containers are actually running. Then read the Compose file rather than guessing from a connection string. Look for the database service name, the application’s configured host and port, and any explicitly declared networks.

services:
  api:
    environment:
      DATABASE_HOST: db
      DATABASE_PORT: 5432
    depends_on:
      - db

  db:
    image: postgres
    ports:
      - "15432:5432"

In this illustrative configuration, the ports line is for access from the host. It does not change the internal PostgreSQL port used by peer containers. Publishing a port is unnecessary when only other services in the Compose network need the database, and omitting it reduces accidental host exposure.

Use Docker’s inspection tools to verify the assumptions. docker compose ps shows service state and published ports. docker compose port db 5432 shows the host mapping when one exists. docker network inspect can show which containers are attached to a network. For a meaningful test, run a client or a simple DNS/network check from the application container or an equivalent container on the same network—not only from your laptop.

Confirm PostgreSQL is listening on the intended interface

If the hostname and port are right but the connection is still refused, inspect the database container logs and PostgreSQL configuration. TCP connections require PostgreSQL to listen on an address reachable from the client. A loopback-only setting works for local clients in the same network namespace, but not for a separate application container.

The relevant setting is listen_addresses. Its appropriate value depends on the deployment design. In a private Compose network, it must include an interface through which the application container can reach PostgreSQL. Do not copy a broad address setting into a production system without considering who can reach the network. Changes to startup configuration require a PostgreSQL restart before they take effect.

Avoid a misleading readiness assumption

A container being marked as running does not necessarily mean the database is ready for application connections. PostgreSQL may still be initializing, recovering, or applying initial setup. Likewise, Compose startup ordering alone does not prove that the database has accepted a connection. Check the database logs and use application retry behavior or an appropriate health check where your deployment calls for it.

Treat authentication as a separate stage

Once PostgreSQL returns a FATAL message, stop changing Docker port mappings. Networking has progressed far enough for PostgreSQL to answer. Compare the application’s database name, role name, password source, and SSL mode with the database configuration. A surprisingly common issue is that an application still has an old environment variable or secret after a password change.

For TCP connections, PostgreSQL evaluates pg_hba.conf rules as well as listen_addresses. Rule type matters: host is for TCP connections, while hostssl requires SSL and hostnossl excludes it. Rules also match by database, user, and client address range. PostgreSQL’s pg_hba.conf documentation explains these matching dimensions.

  • Use the smallest client network range that fits the actual deployment.
  • Grant the application its own role and only the database privileges it needs.
  • Match the application’s SSL expectation to the server and access-rule design.
  • Do not add an unrestricted all-addresses, all-users rule just to make a test pass.

When failures appear only under load

If connections succeed at first and then fail during busy periods, inspect current sessions before increasing max_connections. The pg_stat_activity view provides one row per server process and can show the database, user, application name, client address, state, and current activity, subject to privileges. PostgreSQL documents pg_stat_activity and its visibility limits here.

SELECT datname, usename, application_name, client_addr, state
FROM pg_stat_activity
ORDER BY datname, usename, application_name;

Read the result as an operational clue, not permission to terminate sessions. Look for many idle connections from one application, unexpected client addresses, or a workload that creates a new connection for each request. Connection pooling and sensible application-side limits are often more durable fixes than simply raising the server limit. A higher max_connections also changes resource demands, so size and test that change for the server and workload rather than applying an arbitrary value.

A safe troubleshooting sequence

  1. Record the full error, target hostname, target port, and where the failing client runs.
  2. For same-network Compose services, test the service name and container port first.
  3. Confirm both services share the intended Docker network and that the database service is running.
  4. Use the published host port only when testing from the host machine.
  5. Check PostgreSQL logs and listening configuration if the result is connection refused.
  6. When PostgreSQL returns a FATAL response, verify credentials, database name, TLS expectations, and matching pg_hba.conf rules.
  7. For intermittent failures, inspect sessions and application connection behavior before changing capacity limits.
  8. Change one layer at a time, retest from the same network location as the application, and keep a note of the working connection string.

Know when this guide does not apply directly

This sequence is for a self-managed PostgreSQL instance, particularly one used with Docker Compose. Managed database services, Kubernetes clusters, Linux package installations, and Windows installations can have different configuration locations, network controls, TLS requirements, and log collection methods. In those environments, use the platform’s documented connection and networking guidance before changing firewalls or production authentication rules.

The central rule still holds: establish the client’s network location, use the address and port valid from that location, then move upward through server listening and access control. That order prevents unrelated changes and produces a clearer trail when the problem needs escalation.

Leave a Comment

Related Posts