docs(supabase): owner procedure for M1 on DEV and the isolated stack

SUPABASE.md §3.3: target, history, drift, accounts, backup with auth data and its check, migration up without reset, checks after; every command rehearsed on the isolated stack. §5.1: pnpm db:sandbox.
This commit is contained in:
bchanot committed 2026-10-25 20:57:09 +01:00
1 parent 08abe42c48
commit 5ed1f01c37
1 file changed
+87 -13
+87 -13
View File
@@ -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 <version>` | the migrations before `<version>`, 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