PostgreSQL 'could not connect to server: Connection refused' / 'connection to server at ... failed: Connection refused' - is the server running, listen_addresses, pg_hba.conf and Docker networking

Cause: 'Connection refused' means nothing accepted the TCP connection at that host and port. It is different from an authentication error, which means the server was reached. Common reasons: the server is not running, it listens only on localhost (the default listen_addresses is 'localhost'), the port differs from the 5432 you are using, a firewall drops traffic, or in Docker the client uses localhost to mean another container. Fix (best first): 1. Confirm the server is up and where it listens: check the service or container status and its log, and on the server run ss -ltnp | grep postgres (or psql through the Unix socket) to see the address and port. 2. For remote clients, set listen_addresses in postgresql.conf to the needed interface address (for example 'localhost,10.0.0.5', or '*' only behind a firewall), then restart; this setting only changes at server start. Listening is separate from authorization. 3. Allow the client in pg_hba.conf with the narrowest rule, for example: host appdb appuser 10.0.0.0/24 scram-sha-256 (use hostssl to require TLS). The first matching line wins. Reload with SELECT pg_reload_conf(); and check the pg_hba_file_rules view for lines with a non-null error. A missing pg_hba entry normally gives a 'no pg_hba.conf entry' message rather than 'refused'. 4. Docker: inside a container, localhost is the container itself, so an app container must use the database container's service name on a user-defined network (such as a Compose network), not localhost, and not the default bridge where names do not resolve. Publishing a port with -p 5432:5432 is needed only for access from the host or outside, and the Postgres server inside the container must listen on a non-loopback address (the official image does by default). 5. Check firewalls and cloud security groups for the port, and avoid opening 5432 to the whole internet. Verify: pg_isready -h <host> -p 5432 reports 'accepting connections', and psql 'host=<host> port=5432 dbname=<db> user=<user>' connects. Sources: https://www.postgresql.org/docs/current/runtime-config-connection.html https://www.postgresql.org/docs/current/auth-pg-hba-conf.html https://docs.docker.com/engine/network/