Connect to Postgres.app from your Mac

What you need

• Postgres.app in your Applications folder, with a server initialised and running. (Drag the app to Applications, open it, and click Initialize.)
• Your macOS short user name: run whoami in Terminal if you’re not sure.

Find your connection details

Postgres.app’s defaults are:

Postgres.app can run several servers (for example, two PostgreSQL versions) side by side: click + in the sidebar to add one. Only one server can use a port, so give each its own port in that server’s settings.

By default, PostgreSQL in Postgres.app accepts connections only from apps on your Mac, and without a password (“trust” authentication). To protect it, Postgres.app’s guide has you stop the server, open the HBA file from Server Settings…, replace trust with scram-sha-256, set a password with Change Password…, and start the server again. After that, Postgres.app no longer lists the databases in its window, and every client needs the password.

Connection string

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

Postgres.app documents this form for GUI apps; postgresql://localhost alone also works for tools that default the user and database to your user name, as psql does. Add :<password> after the user name if you’ve turned on password authentication. See PostgreSQL connection strings.

TLS

A connection to localhost never leaves your Mac, so TLS adds nothing here. Leave it off, or at prefer. TLS matters when you open the server to other computers on your network, which Postgres.app explains how to do once a password is set.

Connect with Inlet

1. Choose New Connection and enter localhost, port 5432, your user name and database. Or paste postgresql://<your-user-name>@localhost/<your-user-name> and Inlet fills in the form.
2. Leave the password empty, unless you’ve set one; then save it in the Keychain or have Inlet ask each time.
3. Connect. Postgres.app 2.7 and later shows a permission prompt the first time an app connects without a password. Click OK to allow Inlet; Postgres.app remembers the choice.
4. Tag the connection local, so it’s clearly not production.

Connect from the command line

Postgres.app includes psql but doesn’t put it on your PATH. Its documented fix, after which you open a new Terminal window:

sudo mkdir -p /etc/paths.d &&
echo /Applications/Postgres.app/Contents/Versions/latest/bin | sudo tee /etc/paths.d/postgresapp

Check with which psql. Then psql with no arguments connects as your user to your database. You can also double-click a database in Postgres.app’s window to open psql on it.

Troubleshooting

• FATAL: Postgres.app rejected "trust" authentication, with DETAIL: You did not allow … to connect without a password: someone clicked Don’t Allow in the permission prompt. Open Postgres.app, choose Settings from the Postgres menu, find the app, and set it to allow.
• Postgres.app failed to verify trust authentication: usually the permission prompt went unanswered and the attempt timed out after a minute. Approve the app in Postgres.app’s Settings (version 2.7.2 or later).
• Port 5432 is already in use when you start the server: another PostgreSQL is running, either another server in Postgres.app (stop it from the sidebar, or change its port) or a different installation such as Homebrew’s. Only one server can use each port.
• Connection refused: the server isn’t running. Start it in Postgres.app.
• no password supplied or password authentication failed: you’ve switched to password authentication; give the password you set.
• database "<name>" does not exist: by default only the database named after you (and postgres) exists. Connect to one of those, or create another with createdb <name>.