PostgreSQL · error reference

PostgreSQL: Connection refused — is the server accepting TCP/IP connections?

connection to server at "db.example.com" (203.0.113.7), port 5432 failed: Connection refused
	Is the server running on that host and accepting TCP/IP connections?

The host answered and said no. Nothing is listening on that address and port — which is a different problem from a firewall, and has a different fix.

What the database is telling you

The client's TCP connection was actively rejected: the machine is reachable, but no process accepts connections on that port, or a firewall rule rejects (rather than drops) the packet. A firewall that drops packets produces a timeout instead — the distinction tells you where to look.

Why it shows up in a migration

A server that works for an application on the same machine is often listening on localhost only. The first connection from outside — a migration tool, a CI job — is the first time anyone notices.

Common causes

  • listen_addresses is 'localhost' (the default in many packages), so remote connections are refused.
  • PostgreSQL is not running, or is running on another port (5433 is common when two versions are installed).
  • In Docker, the container's 5432 is not published to the host (-p 5432:5432), or you are connecting to localhost from inside another container.
  • A host firewall rule REJECTs the port.

How to fix it

  1. 1

    On the server, see what it listens on and on which port.

    SHOW listen_addresses;
    SHOW port;
  2. 2

    Listen on the network interface too (needs a restart), and allow the client in pg_hba.conf.

    ALTER SYSTEM SET listen_addresses = '*';
    -- then restart PostgreSQL, and add to pg_hba.conf:
    -- host  shop  app  203.0.113.7/32  scram-sha-256
  3. 3

    From the server's shell, confirm something is listening on the port.

    ss -ltnp | grep 5432
  4. 4

    Between containers, connect to the service name (db:5432), not localhost — localhost is the container itself.

What DBShifts does about it

Connection diagnosis tells refused from timed out: refused gets "Connection refused" with the hint to check the port and that the server accepts remote connections, or to add an SSH bastion for a private database; a timeout is reported as most likely a firewall, with the address to allowlist.

Connection diagnosis

Connecting a database?

Add the database to DBShifts and the connection is tested on the spot. If it fails, you get which of these errors it is and what to change — not the driver's raw message. Once it connects, browse it, migrate it, or let an AI agent read it through the gateway with sensitive columns masked.

← All database errors