Connect to Homebrew PostgreSQL from your Mac

What you need

• PostgreSQL from Homebrew, for example brew install postgresql@18 (18.6 when this was checked; postgresql is an alias for it).
• The server running: brew services start postgresql@18 starts it now and at every login.

The paths below are for Apple silicon, where Homebrew lives in /opt/homebrew. On an Intel Mac, replace /opt/homebrew with /usr/local.

Find your connection details

When you install it, the formula creates a database cluster with initdb --locale=en_US.UTF-8 -E UTF-8 /opt/homebrew/var/postgresql@18. Because initdb runs with its defaults, you get:

There is no postgres role and no database named after you. That catches people out: psql with no arguments looks for a database with your user name and fails, and -U postgres fails because the role doesn’t exist. Connect to the postgres database as yourself, or create the missing pieces:

CREATE DATABASE "<your-user-name>";

The server listens on localhost only, as PostgreSQL does by default. Its data is in /opt/homebrew/var/postgresql@18, and its log in /opt/homebrew/var/log/postgresql@18.log.

Connection string

postgresql://<your-user-name>@localhost:5432/postgres

No password is needed while authentication is trust. See PostgreSQL connection strings.

TLS

Not needed: the server only listens on your Mac, and Homebrew doesn’t set up certificates. Leave TLS off or at prefer. (With sslmode=require, a server without TLS answers with server does not support SSL.)

Connect with Inlet

1. Choose New Connection and enter host localhost, port 5432, your macOS user name, and database postgres. Or paste postgresql://<your-user-name>@localhost:5432/postgres and Inlet fills in the form.
2. Leave the password empty. If you later set one, save it in the Keychain or have Inlet ask every time.
3. Tag the connection local.

Inlet can also import connections from ~/.pgpass and pg_service.conf, if you keep your local setups there.

Connect from the command line

postgresql@18 is keg-only: Homebrew doesn’t link its programs into /opt/homebrew/bin, because it’s one of several versions you could install side by side. Run psql by its full path:

/opt/homebrew/opt/postgresql@18/bin/psql -d postgres

Or put that folder first on your PATH, for example in ~/.zshrc:

export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"

With no -h, psql connects through the Unix socket in /tmp. To test the TCP path a GUI client uses, add -h localhost.

Check what’s running and where:

brew services list

Troubleshooting

• FATAL: database "<your-user-name>" does not exist: psql defaults the database to your user name. Add -d postgres, or create that database.
• FATAL: role "postgres" does not exist: the superuser is your macOS user name. Use -U with that name, or create a postgres role if a tool insists on it.
• Connection refused: the server isn’t running. Start it with brew services start postgresql@18, and look in the log if it stops again.
• The service won’t start after a crash, with a postmaster.pid lock file error: if no postgres process is running, Homebrew’s advice is to remove the stale file: rm /opt/homebrew/var/postgresql@18/postmaster.pid.
• Two servers on port 5432: Postgres.app, Docker or another Homebrew version may already use it. Stop one, or run it on another port.
• command not found: psql: the formula is keg-only. Use the full path or add it to your PATH, as above.