# Supabase: local stack, migrations, tests Status: Step 3 deliverable, extended at Step 4 (2026-10-08). Covers the foundation (profiles, platform roles, audit log) and the anatomical sheet tables (`ANATOMICAL_SHEET_MODEL.md`). Conventions: `BACKEND_ARCHITECTURE.md` §3–§9. ## 1. Layout ```text supabase/ ├─ config.toml CLI config (public schema exposed only, PG 17, strong passwords) ├─ migrations/ forward-only SQL, _.sql │ ├─ 20261008100000_foundation.sql schemas private/audit, updated_at, audit log │ ├─ 20261008100100_profiles.sql profiles + auth.users trigger + RLS │ ├─ 20261008100200_platform_roles.sql platform_role, profile_roles, helpers, RPCs │ ├─ 20261008110000_anatomical_sheets.sql species, sheets, immutable versions, assets, lifecycle RPCs │ ├─ 20261008110100_private_execute_hardening.sql EXECUTE revoked from PUBLIC on the Step 3 helpers │ ├─ 20261009100000_sheet_asset_storage.sql bucket anatomical-sheet-assets + read policy through the sheet │ ├─ 20261010100000_sheet_document_schema_v2.sql document schema 2: references, review_status, count_range checks │ ├─ 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) │ └─ 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) │ ├─ legacy-import/ baseline import (document, id map, SVG copies, IMPORT-REPORT.md), no SQL │ ├─ curation/ authored changes.json + references.json │ └─ draft/ curated working revision (document, horse.svg, sheet-ref.json, report-migration-map.json, CHANGELOG, REVIEW-REPORT, review/*.svg; bundled into the app with SHEET_BUNDLE=draft) + equine_draft.sql: idempotent, converging seed (sheet, 1 asset row, working draft), applied by db reset and by PGlite └─ tests/ pgTAP, one file per concern, allowed AND denied paths packages/supabase/ ├─ src/client.ts createBrowserClient() (anon key, PKCE) ├─ src/database.types.ts `supabase gen types` output ├─ src/anatomical-sheets.ts publishSheetVersion(): the core's verdict (`sheet.check`) as gate before the RPC ├─ src/assets.ts avatar flow: begin / quarantine upload / confirm / remove / own state / download, closed AssetFailure kinds ├─ tests/db/ PGlite harness: runs the pgTAP files without Docker └─ tests/e2e/ real-stack end-to-end (avatar flow with the worker container), `pnpm e2e:avatar` on the sandbox crates/core/src/domain/sheet/ canonical sheet document and its integrity rules (Rust core; `packages/domain` deleted at R5.7) ``` ## 2. Prerequisites - Node 24 + pnpm via corepack (`WORKSPACE.md`). - Docker daemon reachable by your user for the real stack. If `docker info` says `permission denied ... docker.sock`, add yourself to the `docker` group and log in again: ```bash sudo usermod -aG docker "$USER" ``` - No Docker: the PGlite suite still runs (see §5), the CLI commands do not. The Supabase CLI is a root devDependency (`pnpm supabase `), pinned like every other tool. Never install it globally. ## 3. Start, stop, reset Every CLI call goes through `scripts/supabase.sh` (`pnpm db:*`, `pnpm supabase `): it exports the DEV origin that `config.toml` reads with `env()` (`api.external_url`, `auth.site_url`, `studio.api_url`). A direct `node_modules/.bin/supabase start` would leave the literal `env(...)` text in GoTrue's mail links. The CLI publishes API 54321, PostgreSQL 54322, Studio 54323 and Mailpit 54324 on `0.0.0.0` (no bind option); the host firewall closes 54322-54324 on the LAN interface and the DEV gateway serves Mailpit behind basic auth on 54325 (`ENVIRONMENTS.md` §3). ```bash pnpm db:start # supabase start: pulls images, applies migrations + seed, prints URLs and keys pnpm db:stop # supabase stop (keeps the volume) pnpm db:reset # drop + replay every migration + seed from zero ``` Local endpoints (`config.toml`): | Service | URL | | --------------------------------------- | --------------------------------------------------------- | | API (PostgREST, Auth, Storage) | `http://127.0.0.1:54321` | | PostgreSQL | `postgresql://postgres:postgres@127.0.0.1:54322/postgres` | | Studio | `http://127.0.0.1:54323` | | Mail catcher (confirmation / OTP mails) | `http://127.0.0.1:54324` | Addresses on the host itself. From another device of the network: app `:5173`, API `:54321`, Mailpit through the gateway `:54325` (basic auth); Studio by SSH tunnel; PostgreSQL not at all (`ENVIRONMENTS.md` §3). `pnpm db:start` prints the `anon` and `service_role` keys. Only the anon key ever reaches the browser. Containers, volumes and network are named `supabase__faunosteo` (`project_id` of `config.toml`): the CLI imposes this pattern, so the `faunosteo_` prefix convention of DEPLOY.md ("Docker resource naming") applies as a suffix here. Several projects can run side by side as long as their `project_id` and ports differ. Two kinds of seed (`config.toml [db.seed] sql_paths`): | File | Scope | Content | | -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `seed.sql` | local only | dev accounts + first owner | | `seed/…/*.sql` | every environment | versioned reference data, idempotent (today: the official equine sheet as a draft); each file listed explicitly in `sql_paths` | The PGlite harness applies every `.sql` under `seed/` after the migrations, `seed.sql` never (it needs the real auth schema); a test fails when a seed file is missing from `sql_paths`. On another environment, apply a versioned seed with `psql -f` from a privileged session, then upload its assets (§3.1). Never run `supabase db push --include-seed` against a shared database: the list also contains `seed.sql` and its known local password. ### 3.1 Sheet assets (Storage) SVG files live in the private bucket `anatomical-sheet-assets`, keyed by content (`.svg`). Reading goes through the sheet (policy `anatomical_sheet_assets_read`): a published version of a usable sheet, or any version for its editors. No API role uploads; the operator does, with the service key, from the generated seed folder. The tool is the Rust binary `upload-sheet-assets` (`crates/core`, feature `upload`, R5.5). It targets the **local stack only**: there is no default destination and a host that is not this machine (or the configured `FAUNOSTEO_DEV_HOST`, a private address) is refused before any request. Run it by hand; the assistant does not. ```bash pnpm db:start # the seed creates the asset rows (pending) export SUPABASE_URL=http://127.0.0.1:54321 # http, explicit port; the DEV address needs FAUNOSTEO_DEV_HOST read -rs SUPABASE_SERVICE_ROLE_KEY && export SUPABASE_SERVICE_ROLE_KEY # typed, not in shell history pnpm assets:upload --check supabase/seed/anatomical-sheets/equine/draft # read-only plan pnpm assets:upload supabase/seed/anatomical-sheets/equine/draft # upload + confirm ``` What a run does, in order, and stops at the first refusal before the first write: 1. The folder must lie under `supabase/seed/anatomical-sheets`. `assets.json` is read under a size cap (strict keys, plain `.svg` file names, lowercase sha256 and uuid, no repeated entry, 64 entries at most). Each drawing is read under a cap and must match its entry (size, sha256) and be a drawing the product accepts (the core's SVG reader, nothing removed). 2. The destination is checked, then a handshake: the bucket exists, is private, and the key is accepted. 3. Each entry is planned from what the destination holds: an object under the key is read back and hashed; different bytes, a missing asset row or a row recording another hash refuse the run (nothing is overwritten, no row is invented; apply the seed first). 4. Missing objects are created without replacing anything (`x-upsert: false`), read back and verified, and only then is the row confirmed (`confirm_sheet_asset_upload`, service role only): the read policy ignores a row whose upload was never confirmed, so a user who registers a known hash on their own sheet opens nothing. A rerun after any failure resumes: an object already verified is kept, a confirmed row is left alone. A connection failure or a 5xx answer is retried three times (four attempts); a refusal (401, 403, a state mismatch, an oversized answer) is final. Exit codes: 0 done, 1 refused (usage, manifest, destination, content, handshake, state, access), 2 an argument that is not UTF-8, 3 network. The DEV address counts only if it is an address of this machine. The key is never printed and goes through no proxy. `pnpm e2e:sheet-assets` (= `pnpm db:sandbox sheet-assets-e2e`) runs the whole behaviour against the sandbox stack, never DEV (upload, rerun, anon and wrong key, refused destinations, unreachable port); the script refuses any URL but `http://127.0.0.1:57800` and any key whose issuer is not `db-sandbox`. The TypeScript tool (`packages/supabase/scripts/upload-sheet-assets.ts`) was deleted at R5.7 (RUST.md §11.23). ### 3.2 Files worker (Storage, Step 8) User files land in private buckets and are processed by the Rust worker (`crates/worker`, `docs/development/STORAGE.md`). Against the local stack: ```bash pnpm worker:image # faunosteo_worker:dev pnpm e2e:avatar # = pnpm db:sandbox avatar-e2e: the suite and the worker on the throwaway stack (§5.1) only docker compose --profile worker up worker # the same container from docker-compose.yml, reading .env.worker ``` `.env.worker` (not editable by the assistant): `SUPABASE_URL=http://supabase_kong_faunosteo:8000`, `SUPABASE_SERVICE_ROLE_KEY=`, `WORKER_ID=dev`. The service key stays in that file and in the shell; it never reaches the app `.env`, env.js or a commit. Seed accounts (local only, password `LocalDev-only-password-1`): | Email | Role | | ----------------------- | ------------------------------------------- | | `owner@faunosteo.local` | platform owner (bootstrapped by `seed.sql`) | | `alice@faunosteo.local` | plain user | | `bob@faunosteo.local` | plain user | ### 3.3 Workspaces (V1-1.1, migration M1) Contract: `docs/development/V1-1_OWNERS_ANIMALS.md` §4, §8.1, §9. Every account has exactly one personal workspace, created by the trigger `profiles_create_personal_workspace` in the sign-up transaction (GoTrue → `handle_new_auth_user` → profile → workspace + `holder` membership), through the single write path `private.ensure_personal_workspace(uuid)` (one statement, idempotent, race-safe). A deferred constraint trigger refuses at commit a personal workspace without its holder or with any other member. Reads: RLS through `private.caller_workspace_ids()` (member, active profile, 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, 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`, 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. 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 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. 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 # Privileges (read only), the reference of step 3b: effective ACLs of the application schemas, grants # of auth and storage to the API roles, policies, triggers, constraints, extensions, postgres defaults. cat > "$B/privs.sql" <<'SQL' select 'acl relations ' || n.nspname || ' ' || md5(string_agg(c.relname || ':' || coalesce(c.relacl, acldefault(case c.relkind when 'S' then 's'::"char" else 'r'::"char" end, c.relowner))::text || ':' || c.relrowsecurity || c.relforcerowsecurity, '|' order by c.relname)) from pg_class c join pg_namespace n on n.oid = c.relnamespace where n.nspname in ('public', 'private', 'audit', 'supabase_migrations') and c.relkind in ('r', 'v', 'S', 'p') group by n.nspname order by n.nspname; select 'acl functions ' || n.nspname || ' ' || md5(string_agg(p.oid::regprocedure::text || ':' || coalesce(p.proacl::text, '-') || ':' || p.prosecdef || ':' || coalesce(array_to_string(p.proconfig, ','), '-'), '|' order by p.oid::regprocedure::text)) from pg_proc p join pg_namespace n on n.oid = p.pronamespace where n.nspname in ('public', 'private', 'audit') group by n.nspname order by n.nspname; select 'acl schemas ' || md5(string_agg(nspname || ':' || coalesce(nspacl::text, '-'), '|' order by nspname)) from pg_namespace where nspname in ('public', 'private', 'audit'); select 'grants ' || n.nspname || ' ' || md5(string_agg(c.relname || ':' || pg_get_userbyid(a.grantee) || ':' || a.privilege_type || ':' || a.is_grantable, '|' order by c.relname, pg_get_userbyid(a.grantee), a.privilege_type)) from pg_class c join pg_namespace n on n.oid = c.relnamespace cross join lateral aclexplode(c.relacl) a where n.nspname in ('auth', 'storage') and a.grantee not in (c.relowner, 'postgres'::regrole) group by n.nspname order by n.nspname; select 'policies ' || md5(string_agg(schemaname || '.' || tablename || '.' || policyname || ':' || cmd || ':' || roles::text || ':' || coalesce(qual, '-') || ':' || coalesce(with_check, '-'), '|' order by schemaname, tablename, policyname)) from pg_policies where schemaname in ('public', 'storage', 'audit'); select 'triggers ' || count(*) || ' ' || md5(string_agg(tgrelid::regclass::text || '.' || tgname || ':' || tgenabled::text || ':' || tgfoid::regprocedure::text, '|' order by tgrelid::regclass::text, tgname)) from pg_trigger t join pg_class c on c.oid = t.tgrelid join pg_namespace n on n.oid = c.relnamespace where not tgisinternal and n.nspname in ('public', 'private', 'audit', 'auth', 'storage'); select 'constraints ' || count(*) || ' ' || md5(string_agg(conrelid::regclass::text || '.' || conname || ':' || pg_get_constraintdef(oid), '|' order by conrelid::regclass::text, conname)) from pg_constraint where connamespace::regnamespace::text in ('public', 'private', 'audit'); select 'extensions ' || string_agg(extname || '@' || extversion, ',' order by extname) from pg_extension; select 'default acl postgres ' || count(*) || ' ' || md5(string_agg(defaclnamespace::regnamespace::text || ':' || defaclobjtype::text || ':' || defaclacl::text, '|' order by defaclnamespace::regnamespace::text, defaclobjtype::text)) from pg_default_acl where defaclrole = 'postgres'::regrole; SQL devsql postgres < "$B/privs.sql" > "$B/privs-before.txt" && wc -l < "$B/privs-before.txt" # 15 cat > "$B/managed.sql" <<'SQL' select 'vault secrets ' || count(*) from vault.secrets; select 'managed default acl ' || count(*) from pg_default_acl where defaclrole in ('supabase_admin'::regrole, 'supabase_auth_admin'::regrole); SQL devsql postgres < "$B/managed.sql" # vault secrets 0, else STOP: no backup, no M1 to M3; vault rows need a procedure of their own (keys) # managed default acl D (21 on 2026-10-26): step 3b leaves out exactly D + 8 entries # 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' \ > "$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, on the isolated stack (never on the DEV server), with exit status 0: a scratch # database of the sandbox, restored in one transaction that stops at the first error, compared with # step 2, then dropped. `restore_check_v1_1` is the only database created or dropped here. # Prerequisite, sandbox only: DEV owns the cluster role `supabase_functions_admin` (schema # `supabase_functions`), a fresh sandbox does not, and the dump's ACL entries name it. Create # it once there, NOLOGIN with no global privilege (what a no-owner replay needs); never on DEV: docker exec -i faunosteo_dbsandbox_db sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -X -q -v ON_ERROR_STOP=1 -h 127.0.0.1 -U postgres -d postgres' <<'SQL' do $$ begin if not exists (select 1 from pg_roles where rolname = 'supabase_functions_admin') then create role supabase_functions_admin nologin nosuperuser nocreaterole nocreatedb noreplication nobypassrls noinherit; end if; end $$; SQL # The restore leaves out the D + 8 TOC entries `postgres` may not replay; the dump file itself stays # complete and unchanged (the list is a copy of its table of contents): # - D « DEFAULT ACL … supabase_admin | supabase_auth_admin »: default privileges for objects those # roles create (platform defaults; `postgres` may not change another role's defaults; no data, # no application privilege; the sandbox image holds its own); # - 5 « ACL vault »: secrets, decrypted_secrets, create_secret, update_secret, # _crypto_aead_det_decrypt; with --no-owner their extension makes them postgres's own, and # postgres cannot grant itself a grant option; the service_role grants of these entries come # out identical from the extension (rehearsal of 2026-10-26); # - 1 « ACL pg_catalog » pg_reload_conf, 1 « ACL extensions » pg_stat_statements_reset: owned by # supabase_admin, postgres may not grant on them; # - 1 « TABLE DATA vault secrets »: postgres may not write vault.secrets; nothing is lost only # because step 2 read 0 rows. With rows there, this procedure does not apply. docker exec -i faunosteo_dbsandbox_db pg_restore --list < "$B/dev-before-v1-1.dump" > "$B/full.list"; echo "list exit $?" # 0 grep -E '^[0-9]+; [0-9]+ [0-9]+ (DEFAULT ACL [a-z_]+ DEFAULT PRIVILEGES FOR (SEQUENCES|FUNCTIONS|TABLES) (supabase_admin|supabase_auth_admin)|ACL pg_catalog FUNCTION pg_reload_conf\(\) supabase_admin|ACL extensions FUNCTION pg_stat_statements_reset\(.*\) supabase_admin|ACL vault (FUNCTION|TABLE) .* supabase_admin|TABLE DATA vault secrets supabase_admin)$' \ "$B/full.list" > "$B/excluded.list" cut -d' ' -f4-5 "$B/excluded.list" | sort | uniq -c # exactly: D « DEFAULT ACL », 1 « ACL extensions », 1 « ACL pg_catalog », 5 « ACL vault », 1 « TABLE DATA »; # any other count = STOP (never widen the pattern to make it fit) grep -vxFf "$B/excluded.list" "$B/full.list" > "$B/restore.list" wc -l < "$B/full.list"; wc -l < "$B/restore.list" # the second = the first minus D + 8 docker cp "$B/restore.list" faunosteo_dbsandbox_db:/tmp/restore.list # names only, no data; gone with the sandbox 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 --use-list=/tmp/restore.list --single-transaction --exit-on-error' \ < "$B/dev-before-v1-1.dump" 2> "$B/restore-check.log"; echo "pg_restore exit $?" wc -c < "$B/restore-check.log" # 0: the log, rewritten by this run, holds no message # exit 0 and an empty log, else STOP: the single transaction rolled back, the scratch database is # empty; keep the log (a COPY error can quote a row: report only its ERROR and Command was lines), # drop the database (last line), report boxsql restore_check_v1_1 < "$B/counts.sql" > "$B/counts-restored.txt" diff "$B/counts-before.txt" "$B/counts-restored.txt" && echo "rows identical" # the 28 lines boxsql restore_check_v1_1 < "$B/privs.sql" > "$B/privs-restored.txt" diff "$B/privs-before.txt" "$B/privs-restored.txt" && echo "privileges identical" # the 15 lines 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; 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 on the sandbox with fictitious data, never with DEV data (2026-10-26, a 156 MB dump of the sandbox's `postgres` database at M3, 2 144 accounts, vault empty; D = 18 there, the sandbox has no `supabase_functions` schema). Four variants, exit status read from the shell: - `--no-owner` alone (the earlier procedure): exit 1, 26 errors, the 26 entries above (18 default privileges, 5 vault ACL, 2 ACL on supabase_admin functions, the vault.secrets COPY); rows identical; - `--no-acl`: exit 1 (the vault.secrets COPY), and every grant of the application schemas lost: rejected, it removes what the check must prove; - `--exit-on-error` on the whole list: exit 1 at the vault.secrets COPY, before the policies: rejected; - the filtered list with `--single-transaction --exit-on-error`: exit 0, empty log, the 28 lines and the 15 privilege lines identical. Retained. First run on the real DEV dump (2026-10-27): the 29 expected entries were left out (D = 21), and the restore stopped with exit 1 on `GRANT USAGE ON SCHEMA supabase_functions TO postgres`: role `supabase_functions_admin` missing from the sandbox (DEV: LOGIN, CREATEROLE, `search_path=supabase_functions`, owns the `supabase_functions` objects). With the NOLOGIN role above and nothing else changed: exit 0, empty log, the 28 and 15 lines identical, schema `supabase_functions` restored with its 2 tables. The DEV role's login, CREATEROLE and password are not copied: no privilege is exercised by a `--no-owner` replay. A table whose stored ACL is the explicit owner-only one comes back with no ACL, the same privileges (pg_dump leaves out an ACL equal to the default): `privs.sql` therefore compares effective ACLs (`acldefault`). DEV differs from the sandbox (read-only check, 2026-10-26): D = 21, the three more rows being the defaults of its `supabase_functions` schema, so 29 entries left out; its other own objects (`supabase_functions`, `_realtime`) grant `postgres` no grant option. An entry that would still fail on the DEV dump stops the single transaction: exit status not 0, nothing kept, STOP. 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), nor the Storage file bytes. It holds the vault rows, but a restore as `postgres` cannot reload them (left out of step 3b; it only proves anything because DEV has none, step 2, and says nothing of a restore with vault rows); - 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 # 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; echo "db:test exit $?" # pgTAP 001-014, 921 assertions, exit 0 (see its effects and the 2026-10-27 run 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 ``` 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 and the worker stopped (010 leases the queue rows it finds until its rollback). The files share the stack with the data it already holds: 007 and 010 count only their own keys, and 010 first leases the base's own queued work (due purge entries, avatar jobs, uploads begun more than 24 h ago) inside its transaction. Assumptions that stay: the avatars bucket far below its 10 GiB ceiling; fewer than about 90 quarantine leftovers of the base (the sweep returns at most 100, oldest first); the official equine sheet still at its seeded single draft (007 checks the seed as delivered). - First run on DEV after M1 to M3 (2026-10-27, suites at `6c36e2f`): exit 1, 919 assertions planned, 915 run, 914 passed. 007 stopped at its storage insert (the drawing was already uploaded and confirmed on DEV: duplicate key, 4 assertions never run); 010 failed « nothing is due before its grace elapsed » (13 due purge entries of DEV counted). 012 to 014 (V1-1) passed; data, privileges and `pgtap` (absent) identical before and after. Both files were fixed on the branch (007: 20 assertions, 010: 141) and validated on the sandbox, clean and with those conditions reproduced (scenarios and mutations in the journal of 2026-10-27). DEV is not validated by `db:test` until a run there passes. - `pnpm e2e:avatar`: not part of this procedure. Since 2026-11-01 it runs on the sandbox only (owner decision; the DEV script `scripts/avatar-e2e.sh` is removed). Its DEV run, as recorded on 2026-10-26, wrote on DEV beyond its own fixture: it creates a temporary confirmed account `e2e-avatar-