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
On the server, see what it listens on and on which port.
SHOW listen_addresses; SHOW port;
- 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
From the server's shell, confirm something is listening on the port.
ss -ltnp | grep 5432
- 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.