docs(docs): V1-1.4 animals and relations as built, DEV procedure to M3

Contract §8.3 (differences, relation states, caps, lock order across M2 and
M3, concurrency results, migration states, mutations, residuals), helpers
and derived values; SUPABASE.md §3.3 procedure from DEV's current state to
M3 (not run) and §3.5; TEST_STRATEGY, plan note, backend table, CLAUDE.md.
This commit is contained in:
bchanot committed 2026-10-26 01:06:24 +01:00
1 parent d7845b7339
commit bc6a7ddb6f
6 files changed
+183 -46

No files matched your search

+56 -21
View File
@@ -20,7 +20,8 @@ supabase/
│ ├─ 20261011100000_profiles_professional.sql practice_name, professional_title, siret
│ ├─ 20261013100000_files_foundation.sql assets table, seven private buckets, avatar policies through assets, purge queue, browser + worker RPCs (STORAGE.md)
│ ├─ 20261025100000_workspaces.sql V1-1.1 (M1): workspaces, workspace_members, personal workspace per account, access helpers, audit correlation cap (§3.3)
│ └─ 20261025110000_clients.sql V1-1.2 (M2): clients, unaccent, client RPCs and search, write budget per workspace, N9 audit filter (§3.4)
│ ├─ 20261025110000_clients.sql V1-1.2 (M2): clients, unaccent, client RPCs and search, write budget per workspace, N9 audit filter (§3.4)
│ └─ 20261026100000_animals_relations.sql V1-1.4 (M3): species rows, animals, relations with history and voiding, their RPCs and reads (§3.5)
├─ seed.sql LOCAL dev accounts + first owner (never run in prod)
├─ seed/anatomical-sheets/equine/ official equine sheet as a DRAFT, generated by `pnpm import:equine`
│ ├─ legacy-sources/ the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input)
@@ -197,13 +198,18 @@ 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 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.
M1, M2 and M3 are written and tested on PGlite and on the isolated stack
(§5.1), none is applied to the DEV stack. Applying them there is an owner
action, never run by Claude, never with `db reset`, `db push`, `migration
repair` or any destructive command. The procedure below takes DEV from its
current state (every migration up to `20261013100000` applied, profiles and
fictitious accounts present) to M3 in one run. Every step was rehearsed on the
isolated stack in upgrade mode (`pnpm db:sandbox up upgrade 20261025100000`
for the one-run path, `... 20261025100000 20261025110000` for M1 first, then
M2 and M3), with the sandbox container name in place of
`supabase_db_faunosteo`; on 2026-10-26 the history, dump and count commands
were run again against an M3 sandbox. Nothing below prints a secret: the
database password stays in the container's own environment.
```bash
# 0. Target: the local CLI stack of this project, nothing remote.
@@ -213,12 +219,16 @@ docker ps --filter name=supabase_db_faunosteo --format '{{.Names}} {{.Status}}'
# 1. History: only the V1-1 migrations may be pending.
pnpm supabase migration list --local # every row has local = remote, except the V1-1 ones (remote empty):
# 20261025100000 (M1) on a checkout of 6bf6978-08abe42,
# 20261025100000 and 20261025110000 (M1, M2) from 4adbfcb on
# 20261025100000 (M1), 20261025110000 (M2), 20261026100000 (M3)
# on a checkout from b54c8e5 on (M1 alone: 08abe42; M1 + M2: 2dc04bc)
pnpm db:types:check # the diff must be exactly the objects of those migrations (M1: workspaces,
# workspace_members, workspace_kind, workspace_member_role; M2: clients,
# client_kind, create_client, update_client, set_client_archived,
# search_clients): anything else = drift, STOP
# search_clients; M3: animals, animal_client_relations, animal_sex,
# animal_relation_role, create_animal, update_animal, set_animal_archived,
# create_animal_client_relation, end_/update_/void_animal_client_relation,
# search_animals, list_client_animals, client_archive_preview):
# 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 \
@@ -228,13 +238,14 @@ docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h
# 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 \
> ~/faunosteo-backups/dev-before-v1-1.dump && chmod 600 ~/faunosteo-backups/dev-before-v1-1.dump
docker exec -i supabase_db_faunosteo pg_restore --list < ~/faunosteo-backups/dev-before-v1-1.dump \
| grep -E "TABLE DATA (auth users|public profiles|supabase_migrations schema_migrations)" # three lines expected
# 4. Apply without reset (M1's backfill runs inside the migration). `migration up` applies every
# pending migration of the checkout, in order: to apply M1 alone, run it from a checkout of 08abe42.
pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql" (then ..._clients.sql)
# pending migration of the checkout, in order (a shorter path: run it from the checkouts named in step 1).
pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql", then
# ..._clients.sql, then 20261026100000_animals_relations.sql
```
After applying:
@@ -246,9 +257,12 @@ docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h
|| (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-013 (grants, policies, reads); every file runs in
where w.personal_user_id = p.id) <> 1) || '"'"' profiles without exactly one workspace, '"'"'
|| (select count(*) from public.species where active) || '"'"' active species, '"'"'
|| (select count(*) from public.animals) || '"'"' animals'"'"'"'
# expected: N profiles, N workspaces, N members, 0 profiles without exactly one workspace,
# 10 active species, 0 animals
pnpm db:test # pgTAP 001-014 (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)
@@ -256,13 +270,14 @@ pnpm e2e:avatar # avatar flow and worker on the DE
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`
anything beyond the objects listed in step 1; the dump check misses a line; `migration up`
applies anything else than the expected V1-1 migrations; 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.
touch them. No down migration exists: going back means restoring the step 3
dump, an owner procedure of its own that is not rehearsed here.
### 3.4 Clients (V1-1.2, migration M2)
@@ -280,6 +295,26 @@ PGlite 0.3.16, loaded by the harness). An account whose workspace holds a
client can no longer be deleted (D9a); in DEV, delete its clients first from
a privileged SQL session, or reset.
### 3.5 Animals and relations (V1-1.4, migration M3)
Contract: `V1-1_OWNERS_ANIMALS.md` §5.2 to §5.4, §8.3, §9, §10. M3 adds the
species rows (`asinine` to `leporine` and `other`; `equine` unchanged; a row
never means a sheet exists), `public.animals` and
`public.animal_client_relations`. The browser reads them through RLS and
writes them only through `create_animal` (with an optional first relation),
`update_animal`, `set_animal_archived`, `create_animal_client_relation`,
`end_animal_client_relation`, `update_animal_client_relation` and
`void_animal_client_relation` (security definer); `search_animals`,
`list_client_animals` and `client_archive_preview` read (invoker, POST), and
`search_clients` now returns `current_animal_count`. A relation joins an
animal and a client of one workspace (composite keys); it is current, ended
(`ended_at`, `ended_on` when known) or voided (entered by mistake, kept,
frozen, shown nowhere); it is never deleted. New refusal codes:
`duplicate_relation`, `already_ended`. Writes share the workspace budget of
M2. An account whose workspace holds an animal can no longer be deleted
either (D9a): in DEV, delete its relations, animals and clients first from a
privileged SQL session, in that order.
## 4. Writing a migration
1. `pnpm supabase migration new <name>` creates `supabase/migrations/<timestamp>_<name>.sql`.
@@ -341,7 +376,7 @@ 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 up upgrade <version> [<then>]` | the migrations before `<version>`, the seeds, two GoTrue accounts (confirmed, unconfirmed), then `migration up`: the path a DEV database takes; with `<then>`, the migrations before `<then>` first (the workspaces count is printed), then the rest |
| `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 |