Connect to Crunchy Bridge from your Mac

What you need

• Access to the cluster in the Crunchy Bridge dashboard, or the cb CLI.
• Your team’s certificate, if you want to check the server’s identity (recommended).
• Your IP address allowed by the cluster’s firewall rules, if you’ve narrowed them.

Find your connection details

In the Team Dashboard, click the cluster’s name. On the cluster page, the Connection tab has the credentials: choose a role and a format, then copy the string. Three roles exist out of the box: postgres (the superuser, for administration), application (for your app) and user (your own role as a team member).

The formats are URL, psql (the whole command, ready to paste into Terminal), env (libpq environment variables), YAML and JDBC. From the CLI, cb uri <cluster> prints the connection string and cb psql <cluster> opens a session.

The parts of the string:

• Host: begins with p. and ends with postgresbridge.com, for example p.<cluster-id>.db.postgresbridge.com.
• Port: 5432, or 5431 for PgBouncer.
• Database: postgres unless you choose another.

The string stays the same through cluster operations unless you rotate the credentials.

Firewall rules. A new cluster allows every address (0.0.0.0/0 and ::/0). To restrict it, delete those defaults on the cluster’s Networking tab and add your own rules in CIDR notation (/32 for a single IPv4 address). Rules can’t overlap, so the defaults have to go first.

PgBouncer. Every cluster runs PgBouncer on port 5431, but you turn it on per database by installing an extension as the superuser: CREATE EXTENSION crunchy_pooler;. It runs in transaction mode by default (session and statement modes are available through the pool_mode setting), and it won’t let superusers or replication roles connect through it.

Connection string

postgres://application:<password>@p.<cluster-id>.db.postgresbridge.com:5432/postgres?sslmode=verify-full&sslrootcert=/path/to/team-cert.pem

For the pool, change the port to 5431. On the command line, wrap a string with ? and & in single quotes so the shell leaves it alone. See PostgreSQL connection strings.

TLS

TLS is required on every connection, whatever the firewall settings, and you can’t turn that off. Only TLS 1.2 and 1.3 are accepted, so very old clients can’t connect.

Each team has its own self-signed root certificate, used for all the team’s clusters. Download it from your team’s Settings page in the dashboard (or the API). With sslmode=verify-full&sslrootcert=<that file>, the client checks that the server’s certificate belongs to your team and matches the host name. cb psql does this for you.

Crunchy Bridge recommends at least sslmode=require: clients that default to prefer can fall back to an unencrypted attempt, which the cluster refuses.

Connect with Inlet

1. On the Connection tab, choose the role and the URL format, copy it, and paste it into Inlet; Inlet fills in the connection form. Or choose New Connection and type the fields.
2. Under TLS, choose verify-full and select the team certificate you downloaded as the CA file.
3. Keep the password in the Keychain, or have Inlet ask every time.
4. Tag the environment. A production connection opens read-only: the server refuses writes until you unlock it for ten minutes.

Use port 5432 for production. Inlet’s read-only mode is a session setting. Through PgBouncer on 5431 in transaction mode each transaction can run on a different server connection, and PgBouncer doesn’t reset session state in that mode, so the setting isn’t guaranteed to hold. To make a role read-only on the server, whichever port it uses:

ALTER ROLE <role> SET default_transaction_read_only = on;

That’s a default a session can still change. For a hard limit, browse production with a role that can’t write. Every team member has their own user role (its name starts with u_), and a team administrator can make one read-only with Crunchy Bridge’s built-in roles:

REVOKE crunchy_write FROM <user-role>;
GRANT crunchy_read TO <user-role>;

Connect from the command line

With the CLI, which checks the team certificate itself:

cb psql <cluster>

With psql and the URL from the Connection tab, in single quotes:

psql 'postgres://application:<password>@p.<cluster-id>.db.postgresbridge.com:5432/postgres?sslmode=verify-full&sslrootcert=/path/to/team-cert.pem'

Troubleshooting

• no pg_hba.conf entry for host … SSL off (or … no encryption): the client didn’t use TLS. Set sslmode=require or verify-full.
• FATAL: bouncer config error on port 5431: the crunchy_pooler extension isn’t installed in that database. Run CREATE EXTENSION crunchy_pooler; there as the superuser.
• Can’t connect as postgres on 5431: superusers can’t use PgBouncer. Use application or your own role, or port 5432.
• Timed out or connection refused: check the firewall rules on the Networking tab include your current address.
• password authentication failed: the credentials may have been rotated; copy the string again.
• Too many connections: the default max_connections is 500. Use PgBouncer for your app, or raise the limit (it needs a restart).