| name | schema-change |
| description | Coordinate a PocketBase schema change across both AllerLeih repos so nothing drifts — the backend migration (delegated to new-migration), the frontend TypeScript types, the data-model docs, and a public-view leak check. Use whenever the user adds/changes/removes a field on a collection, adds a collection, or changes a `*_public` view — anything that touches the schema. The point is to stop the frontend types, docs, and the privacy views from falling out of sync with the database. |
schema-change
The schema lives in the backend repo (migrations + views), but its shadow is everywhere: frontend
types, docs, seed factories, search. A change that only lands the migration leaves the frontend
type-checking against a stale shape and — the dangerous case — can quietly expose a new field through
a public view. This skill drives the change end-to-end and keeps the pieces in lockstep.
Work through these in order; skip a step only when you can say why it doesn't apply.
1. Backend migration — delegate to new-migration
The migration itself is the backend repo's job. Invoke the new-migration skill in
allerleih-backend (.claude/skills/new-migration/) — it has the templates for adding a field,
changing access rules, and updating views, plus the down() revert and the npm test check (fresh
DB, all migrations + hooks). Don't hand-roll the migration here.
Two things to decide during the migration, because they ripple into every later step:
- Is the field user-settable? If not (a server/hook-maintained field like the legal-consent
fields on
users), stop clients writing it by appending && @request.body.<field>:isset = false
to the collection's existing updateRule — don't replace the list/view rules, add this body-guard
(the pattern in allerleih-backend/pb_migrations/1781900051_added_legal_fields_to_users.js). The
field still goes in the TS type, marked as hook-maintained.
- Should it be visible to unauthenticated/other users? That decides whether any
*_public /
items_searchable view changes — and drives the leak check in step 4.
2. Frontend types — src/lib/types/models.ts
Update the type to match the new shape:
- The full collection interface (e.g.
User, Item) — add/change the field with its TS type;
mark server-only fields optional and note they're hook-maintained.
- The
*_public view interface (e.g. UserPublic, ItemPublic) — add the field only if it
appears in that view's SQL SELECT. These interfaces must match the view column-for-column;
a field in the interface that the view doesn't select is a lie the compiler can't catch, and a
selected column missing from the interface makes frontend code access undefined.
3. Docs — docs/data-model.md
- Add the field to the collection's block in the Mermaid ER diagram (type + a short comment,
e.g.
string tosAcceptedVersion "legal-consent cache — server-only") — this is the main doc touch
for most fields.
- If the field changes a view's exposure or has special handling, add a note to the views section
— which currently documents the
items_public / items_searchable columns + masking. There is no
users_public SQL block there, so a private users field needs only the ER-diagram entry. Docs
publish to GitHub Pages and are part of the "keep in sync" contract.
4. Public-view leak check (the security-critical step)
A new field on users or items is not in the *_public / items_searchable views unless a
migration adds it — and it usually shouldn't be. Confirm, don't assume:
- Inspect what each view actually selects (in a
pb_migrations/* viewQuery, or live:
app.findCollectionByNameOrId('users_public').viewQuery).
- These are deliberately excluded and must stay out:
users.email, users.password,
users.inviteCode, raw coordinates (geolocation lives in an owner-only collection), the raw
owner relation (exposed only as userId), and any trust-graph data (trust lives in the
separate trusts join collection — its edges must never be joined into a view). Note the two
views protect differently:
users_public works by column omission (a field that isn't in its SELECT is simply absent),
while items_public keeps the row but NULL-masks content fields (name, image,
description, …) for trusteesOnly/group-shared items — check the mechanism for the view you touched.
- If the new field genuinely should be public, add it to the view's
SELECT in the migration and
to the matching *Public interface (step 2) and the docs (step 3). If it shouldn't, verify no
SELECT *-style query sweeps it in. When unsure whether something leaks, get a project-aware
review (the sveltekit-pb-reviewer agent, or /security-review).
5. The usual ripple — touch what applies
- Seed factories
scripts/seed/lib.js — set the field in createUser/createItem/… (required
fields must be set; optional ones get a sensible test default). See the seed-scenario skill.
- Search
src/routes/search/searchFilter.ts — if the field is searchable/filterable, add it to
buildSearchFilter() / buildItemFilter() (these are typed against ItemPublic).
- Texts
src/lib/texts.ts — German label for any user-visible field. Never inline strings.
(Item categories are separate domain data in src/lib/categories.ts; changing them follows
docs/data-model.md → "Item categories".)
- Create/edit route (e.g.
src/routes/items/[id]/) — add the field to the form + the action's
validate/save logic if it's user-editable.
- Lending requirements — if the field is a borrower gate, register it in both
src/lib/server/lendingRequirements.ts and the backend pb_hooks/lending_requirements.pb.js.
Verify
Run npm test in the backend (migrations + hooks apply on a fresh DB) and npm run check in the
frontend (the types must compile against the new shape). Add/extend tests for any new server logic
(the write-tests skill). For a visibility-affecting change, confirm the leak check with a quick
read of the view SELECT — a wrong view is a privacy bug, not just a type error.
