PostgreSQL
psql, libpq clients, JDBC, SQLAlchemy, and anything else that speaks the wire protocol
The Gateway speaks the PostgreSQL wire protocol directly, so any client that talks to Postgres talks to Airbrx. Change the host to your gateway address, keep TLS on, and leave the rest of the connection alone.
Change the host
postgresql://analyst@ db.internal.example.com :5432/analytics ?sslmode=require
Direct to your database.
postgresql://analyst@ your-slug.gateway.airbrx.ai :5432/analytics ?sslmode=require
Same connection, gateway address.
Port 5432, the same database name, the same user. The Gateway resolves
your tenant from the TLS SNI name your client sends during the handshake.
TLS is required, not optional
sslmode=disable does not work, and it does not silently fall back — the
Gateway returns a clean error and closes the connection. Use require at
minimum; verify-full works too, and the gateway address presents a
certificate for its own hostname.
This is a deliberate one-way door. Your credentials cross this connection, and a proxy that quietly accepts plaintext whenever a client asks for it is a proxy that will eventually carry a password in the clear.
If your client does not send SNI
Nearly all modern clients do. For the ones that do not, the Gateway falls back to
reading the database field as your gateway address:
psql "dbname=your-slug.gateway.airbrx.ai sslmode=require user=analyst"
If a connection is rejected with a tenant-resolution error and you are confident the address is right, this fallback is the thing to try.
Authentication
Your tenant is configured with one of three auth modes. Which one you are on changes nothing about your connection string — it changes what the Gateway does with the credentials as they pass through. See Supported engines for the full description of each. In short:
- relay — for token-based backends like RDS IAM or Azure Entra. The exchange is relayed byte for byte and the Gateway never inspects it.
- verifier-proxy — a real SCRAM-SHA-256 exchange against a verifier from your own database. Available for self-hosted PostgreSQL, Neon, and Supabase.
- cleartext — a password over the mandatory TLS channel.
In none of them does Airbrx store a warehouse username and password on your behalf. There is no field for it.
One operational note: if you rotate or revoke a password in your database, allow up to an hour before the old one stops working through the Gateway.
Verify the cache
The PostgreSQL wire protocol has no response headers, so the
X-Airbrx-* trick from the
DBeaver recipe does not apply here. Verify
it the way you would verify any cache — by timing:
\timing on
SELECT region, sum(amount) FROM orders GROUP BY region;
-- Time: 486.221 ms
SELECT region, sum(amount) FROM orders GROUP BY region;
-- Time: 7.442 ms
For the authoritative answer, the App's traffic page shows the statement, the rule that matched, and whether it hit — the same view every other connection gets.
Notes worth knowing
- Both query protocols work. Simple and extended query are both supported, and both cache. Parameterized statements from SQLAlchemy, psycopg, and JDBC behave normally — bound parameter values are part of the cache key, so different parameters are different cache entries.
-
COPYpasses through, uncached. Both directions work through the Gateway, but aCOPY FROMload does not mark cached reads of that table stale, so cached results can be older than the load until their TTL runs out. - Long sessions survive deploys. A routine Gateway deploy does not kill a query mid-execution.
-
Session-mutating statements are never cached. A
SETalways reaches your database, whatever a rule says.
Where to go next
- Supported engines — the auth modes in full, and what is shared across connections.
- Ship your first cache rule — the rule that makes the second query fast.
- Python & JDBC — driver-level detail for programmatic clients.
Try it against your own database
A PostgreSQL tenant takes a hostname and an auth mode. Create an account and connect psql in a couple of minutes.
Create an account