Connect to Neon from your Mac

What you need

• A Neon project, and the password for one of its roles. The Connect window shows it.
• Inlet, or psql version 14 or later (older clients can’t send the server name Neon needs; see Troubleshooting).

Find your connection details

In the Neon Console, click Connect. The Connect to your branch window lets you pick the branch, compute, database and role, and builds the connection string for them.

The Connection pooling switch decides which host you get:

• On (the default): the pooled host. It ends in -pooler, for example ep-cool-darkness-a1b2c3d4-pooler.us-east-2.aws.neon.tech. Neon runs PgBouncer here in transaction mode, which allows up to 10,000 client connections.
• Off: the direct host, the same name without -pooler, straight to Postgres.

Both use port 5432. Neon says to use the direct host for pg_dump and pg_restore, schema migrations, logical replication and long-running analytics; for Inlet, see below. Neon’s docs list what transaction pooling breaks: SET and RESET don’t persist, and LISTEN, SQL-level PREPARE, temporary tables and session-level advisory locks don’t work. The pooler also rejects most startup parameters (it accepts client_encoding, datestyle, timezone, standard_conforming_strings and application_name).

Neon computes scale to zero: by default a compute suspends after 5 minutes without activity, and a new connection wakes it, which typically takes a few hundred milliseconds. A connection left open when the compute suspends is closed by the server.

IP Allow (on the Scale plan) limits which addresses can connect. You set it in the project settings, either for every branch or only for protected branches.

Connection string

postgresql://<role>:<password>@ep-<name>-<id>.<region>.aws.neon.tech/<database>?sslmode=require&channel_binding=require

channel_binding=require makes the client insist on SCRAM-SHA-256-PLUS, which ties the password check to the TLS connection. You can also print a string with the Neon CLI: neon connection-string. For the format of each part, see PostgreSQL connection strings.

TLS

Neon refuses connections without TLS. Its server certificates chain to ISRG Root X1, the Let’s Encrypt root, which is one of the certificates macOS trusts (checked on macOS 26.2). Neon recommends sslmode=verify-full, which checks both the certificate and the host name.

Note that in libpq, sslmode=require encrypts the connection but doesn’t check the certificate (unless you happen to have a ~/.postgresql/root.crt file). The string Neon gives you uses require; change it to verify-full to check who you’re talking to.

Connect with Inlet

1. In the Connect window, turn Connection pooling off and copy the string. Paste it into Inlet and it fills in the connection form. Or choose New Connection and type the host, role, database and password.
2. Under TLS, choose verify-full. You don’t need a CA file: Inlet checks the certificate against the ones macOS trusts.
3. Save the password in the Keychain, or have Inlet ask for it each time.
4. Tag the connection’s environment. Production connections open read-only, so the server refuses writes until you unlock them (for ten minutes at a time).

Use the direct host for production. Inlet’s read-only mode is a session setting, and through the -pooler host each transaction can land on a different server connection, so it isn’t guaranteed to hold. Neon’s docs also describe the reverse problem: a session-level SET default_transaction_read_only sent through the pooler can stay on the server connection, and another client then gets cannot execute INSERT in a read-only transaction. If you must browse through the pooler, create a separate role for browsing and make it read-only on the server:

ALTER ROLE <browsing-role> SET default_transaction_read_only = on;

That applies to every session the role opens, pooled or not, but it’s a default a session can turn off; granting the role only SELECT is what makes it unable to write. Never do this to the role your app writes with: Neon’s docs advise against read-only settings at the role level for exactly that reason, since every write by the role then fails.

Connect from the command line

macOS keeps its trusted root certificates in /etc/ssl/cert.pem, so psql can check Neon’s certificate against them:

psql "postgresql://<role>@ep-<name>-<id>.<region>.aws.neon.tech/<database>?sslmode=verify-full&sslrootcert=/etc/ssl/cert.pem&channel_binding=require"

psql asks for the password. Homebrew’s libpq package includes psql (keg-only: run /opt/homebrew/opt/libpq/bin/psql).

Troubleshooting

• The endpoint ID is not specified: your client is too old to send the host name during the TLS handshake (SNI). Upgrade to libpq 14 or later, or add options=endpoint%3D<endpoint-id> to the connection string, where the endpoint ID is the ep-… part of the host.
• password authentication failed: check the role and password from the Connect window. Neon notes that missing SNI support can also show up as this error.
• terminating connection due to administrator command: the compute scaled to zero while your connection sat idle. Reconnect.
• unsupported startup parameter: the pooler doesn’t accept that option. Remove it or use the direct host.
• Too many connections (remaining connection slots are reserved…): close idle connections, use the pooler for your app, or move to a larger compute.
• Connection refused from a new location: if IP Allow is on, add your current address in the project settings.