docs(supabase): restore check reads pg_restore exit and every error

This commit is contained in:
bchanot committed 2026-10-26 21:46:02 +01:00
1 parent 9570089147
commit a2507fc083
3 files changed
+71 -17

No files matched your search

+4
View File
@@ -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.
+1
View File
@@ -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)
+66 -17
View File
@@ -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