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:
1 parent
08abe42c48
commit
5ed1f01c37
1 file changed
+87
-13
@@ -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
|
||||
|
||||
Reference in new issue
Block a user