Fix a PostgreSQL connection failure

One day psql greets you with this:

psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed:
No such file or directory
        Is the server running locally and accepting connections on that socket?

Start with the complete error. Do not reinstall PostgreSQL: that can hide the cause and put the existing cluster at risk. Reinstalling sometimes “works” by creating a fresh, empty data directory, which is a polite way of saying it can disconnect you from your data. The error text already narrows the problem down; use it.

Read the error as a layer diagnosis

Connection failures happen at one of a few layers, and each produces a distinct message.

A missing socket, like the error above, points to service or socket-directory configuration. The client looked for a local server and found nobody home. On a Homebrew machine that usually means the service is stopped or crashed, often after a brew upgrade that moved you across a major version so the new server refuses the old data directory.

“Connection refused” points to the server, address, port, or firewall. Something answered the network layer with “nothing is listening here”. Wrong port, wrong host, or a server bound only to localhost while you connect from outside.

A FATAL authentication message means the server answered, so check the role, password, pg_hba.conf, TLS, and database name. This is progress: the server is fine, and you are negotiating with it.

Work through it locally

Check the client and Homebrew service:

psql --version
brew services list

If the service shows error or stopped, read the log before touching anything:

tail -50 /opt/homebrew/var/log/[email protected]

A version-mismatch line such as database files are incompatible with server confirms the major-upgrade scenario, and the fix is pg_upgrade with the old binaries, not deletion.

Then try an explicit local connection:

psql -h localhost -p 5432 -U notes_app -d notes_app

Spelling out host, port, role, and database removes every default from the equation. If this works while plain psql fails, your problem was defaults, not the server.

Inspect Homebrew service logs before changing configuration. Change one layer at a time and retry the same command. If you change three things and it starts working, you do not know which change fixed it, and you may have broken something else quietly.