scripts/prod-psql: read-only psql to production (--write to change data), documented in AGENTS.md

Author: zachlatta

AGENTS.md

@@ -250,6 +250,11 @@ make import TRACKING=/tmp/zmr-tracking.csv FILES='…'   # writes to $DATABASE_U
 - One container: `Dockerfile`, which builds the PWA and a static Go binary on distroless. It
   listens on `$PORT` (default 8080). Health check: `GET /healthz` (pings the DB).
 - Migrations run automatically at startup (goose, embedded).
+- **Production SQL:** `scripts/prod-psql` connects to `merch-db` through its public TLS endpoint
+  (enabled 2026-10-14), using `PROD_DATABASE_URL` from the shared `.env`. It is read-only by
+  default; pass `--write` first to change data (`scripts/prod-psql --write -c "update …"`). Wrap
+  writes in `begin; … commit;`, match rows by id *and* name (ids differ from dev), and never
+  print the URL. If the password is rotated, rebuild the URL from `get_database`.
 - Required env: `DATABASE_URL`, `BASE_URL` (public https origin), `SESSION_SECRET`,
   `HCA_CLIENT_ID`, `HCA_CLIENT_SECRET`, `THESEUS_API_KEY`, `ADMIN_EMAILS`. Also needed:
   `AIRTABLE_API_KEY` for authors, `HCB_SHIPPING_PAYMENT_URL` for international payments,

scripts/prod-psql

@@ -0,0 +1,20 @@
+#!/bin/sh
+# psql against the PRODUCTION database (Orchard merch-db), using PROD_DATABASE_URL
+# from the shared .env (scripts/env-file). Read-only unless the first argument is
+# --write. Everything else goes to psql:
+#   scripts/prod-psql -c 'select id, name from items order by id'
+#   scripts/prod-psql --write -c "update items set … where id = 1"
+# Never echo the URL; it holds the password.
+set -e
+write=
+if [ "$1" = "--write" ]; then write=1; shift; fi
+env_file=$(dirname "$0")/env-file
+url=$(sed -n 's/^PROD_DATABASE_URL=//p' "$("$env_file")" | tail -1)
+if [ -z "$url" ]; then
+	echo "PROD_DATABASE_URL is not set in $("$env_file")" >&2
+	exit 1
+fi
+if [ -n "$write" ]; then
+	PGOPTIONS='-c statement_timeout=30000' exec psql "$url" -v ON_ERROR_STOP=1 "$@"
+fi
+PGOPTIONS='-c default_transaction_read_only=on -c statement_timeout=30000' exec psql "$url" -v ON_ERROR_STOP=1 "$@"