diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index 11f388b3..074e1b85 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -201,105 +201,256 @@ the same helpers; the app passes its workspace id explicitly. 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. +repair`, a volume removal or any other destructive command. The procedure +below takes DEV from its current state (every migration up to +`20261013100000` applied, fictitious accounts present) to M3 in one run; the +upgrade path was rehearsed on the isolated stack (`pnpm db:sandbox up upgrade +20261025100000`). Steps 0 to 3 only read DEV (the SQL helpers force a +read-only session); step 3b writes on the sandbox only; step 4 is the one +write on DEV. Nothing below prints a key: the database password stays in the +containers' environment, and `supabase status` is read with `-o env` +filtered to the API URL, because its default output prints the service key +and the JWT secret. + +Read-only preflight of 2026-10-26 (Claude; CLI 2.120.0, PostgreSQL 17.11, +branch at `9f585e9`): history 9 applied, M1 to M3 pending, nothing +remote-only, no linked project; none of the tables, types, functions, +trigger, constraint or extension M1 to M3 create exists; types drift = +exactly the 24 names of step 1, nothing removed; 6 accounts = 6 profiles (4 +confirmed), 1 platform role, 9 asset rows (1 clean), 2 storage objects (11 +files in the storage volume, leftovers of earlier resets), 13 due rows in the +purge queue, 35 audit rows, species `equine` only, vault empty; `unaccent` +and `pgtap` available, not installed. Run steps 0 to 2 again on the day: DEV +changes as it is used. ```bash +# Same shell for every step: helpers, backup folder, private file mode. +devsql() { docker exec -i supabase_db_faunosteo sh -c 'PGOPTIONS="-c default_transaction_read_only=on" \ + PGPASSWORD="$POSTGRES_PASSWORD" psql -X -q -A -t -v ON_ERROR_STOP=1 -h 127.0.0.1 -U postgres -d "$1"' sh "$1"; } +boxsql() { docker exec -i faunosteo_dbsandbox_db sh -c 'PGOPTIONS="-c default_transaction_read_only=on" \ + PGPASSWORD="$POSTGRES_PASSWORD" psql -X -q -A -t -v ON_ERROR_STOP=1 -h 127.0.0.1 -U postgres -d "$1"' sh "$1"; } +B=~/faunosteo-backups +umask 077 + # 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}}' +git status -sb # the V1-1 branch, clean, equal to origin +test ! -f supabase/.temp/project-ref && echo "no linked project" +pnpm -s supabase status -o env | grep '^API_URL=' # http://:54321 +docker port supabase_db_faunosteo 5432 # 0.0.0.0:54322: the DEV database +docker inspect -f '{{.Name}} {{.Config.Image}}' supabase_db_faunosteo faunosteo_dbsandbox_db + # the same postgres:17.11.0.004 image twice; no sandbox + # container → `pnpm db:sandbox up fresh` first (§5.1) +mkdir -p "$B" && chmod 700 "$B" # outside Git, never synced, never attached to a report -# 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), 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; 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 +# 1. History and drift: only the V1-1 migrations may be pending. +pnpm supabase migration list --local # local = remote on every row up to 20261013100000, remote empty on + # 20261025100000 (M1), 20261025110000 (M2), 20261026100000 (M3), nothing else +pnpm -s db:types:check > "$B/types-before.diff" +grep -c '^<' "$B/types-before.diff" # 0: nothing removed +grep -oE '^> [a-z_]+:' "$B/types-before.diff" | sort -u | wc -l +# 24 names, only these: workspaces, workspace_members, workspace_kind, workspace_member_role (M1); +# clients, client_kind, create_client, update_client, set_client_archived, search_clients (M2); +# animals, animal_client_relations, animal_sex, animal_relation_role, create_animal, update_animal, +# set_animal_archived, create_/end_/update_/void_animal_client_relation, search_animals, +# list_client_animals, client_archive_preview (M3); any other name = 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 +# 2. State before: counts, row fingerprints (md5 only, no row printed) and structure. +cat > "$B/counts.sql" <<'SQL' +set timezone = 'UTC'; +select 'users ' || count(*) from auth.users; +select 'identities ' || count(*) from auth.identities; +select 'profiles ' || count(*) from public.profiles; +select 'profile_roles ' || count(*) from public.profile_roles; +select 'species ' || count(*) from public.species; +select 'sheets ' || count(*) from public.anatomical_sheets; +select 'sheet_versions ' || count(*) from public.anatomical_sheet_versions; +select 'assets ' || count(*) from public.assets; +select 'purge_queue ' || count(*) from private.object_purge_queue; +select 'buckets ' || count(*) from storage.buckets; +select 'objects ' || count(*) from storage.objects; +select 'audit_logs ' || count(*) from audit.audit_logs; +select 'migrations ' || string_agg(version, ',' order by version) from supabase_migrations.schema_migrations; +select 'md5 users ' || md5(coalesce(string_agg(t::text, '|' order by t::text), '')) from auth.users t; +select 'md5 profiles ' || md5(coalesce(string_agg(t::text, '|' order by t::text), '')) from public.profiles t; +select 'md5 profile_roles ' || md5(coalesce(string_agg(t::text, '|' order by t::text), '')) from public.profile_roles t; +select 'md5 assets ' || md5(coalesce(string_agg(t::text, '|' order by t::text), '')) from public.assets t; +select 'md5 sheet_versions ' || md5(coalesce(string_agg(t::text, '|' order by t::text), '')) from public.anatomical_sheet_versions t; +select 'md5 species equine ' || md5(t::text) from public.species t where t.id = 'equine'; +select 'tables ' || n.nspname || ' ' || count(*) from pg_class c join pg_namespace n on n.oid = c.relnamespace + where c.relkind in ('r', 'p') and n.nspname in ('public', 'private', 'audit', 'auth', 'storage') group by n.nspname order by n.nspname; +select 'functions ' || n.nspname || ' ' || count(*) from pg_proc p join pg_namespace n on n.oid = p.pronamespace + where n.nspname in ('public', 'private') group by n.nspname order by n.nspname; +select 'policies ' || count(*) from pg_policies where schemaname in ('public', 'storage', 'audit'); +select 'rls tables public ' || count(*) from pg_class c join pg_namespace n on n.oid = c.relnamespace + where n.nspname = 'public' and c.relkind = 'r' and c.relrowsecurity; +SQL +devsql postgres < "$B/counts.sql" > "$B/counts-before.txt" && cat "$B/counts-before.txt" +# users = profiles = N (6 on 2026-10-26); the other lines are the reference of steps 3b and 5 -# 3. Backup outside Git (includes auth.users and the migration history), then check it. -mkdir -p ~/faunosteo-backups && chmod 700 ~/faunosteo-backups +# 3. Backup outside Git: the whole `postgres` database (auth, storage metadata, public, private, audit, +# migration history, grants) and the bytes of the Storage files (the storage container's volume). 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-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 + > "$B/dev-before-v1-1.dump" && chmod 600 "$B/dev-before-v1-1.dump" +docker cp supabase_storage_faunosteo:/mnt - > "$B/dev-before-v1-1-storage.tar" && chmod 600 "$B/dev-before-v1-1-storage.tar" +ls -l "$B" # both files non-empty, -rw------- +docker exec -i supabase_db_faunosteo pg_restore --list < "$B/dev-before-v1-1.dump" \ + | grep -cE "TABLE DATA (auth users|public profiles|storage objects|supabase_migrations schema_migrations)" # 4 +tar -tvf "$B/dev-before-v1-1-storage.tar" | grep -c '^-' # the volume's file count (11 on 2026-10-26) -# 3b. The dump restores: into a scratch database of the same server, counts compared, then dropped. -# The scratch name is the only database created or dropped here; never type another one. -docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" createdb -h 127.0.0.1 -U postgres restore_check_v1_1' -docker exec -i supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_restore -h 127.0.0.1 -U postgres \ - -d restore_check_v1_1 --no-owner' < ~/faunosteo-backups/dev-before-v1-1.dump 2> ~/faunosteo-backups/restore-check.log -grep -c "error:" ~/faunosteo-backups/restore-check.log # only privilege errors on Supabase-managed objects (see below) -for db in postgres restore_check_v1_1; do - docker exec supabase_db_faunosteo sh -c "PGPASSWORD=\"\$POSTGRES_PASSWORD\" psql -h 127.0.0.1 -U postgres -d $db -t -A -c \ - \"select '$db: ' || (select count(*) from auth.users) || ' users, ' || (select count(*) from public.profiles) - || ' profiles, ' || (select count(*) from supabase_migrations.schema_migrations) || ' migrations'\"" -done # the two lines must give the same counts -docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" dropdb -h 127.0.0.1 -U postgres restore_check_v1_1' +# 3b. The dump restores, on the isolated stack (never on the DEV server): a scratch database of the +# sandbox, compared line by line with step 2, then dropped. `restore_check_v1_1` is the only database +# created or dropped here; never type another name. +docker exec faunosteo_dbsandbox_db sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" createdb -h 127.0.0.1 -U postgres restore_check_v1_1' +docker exec -i faunosteo_dbsandbox_db sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_restore -h 127.0.0.1 -U postgres \ + -d restore_check_v1_1 --no-owner' < "$B/dev-before-v1-1.dump" 2> "$B/restore-check.log" +grep 'ERROR:' "$B/restore-check.log" | sed -E 's/.*ERROR: +//' | sort | uniq -c +# only these privilege refusals on Supabase-managed objects (exit status 1 because of them): +# 18 « permission denied to change default privileges », 5 « grant options cannot be granted back to +# your own grantor », 1 each « permission denied for » table secrets (vault, empty on DEV), +# function pg_stat_statements_reset, function pg_reload_conf; any other line = STOP +boxsql restore_check_v1_1 < "$B/counts.sql" > "$B/counts-restored.txt" +diff "$B/counts-before.txt" "$B/counts-restored.txt" && echo "restore identical" # no line may differ +docker exec faunosteo_dbsandbox_db sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" dropdb -h 127.0.0.1 -U postgres restore_check_v1_1' -# 4. Apply without reset (M1's backfill runs inside the migration). `migration up` applies every -# 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 +# 4. Apply without reset (M1's backfill runs inside the migration); no app session open on DEV meanwhile. +# `migration up` applies every pending migration of the checkout, in order. +pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql...", then + # ..._clients.sql, then 20261026100000_animals_relations.sql ``` -After applying: +Step 3b was rehearsed twice on the sandbox with fictitious data (2026-10-26: +a 119 MB load-test dump, then the same database piped into the scratch +database): the 26 privilege refusals above and nothing else, and on the second +run the step 2 output (2 144 accounts, row fingerprints, structure) identical +line by line. What the backup covers and what it does not: + +- the dump holds the whole `postgres` database: auth (accounts, identities, + sessions, password hashes: the files are as sensitive as DEV itself), + profiles, roles, assets, storage metadata, audit, the migration history and + the grants. It does not hold the cluster roles (created by the image), the + `_supabase` database (services' internal metadata), the Storage file bytes, + nor the vault rows (`--no-owner` cannot restore them as `postgres`; DEV has + none); +- the tar holds the Storage file bytes; restoring it is not rehearsed, and M1 + to M3 touch neither Storage nor `assets`; +- a restore of this dump into the DEV stack is not rehearsed: step 3b proves + the dump is complete and readable, not that DEV can be rolled back with it + (see below). + +After applying (read only, before anyone signs in): ```bash -pnpm supabase migration list --local # each applied migration 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, '"'"' - || (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: the privilege census (001: grants of every role, - # definer functions, RLS on every table), the policies and the - # RPC refusals; 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) +pnpm supabase migration list --local # M1, M2, M3 now have their remote column; nothing pending +cat > "$B/post.sql" <<'SQL' +select 'workspaces ' || count(*) from public.workspaces; +select 'members ' || count(*) from public.workspace_members; +select 'profiles without exactly one personal workspace ' || count(*) from public.profiles p + where (select count(*) from public.workspaces w where w.personal_user_id = p.id) <> 1; +select 'personal workspaces without their sole holder ' || count(*) from public.workspaces w + where w.kind = 'personal' + and ((select count(*) from public.workspace_members m where m.workspace_id = w.id) <> 1 + or not exists (select 1 from public.workspace_members m + where m.workspace_id = w.id and m.user_id = w.personal_user_id and m.member_role = 'holder')); +select 'duplicate memberships ' || count(*) from ( + select workspace_id, user_id from public.workspace_members group by 1, 2 having count(*) > 1) d; +select 'active species ' || count(*) from public.species where active; +select 'species ' || string_agg(id, ',' order by sort_order) from public.species; +select 'clients ' || count(*) from public.clients; +select 'animals ' || count(*) from public.animals; +select 'relations ' || count(*) from public.animal_client_relations; +select 'rls off on V1-1 tables ' || count(*) from pg_class c join pg_namespace n on n.oid = c.relnamespace + where n.nspname = 'public' and not c.relrowsecurity + and c.relname in ('workspaces', 'workspace_members', 'clients', 'animals', 'animal_client_relations'); +select 'anon, service_role or PUBLIC grants on V1-1 tables ' || count(*) from information_schema.role_table_grants + where table_schema = 'public' and grantee in ('anon', 'service_role', 'PUBLIC') + and table_name in ('workspaces', 'workspace_members', 'clients', 'animals', 'animal_client_relations'); +select 'anon EXECUTE on V1-1 RPCs ' || count(*) from information_schema.role_routine_grants + where routine_schema = 'public' and grantee in ('anon', 'PUBLIC') + and routine_name in ('create_client', 'update_client', 'set_client_archived', 'search_clients', + 'create_animal', 'update_animal', 'set_animal_archived', 'search_animals', 'list_client_animals', + 'client_archive_preview', 'create_animal_client_relation', 'end_animal_client_relation', + 'update_animal_client_relation', 'void_animal_client_relation'); +select 'unaccent ' || count(*) from pg_extension where extname = 'unaccent'; +select 'pgtap ' || count(*) from pg_extension where extname = 'pgtap'; +SQL +devsql postgres < "$B/post.sql" +# workspaces N, members N, then 0, 0, 0; active species 10; +# species equine,asinine,canine,feline,bovine,caprine,ovine,porcine,leporine,other; +# clients 0, animals 0, relations 0; then 0, 0, 0; unaccent 1; pgtap 0 +devsql postgres < "$B/counts.sql" > "$B/counts-after.txt"; diff "$B/counts-before.txt" "$B/counts-after.txt" +# only these lines differ (2026-10-26 values): species 1 → 10; migrations + the three V1-1 versions; +# tables private 1 → 2, public 7 → 12; functions private 41 → 54, public 26 → 40; policies 15 → 20; +# rls tables public 7 → 12. Every count and md5 of the existing rows is unchanged. +pnpm db:types:check # no diff +pnpm db:test # pgTAP 001-014 (see its effects below) +devsql postgres < "$B/counts.sql" | diff "$B/counts-after.txt" - # no diff: the tests left no row ``` +Effects of the test commands on DEV, read from the installed CLI 2.120.0 and +the scripts: + +- `pnpm db:test` (`supabase test db`): runs pg_prove as `postgres`; every file + of `supabase/tests` is one `begin … rollback`, so no row stays. It creates + the `pgtap` extension before the run and drops it after when it was absent + (DEV: absent), a transient schema change; an interrupted run can leave + `pgtap` installed (`post.sql` shows it). Run it before the browser + acceptance, with no app session open. +- `pnpm e2e:avatar`: not part of this procedure; optional, the owner's call. + It writes on DEV beyond its own fixture: it creates a temporary confirmed + account `e2e-avatar-