Files
faunosteo/docs/development/SUPABASE.md
T
bchanot e215e9b2cb docs(docs): V1-1.6 as built, D11 drawer only, closure inventory, DEV steps
Contract §11.8 and §15; D11 and U3 decided, D12 open; SUPABASE.md §3.3 gains
the rehearsed restore check and the owner's browser acceptance on DEV; browser,
test and frontend docs, design README, CLAUDE.md map.
2026-10-26 17:24:19 +01:00

544 lines
34 KiB
Markdown

# 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, <timestamp>_<name>.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`
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 <cmd>`), 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
<args>`): 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_<service>_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 (`<sha256>.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` runs the
whole behaviour against the local stack (upload, rerun, anon and wrong key,
refused destinations, unreachable port). 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 # starts the container on supabase_network_faunosteo, runs tests/e2e, stops it
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=<the service key of pnpm supabase status>`, `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` or any destructive command. The procedure below takes DEV from its
current state (every migration up to `20261013100000` applied, profiles and
fictitious accounts present) to M3 in one run. Every step was rehearsed on the
isolated stack in upgrade mode (`pnpm db:sandbox up upgrade 20261025100000`
for the one-run path, `... 20261025100000 20261025110000` for M1 first, then
M2 and M3), with the sandbox container name in place of
`supabase_db_faunosteo`; on 2026-10-26 the history, dump and count commands
were run again against an M3 sandbox. Nothing below prints a secret: the
database password stays in the container's own environment.
```bash
# 0. Target: the local CLI stack of this project, nothing remote.
pnpm supabase status # API on the DEV origin, DB on port 54322; no error
test ! -f supabase/.temp/project-ref && echo "no linked project" # nothing remote is linked
docker ps --filter name=supabase_db_faunosteo --format '{{.Names}} {{.Status}}'
# 1. History: only the V1-1 migrations may be pending.
pnpm supabase migration list --local # every row has local = remote, except the V1-1 ones (remote empty):
# 20261025100000 (M1), 20261025110000 (M2), 20261026100000 (M3)
# on a checkout from b54c8e5 on (M1 alone: 08abe42; M1 + M2: 2dc04bc)
pnpm db:types:check # the diff must be exactly the objects of those migrations (M1: workspaces,
# workspace_members, workspace_kind, workspace_member_role; M2: clients,
# client_kind, create_client, update_client, set_client_archived,
# search_clients; M3: animals, animal_client_relations, animal_sex,
# animal_relation_role, create_animal, update_animal, set_animal_archived,
# create_animal_client_relation, end_/update_/void_animal_client_relation,
# search_animals, list_client_animals, client_archive_preview):
# anything else = drift, STOP
# 2. Existing accounts (the backfill creates one workspace per profile).
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A \
-c "select (select count(*) from auth.users) || '"'"' users, '"'"' || (select count(*) from public.profiles) || '"'"' profiles'"'"'"'
# users = profiles expected; note the profile count N
# 3. Backup outside Git (includes auth.users and the migration history), then check it.
mkdir -p ~/faunosteo-backups && chmod 700 ~/faunosteo-backups
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_dump -h 127.0.0.1 -U postgres -d postgres -Fc' \
> ~/faunosteo-backups/dev-before-v1-1.dump && chmod 600 ~/faunosteo-backups/dev-before-v1-1.dump
docker exec -i supabase_db_faunosteo pg_restore --list < ~/faunosteo-backups/dev-before-v1-1.dump \
| grep -E "TABLE DATA (auth users|public profiles|supabase_migrations schema_migrations)" # three lines expected
# 3b. The dump restores: into a scratch database of the same server, counts compared, then dropped.
# The scratch name is the only database created or dropped here; never type another one.
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" createdb -h 127.0.0.1 -U postgres restore_check_v1_1'
docker exec -i supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_restore -h 127.0.0.1 -U postgres \
-d restore_check_v1_1 --no-owner' < ~/faunosteo-backups/dev-before-v1-1.dump 2> ~/faunosteo-backups/restore-check.log
grep -c "error:" ~/faunosteo-backups/restore-check.log # only privilege errors on Supabase-managed objects (see below)
for db in postgres restore_check_v1_1; do
docker exec supabase_db_faunosteo sh -c "PGPASSWORD=\"\$POSTGRES_PASSWORD\" psql -h 127.0.0.1 -U postgres -d $db -t -A -c \
\"select '$db: ' || (select count(*) from auth.users) || ' users, ' || (select count(*) from public.profiles)
|| ' profiles, ' || (select count(*) from supabase_migrations.schema_migrations) || ' migrations'\""
done # the two lines must give the same counts
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" dropdb -h 127.0.0.1 -U postgres restore_check_v1_1'
# 4. Apply without reset (M1's backfill runs inside the migration). `migration up` applies every
# pending migration of the checkout, in order (a shorter path: run it from the checkouts named in step 1).
pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql", then
# ..._clients.sql, then 20261026100000_animals_relations.sql
```
After applying:
```bash
pnpm supabase migration list --local # each applied migration now has its remote column
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A -c "
select (select count(*) from public.profiles) || '"'"' profiles, '"'"'
|| (select count(*) from public.workspaces) || '"'"' workspaces, '"'"'
|| (select count(*) from public.workspace_members) || '"'"' members, '"'"'
|| (select count(*) from public.profiles p where (select count(*) from public.workspaces w
where w.personal_user_id = p.id) <> 1) || '"'"' profiles without exactly one workspace, '"'"'
|| (select count(*) from public.species where active) || '"'"' active species, '"'"'
|| (select count(*) from public.animals) || '"'"' animals'"'"'"'
# expected: N profiles, N workspaces, N members, 0 profiles without exactly one workspace,
# 10 active species, 0 animals
pnpm db:test # pgTAP 001-014: the privilege census (001: grants of every role,
# definer functions, RLS on every table), the policies and the
# RPC refusals; every file runs in begin ... rollback: rows
# unchanged (checked on the sandbox)
pnpm db:types:check # no diff
pnpm e2e:avatar # avatar flow and worker on the DEV stack (fictitious seed accounts)
```
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
anything beyond the objects listed in step 1; the dump check misses a line; the
restore check gives other counts or an error that is not one of the expected
privilege errors; `migration up`
applies anything else than the expected V1-1 migrations; any count after it differs from
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
data): users, profiles, workspaces, animals and the migration history came back
with the same counts; `pg_restore --no-owner` printed 26 errors, all privilege
refusals on Supabase-managed objects (18 « permission denied to change default
privileges », 5 « grant options cannot be granted back to your own grantor »,
`vault.secrets`, `pg_stat_statements_reset`, `pg_reload_conf`), none on a
table of the application. Storage file bytes
(avatars) live in the storage container's volume, not in the dump; M1 does not
touch them. No down migration exists: going back means restoring the step 3
dump, an owner procedure of its own that is not rehearsed here.
### 3.4 Clients (V1-1.2, migration M2)
Contract: `V1-1_OWNERS_ANIMALS.md` §5.1, §8.2, §9, §10. `public.clients`
holds the clients of a workspace; the browser reads them through RLS (members
of the workspace, active profile, confirmed email) and writes them only
through `create_client`, `update_client` and `set_client_archived` (security
definer); `search_clients` (invoker, POST) searches one workspace. Refusals
are closed codes: 42501 `not_found` (also for a foreign id), P0001
`invalid_input`, `archived`, `conflict`, `request_conflict`, `limit_reached`,
`rate_limited`. Writes are counted per workspace in
`private.workspace_write_budgets` (UTC hour and day). M2 creates the
extension `unaccent` in `extensions` (available on the CLI image and in
PGlite 0.3.16, loaded by the harness). An account whose workspace holds a
client can no longer be deleted (D9a); in DEV, delete its clients first from
a privileged SQL session, or reset.
### 3.5 Animals and relations (V1-1.4, migration M3)
Contract: `V1-1_OWNERS_ANIMALS.md` §5.2 to §5.4, §8.3, §9, §10. M3 adds the
species rows (`asinine` to `leporine` and `other`; `equine` unchanged; a row
never means a sheet exists), `public.animals` and
`public.animal_client_relations`. The browser reads them through RLS and
writes them only through `create_animal` (with an optional first relation),
`update_animal`, `set_animal_archived`, `create_animal_client_relation`,
`end_animal_client_relation`, `update_animal_client_relation` and
`void_animal_client_relation` (security definer); `search_animals`,
`list_client_animals` and `client_archive_preview` read (invoker, POST), and
`search_clients` now returns `current_animal_count`. A relation joins an
animal and a client of one workspace (composite keys); it is current, ended
(`ended_at`, `ended_on` when known) or voided (entered by mistake, kept,
frozen, shown nowhere); it is never deleted. New refusal codes:
`duplicate_relation`, `already_ended`. Writes share the workspace budget of
M2. An account whose workspace holds an animal can no longer be deleted
either (D9a): in DEV, delete its relations, animals and clients first from a
privileged SQL session, in that order.
The browser reaches these tables through `packages/supabase/src/{workspaces,clients,species,records}.ts`
since V1-1.5 (contract §11.7) and `{animals,relations}.ts` since V1-1.6
(§11.8). The client and animal screens run against DEV only once the owner has
applied M1 to M3 with §3.3; until then they are developed and tested on the
isolated stack, and no DEV acceptance is recorded.
#### Browser acceptance on DEV (owner, after §3.3)
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
`pnpm dev` (DEV origin), with fictitious accounts only (never a real profile
changed for a test). Each line is done in French and in English:
1. sign in; Clients and Animaux open from the sidebar and the drawer;
2. journey 1: new client, « Ajouter un premier animal » from its page, owner
chosen, back on the client page with the animal;
3. journey 2: find the animal from the phone, open it, call the owner through
the `tel:` link;
4. journey 3: add the new owner, end the former owner's relation with a date,
the former owner's page shows « Ancien propriétaire »;
5. journey 4: an animal with no client shows « Propriétaire non renseigné »;
6. journey 5: archive a client (the confirmation lists its sole-owned
animals), find it under « Afficher les archivés », restore it;
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
both pages;
9. a second account sees none of it (list, search, a copied record URL).
Results are recorded per line, device and language; a line not done is
reported as not done.
## 4. Writing a migration
1. `pnpm supabase migration new <name>` creates `supabase/migrations/<timestamp>_<name>.sql`.
2. A migration that adds a table adds, in the same file: RLS enable, explicit
`revoke all ... from public, anon, authenticated` (and `service_role` for
V1-1 record tables, contract N7) then the exact grants,
separate SELECT / INSERT / UPDATE / DELETE policies, indexes, comments.
3. Add or extend a pgTAP file under `supabase/tests/`: the allowed path and
every denied path (other user, anon, direct write bypassing an RPC). Scope
counts to the fixture ids: on the real stack the seed accounts exist, in
PGlite they do not.
4. `pnpm --filter @faunosteo/supabase test:run` (PGlite, seconds), then
`pnpm db:reset && pnpm db:test` on the real stack.
5. `pnpm db:types` and commit `packages/supabase/src/database.types.ts`.
6. Never edit an applied migration. Corrections are new migrations.
Rules enforced by the schema-types test for every future `public` table:
RLS enabled, no `using (true)` / `with check (true)` policy for `anon` or
`authenticated`.
## 5. Tests
Two runners, one SQL source of truth (`supabase/tests/*.sql`, pgTAP):
| Command | Engine | Needs Docker | What runs |
| -------------------------------------------- | ------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pnpm --filter @faunosteo/supabase test:run` | PGlite (PostgreSQL 17 in WASM) | no | shim of the Supabase base schema (auth + storage tables) + all migrations + `seed/**` + every pgTAP file; schema ↔ types check; client factory; publish gate |
| `pnpm db:test` | `supabase test db` (pg_prove in the local stack) | yes | the same pgTAP files against the real Supabase image |
`pnpm test:run` at the root runs the PGlite suite together with the app
suite. The shim (`packages/supabase/tests/db/supabase-shim.sql`) recreates
the API roles, `auth.users`, `auth.uid()` and the permissive default
privileges of Supabase so that a forgotten `revoke` fails a test.
Two parity traps met so far: counts must be scoped to fixture ids (the real
stack carries `seed.sql` rows), and `order by` on text must pin
`collate "C"` (the real image sorts with a locale collation, PGlite with C).
### 5.1 Isolated stack (`pnpm db:sandbox`)
A throwaway Supabase stack for migration steps, so the DEV stack is never
reset or migrated by a test (owner rule since V1-1.1). `scripts/db-sandbox.sh`
starts the images the CLI stack uses (PostgreSQL 17.11.0.004, GoTrue v2.197.0,
Storage v1.79.36, PostgREST v16.4, Mailpit v1.31.3, pinned in the script) on
the network `faunosteo_dbsandbox_net`, containers `faunosteo_dbsandbox_*`,
ports on 127.0.0.1 only and distinct from DEV (db 57432, auth 57999, rest
57300, storage 57500, mail 57025). Nothing is mounted and the images declare
no volume, so `down` removes the containers and the network by their literal
names and can never reach a `supabase_*_faunosteo` volume. The password, JWT
secret and keys are generated at each `up` into a 600 file under
`~/.cache/faunosteo-db-sandbox` (`FAUNOSTEO_SANDBOX_DIR`, refused inside the
repository), with 600 env files that hand them to the containers; deleted by
`down`, never printed, never on a command line (the CLI and psql read
`PGPASSWORD` from the environment). An incomplete secrets file stops the
script before any CLI call, and a wrong `up` mode or version (fourteen
digits) is refused before any container or secret exists. Works with rootless
Docker.
| Command | What it does |
|---|---|
| `pnpm db:sandbox up fresh` | every migration through `supabase migration up --db-url`, then the seeds of `config.toml` (as `db reset`) |
| `pnpm db:sandbox up upgrade <version> [<then>]` | the migrations before `<version>`, the seeds, two GoTrue accounts (confirmed, unconfirmed), then `migration up`: the path a DEV database takes; with `<then>`, the migrations before `<then>` first (the workspaces count is printed), then the rest |
| `pnpm db:sandbox test-db` | `supabase test db --db-url`: the pgTAP files on the real image (rows unchanged afterwards) |
| `pnpm db:sandbox types [--check]` | `supabase gen types --db-url ... --schema public` through Prettier, written or diffed with the committed file |
| `pnpm db:sandbox test` | `packages/supabase/tests/sandbox/*.sandbox.ts`: real GoTrue and PostgREST sessions, concurrent SQL sessions |
| `pnpm db:sandbox e2e-shell` (= `pnpm e2e:shell`) | the authenticated `/app` shell in Chromium (`apps/app/e2e/shell`, `docs/development/BROWSER_TESTS.md`): a loopback dev server whose Supabase calls are replayed on the sandbox, fictitious accounts per test |
| `pnpm db:sandbox sql` / `down` | psql as postgres on stdin / remove the stack |
Every CLI call passes `--db-url` with `sslmode=disable` (the sandbox has no
TLS); none can fall back to the local DEV database. Differences from the CLI
stack: no Kong (GoTrue and PostgREST are called directly), no Studio, no
realtime or edge runtime, and the database init keeps only the role
passwords the services use.
How a test impersonates a user (same technique in both runners):
```sql
set local role authenticated;
select set_config('request.jwt.claims', '{"sub":"<user uuid>","role":"authenticated"}', true);
```
## 6. Generated types
```bash
pnpm db:types # regenerate packages/supabase/src/database.types.ts (local stack running)
pnpm db:types:check # CI: fail on any diff
```
The CLI emits unformatted TypeScript; both scripts pipe it through Prettier
(repo config) so the committed file is stable byte for byte. The schema-types
test checks tables, columns, enum labels and RPC argument names against the
migrated schema, so a stale file fails before CI.
## 7. First platform owner in a real environment
The RPCs refuse self-grants and need an existing owner or admin. The first
owner is created once, from a privileged SQL session (service connection,
`psql` on the host), never from the browser:
```sql
select private.assign_platform_role(null, '<auth.users.id of the owner>', 'owner');
```
The call is audited with a null actor. Afterwards every role change goes
through `grant_platform_role` / `revoke_platform_role`.
## 8. Manual validation (Definition of Done: "an authenticated request hits a protected table safely")
```bash
URL=http://127.0.0.1:54321
ANON=<anon key printed by pnpm db:start>
token() { # $1 = email
curl -s -X POST "$URL/auth/v1/token?grant_type=password" \
-H "apikey: $ANON" -H "Content-Type: application/json" \
-d "{\"email\":\"$1\",\"password\":\"LocalDev-only-password-1\"}" | jq -r .access_token
}
ALICE=$(token alice@faunosteo.local); OWNER=$(token owner@faunosteo.local)
ALICE_ID=10000000-0000-0000-0000-00000000000a
# 1. alice reads exactly one profile (hers)
curl -s "$URL/rest/v1/profiles?select=id,display_name" -H "apikey: $ANON" -H "Authorization: Bearer $ALICE"
# 2. anon reads nothing (permission denied)
curl -s "$URL/rest/v1/profiles" -H "apikey: $ANON"
# 3. alice cannot deactivate herself (column privilege) nor self-grant admin
curl -s -X PATCH "$URL/rest/v1/profiles?id=eq.$ALICE_ID" -H "apikey: $ANON" \
-H "Authorization: Bearer $ALICE" -H "Content-Type: application/json" -d '{"active":false}'
curl -s -X POST "$URL/rest/v1/rpc/grant_platform_role" -H "apikey: $ANON" \
-H "Authorization: Bearer $ALICE" -H "Content-Type: application/json" \
-d "{\"target_user_id\":\"$ALICE_ID\",\"role\":\"admin\"}"
# 4. the owner grants moderator to alice; the grant is audited
curl -s -X POST "$URL/rest/v1/rpc/grant_platform_role" -H "apikey: $ANON" \
-H "Authorization: Bearer $OWNER" -H "Content-Type: application/json" \
-d "{\"target_user_id\":\"$ALICE_ID\",\"role\":\"moderator\"}"
psql postgresql://postgres:postgres@127.0.0.1:54322/postgres \
-c "select actor_user_id, action, target_user_id, metadata from audit.audit_logs order by occurred_at"
```
Expected: 1 → one row; 2 → `42501`; 3 → both `42501`; 4 → a uuid, then two
audit rows (bootstrap with null actor, grant by the owner).
## 9. Wiring the app
Development: `pnpm dev` (`scripts/dev.sh`) sets `VITE_SUPABASE_URL` to the DEV
origin (`http://<FAUNOSTEO_DEV_HOST>:54321`, the LAN address of the machine:
`ENVIRONMENTS.md` §2) and the anon key from `supabase status`; the app is
served on `http://<host>:5173` for every device of the private network.
`pnpm dev:offline` runs the local tool without backend. Docker deployments use
`.env`:
```bash
APP_SUPABASE_URL=<Supabase origin reachable by the browser>
APP_SUPABASE_ANON_KEY=<anon key> # public by design
```
Both empty keeps the app in its local-only mode:
`getSupabaseClient()` returns null, the auth screens show an "unavailable"
notice and `/app` redirects to `/login`. `APP_AUTH_PROVIDERS` /
`VITE_AUTH_PROVIDERS` (`google,apple`) lists the OAuth buttons to show.
Sign-in, sign-up, email confirmation, password recovery, the `/app` shell
and Mon compte are documented in `IDENTITY.md` (routes, session handling,
provider setup, MFA gap, manual validation).
## 10. Self-hosted parity
The local stack runs the same images as a self-hosted deployment
(`supabase/docker` compose), so migrations, policies and tests transfer
unchanged. The self-hosted runbook (VPS sizing, secrets, backups, TLS) is a
separate deliverable once the hosting question (OPEN_QUESTIONS Q2) is
settled; it reuses `pnpm supabase db push --db-url <...>` for migrations.