Cloud DB cookbook — page index Community
Status: 10/10 provider pages as of 2026-05-22.
A side-by-side catalog of every Querycop cookbook page in this directory. The full per-provider walkthroughs live behind the links below; the matrices on this page exist so you can pick the right page (and spot the differences between providers) without reading all ten.
For the cookbook’s conventions, page format, and maintenance
contract, see README.md.
Pages, alphabetically
Section titled “Pages, alphabetically”| Page | Provider |
|---|---|
alloydb.md | Google AlloyDB for PostgreSQL |
azure-postgresql.md | Azure Database for PostgreSQL — Flexible Server |
cloud-sql-postgresql.md | Google Cloud SQL for PostgreSQL |
cockroach-cloud.md | CockroachDB Cloud (Basic / Standard / Advanced) |
neon.md | Neon serverless PostgreSQL |
planetscale.md | PlanetScale (Vitess-on-MySQL) |
rds-mysql.md | AWS RDS for MySQL + Aurora MySQL |
rds-postgresql.md | AWS RDS for PostgreSQL + Aurora PostgreSQL |
supabase.md | Supabase (direct + Supavisor pooler) |
timescale-cloud.md | Timescale Cloud (managed TimescaleDB) |
Pages, by introduction tier
Section titled “Pages, by introduction tier”The order pages landed in main — a useful
guide for which providers were validated first and against what
Querycop version.
| Tier | Page | Landed in |
|---|---|---|
| Sample (P0 format ratification) | rds-postgresql.md | PR #93 |
| P0 | cloud-sql-postgresql.md | PR #94 |
| P0 | neon.md | PR #94 |
| P0 | supabase.md | PR #94 |
| P1 | alloydb.md | PR #95 |
| P1 | rds-mysql.md | PR #95 |
| P1 | planetscale.md | PR #95 |
| P2 | azure-postgresql.md | PR #96 |
| P2 | cockroach-cloud.md | PR #96 |
| P2 | timescale-cloud.md | PR #96 |
Auth + TLS at a glance
Section titled “Auth + TLS at a glance”What auth patterns each page covers, and what BACKEND_TLS_MODE
the cookbook default uses. The full env-var TL;DR tables live at
the top of each page.
| Page | Auth patterns | TLS default | Why verify-ca / verify-full |
|---|---|---|---|
rds-postgresql.md | Password + IAM (aws rds generate-db-auth-token) | verify-full | RDS cert SAN matches public DNS |
rds-mysql.md | Password + IAM (same AWS tooling, MySQL AWSAuthenticationPlugin) | verify-full | RDS cert SAN matches public DNS |
cloud-sql-postgresql.md | Password + IAM (gcloud sql generate-login-token) | verify-ca (default); verify-full via dnsNames recipe | Per-instance cert SAN ≠ IP; dnsNames field populated only for PSC / cluster-DNS instances |
alloydb.md | Password + IAM (gcloud auth print-access-token OAuth2) | verify-ca (default); verify-full via matching DNS recipe | Per-cluster cert SAN ≠ IP; requires a matching DNS name (Service Directory / Private DNS / PSC DNS) |
azure-postgresql.md | Password + Microsoft Entra ID (az account get-access-token --resource-type oss-rdbms) | verify-full | Publicly-trusted root chain (DigiCert G2 / Microsoft RSA 2017); cert SAN matches *.postgres.database.azure.com |
supabase.md | Password (direct + Supavisor pooler) | verify-full | Per-project cert SAN matches the project hostname |
neon.md | Password (direct + PgBouncer pooler) | verify-full | Let’s Encrypt cert SAN matches the SNI-routed hostname |
planetscale.md | Branch password (per-branch dashboard-generated) | verify-full | Let’s Encrypt cert SAN matches *.connect.psdb.cloud |
cockroach-cloud.md | SQL-user password (Basic / Standard / Advanced) | verify-full | Per-cluster cert SAN matches the dashboard FQDN; tenant routing is hostname-encoded |
timescale-cloud.md | Password | verify-full | Let’s Encrypt cert SAN matches the per-service hostname |
Ports + CA bundle source
Section titled “Ports + CA bundle source”What backend port to dial and where the CA bundle comes from. The non-5432 ports and the per-cluster / per-project bundle sources are the most common first-setup misfires.
| Page | Backend port | BACKEND_TLS_CA_FILE source |
|---|---|---|
rds-postgresql.md | 5432 | AWS global bundle (truststore.pki.rds.amazonaws.com/global/global-bundle.pem) |
rds-mysql.md | 3306 | AWS global bundle (same file as RDS PG) |
cloud-sql-postgresql.md | 5432 | Per-instance, via gcloud sql instances describe ... serverCaCert.cert |
alloydb.md | 5432 | Per-cluster, via Cloud Console download or REST GenerateClientCertificateResponse.caCert |
azure-postgresql.md | 5432 | OS root bundle (publicly-trusted chain) |
supabase.md | 5432 (direct) / 6543 transaction / 5432 session (pooler) | Per-project, downloaded from dashboard |
neon.md | 5432 | OS root bundle (Let’s Encrypt) |
planetscale.md | 3306 | OS root bundle (Let’s Encrypt) |
cockroach-cloud.md | 26257 | Per-cluster, downloaded from dashboard |
timescale-cloud.md | per-service custom port | OS root bundle (Let’s Encrypt) |
IAM / token-mint commands
Section titled “IAM / token-mint commands”The Pattern B IAM-auth BACKEND_TOKEN_CMD value for each
provider that exposes one. Pages without a row don’t have an
IAM-equivalent at the SQL wire layer.
| Page | BACKEND_TOKEN_CMD shape | Token lifetime | Mints per |
|---|---|---|---|
rds-postgresql.md | aws rds generate-db-auth-token --hostname "$QUERYCOP_BACKEND_HOST" --port 5432 --region <r> --username "$QUERYCOP_BACKEND_USER" | 15 min (mint → handshake window) | connection |
rds-mysql.md | Same aws rds generate-db-auth-token with --port 3306 | 15 min | connection |
cloud-sql-postgresql.md | gcloud sql generate-login-token | 60 min (mint → handshake window) | connection |
alloydb.md | gcloud auth print-access-token (OAuth2 access token) | 60 min | connection |
azure-postgresql.md | az account get-access-token --resource-type oss-rdbms --query accessToken -o tsv | 60 min | connection |
For all 5 IAM-supporting providers, the lifetime applies to the mint → handshake window only; once the server accepts the token during auth, it does not re-check during steady-state traffic. A successfully-authed connection stays alive for the TCP socket’s lifetime regardless of the token’s nominal expiry.
Pooler awareness flag
Section titled “Pooler awareness flag”GATEKEEPER_BACKEND_POOLER is an observability-only topology hint:
when set, Querycop logs a single startup line describing the pooler’s
session-mode constraints. It does NOT inspect or filter client SQL.
Leaving it unset (or none) preserves the previous silent behavior.
| Page | Recommended value | When the recipe applies |
|---|---|---|
neon.md | pgbouncer-txn | Pointing Querycop at <endpoint-id>-pooler.…neon.tech (the PgBouncer-backed pooler endpoint). The direct endpoint stays unset. |
supabase.md | pgbouncer-txn (port 6543) or pgbouncer-session (port 5432) | Pointing Querycop at aws-0-<region>.pooler.supabase.com. Match the value to the port. The direct endpoint stays unset. |
planetscale.md | vitess | Always — every PlanetScale connection rides Vitess. |
All other pages leave the flag unset because their cookbook recipe points Querycop at a direct (non-pooled) endpoint by default.
Notable per-provider gotchas
Section titled “Notable per-provider gotchas”The single most operator-disruptive footgun per page. Click through for the full Gotchas section on each page.
| Page | Headline gotcha |
|---|---|
rds-postgresql.md | IAM token 15-min lifetime applies to mint → handshake only, not connection lifetime |
rds-mysql.md | Client needs --enable-cleartext-plugin so it sends the password packet Querycop rewrites with the IAM token |
cloud-sql-postgresql.md | verify-full requires a DNS name from the instance’s dnsNames field — for vanilla public-IP instances, stay on verify-ca |
alloydb.md | alloydb.iam_authentication=on is a per-instance flag (primary + each read-pool instance), and the principal needs roles/serviceusage.serviceUsageConsumer on top of roles/alloydb.databaseUser |
azure-postgresql.md | Entra ID username format differs: UPN for user principals vs display name (NOT app ID / object ID) for service principals registered via pgaadauth_create_principal_with_oid |
supabase.md | Direct endpoint resolves IPv6-only on the default plan; either enable the IPv4 add-on, use the Supavisor pooler (IPv4), or add IPv6 to the Querycop host network |
neon.md | Neon routes by TLS SNI — BACKEND_HOST must be the project-encoded hostname, never an IP literal; pooler endpoint trades session-bound features for connection density |
planetscale.md | Auth is branch passwords (dashboard-generated per branch + role), NOT PlanetScale service tokens (those are control-plane / REST API credentials) |
cockroach-cloud.md | Tenant routing is encoded in the FQDN (no options=--cluster=... needed — that token is deprecated); port is 26257, not 5432 |
timescale-cloud.md | Each service is provisioned with its own custom port (not 5432); the port is stable for the service’s lifetime and must be in any egress-firewall allow-list |
Cross-links
Section titled “Cross-links”README.md— cookbook conventions, page format, maintenance contract../configuration.md— full Querycop env-var reference (the cookbook quotes §1.5 backend TLS and §1.6 BACKEND_TOKEN_CMD throughout)../known-limitations.md— MySQL protocol coverage gaps (cited from rds-mysql.md, planetscale.md)../rbac-policy-guide.md— RBAC policy authoring (cited from timescale-cloud.md)