From a2507fc0836e4ed212821d7d379f7ea8c0576066 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 26 Oct 2026 21:46:02 +0100 Subject: [PATCH] docs(supabase): restore check reads pg_restore exit and every error --- .claude/memory/journal.md | 4 ++ .claude/tasks/TODO.md | 1 + docs/development/SUPABASE.md | 83 ++++++++++++++++++++++++++++-------- 3 files changed, 71 insertions(+), 17 deletions(-) diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 0346eedc..5e8a01fe 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -434,3 +434,7 @@ R5.4: `draft/{labels,changelog,review_report,drawing,overlay,app_review,svg_comp - Owner validated V1-1.6 + closure limits. Read-only DEV preflight: 9 applied, M1-M3 pending only, no V1-1 object, types drift 24 names, 6 accounts = 6 profiles, 2 objects / 11 volume files. Git clean = origin, develop/main/release untouched. - SUPABASE.md §3.3 rewritten (read-only helpers, fingerprints, storage tar, restore check on sandbox, post.sql, failure + restore effects, acceptance 19 lines); restore comparison rehearsed on sandbox, identical. BDR-080, LRN-090. Rehearsal dump already gone. - STOP: backup, migration up, acceptance, merge = owner. + +## 2026-10-26 (V1-1.7 owner brief: preflight accepted) +- Owner accepted preflight, keeps backup/restore/migration/acceptance. Classified 26 restore errors: pg_restore errors, not negative tests (18 ALTER DEFAULT PRIVILEGES, 7 GRANT ... WITH GRANT OPTION, 1 COPY vault.secrets). DEV vault 0 (read-only check). +- §3.3 hardened: pg_restore exit + full message/command set, vault count, exit codes, pgtap after db:test, object query. Exit status of earlier rehearsal not recorded. STOP: owner runs steps 0-4. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index dfdeb369..608bbfd6 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -507,6 +507,7 @@ Order (BDR-071): P0 docs + decisions → V1-1 clients and animals → V1-2 sheet - [x] read-only DEV preflight (session forced read-only): 9 applied + M1-M3 pending, nothing remote-only, no linked project, no V1-1 object present, types drift = 24 names added 0 removed, 6 accounts = 6 profiles, storage 2 objects / 11 volume files, purge queue 13 due - [x] scripts read: supabase.sh / dev-env.sh (local CLI, no remote), CLI 2.120.0 `test db` creates + drops pgtap, `supabase status` prints keys, e2e:avatar writes beyond its fixture (temp account, bob sign-in, purge-queue drain) - [x] SUPABASE.md §3.3 corrected: read-only helpers, counts + md5 fingerprints, Storage bytes tar, restore check on the sandbox (not the DEV server), post-migration SQL, test effects, failure handling, restore effects; browser acceptance aligned on the brief §11 (19 lines); restore comparison rehearsed on the sandbox (identical, 26 privilege refusals) + - [x] owner brief 2026-10-26 « V1-1.7 validation du préflight »: preflight accepted, owner runs backup + M1-M3. 26 restore errors classified = pg_restore errors, NOT negative tests (25 ACL on Supabase-managed objects + COPY vault.secrets, lossless only with vault empty); §3.3 now checks pg_restore exit (1) + full message/command set, vault count (step 2), migration up + db:test exit, pgtap after db:test, object query for failure; acceptance lines 9 (no duplicate current relation) and 17 (session change, same browser) - [ ] owner: steps 0-3b of SUPABASE.md §3.3 (backup + restore check) - [ ] owner: step 4 `pnpm supabase migration up --local`, then the post-migration checks and `pnpm db:test` - [ ] owner: browser acceptance on DEV (19 lines × FR/EN × computer/375 px) diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index 074e1b85..88e2a8f9 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -286,6 +286,8 @@ select 'rls tables public ' || count(*) from pg_class c join pg_namespace n on n 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 +echo "select 'vault secrets ' || count(*) from vault.secrets;" | devsql postgres +# 0: the one table whose rows step 3b cannot reload (see its COPY error); any other value = STOP # 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). @@ -302,35 +304,49 @@ tar -tvf "$B/dev-before-v1-1-storage.tar" | grep -c '^-' # the volume's file c # 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" + -d restore_check_v1_1 --no-owner' < "$B/dev-before-v1-1.dump" 2> "$B/restore-check.log"; echo "pg_restore exit $?" +# exit 1: pg_restore reports the 26 errors below and goes on; any other status = STOP +grep -c '^pg_restore:' "$B/restore-check.log" # 27: the 26 errors and the closing line +grep '^pg_restore:' "$B/restore-check.log" | grep -v 'could not execute query: ERROR:' +# only « pg_restore: warning: errors ignored on restore: 26 »; any other line (input file, connection) = STOP 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 +# your own grantor », 1 each « permission denied for » table secrets, function pg_stat_statements_reset, +# function pg_reload_conf +grep '^Command was:' "$B/restore-check.log" | cut -d' ' -f3-4 | sort | uniq -c +# 18 ALTER DEFAULT, 1 COPY vault.secrets, 5 GRANT ALL, 2 GRANT SELECT,REFERENCES,DELETE,TRUNCATE; +# any other message or command = STOP. These are pg_restore errors, not privilege tests (none runs +# here): 25 statements `postgres` may not issue on Supabase-managed objects (default privileges of +# supabase_admin and supabase_auth_admin, grant options on vault, pg_catalog and extensions +# functions), which the image sets up itself; and the load of vault.secrets, lossless only because +# step 2 found that table empty 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); 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 +pnpm supabase migration up --local; echo "migration up exit $?" +# "Applying migration 20261025100000_workspaces.sql...", then ..._clients.sql, then +# 20261026100000_animals_relations.sql; exit 0. Keep the whole output for the report. ``` 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: +database): the 26 pg_restore errors above (same messages, same 26 commands) +and nothing else, and on the second run the step 2 output (2 144 accounts, +row fingerprints, structure) identical line by line. The exit status was not +recorded then; pg_restore exits 1 whenever it ends on « errors ignored on +restore ». This backup is no full cluster backup. What it 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); + `_supabase` database (services' internal metadata), nor the Storage file + bytes. It holds the vault rows, but a restore as `postgres` cannot reload + them (the COPY error of step 3b; DEV has none, step 2); - 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 @@ -382,7 +398,9 @@ devsql postgres < "$B/counts.sql" > "$B/counts-after.txt"; diff "$B/counts-befor # 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) +pnpm db:test; echo "db:test exit $?" # pgTAP 001-014, exit 0 (see its effects below) +echo "select 'pgtap ' || count(*) from pg_extension where extname = 'pgtap';" | devsql postgres +# 0, as before the run; 1 = left installed (interrupted run): report it, do not drop it by hand devsql postgres < "$B/counts.sql" | diff "$B/counts-after.txt" - # no diff: the tests left no row ``` @@ -422,8 +440,10 @@ When something fails: insert into the history. The divergence is analysed first, then resolved by its own owner-validated procedure; - `migration up` fails: run nothing else. Read its message, then - `pnpm supabase migration list --local` and the object query of the - preflight (which of the three versions are recorded, which objects exist). + `pnpm supabase migration list --local` (which of the three versions are + recorded) and the object query below (which objects exist; before M1: 0 + everywhere and species 1; after M3: tables 6, types 5, functions 27, + trigger 1, constraint 1, unaccent 1, species 10). The CLI applies the files one after the other and stops at the first failure: M1 can be recorded with M2 not. Whether a failed file leaves part of its statements behind was not verified on this CLI version: check the @@ -441,6 +461,32 @@ When something fails: - the browser acceptance finds a regression: record it per line, device and language; the fix goes through the branch, its gates and a fresh verifier. +Object query (read only), for a failed or doubtful step 4: + +```bash +cat > "$B/objects.sql" <<'SQL' +select 'tables ' || count(*) from pg_class c join pg_namespace n on n.oid = c.relnamespace + where (n.nspname, c.relname) in (('public', 'workspaces'), ('public', 'workspace_members'), ('public', 'clients'), + ('public', 'animals'), ('public', 'animal_client_relations'), ('private', 'workspace_write_budgets')); +select 'types ' || count(*) from pg_type t join pg_namespace n on n.oid = t.typnamespace where n.nspname = 'public' + and t.typname in ('workspace_kind', 'workspace_member_role', 'client_kind', 'animal_sex', 'animal_relation_role'); +select 'functions ' || count(*) from pg_proc p join pg_namespace n on n.oid = p.pronamespace + where (n.nspname = 'private' and p.proname in ('backfill_personal_workspaces', 'caller_workspace_ids', + 'check_personal_workspace', 'create_personal_workspace', 'ensure_personal_workspace', 'writable_workspace_ids', + 'consume_write_budget', 'fold_text', 'is_clean_text', 'lock_relation_for_write', 'parse_birth_year', + 'parse_record_date', 'utc_tomorrow')) + or (n.nspname = 'public' and p.proname in ('create_client', 'update_client', 'set_client_archived', 'search_clients', + 'client_archive_preview', 'create_animal', 'update_animal', 'set_animal_archived', 'search_animals', + 'list_client_animals', 'create_animal_client_relation', 'end_animal_client_relation', + 'update_animal_client_relation', 'void_animal_client_relation')); +select 'trigger ' || count(*) from pg_trigger where tgname = 'profiles_create_personal_workspace'; +select 'constraint ' || count(*) from pg_constraint where conname = 'audit_logs_correlation_id_format'; +select 'unaccent ' || count(*) from pg_extension where extname = 'unaccent'; +select 'species ' || count(*) from public.species; +SQL +devsql postgres < "$B/objects.sql" +``` + Going back is a decision of its own, never a reflex. No down migration exists. The preferred way is forward: a new migration that corrects. A restore of the step 3 dump into DEV is not rehearsed: it would replace the @@ -532,7 +578,8 @@ Animals and relations: client page with the animal; 9. link an existing animal to a second client (co-ownership), then a structure as keeper and a third client as contact: each role shows on both - pages; + pages; linking a client already linked in the same role is refused (no + second current relation); 10. end a relation with a date: « Ancien propriétaire » on that client's page, the relation under the former ones on the animal's page; 11. correct the dates of a relation; @@ -547,7 +594,9 @@ Animals and relations: Isolation: -17. B signs in: no client and no animal of A in the lists or the searches; +17. A signs out and B signs in on the same browser: no client and no animal + of A in the lists or the searches, not even for an instant, nor with the + back button; 18. B opens a copied URL of A's client and of A's animal, then the same URL with one character changed: the same « introuvable » screen each time; 19. optional: `owner@faunosteo.local` (platform owner) sees none of A's