Postgres Connection Refused on Mac: A Practical Fix

Check port 5432 and test the same TCP connection

lsof -nP -iTCP:5432 -sTCP:LISTEN
pg_isready -h 127.0.0.1 -p 5432
psql -h 127.0.0.1 -p 5432 -d postgres -U "$USER"

An empty lsof result means nothing is listening on that TCP port. pg_isready can report whether a server responds without proving that your database name or password is correct.

Read the error before applying a fix

Connection refused is not an authentication failure. A bad password usually reaches PostgreSQL and returns a FATAL authentication message. A missing database also reaches PostgreSQL and names the missing database. Refused means the TCP listener was not there at the requested address and port.

A timeout is different again. It commonly points to a firewall, unreachable private address, failed IPv6 route, or cloud allowlist. Keep the original error text because it tells you which layer to inspect first.

Find which PostgreSQL installation owns the port

A Mac can have Postgres.app, Homebrew PostgreSQL, Docker, and an old installer present at the same time. Only one process can normally bind the same address and port. Check the process reported by lsof, then use that installation's controls to start or stop the server.

Do not delete postmaster.pid just because a page online suggests it. That file can describe a running server. Postgres.app recommends checking for PostgreSQL processes and reading its server log before treating a PID file as stale.

• Postgres.app: open the app and confirm the intended server shows as running.
• Homebrew: run brew services list and inspect the named PostgreSQL service.
• Docker: run docker ps and confirm the container publishes a host port such as 5432:5432.
• Manual server: use the matching pg_ctl binary and data directory, not a pg_ctl from another PostgreSQL version.

Force psql to use TCP

On macOS, psql without -h commonly uses a Unix-domain socket. A GUI connection to localhost uses TCP. This explains the confusing case where psql works but a desktop client receives connection refused.

Test with -h 127.0.0.1 and the exact port from the server. If the socket connection works but TCP does not, inspect listen_addresses and the server log. Restart PostgreSQL after changing server configuration.

Compare socket and TCP behavior

# Local socket chosen by libpq
psql -d postgres

# Explicit TCP connection
psql -h 127.0.0.1 -p 5432 -d postgres -U "$USER"

Use localhost instead of 127.0.0.1 if certificate hostname verification or local configuration requires the host name.

Check the port and server log

If another process already owns 5432, PostgreSQL may start on a different configured port or fail to start. Read the startup log for cannot bind, data-directory, permission, recovery, and version mismatch messages.

Postgres.app keeps postgres-server.log inside the selected data directory. For Homebrew or another package, use that service's log location. Fix the first startup error rather than the later connection symptom.

Use the verified values in PostgresGUI

Create a connection with the host, port, database, and user that worked in the explicit psql test. Local development servers often do not need SSL. Hosted databases usually do. Use the connection string builder to inspect a provider URL without saving it on the server.

If Postgres.app is the server, continue with the dedicated Postgres.app connection guide. If the server responds but rejects SSL or the URL, troubleshoot those errors separately.