prole/docs/db-access.md

Direct database access — psql + Rust apps

Per-engineer access to the knoe-db Postgres cluster (PG18 / Percona) at pg.0.knoe.dev:5432.

Phase 1 (current): per-engineer postgres roles with strong passwords (30-day rotation), TLS required, named-roles-only ACL on the public LB. Phase 2 (queued for Junie): replaces the password mechanism with PG18 native OAUTHBEARER (libpq drives a Google Device Flow) + a small validator library bundled into our knoe-db image. Connection target stays the same; engineers' psql invocation only changes from -W to setting oauth_issuer / oauth_client_id in the connection string.

---

First-day flow (engineer-facing)

See docs/onboarding.md — the canonical engineer checklist. Two-line summary:

1. chrisfu runs etc/onboard_engineer.sh <username> <email>. Script outputs a one-time URL (and QR-code rendering of it) plus a 24h temp password.
2. Engineer opens URL on phone or laptop → page at db.0.knoe.dev/onboard.html shows their password + connection string with [Copy] buttons. Engineer pastes into psql, immediately rotates via \password, saves their new password to personal 1Password (no shared vault required).

The CA cert lives at etc/knoe-db-ca.crt in this repo — engineers reference it with sslrootcert=etc/knoe-db-ca.crt after cloning. It's a public CA root, not a secret. Auto-rotates with CNPG; we re-export and commit when it does.

Connection string (engineers substitute their own role):

psql "host=pg.0.knoe.dev port=5432 user=$USER dbname=postgres \
      sslmode=verify-full sslrootcert=etc/knoe-db-ca.crt"

---

Rust apps (sqlx / tokio-postgres / deadpool-postgres)

Connection string with the same TLS configuration:

let url = format!(
    "postgres://{user}:{password}@pg.0.knoe.dev:5432/postgres\
     ?sslmode=verify-full&sslrootcert={ca_path}",
    user = std::env::var("KNOE_PG_USER")?,
    password = std::env::var("KNOE_PG_PASSWORD")?,
    ca_path = format!("{}/.knoe/knoe-db-ca.crt", std::env::var("HOME")?),
);

let pool = sqlx::PgPool::connect(&url).await?;

For tokio-postgres directly, configure the MakeTlsConnector with the same CA bundle (use postgres-native-tls or tokio-postgres-rustls).

Service apps on GKE (Phase 2.5 territory): the same connection string, but KNOE_PG_USER / KNOE_PG_PASSWORD come from a per-app k8s Secret rather than 1Password. Phase 2 swaps this to Workload-Identity-issued OAUTHBEARER tokens — the app code change is one line.

---

What can a knoe_developer do?

The per-engineer roles (chrisfu, ron) are members of the knoe_developer group. Grants:

Schema	Permission	Notes
knoe	SELECT, INSERT, UPDATE, DELETE	Application schema; ALTER DEFAULT PRIVILEGES propagates to new tables
public	SELECT, INSERT, UPDATE, DELETE	Same
auth	SELECT only	Read-only on Supabase GoTrue tables (debugging / inspection)
storage	SELECT only	Read-only on Supabase storage tables
extensions	USAGE	Lets queries reach extensions.pg_stat_statements etc.

What you can NOT do:

• Drop / truncate auth.* or storage.* (read-only)
• ALTER ROLE, CREATE ROLE, CREATE EXTENSION (those are postgres-only)
• Connect as postgres, supabase_admin, authenticator from outside the cluster
• Connect at all without TLS (pg_hba hostnossl ... reject)

Need broader access? Ask chrisfu — easier to extend the knoe_developer group than to mint role-specific grants per engineer.

---

Onboarding a new engineer (admin-facing)

./etc/onboard_engineer.sh <username> <email>

Outputs:

• A one-time URL: https://db.0.knoe.dev/onboard.html#user=...&pw=...&exp=...
• A QR-code rendering of that URL (in your terminal, via qrencode)
• The plaintext temp password (fallback)

Deliver the URL to the new engineer via Gmail (to their @knoey.com address) or by showing the QR on screenshare for them to scan with their phone. The landing page handles all the engineer-side UX (copy buttons, connection string, rotation guidance). They save the password to their personal 1Password — no shared vault required. See docs/onboarding.md.

The script idempotently CREATEs / ALTERs the role:

• LOGIN INHERIT VALID UNTIL <now+24h>
• PASSWORD set to a fresh 192-bit random
• GRANT knoe_developer

The pg_hba.conf hostssl all +knoe_developer all scram-sha-256 rule means the new role is reachable via pg.0.knoe.dev immediately — no pg_hba edits needed per onboard.

Other actions:

./etc/onboard_engineer.sh --rotate <username>     # fresh 24h temp password
./etc/onboard_engineer.sh --revoke <username>     # DROP ROLE

---

Rotate your password

The engineer-side path is \password inside psql — they pick a new password locally, postgres updates the SCRAM verifier, the password never leaves their machine. No coordination with chrisfu needed.

If chrisfu needs to issue a fresh temp password (engineer locked out, forgot to rotate before VALID UNTIL expired):

./etc/onboard_engineer.sh --rotate <username>

Same delivery (URL/QR/email) as initial onboarding.

---

Troubleshooting

• pg_hba.conf rejects connection for host ... no encryption — you set sslmode=disable. Use verify-full (requires the CA cert) or require (encrypted but not verified).

• pg_hba.conf rejects connection for host <ip>, user <u>, no encryption — you're on a network that's stripping TLS, OR your psql client is too old. Update libpq to ≥17.

• password authentication failed for user "<u>" — typically wrong password, but also fires for roles not in our allow list (postgres, knoe-db, etc.) when connecting from outside the cluster. Check you're using your own role.

• FATAL: role "<u>" is not permitted to log in — your VALID UNTIL lapsed. Ask for rotation.

---

Related

• Phase 2 plan (queued, owned by Junie): install/deploy.sh switches to pg_oauth as the default until knoey-system/authority auth is live. Includes building a validator library against PG18's OAuthValidatorCallbacks API and bundling into the knoe-db image. See docs/TODO.md follow-up for the active reference.
• k3d build: same Service + cluster cert pattern in k3d mode. Owned by Junie alongside the install.sh true-up.
• knoe-auth Round 1: the longer-term identity story (Kerberos KDC + Java authority). Becomes the Phase 2 issuer when it deploys, but Phase 2 doesn't block on it — Google's issuer is sufficient for now.

Files

• deploy/gcp/gke/knoe-db.yaml — CNPG cluster spec; pg_hba block, server cert SAN list.
• deploy/gcp/gke/knoe-db-external-lb.yaml — external TCP LoadBalancer Service.