How to Connect TablePlus to PostgreSQL (SSH, SSL, Errors)

Short answer

A TablePlus PostgreSQL connection needs host, port (5432 by default), user, password and database; you can type them into the form or import a URL such as postgres://user:password@host:port/database.
TablePlus has built-in SSH tunnelling with a password or private key, and reads ~/.ssh/config when the private key field is left empty.
The TablePlus documentation does not describe its SSL fields in detail; PostgreSQL's own sslmode values (disable to verify-full) explain the choices, and pg_stat_ssl confirms whether a session is encrypted.
Most failures are server-side: PostgreSQL listens only on localhost by default, and pg_hba.conf must allow your address, user and database.

How we know: Research-based: TablePlus steps and options were checked against the TablePlus documentation (Getting Started, Connections) and the TablePlus macOS changelog; PostgreSQL defaults, SSL modes and error messages were checked against the PostgreSQL 18 documentation on 8 October 2026. We have not run these connections for this guide; follow the official pages if your version differs.

What you need for a TablePlus PostgreSQL connection

TablePlus asks for the same details as any PostgreSQL client. The TablePlus documentation lists them as the database driver, host, port, username and password, and TablePlus stores the credentials in your device's Keychain rather than on the vendor's servers.

Host: the server name or IP address, or 127.0.0.1 for a local server.
Port: PostgreSQL listens on TCP port 5432 by default.
User and Password: a PostgreSQL role allowed to log in.
Database: the database to open first (you can switch later with Cmd + K, or Ctrl + K on Windows).

If the server is new, two PostgreSQL defaults matter before TablePlus is involved at all. The listen_addresses setting defaults to localhost, which allows only local loopback connections, and every client address must be permitted by a line in pg_hba.conf.

Create the connection step by step

Launch TablePlus. On the welcome screen click Create a new connection near the bottom, or right-click the connection list and choose New.
Choose PostgreSQL as the driver and click Create.
Give the connection a Name, pick a colour and a tag. TablePlus has five tags (Local, Testing, Development, Staging, Production); tagging a production server helps you notice where you are.
Enter host, port, user, password and database.
Test the connection, then save and connect. TablePlus's own Supabase guide describes this as verifying that the connection is successful and then saving it.

After connecting, the connection is saved to the welcome screen; right-click it and choose Edit... to change it later. By default TablePlus pings the server every 30 seconds to keep the connection alive, which you can turn off under Preferences > General > Keep connection alive.

Import a PostgreSQL connection URL

Instead of filling the form, you can choose to import from URL and paste a connection string. The documentation gives the PostgreSQL structure below, and the Getting Started page uses a passwordless local example. Hosted services such as Supabase or Amazon RDS for PostgreSQL show a connection string in their console that you can paste the same way.

On macOS you can also open a saved-style URL from the terminal with open -a TablePlus; values in the URL must be URL encoded. Right-clicking a connection and choosing Copy as URL gives you the URL of an existing connection.

PostgreSQL connection URL formats from the TablePlus documentation

postgres://user:password@host:port/database
postgresql://postgres@127.0.0.1

macOS terminal: open a PostgreSQL connection in TablePlus (documented example)

open -a TablePlus "postgresql://postgres@127.0.0.1/tools"

Connect over an SSH tunnel or with SSL

SSH tunnel

Use SSH when PostgreSQL is reachable only from inside the server's network. In the same connection form, enter the SSH server and user and either a password or a private key; TablePlus has a built-in SSH client. If you rely on your SSH config file, tick Use SSH key and leave the private key empty, and TablePlus uses ~/.ssh/config. With a tunnel, the database host is usually 127.0.0.1 as seen from the SSH server.

If the tunnel fails although the settings are right, the TablePlus troubleshooting advice is to enable Help > Enable SSH Debug Log and send the log to TablePlus support.

SSL and TLS

The TablePlus documentation does not describe the SSL options of the connection form in detail. It lists a tLSMode parameter for connection URLs, and the macOS changelog records added support for PostgreSQL SSL negotiation in version 6.9.6 (May 2026). Pick the SSL level in the form to match what your server requires.

PostgreSQL defines the levels. Its sslmode setting ranges from disable through prefer (the default when SSL support is compiled in) and require to verify-ca and verify-full, which also check the server certificate and, for verify-full, the host name. Cloud providers commonly require at least require. To confirm that a TablePlus session is encrypted, run the query below in the TablePlus query editor.

PostgreSQL: is the current session using SSL?

SELECT ssl, version, cipher
FROM pg_stat_ssl
WHERE pid = pg_backend_pid();

Common TablePlus PostgreSQL connection errors

TablePlus shows the error the PostgreSQL server returns, so the PostgreSQL documentation is the right reference.

PostgreSQL connection errors and where to look (PostgreSQL 18 documentation)
Message	What it means	What to check
`FATAL: no pg_hba.conf entry for host ...`	The server was reached but no pg_hba.conf line matches your address, user, database and SSL use.	Add a matching line to pg_hba.conf and reload the configuration; check whether the rule requires SSL.
`FATAL: password authentication failed for user ...`	The server is willing to talk to you but the password check failed.	User name, password and which role you are logging in as; reset the password if needed.
Connection refused or timed out	Nothing is listening at that host and port, or a firewall blocks it.	`listen_addresses` (localhost only by default), port 5432, firewalls and cloud security groups; or use an SSH tunnel.
SSH errors before the database is reached	The tunnel itself failed.	SSH user, key and host; enable the SSH debug log in TablePlus.

Next steps

Once connected, see importing CSV files, exporting query results and the keyboard shortcut cheat sheet. If you have not installed TablePlus yet, start with downloading and installing TablePlus. To compare PostgreSQL clients, see our PostgreSQL GUI tools guide and the TablePlus review.

Frequently asked questions

What port does TablePlus use for PostgreSQL?

TablePlus uses whatever port you enter. PostgreSQL listens on 5432 by default, so that is the usual value unless your provider or administrator has changed it.

Can TablePlus connect to PostgreSQL through an SSH tunnel?

Yes. The connection form has built-in SSH with a password or private key, and TablePlus reads ~/.ssh/config when you tick Use SSH key and leave the key empty.

How do I connect TablePlus to Supabase?

TablePlus's own guide uses Supabase's Session pooler details: host, port 5432, database postgres, a user in the form postgres.your-project-ref and your database password, entered in a new PostgreSQL connection.

Why does TablePlus say no pg_hba.conf entry?

The PostgreSQL server rejected your address, user or database combination before checking the password. Add a matching rule to pg_hba.conf on the server and reload the configuration.

Where does TablePlus store my PostgreSQL password?

According to the TablePlus documentation, credentials are stored in your device's Keychain and are never synced to the vendor's servers.

Sources

Checked 8 October 2026.

How we research tool guides: our editorial method. CodeWithSQL earns nothing from the vendors mentioned.