diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index d14fa979..cd26d4a6 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -196,23 +196,67 @@ confirmed email, `auth.uid()` only). No API role writes either table; `anon` and `service_role` hold no privilege on them. From M2 on, record tables use the same helpers; the app passes its workspace id explicitly. -M1 is written and tested on PGlite and on an isolated stack, not applied to -the DEV stack. Applying it there is an owner action, without a reset: +M1 is written and tested on PGlite and on the isolated stack (ยง5.1), not +applied to the DEV stack. Applying it there is an owner action, never run by +Claude, never with `db reset`, `db push`, `migration repair` or any +destructive command. Every step below was rehearsed on the isolated stack in +upgrade mode (`pnpm db:sandbox up upgrade 20261025100000`), with the sandbox +container name in place of `supabase_db_faunosteo`. Nothing below prints a +secret: the database password stays in the container's own environment. ```bash -pnpm supabase db dump --local -f ~/faunosteo-dev-schema-before-m1.sql # optional safety copy: schema -pnpm supabase db dump --local --data-only -f ~/faunosteo-dev-data-before-m1.sql # and data (DEV accounts are fictitious) -pnpm supabase migration list --local # 20261025100000 listed as local only -pnpm supabase migration up --local # applies the pending migration; its backfill creates the missing workspaces -pnpm db:test # the 12 pgTAP files on the DEV database (each rolled back) -pnpm db:types:check # no diff with the committed types +# 0. Target: the local CLI stack of this project, nothing remote. +pnpm supabase status # API on the DEV origin, DB on port 54322; no error +test ! -f supabase/.temp/project-ref && echo "no linked project" # nothing remote is linked +docker ps --filter name=supabase_db_faunosteo --format '{{.Names}} {{.Status}}' + +# 1. History: M1 must be the only pending migration. +pnpm supabase migration list --local # every row has local = remote, except 20261025100000 (remote empty) +pnpm db:types:check # the diff must be exactly the M1 objects (workspaces, workspace_members, + # workspace_kind, workspace_member_role): anything else = drift, STOP + +# 2. Existing accounts (the backfill creates one workspace per profile). +docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A \ + -c "select (select count(*) from auth.users) || '"'"' users, '"'"' || (select count(*) from public.profiles) || '"'"' profiles'"'"'"' +# users = profiles expected; note the profile count N + +# 3. Backup outside Git (includes auth.users and the migration history), then check it. +mkdir -p ~/faunosteo-backups && chmod 700 ~/faunosteo-backups +docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_dump -h 127.0.0.1 -U postgres -d postgres -Fc' \ + > ~/faunosteo-backups/dev-before-m1.dump && chmod 600 ~/faunosteo-backups/dev-before-m1.dump +docker exec -i supabase_db_faunosteo pg_restore --list < ~/faunosteo-backups/dev-before-m1.dump \ + | grep -E "TABLE DATA (auth users|public profiles|supabase_migrations schema_migrations)" # three lines expected + +# 4. Apply M1 without reset (its backfill runs inside the migration). +pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql" ``` -Afterwards every existing account has its workspace: in Studio's SQL editor, -`select count(*) from public.profiles p where not exists (select 1 from -public.workspaces w where w.personal_user_id = p.id)` returns 0. The migration is forward-only: undoing it means restoring -the dumps or writing a new migration. `pnpm db:reset` also applies it, but -replays the whole database from zero and loses the DEV accounts and data. +After applying: + +```bash +pnpm supabase migration list --local # 20261025100000 now has its remote column +docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A -c " + select (select count(*) from public.profiles) || '"'"' profiles, '"'"' + || (select count(*) from public.workspaces) || '"'"' workspaces, '"'"' + || (select count(*) from public.workspace_members) || '"'"' members, '"'"' + || (select count(*) from public.profiles p where (select count(*) from public.workspaces w + where w.personal_user_id = p.id) <> 1) || '"'"' profiles without exactly one workspace'"'"'"' +# expected: N profiles, N workspaces, N members, 0 profiles without exactly one workspace +pnpm db:test # pgTAP 001-012 (grants, policies, reads); every file runs in + # begin ... rollback: rows unchanged (checked on the sandbox) +pnpm db:types:check # no diff +pnpm e2e:avatar # avatar flow and worker on the DEV stack (fictitious seed accounts) +``` + +Stop and report instead of continuing when: `migration list` shows another +pending migration or a remote-only one; `db:types:check` before step 4 shows +anything beyond the M1 objects; the dump check misses a line; `migration up` +applies anything else than `20261025100000`; any count after it differs from +the expectation. The backup restores into a scratch database (rehearsed: +every row back; `pg_restore --no-owner` prints privilege errors on +Supabase-managed objects, which do not affect the data). Storage file bytes +(avatars) live in the storage container's volume, not in the dump; M1 does not +touch them. ## 4. Writing a migration @@ -252,6 +296,36 @@ Two parity traps met so far: counts must be scoped to fixture ids (the real stack carries `seed.sql` rows), and `order by` on text must pin `collate "C"` (the real image sorts with a locale collation, PGlite with C). +### 5.1 Isolated stack (`pnpm db:sandbox`) + +A throwaway Supabase stack for migration steps, so the DEV stack is never +reset or migrated by a test (owner rule since V1-1.1). `scripts/db-sandbox.sh` +starts the images the CLI stack uses (PostgreSQL 17.11.0.004, GoTrue v2.197.0, +Storage v1.79.36, PostgREST v16.4, Mailpit v1.31.3, pinned in the script) on +the network `faunosteo_dbsandbox_net`, containers `faunosteo_dbsandbox_*`, +ports on 127.0.0.1 only and distinct from DEV (db 57432, auth 57999, rest +57300, storage 57500, mail 57025). Nothing is mounted and the images declare +no volume, so `down` removes the containers and the network by their literal +names and can never reach a `supabase_*_faunosteo` volume. The password, JWT +secret and keys are generated at each `up` into a 600 file under +`~/.cache/faunosteo-db-sandbox` (`FAUNOSTEO_SANDBOX_DIR`), outside the +repository, deleted by `down`, never printed. Works with rootless Docker. + +| Command | What it does | +|---|---| +| `pnpm db:sandbox up fresh` | every migration through `supabase migration up --db-url`, then the seeds of `config.toml` (as `db reset`) | +| `pnpm db:sandbox up upgrade ` | the migrations before ``, the seeds, two GoTrue accounts (confirmed, unconfirmed), then `migration up`: the path a DEV database takes | +| `pnpm db:sandbox test-db` | `supabase test db --db-url`: the pgTAP files on the real image (rows unchanged afterwards) | +| `pnpm db:sandbox types [--check]` | `supabase gen types --db-url ... --schema public` through Prettier, written or diffed with the committed file | +| `pnpm db:sandbox test` | `packages/supabase/tests/sandbox/*.sandbox.ts`: real GoTrue and PostgREST sessions, concurrent SQL sessions | +| `pnpm db:sandbox sql` / `down` | psql as postgres on stdin / remove the stack | + +Every CLI call passes `--db-url` with `sslmode=disable` (the sandbox has no +TLS); none can fall back to the local DEV database. Differences from the CLI +stack: no Kong (GoTrue and PostgREST are called directly), no Studio, no +realtime or edge runtime, and the database init keeps only the role +passwords the services use. + How a test impersonates a user (same technique in both runners): ```sql