docs(supabase): DEV procedure with read-only checks and sandbox restore
Preflight of DEV recorded; backup adds row fingerprints and Storage bytes; restore check runs on the isolated stack; post-migration SQL, test effects, failure and restore effects; browser acceptance aligned on the owner brief.
This commit is contained in:
1 parent
9f585e9185
commit
e3b841799a
2 files changed
+296
-102
No files matched your search
+291
-99
@@ -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
|
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
|
(§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
|
action, never run by Claude, never with `db reset`, `db push`, `migration
|
||||||
repair` or any destructive command. The procedure below takes DEV from its
|
repair`, a volume removal or any other destructive command. The procedure
|
||||||
current state (every migration up to `20261013100000` applied, profiles and
|
below takes DEV from its current state (every migration up to
|
||||||
fictitious accounts present) to M3 in one run. Every step was rehearsed on the
|
`20261013100000` applied, fictitious accounts present) to M3 in one run; the
|
||||||
isolated stack in upgrade mode (`pnpm db:sandbox up upgrade 20261025100000`
|
upgrade path was rehearsed on the isolated stack (`pnpm db:sandbox up upgrade
|
||||||
for the one-run path, `... 20261025100000 20261025110000` for M1 first, then
|
20261025100000`). Steps 0 to 3 only read DEV (the SQL helpers force a
|
||||||
M2 and M3), with the sandbox container name in place of
|
read-only session); step 3b writes on the sandbox only; step 4 is the one
|
||||||
`supabase_db_faunosteo`; on 2026-10-26 the history, dump and count commands
|
write on DEV. Nothing below prints a key: the database password stays in the
|
||||||
were run again against an M3 sandbox. Nothing below prints a secret: the
|
containers' environment, and `supabase status` is read with `-o env`
|
||||||
database password stays in the container's own environment.
|
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
|
```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.
|
# 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
|
git status -sb # the V1-1 branch, clean, equal to origin
|
||||||
test ! -f supabase/.temp/project-ref && echo "no linked project" # nothing remote is linked
|
test ! -f supabase/.temp/project-ref && echo "no linked project"
|
||||||
docker ps --filter name=supabase_db_faunosteo --format '{{.Names}} {{.Status}}'
|
pnpm -s supabase status -o env | grep '^API_URL=' # http://<DEV host>: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.
|
# 1. History and drift: 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):
|
pnpm supabase migration list --local # local = remote on every row up to 20261013100000, remote empty on
|
||||||
# 20261025100000 (M1), 20261025110000 (M2), 20261026100000 (M3)
|
# 20261025100000 (M1), 20261025110000 (M2), 20261026100000 (M3), nothing else
|
||||||
# on a checkout from b54c8e5 on (M1 alone: 08abe42; M1 + M2: 2dc04bc)
|
pnpm -s db:types:check > "$B/types-before.diff"
|
||||||
pnpm db:types:check # the diff must be exactly the objects of those migrations (M1: workspaces,
|
grep -c '^<' "$B/types-before.diff" # 0: nothing removed
|
||||||
# workspace_members, workspace_kind, workspace_member_role; M2: clients,
|
grep -oE '^> [a-z_]+:' "$B/types-before.diff" | sort -u | wc -l
|
||||||
# client_kind, create_client, update_client, set_client_archived,
|
# 24 names, only these: workspaces, workspace_members, workspace_kind, workspace_member_role (M1);
|
||||||
# search_clients; M3: animals, animal_client_relations, animal_sex,
|
# clients, client_kind, create_client, update_client, set_client_archived, search_clients (M2);
|
||||||
# animal_relation_role, create_animal, update_animal, set_animal_archived,
|
# animals, animal_client_relations, animal_sex, animal_relation_role, create_animal, update_animal,
|
||||||
# create_animal_client_relation, end_/update_/void_animal_client_relation,
|
# set_animal_archived, create_/end_/update_/void_animal_client_relation, search_animals,
|
||||||
# search_animals, list_client_animals, client_archive_preview):
|
# list_client_animals, client_archive_preview (M3); any other name = drift, STOP
|
||||||
# anything else = drift, STOP
|
|
||||||
|
|
||||||
# 2. Existing accounts (the backfill creates one workspace per profile).
|
# 2. State before: counts, row fingerprints (md5 only, no row printed) and structure.
|
||||||
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A \
|
cat > "$B/counts.sql" <<'SQL'
|
||||||
-c "select (select count(*) from auth.users) || '"'"' users, '"'"' || (select count(*) from public.profiles) || '"'"' profiles'"'"'"'
|
set timezone = 'UTC';
|
||||||
# users = profiles expected; note the profile count N
|
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.
|
# 3. Backup outside Git: the whole `postgres` database (auth, storage metadata, public, private, audit,
|
||||||
mkdir -p ~/faunosteo-backups && chmod 700 ~/faunosteo-backups
|
# 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' \
|
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
|
> "$B/dev-before-v1-1.dump" && chmod 600 "$B/dev-before-v1-1.dump"
|
||||||
docker exec -i supabase_db_faunosteo pg_restore --list < ~/faunosteo-backups/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"
|
||||||
| grep -E "TABLE DATA (auth users|public profiles|supabase_migrations schema_migrations)" # three lines expected
|
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.
|
# 3b. The dump restores, on the isolated stack (never on the DEV server): a scratch database of the
|
||||||
# The scratch name is the only database created or dropped here; never type another one.
|
# sandbox, compared line by line with step 2, then dropped. `restore_check_v1_1` is the only database
|
||||||
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" createdb -h 127.0.0.1 -U postgres restore_check_v1_1'
|
# created or dropped here; never type another name.
|
||||||
docker exec -i supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_restore -h 127.0.0.1 -U postgres \
|
docker exec faunosteo_dbsandbox_db sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" createdb -h 127.0.0.1 -U postgres restore_check_v1_1'
|
||||||
-d restore_check_v1_1 --no-owner' < ~/faunosteo-backups/dev-before-v1-1.dump 2> ~/faunosteo-backups/restore-check.log
|
docker exec -i faunosteo_dbsandbox_db sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_restore -h 127.0.0.1 -U postgres \
|
||||||
grep -c "error:" ~/faunosteo-backups/restore-check.log # only privilege errors on Supabase-managed objects (see below)
|
-d restore_check_v1_1 --no-owner' < "$B/dev-before-v1-1.dump" 2> "$B/restore-check.log"
|
||||||
for db in postgres restore_check_v1_1; do
|
grep 'ERROR:' "$B/restore-check.log" | sed -E 's/.*ERROR: +//' | sort | uniq -c
|
||||||
docker exec supabase_db_faunosteo sh -c "PGPASSWORD=\"\$POSTGRES_PASSWORD\" psql -h 127.0.0.1 -U postgres -d $db -t -A -c \
|
# only these privilege refusals on Supabase-managed objects (exit status 1 because of them):
|
||||||
\"select '$db: ' || (select count(*) from auth.users) || ' users, ' || (select count(*) from public.profiles)
|
# 18 « permission denied to change default privileges », 5 « grant options cannot be granted back to
|
||||||
|| ' profiles, ' || (select count(*) from supabase_migrations.schema_migrations) || ' migrations'\""
|
# your own grantor », 1 each « permission denied for » table secrets (vault, empty on DEV),
|
||||||
done # the two lines must give the same counts
|
# function pg_stat_statements_reset, function pg_reload_conf; any other line = STOP
|
||||||
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" dropdb -h 127.0.0.1 -U postgres restore_check_v1_1'
|
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
|
# 4. Apply without reset (M1's backfill runs inside the migration); no app session open on DEV meanwhile.
|
||||||
# pending migration of the checkout, in order (a shorter path: run it from the checkouts named in step 1).
|
# `migration up` applies every pending migration of the checkout, in order.
|
||||||
pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql", then
|
pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql...", then
|
||||||
# ..._clients.sql, then 20261026100000_animals_relations.sql
|
# ..._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
|
```bash
|
||||||
pnpm supabase migration list --local # each applied migration now has its remote column
|
pnpm supabase migration list --local # M1, M2, M3 now have their remote column; nothing pending
|
||||||
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A -c "
|
cat > "$B/post.sql" <<'SQL'
|
||||||
select (select count(*) from public.profiles) || '"'"' profiles, '"'"'
|
select 'workspaces ' || count(*) from public.workspaces;
|
||||||
|| (select count(*) from public.workspaces) || '"'"' workspaces, '"'"'
|
select 'members ' || count(*) from public.workspace_members;
|
||||||
|| (select count(*) from public.workspace_members) || '"'"' members, '"'"'
|
select 'profiles without exactly one personal workspace ' || count(*) from public.profiles p
|
||||||
|| (select count(*) from public.profiles p where (select count(*) from public.workspaces w
|
where (select count(*) from public.workspaces w where w.personal_user_id = p.id) <> 1;
|
||||||
where w.personal_user_id = p.id) <> 1) || '"'"' profiles without exactly one workspace, '"'"'
|
select 'personal workspaces without their sole holder ' || count(*) from public.workspaces w
|
||||||
|| (select count(*) from public.species where active) || '"'"' active species, '"'"'
|
where w.kind = 'personal'
|
||||||
|| (select count(*) from public.animals) || '"'"' animals'"'"'"'
|
and ((select count(*) from public.workspace_members m where m.workspace_id = w.id) <> 1
|
||||||
# expected: N profiles, N workspaces, N members, 0 profiles without exactly one workspace,
|
or not exists (select 1 from public.workspace_members m
|
||||||
# 10 active species, 0 animals
|
where m.workspace_id = w.id and m.user_id = w.personal_user_id and m.member_role = 'holder'));
|
||||||
pnpm db:test # pgTAP 001-014: the privilege census (001: grants of every role,
|
select 'duplicate memberships ' || count(*) from (
|
||||||
# definer functions, RLS on every table), the policies and the
|
select workspace_id, user_id from public.workspace_members group by 1, 2 having count(*) > 1) d;
|
||||||
# RPC refusals; every file runs in begin ... rollback: rows
|
select 'active species ' || count(*) from public.species where active;
|
||||||
# unchanged (checked on the sandbox)
|
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:types:check # no diff
|
||||||
pnpm e2e:avatar # avatar flow and worker on the DEV stack (fictitious seed accounts)
|
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-<time>@faunosteo.local` (and, after M1, its workspace),
|
||||||
|
deletes it at the end (a failed run leaves it), signs in as
|
||||||
|
`bob@faunosteo.local` (sessions and `last_sign_in_at` of an existing
|
||||||
|
account), and its worker drains every due purge-queue row and quarantine
|
||||||
|
leftover of the stack (13 rows on 2026-10-26). M1 to M3 touch neither
|
||||||
|
Storage nor `assets`; the avatar stays covered by the browser acceptance
|
||||||
|
below.
|
||||||
|
|
||||||
Stop and report instead of continuing when: `migration list` shows another
|
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
|
pending migration or a remote-only one; `db:types:check` before step 4 shows a
|
||||||
anything beyond the objects listed in step 1; the dump check misses a line; the
|
removed line or another name than the 24 of step 1; the dump check misses a
|
||||||
restore check gives other counts or an error that is not one of the expected
|
line; the restore check prints another error or a differing line; `migration
|
||||||
privilege errors; `migration up`
|
up` applies anything else than the three V1-1 migrations or fails; any check
|
||||||
applies anything else than the expected V1-1 migrations; any count after it differs from
|
after it differs from the expectation.
|
||||||
the expectation. Step 3b was rehearsed on 2026-10-26 against the M3 sandbox
|
|
||||||
(container `faunosteo_dbsandbox_db`, 119 MB dump of fictitious load-test
|
When something fails:
|
||||||
data): users, profiles, workspaces, animals and the migration history came back
|
|
||||||
with the same counts; `pg_restore --no-owner` printed 26 errors, all privilege
|
- backup or restore check fails: nothing was applied; fix the cause (space,
|
||||||
refusals on Supabase-managed objects (18 « permission denied to change default
|
container, sandbox) and start again from step 2. Never apply without a
|
||||||
privileges », 5 « grant options cannot be granted back to your own grantor »,
|
restore check that passed;
|
||||||
`vault.secrets`, `pg_stat_statements_reset`, `pg_reload_conf`), none on a
|
- history diverges (another pending version, a remote-only version, an object
|
||||||
table of the application. Storage file bytes
|
present without its history): stop; no `migration repair`, no hand-made
|
||||||
(avatars) live in the storage container's volume, not in the dump; M1 does not
|
insert into the history. The divergence is analysed first, then resolved by
|
||||||
touch them. No down migration exists: going back means restoring the step 3
|
its own owner-validated procedure;
|
||||||
dump, an owner procedure of its own that is not rehearsed here.
|
- `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).
|
||||||
|
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
|
||||||
|
objects, not only the history. Do not assume a full rollback, and do not
|
||||||
|
run `migration up` again before the state is understood;
|
||||||
|
- profiles not caught up (a profile without exactly one workspace): stop;
|
||||||
|
`private.backfill_personal_workspaces()` is idempotent, but running it by
|
||||||
|
hand is a write on DEV, decided after the cause is known;
|
||||||
|
- an RLS policy refuses a legitimate access in the browser: note the account
|
||||||
|
(fictitious), the screen and the time; read `pnpm db:test` and `post.sql`;
|
||||||
|
the fix is a new migration on the branch, tested on the sandbox first,
|
||||||
|
never a grant typed on DEV;
|
||||||
|
- the generated types differ: compare with the committed file; a difference
|
||||||
|
means the applied schema is not the branch's: stop;
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
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
|
||||||
|
`postgres` database the services use, and it loses every write made after
|
||||||
|
the backup (accounts created or confirmed, password and profile changes,
|
||||||
|
sessions, which would end on every device, audit rows, clients, animals and
|
||||||
|
relations created during the acceptance, assets and purge-queue changes);
|
||||||
|
a Storage file uploaded after the backup would remain without its row, and a
|
||||||
|
file deleted after it would come back as a row without bytes. Rehearse it on
|
||||||
|
the sandbox before relying on it.
|
||||||
|
|
||||||
### 3.4 Clients (V1-1.2, migration M2)
|
### 3.4 Clients (V1-1.2, migration M2)
|
||||||
|
|
||||||
@@ -346,27 +497,68 @@ isolated stack, and no DEV acceptance is recorded.
|
|||||||
#### Browser acceptance on DEV (owner, after §3.3)
|
#### Browser acceptance on DEV (owner, after §3.3)
|
||||||
|
|
||||||
A checkpoint of its own: the Playwright suites never run against DEV, so this
|
A checkpoint of its own: the Playwright suites never run against DEV, so this
|
||||||
is the owner's check, from a phone and a computer of the private network, on
|
is the owner's check, on `pnpm dev` (DEV origin), from a computer and a phone
|
||||||
`pnpm dev` (DEV origin), with fictitious accounts only (never a real profile
|
of the private network, with fictitious accounts only: `alice@faunosteo.local`
|
||||||
changed for a test). Each line is done in French and in English:
|
(account A) and `bob@faunosteo.local` (account B), password of §3.2. No real
|
||||||
|
profile is changed for a test and nothing is created outside these two
|
||||||
|
workspaces; records carry names that say they are tests (« Recette Client
|
||||||
|
1 »). Each journey is done in French and in English, on a computer and at
|
||||||
|
375 px (a phone, or the browser's responsive mode); the main actions once more
|
||||||
|
with the keyboard only (Tab, Enter, Escape in the dialogs). Results are
|
||||||
|
recorded per line, device and language; a line not done is reported as not
|
||||||
|
done.
|
||||||
|
|
||||||
1. sign in; Clients and Animaux open from the sidebar and the drawer;
|
Sign-in and workspace:
|
||||||
2. journey 1: new client, « Ajouter un premier animal » from its page, owner
|
|
||||||
chosen, back on the client page with the animal;
|
1. A signs in; the dashboard opens; Clients and Animaux open from the sidebar
|
||||||
3. journey 2: find the animal from the phone, open it, call the owner through
|
(computer) and from the drawer (phone);
|
||||||
the `tel:` link;
|
2. A signs out and signs in again: the records of the lines below are still
|
||||||
4. journey 3: add the new owner, end the former owner's relation with a date,
|
there, after a reload too;
|
||||||
the former owner's page shows « Ancien propriétaire »;
|
3. signed out, `/app/clients` and a copied record URL lead to the sign-in
|
||||||
5. journey 4: an animal with no client shows « Propriétaire non renseigné »;
|
page, then back to that page after sign-in.
|
||||||
6. journey 5: archive a client (the confirmation lists its sole-owned
|
|
||||||
animals), find it under « Afficher les archivés », restore it;
|
Clients:
|
||||||
7. journey 6: a structure linked as keeper; journey 7: « Autre » with « Furet »;
|
|
||||||
8. a relation entered by mistake removed with « Erreur de saisie », gone from
|
4. create a client; find it by name, by city, then by phone digits; open its
|
||||||
|
page;
|
||||||
|
5. edit its details (address, phone), save, reload: the values are kept;
|
||||||
|
6. archive it (the confirmation lists its sole-owned animals), find it under
|
||||||
|
« Afficher les archivés », restore it.
|
||||||
|
|
||||||
|
Animals and relations:
|
||||||
|
|
||||||
|
7. create an animal with no client: « Propriétaire non renseigné »;
|
||||||
|
8. from a client's page, « Ajouter un animal »: owner role chosen, back on the
|
||||||
|
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;
|
||||||
|
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;
|
||||||
|
12. remove a relation entered by mistake (« Erreur de saisie »): gone from
|
||||||
both pages;
|
both pages;
|
||||||
9. a second account sees none of it (list, search, a copied record URL).
|
13. « Autre » with « Furet »; a birth year alone, then a full date;
|
||||||
|
14. archive the animal, find it with the archived toggle, restore it;
|
||||||
|
15. from the phone: find an animal, open it, the owner's `tel:` link opens the
|
||||||
|
dialer;
|
||||||
|
16. Mon compte: A's photo still shows (no V1-1 change; checks the Storage path
|
||||||
|
after the migrations).
|
||||||
|
|
||||||
Results are recorded per line, device and language; a line not done is
|
Isolation:
|
||||||
reported as not done.
|
|
||||||
|
17. B signs in: no client and no animal of A in the lists or the searches;
|
||||||
|
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
|
||||||
|
records either (no staff access in V1-1).
|
||||||
|
|
||||||
|
Not covered: Safari iOS and Firefox unless such a device is used (the browser
|
||||||
|
suites are Chromium only until V1-5); the refusal of an unconfirmed account
|
||||||
|
(only with a fictitious unconfirmed account whose password is known, which
|
||||||
|
means a sign-up on DEV, the owner's choice); the back and forward guard
|
||||||
|
(accepted debt). This acceptance is no production security certification:
|
||||||
|
RR-1 to RR-10 stay open.
|
||||||
|
|
||||||
## 4. Writing a migration
|
## 4. Writing a migration
|
||||||
|
|
||||||
|
|||||||
@@ -1555,7 +1555,7 @@ validates after V1-1.1 and after the first UI step; nothing merges into
|
|||||||
| V1-1.3 | UI foundations: Playwright Chromium and axe (D14), `Dialog` containment and restore (D13). Built (§11.6), validated 2026-10-26 |
|
| V1-1.3 | UI foundations: Playwright Chromium and axe (D14), `Dialog` containment and restore (D13). Built (§11.6), validated 2026-10-26 |
|
||||||
| V1-1.4 | Animals and relations data: M3 with the species rows, RPCs, history rules, D9a proof. Written and tested on the isolated stack (§8.3), validated 2026-10-26; not applied to DEV |
|
| V1-1.4 | Animals and relations data: M3 with the species rows, RPCs, history rules, D9a proof. Written and tested on the isolated stack (§8.3), validated 2026-10-26; not applied to DEV |
|
||||||
| V1-1.5 | Clients UI: routes, forms, list and search, archive, navigation entry. Built and tested on the isolated stack (§11.7), validated 2026-10-26 |
|
| V1-1.5 | Clients UI: routes, forms, list and search, archive, navigation entry. Built and tested on the isolated stack (§11.7), validated 2026-10-26 |
|
||||||
| V1-1.6 | Animals and relations UI, navigation (D11: drawer only), documents, closure inventory (§15). Built and tested on the isolated stack (§11.8), awaiting the owner's checkpoint; D12 not in its brief; the owner's check over the LAN needs M1 to M3 on DEV |
|
| V1-1.6 | Animals and relations UI, navigation (D11: drawer only), documents, closure inventory (§15). Built and tested on the isolated stack (§11.8), validated 2026-10-26; D12 not in its brief; the owner's check over the LAN needs M1 to M3 on DEV |
|
||||||
|
|
||||||
Recommended first step: V1-1.1. It is SQL only, has no visible choice, and
|
Recommended first step: V1-1.1. It is SQL only, has no visible choice, and
|
||||||
every later step depends on its helpers.
|
every later step depends on its helpers.
|
||||||
@@ -1591,7 +1591,9 @@ Owner brief §21. Status words: **done** (built, tested on the isolated stack),
|
|||||||
**debt** (non-blocking, documented, kept in the product follow-up),
|
**debt** (non-blocking, documented, kept in the product follow-up),
|
||||||
**deferred** (left out on purpose, with who decided), **blocking** (before a
|
**deferred** (left out on purpose, with who decided), **blocking** (before a
|
||||||
merge into `develop`), **DEV** (to verify once M1 to M3 are applied, SUPABASE.md
|
merge into `develop`), **DEV** (to verify once M1 to M3 are applied, SUPABASE.md
|
||||||
§3.3). Nothing below is verified on DEV: no V1-1 migration is applied there.
|
§3.3). Nothing below is verified on DEV: no V1-1 migration is applied there. The
|
||||||
|
read-only preflight of DEV (2026-10-26) found M1 to M3 pending and nothing
|
||||||
|
else, and none of their objects present (SUPABASE.md §3.3).
|
||||||
|
|
||||||
| Area | Item | Status | Proof or reason |
|
| Area | Item | Status | Proof or reason |
|
||||||
|---|---|---|---|
|
|---|---|---|---|
|
||||||
@@ -1617,6 +1619,6 @@ merge into `develop`), **DEV** (to verify once M1 to M3 are applied, SUPABASE.md
|
|||||||
| Debt | no separate message for a relation voided elsewhere (seen as `conflict`) | debt | §11.8 |
|
| Debt | no separate message for a relation voided elsewhere (seen as `conflict`) | debt | §11.8 |
|
||||||
| Debt | pre-existing axe exceptions of RR-7 (language switcher, top bar account link, dashboard `dl`) | debt | scoped to their element and route; no V1-1 page relies on them for its own elements |
|
| Debt | pre-existing axe exceptions of RR-7 (language switcher, top bar account link, dashboard `dl`) | debt | scoped to their element and route; no V1-1 page relies on them for its own elements |
|
||||||
| Debt | GoTrue admin with the service key, `service_role` on the species table, no read limit of its own, partial Unicode folding | debt | release track RR-3, RR-4 (§14) |
|
| Debt | GoTrue admin with the service key, `service_role` on the species table, no read limit of its own, partial Unicode folding | debt | release track RR-3, RR-4 (§14) |
|
||||||
| DEV | M1 to M3 applied, workspaces and ten active species counted, pgTAP, types | DEV | SUPABASE.md §3.3, owner action |
|
| DEV | M1 to M3 applied, workspaces and ten active species counted, pgTAP, types | DEV | SUPABASE.md §3.3, owner action; read-only preflight conform 2026-10-26, backup, restore check and migration not run |
|
||||||
| DEV | browser acceptance on a phone and a computer over the LAN | DEV | SUPABASE.md §3.3 « Browser acceptance on DEV »; not done |
|
| DEV | browser acceptance on a phone and a computer over the LAN | DEV | SUPABASE.md §3.3 « Browser acceptance on DEV »; not done |
|
||||||
| Merge | owner's go after the V1-1.6 checkpoint and the DEV acceptance | blocking | §14; nothing merges into `develop` without it |
|
| Merge | owner's go after the V1-1.6 checkpoint and the DEV acceptance | blocking | §14; nothing merges into `develop` without it |
|
||||||
Reference in new issue
Block a user