Connect

Everything you connect to lives at the host db.database.pizza. Your organization and database slugs form the routing path: for org acme and database production, that path is acme/production.

There are two connection surfaces, and they share the same API key.

Surface	Endpoint	Authentication
PostgreSQL wire protocol	db.database.pizza:5432	API key as password
HTTP query API	https://db.database.pizza/acme/production/query	API key as Authorization: Bearer

PostgreSQL wire protocol

Connect to db.database.pizza on port 5432 like any PostgreSQL server. Three things are different from a stock Postgres setup:

1. The database name is acme/production — organization and database joined by a slash. It’s a single name, not two path segments.
2. The password is your API key. The user field is ignored; you can use any value (the examples use u).
3. TLS is declined. The proxy currently answers SSL negotiation with N, so connect with sslmode=disable. Don’t require or verify TLS here — it will fail.

Connection string

postgresql://u:pz_live_REPLACE_ME@db.database.pizza:5432/acme%2Fproduction?sslmode=disable

The slash in the database name must be percent-encoded as %2F when a client parses the URI (libpq, pg, SQLAlchemy, JDBC, and most others do). If your client takes discrete fields instead of a URI — many GUIs do — enter acme/production literally in the database field, no encoding.

With psql

PGPASSWORD='pz_live_REPLACE_ME' psql \
  "postgresql://u@db.database.pizza:5432/acme%2Fproduction?sslmode=disable"

psql also accepts the parts as flags:

PGPASSWORD='pz_live_REPLACE_ME' psql \
  -h db.database.pizza -p 5432 -U u -d acme/production

HTTP query API

Send a JSON body to the query endpoint with the key in a Bearer header:

curl -s https://db.database.pizza/acme/production/query \
  -H "Authorization: Bearer pz_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT version()"}'

The HTTP surface also exposes a batch endpoint, schema introspection, and a health check. See HTTP query API for the full reference.

Connection parameters

Parameter	PostgreSQL	HTTP
Host	db.database.pizza	https://db.database.pizza
Port	5432	443
Database	acme/production	path segment /acme/production
User	ignored (use u)	—
Password / token	API key	Authorization: Bearer <key>
SSL	sslmode=disable (TLS declined)	HTTPS only

Which should I use?

• PostgreSQL wire protocol is the right default when you already have a Postgres driver, ORM, or GUI. It gives you transactions and the full SQL surface.
• HTTP query API is best for serverless functions, edge workloads, and environments where a long-lived database connection isn’t practical. Transactions are not supported over HTTP — use the Postgres protocol when you need them. Do not expose a database API key in browser code.

Both surfaces enforce the same API key scopes. See API keys & permissions and PostgreSQL clients for idiomatic client examples.

Troubleshooting

• invalid_password / “authentication failed” — the key is wrong, revoked, or lacks DB_ACCESS permission. Check the key and its scopes.
• invalid_catalog_name / “database must be org/db” — the database name doesn’t contain the /. Use acme/production.
• SSL negotiation fails — you forced TLS. Use sslmode=disable.
• invalid api key — the key isn’t a valid live key, or you pasted it with whitespace.

More error cases are covered in Errors & troubleshooting.