docs(supabase): db:trial operating guide

This commit is contained in:
bchanot committed 2026-11-10 22:59:29 +01:00
1 parent 3b687a218e
commit f7bf0c85cb
5 files changed
+144 -10

No files matched your search

+29 -9
View File
@@ -1,12 +1,10 @@
# Dedicated manual trial stack: technical plan
Status: PROPOSAL, 2026-11-09 (owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire », §5), with the
decisions of the briefs « R0 — Décisions propriétaire et dernière validation graphique » (BDR-108) and « R0 — Verdict
de revue graphique propriétaire » (BDR-109), both 2026-11-09: name
`pnpm db:trial`, two trial accounts, `db:sandbox trial*` kept for now, isolation from the suites, volumes preserved,
resources capped, secrets renewable. Plan
only: no stack is created, started, reset or removed, no script changes, existing data untouched. Implementation
needs its own owner authorisation. Companion of `V1-2-6_U1_CORRECTIONS.md`.
Status: IMPLEMENTED 2026-11-10 (scripts and environment-free checks, lots committed 2026-11-09 and 2026-11-10), NOT
CREATED: the stack is created only after the owner's explicit go (brief « Après R0 — Implémentation technique de la
pile d'essai dédiée »). Design from the briefs « V1-2.6 UX — Arbitrages du premier essai propriétaire » §5,
« R0 — Décisions propriétaire et dernière validation graphique » (BDR-108) and « R0 — Verdict de revue graphique
propriétaire » (BDR-109). Operating guide: `SUPABASE.md` §5.2. Companion of `V1-2-6_U1_CORRECTIONS.md`.
## 1. Why
@@ -67,8 +65,9 @@ its first initialisation). Keys valid one year instead of 30 days, with a `rotat
keys with the same secret and restarts the services: a persistent stack with the sandbox's 30-day keys would lock
itself out after a month. Full renewal (owner 2026-11-09) is `rotate-secrets`: a new JWT secret and new keys, new role
passwords set in the database (`alter role … password`, values through psql variables, never argv), env files
rewritten (600), services restarted in order, the previous secrets file kept as `secrets.prev.sh` (600) until the
stack answers; account passwords are untouched. Both commands print no secret. Rules (A14, decided 2026-11-09): keys valid one year on this dedicated local stack
rewritten (600), services restarted in order; the new values wait in `secrets.next.env` (600) until the commit is
known, and the previous secrets stay in the backup taken just before (no `secrets.prev` file); account passwords
are untouched. Both commands print no secret. Rules (A14, decided 2026-11-09): keys valid one year on this dedicated local stack
only; no secret in Git, in a command line, in the script's output or in a log (the state folder sits outside the
repository and the script refuses one inside it); the rotation procedure is written in the script's help and in
`SUPABASE.md`; the renewal code gets a security review (fresh security gate) before the stack is used. Since every secret differs from the sandbox's, a suite that reached a trial port by mistake
@@ -154,3 +153,24 @@ they created; `shellcheck` on both scripts.
| A13 | Trial accounts | DECIDED: two accounts (3.5); practitioner = technical `admin` + `sheet_editor`, not a production profile; O1 unchanged. |
| A14 | Key lifetime and renewal | DECIDED: one year, documented rotation, no secret in Git or logs, security review of the renewal (3.3). |
| A15 | Backup before every `migrate` | RATIFIED: automatic, kept in the state folder, never pruned without the owner. |
## 7. Implementation (2026-11-10)
`scripts/db-trial.sh`, `scripts/db-trial-check.sh`, the suites' guard `packages/supabase/tests/sandbox/target.ts`.
Owner choices made at implementation (contract `.claude/tasks/contracts/2026-11-09-db-trial-stack-1809.md`):
cold physical backups (both volumes and the secrets, the stack stopped a few seconds) and a `restore` command
instead of `pg_dump -Fc` (§3.4); a read-only `plan` command; `db-sandbox.sh` gains a state-folder guard only, no
shared helper file (§4), and `db-trial.sh` pins its own images; GoTrue's public sign-up closed. Also: the gateway
refuses `/auth/v1/admin/`; `grant owner|admin` follows §5.7.1 of the V1-2 contract (factors first, typed
confirmation, audit row); catalogue rights mirror `public.grant_catalog_right` (admin first, no implicit admin
role), and every grant asks a typed confirmation. After the plan challenge (2026-11-10): `account`, `grant`,
`restore` and `destroy` need a terminal; the app host is decided at each run, not recorded (§3.2); `start`
recreates a missing container; backups check free space, list each archive back and write checksums last, and
`restore` and `destroy` never remove a volume without a backup of it: `destroy` refuses without a restorable
backup of what it would remove and names the manual removal commands; the stub harness is run by hand, not by
`check:all` (it reads the host's real ports). R13 (owner 2026-11-10): the shared trial dev server serves exactly
one of two listed stacks (`apps/app/vite/trial-targets.ts`), and `db-trial.sh` checks each operation's target and
every key it hands over (`SUPABASE.md` §5.2). Known limit: `app` takes no lock, so a `stop`, `destroy`, `restore`
or rotation run in another terminal just before Vite listens goes ahead (`SUPABASE.md` §5.2). The tests of §5 that
create a stack under a test prefix were not run (owner brief: environment-free checks only); the stub harness
replaces them until the first `create`.