Connecting to Databasezy

Tested with: Gateway TLS policy as of 2026-09 · OpenSSL 3.x

Every instance, whatever the engine, is reached the same way. Read this page once, then jump to your engine.

Hostnames and ports

Kind	Pattern	Notes
Default	`<engine>-<id>.<region>.databasezy.com`	Wildcard certificate per region, rotated every 60 days
Custom domain (Solo and above, add-on)	`db.example.com` CNAME to the default host, plus `_acme-challenge.db.example.com` CNAME to the value the Network tab shows	Publicly trusted certificate (Let’s Encrypt, DNS-01), issued and renewed automatically; billed while it is issued. Not available in every region yet
Private (Enterprise, Phase 4)	`<id>.private.<region>.databasezy.com`	Resolves inside your VPC over PrivateLink or PSC

Every instance is reached through the gateway on a small fixed set of ports: 5432 for the Postgres wire (including QuestDB), 3306 for MySQL, 6379 for RESP, 27017 for MongoDB, and 443 for every HTTP and gRPC engine, routed by hostname. ClickHouse is the exception: HTTPS on 8443 and the native protocol on 9440. Qdrant and Weaviate serve gRPC on a second -grpc hostname, also on 443. The ports an engine listens on inside the cell are never exposed, and neither are plaintext ports.

Single-IP regions use 8443 for HTTP engines (and the -grpc hostnames) instead of 443; every other port is the same. The portal Connect page and the API’s endpoints list always show the right host and port.

TLS: always on, always verified

TLS 1.2 minimum, TLS 1.3 preferred, AEAD suites with forward secrecy only. This satisfies Apple App Transport Security and the HIPAA transmission-security control.
Drivers that start plaintext and upgrade (Postgres SSLRequest, MySQL capability flag) are supported; a client that refuses TLS is disconnected with a clear error.
Verify the server, do not merely encrypt: sslmode=verify-full (Postgres), ssl-mode=VERIFY_IDENTITY (MySQL), rediss:// with hostname checking, tls=true plus a CA (MongoDB). Every snippet in these docs does this.

The CA bundle

The gateway presents a publicly trusted certificate. Drivers that use the OS trust store (most Node, Go, .NET, JVM and Ruby drivers) verify it with no extra configuration. libpq-based drivers (psql, psycopg, pg for Ruby, PDO pgsql, Npgsql’s Root Certificate) and some MySQL drivers need the bundle path explicitly:

zb api GET /v1/orgs/{org}/ca.pem > databasezy-ca.pem   # or: Instance → Connect → Download CA
openssl x509 -in databasezy-ca.pem -noout -subject -enddate

Pin the intermediate, never the leaf. Rotation dates are published twelve months ahead; see mTLS and certificate pinning.

IP allow-list

The gateway checks the client address against the instance’s allow-list before authentication, on every plan.

Manage it under Network → Allow-list in the portal, or replace the whole list through the API (if you turned on two-factor authentication, or your organization requires it, the session must have completed it):

zb api GET /v1/orgs/{org}/instances/<instance>/network
zb api PUT /v1/orgs/{org}/instances/<instance>/network -d '{"allow_cidrs": ["203.0.113.0/24"]}'

Prefer CIDRs from your platform’s static-egress feature; each platform guide tells you where to find them.
0.0.0.0/0 works but is flagged in the portal and written to the audit log.
Changes apply within seconds and never drop established connections.

Credentials

Credentials are generated inside the cell when the instance is created and shown once. The control plane stores only a secret reference; a reveal is a signed, short-lived fetch straight from the cell and is audited.

Store them in your platform’s secret manager, never in the repository or a mobile app.
Rotate with a dual-valid window so nothing restarts at once: Rotating credentials.
API keys (zb_...) are for the control-plane API, not for database connections.

Pooling and connection limits

Each size has a max_connections ceiling (see sizes) enforced by the engine and the gateway. Use a pool in long-running services, and the built-in transaction-mode pooler for serverless: Connection pooling.