Connect PostgresGUI to Postgres.app on Mac

Confirm the default Postgres.app connection

/Applications/Postgres.app/Contents/Versions/latest/bin/pg_isready \
  -h localhost -p 5432

/Applications/Postgres.app/Contents/Versions/latest/bin/psql \
  -h localhost -p 5432 -U "$USER" -d "$USER"

If the Postgres.app window shows a different port or database, use those displayed values instead of the defaults.

Understand which app does which job

Postgres.app installs and runs the database server and command-line tools. Closing every database client does not stop that server. PostgresGUI does not create or manage the server process; it opens a normal PostgreSQL client connection.

If you are choosing between the two apps, the answer is often both. The Postgres.app and PostgresGUI comparison explains the server-client distinction in more detail.

Enter the connection fields

Open PostgresGUI, add a connection, and enter a useful name such as Local Postgres.app. Set host to localhost and port to the port shown next to the running Postgres.app server. Use your macOS account name for the default user and database.

Leave the password blank only when the local Postgres.app configuration still uses its documented default. If you changed authentication or created another login, enter that role's actual password. Local default connections do not need an SSL mode.

• Name: Local Postgres.app
• Host: localhost
• Port: 5432 by default
• Database: your macOS user name by default
• User: your macOS user name by default
• Password: blank in the default local configuration

Create a separate practice database

Using a named practice database makes examples easier to recognize and avoids mixing tutorial tables into the default maintenance database. Create it with the Postgres.app binary or from a connected SQL editor.

Create and verify a practice database

/Applications/Postgres.app/Contents/Versions/latest/bin/createdb postgresgui_practice

/Applications/Postgres.app/Contents/Versions/latest/bin/psql \
  -h localhost -d postgresgui_practice \
  -c "select current_database(), current_user;"

Fix the common local failures

Connection refused means the server is stopped or is not listening on the chosen port. Role does not exist usually means the user field does not match a PostgreSQL role. Database does not exist means the database field is wrong. Password authentication failed means this server is no longer using the blank-password default for that connection.

If port 5432 is already occupied, Postgres.app may show a different port or fail to start. Its troubleshooting documentation recommends reading postgres-server.log inside the data directory for the exact startup failure.

Browse the local database

After the test succeeds, save the connection and open the practice database. Create a small table, insert rows, and confirm they appear in the table browser. That proves the server, role, database, and client are all aligned.

For a listener or port problem, use the full connection refused checklist for Mac. Do not reset Postgres.app or delete its data directory as a first troubleshooting step.