Querycop cloud DB cookbook Community

This directory holds per-provider recipes for running Querycop in front of managed cloud databases. Each page is a self-contained runbook: the TL;DR table is enough to copy-paste a config, the rest of the page explains why each value is what it is and where the per-provider footguns are.

For the catalog of all 10 pages with side-by-side defaults, see index.md.

Who this is for

Operators standing up Querycop against a managed cloud database for the first time. The pages assume you already know what Querycop does at a high level (../../README.md) and have read ../configuration.md §1.5 (backend TLS) and §1.6 (BACKEND_TOKEN_CMD) at least once.

The pages do not re-derive what a verify-full TLS mode means or what an IAM token looks like — that’s in configuration.md. They DO show the exact env var values, gcloud / az / aws commands, and psql / mysql client invocations that produce a working setup for the specific provider in front of you.

Base structure (common conventions)

The skeleton below is the base structure every page builds on. Where a provider’s reality diverges (different number of auth patterns, provider-specific auth concept names) the page deviates from the literal template — see the per-section notes after the block. The point of this section is to make the shape familiar across pages, not to lock pages to a literal Pattern A / Pattern B form they often don’t fit.

# <Provider name>

> Status banner: tested against <version> on <date>.

## TL;DR
Env-var table — copy-pastable production-ready defaults.

## Prerequisites
Network reachability, IAM perms, CA bundle on disk, required
provider-side flags, Querycop minimum version.

## <Auth section(s)>
See per-page variations below — each Auth section follows the
Step 1: download / verify CA / Step 2: configure Querycop /
Step 3: connect the client cadence.

## Smoke test
docker compose up -d → psql/mysql → select 1
Plus a 3-5-row diagnostic table for the most common first-setup
failure surfaces.

## Gotchas
Per-provider real footguns: cert SAN quirks, IPv6 defaults,
token lifetimes, pooler trade-offs, etc.

## Cross-links
configuration.md anchors and vendor official docs.

Per-page variations on the Auth section(s) that the corpus actually uses:

• Two patterns, password + IAM (rds-postgresql.md, rds-mysql.md, cloud-sql-postgresql.md, alloydb.md, azure-postgresql.md): split into ## Pattern A — Password auth (evaluation / early production) and ## Pattern B — IAM auth (recommended for production) / ## Pattern B — Microsoft Entra ID auth (recommended for production).
• Two patterns, two endpoint shapes (supabase.md): split into ## Pattern A — Direct endpoint (password auth) and ## Pattern B — Supavisor pooler endpoint (password auth on both — the patterns are about the endpoint choice, not the auth flow).
• Single password-auth section (neon.md, cockroach-cloud.md, timescale-cloud.md): just ## Password auth — no Pattern A / B split because there’s only one auth flow on the provider.
• Single section named after the provider’s auth concept (planetscale.md): ## Branch-password auth — same shape as the single password-auth pages, named to match PlanetScale’s own terminology.

Sections that don’t apply to a provider (e.g. PlanetScale has no IAM auth section) are omitted entirely rather than carrying an “N/A” placeholder.

Defaults that hold across every page

These are conventions the cookbook bakes into every TL;DR without re-explaining them per page:

• GATEKEEPER_BACKEND_TLS_MODE is set explicitly to verify-ca or verify-full — never prefer or disable. The cookbook default is whichever of verify-ca / verify-full actually produces a passing handshake for the provider’s cert SAN conventions (see index.md for the per-provider matrix).
• GATEKEEPER_BACKEND_TLS_CA_FILE is always set explicitly. Querycop’s verify-ca / verify-full modes reject empty CA_FILE at startup with a clear fail-fast message — implicit system root pool fallback is deliberately not supported (pkg/proxy/backend_tls.go).
• GATEKEEPER_BACKEND_TLS_SERVER_NAME is left unset whenever BACKEND_HOST already matches the cert SAN — Querycop derives the TLS SNI from BACKEND_HOST in that case, which is what the provider’s TLS layer expects.
• GATEKEEPER_BACKEND_TOKEN_CMD is shown on the IAM-auth Pattern B page-sections. When set, Querycop enforces at startup that the TLS mode is require / verify-ca / verify-full — prefer is rejected because its plaintext-fallback path would leak the token (safety guard, see ../configuration.md §1.6).
• GATEKEEPER_LISTEN_PORT uses 15432 for PostgreSQL-shaped pages and 15336 for MySQL-shaped pages. The number isn’t load-bearing — apps dial Querycop on whatever you choose.

Maintenance contract

A cookbook page goes stale when:

1. The vendor rotates its CA root and the download URL changes.
2. The vendor changes endpoint shape (e.g. Aurora went cluster-X → cluster-X.cluster-…; CockroachDB Cloud retired the --cluster= routing token).
3. A new feature affects config (e.g. a pooler awareness flag was added → the Neon + Supabase pages would gain a pooler section).

The maintenance pattern:

• Every page carries a “tested against querycop HEAD on YYYY-MM-DD” status banner so staleness is observable at a glance.
• Cookbook updates ride along with the feature work that motivates them — e.g. a future pooler-flag epic adds a pooler section to the Neon + Supabase pages in the same PR that ships the flag.
• Vendor-driven changes (CA rotation, deprecation announcements, tier renames) get their own short follow-up PRs as the cookbook’s stewards become aware.

Related work

• ../configuration.md — full env-var reference. The cookbook quotes from §1.5 and §1.6.
• ../known-limitations.md — the full list of MySQL protocol gaps (cited from rds-mysql.md and planetscale.md).
• ../rbac-policy-guide.md — RBAC policy authoring (cited from timescale-cloud.md for TimescaleDB-feature exemption patterns).