PocketBase Platform
PocketBase is a single-binary backend: SQLite database, REST + realtime API, auth, file storage, and admin UI.
Official docs: https://pocketbase.io/docs/
Which skill to use
| Task |
Skill |
| Design collections, rules, auth |
pocketbase (this skill) |
| Browser/Node app calling PocketBase over HTTP |
pocketbase-js-sdk |
Server-side hooks in pb_hooks/*.pb.js |
pocketbase-jsvm |
| Superuser admin UI extensions (PB ≥0.37) |
pocketbase-admin-plugins |
Core concepts
Collections and records
- Collections are tables; records are rows.
- Field types: text, number, bool, email, url, date, select, relation, file, json, etc.
- Relations link collections; use expand in API queries to include related records.
- Indexes improve filter/sort performance on large collections.
Auth
- Auth collections (e.g.
users) support registration, login, OAuth2, OTP.
- Superusers are admin accounts (
_superusers); regular auth records live in auth collections.
- JWT tokens identify authenticated requests; API rules reference
@request.auth.
API rules (security)
Rules control list/view/create/update/delete per collection. Write rules as filter expressions:
@request.auth.id != "" && @request.auth.id = user.id
- Prefer API rules over middleware for access control.
@request.auth — current authenticated record (or null).@collection.* — cross-collection lookups in rules.- Empty rule = locked;
@request.auth.id != "" = any authenticated user.
Migrations
Two migration systems:
| Type |
Location |
Language |
Use for |
| Go migrations |
pb_migrations/ |
Go (compiled into binary) |
Core schema shipped with PocketBase |
| JS migrations |
pb_migrations/*.js |
JSVM (sync) |
User/instance schema changes via FTP |
JS migrations run in the JSVM — see pocketbase-jsvm for constraints.
Realtime
- Clients subscribe to collection or record changes via the SDK.
- Subscription access is governed by the same API rules as list/view.
Files
- File fields store uploads in
pb_data/storage/.
- Public static assets can be served from
pb_public/.
Architecture decisions
Prefer direct client access
PocketBase is designed for client → PocketBase communication with API rules enforcing security.
Avoid wrapping PocketBase in SvelteKit/Next.js server routes unless necessary:
- Adds double network hops and latency
- Complicates JWT/cookie state
- Concentrates traffic on one IP (rate limits)
Prefer JS hooks for privileged server logic
When clients need elevated operations (payments, external APIs, admin-only mutations):
- Add a custom route or record hook in
pb_hooks/ (pocketbase-jsvm)
- Call it from the client via
pb.send() (pocketbase-js-sdk)
Do not instantiate the JS SDK inside hooks to call the same server — use $app APIs directly.
When server-side SDK access is OK
- CLI tools, admin scripts, mothership internal services
- Aggregations that cannot be expressed in rules or hooks
- Integrations that must stay off the client
PocketHost context
This monorepo is the PocketHost platform. For hosting-specific details (FTP dirs, instance URLs, limits), see pockethost-hosting.md.
Official reference links
1---2name: pocketbase3description: Models PocketBase backends: collections, relations, auth, API rules, migrations, and architecture. Use when designing schema, security rules, data modeling, choosing between hooks vs client access, or explaining PocketBase platform concepts — not for npm JS SDK code or pb_hooks.4---56# PocketBase Platform78PocketBase is a single-binary backend: SQLite database, REST + realtime API, auth, file storage, and admin UI.910Official docs: https://pocketbase.io/docs/1112## Which skill to use1314| Task | Skill |15|------|-------|16| Design collections, rules, auth | **pocketbase** (this skill) |17| Browser/Node app calling PocketBase over HTTP | **pocketbase-js-sdk** |18| Server-side hooks in `pb_hooks/*.pb.js` | **pocketbase-jsvm** |19| Superuser admin UI extensions (PB ≥0.37) | **pocketbase-admin-plugins** |2021## Core concepts2223### Collections and records2425- **Collections** are tables; **records** are rows.26- Field types: text, number, bool, email, url, date, select, relation, file, json, etc.27- **Relations** link collections; use expand in API queries to include related records.28- **Indexes** improve filter/sort performance on large collections.2930### Auth3132- **Auth collections** (e.g. `users`) support registration, login, OAuth2, OTP.33- **Superusers** are admin accounts (`_superusers`); regular auth records live in auth collections.34- JWT tokens identify authenticated requests; API rules reference `@request.auth`.3536### API rules (security)3738Rules control list/view/create/update/delete per collection. Write rules as filter expressions:3940```41@request.auth.id != "" && @request.auth.id = user.id42```4344- Prefer **API rules** over middleware for access control.45- `@request.auth` — current authenticated record (or null).46- `@collection.*` — cross-collection lookups in rules.47- Empty rule = locked; `@request.auth.id != ""` = any authenticated user.4849### Migrations5051Two migration systems:5253| Type | Location | Language | Use for |54|------|----------|----------|---------|55| Go migrations | `pb_migrations/` | Go (compiled into binary) | Core schema shipped with PocketBase |56| JS migrations | `pb_migrations/*.js` | JSVM (sync) | User/instance schema changes via FTP |5758JS migrations run in the JSVM — see **pocketbase-jsvm** for constraints.5960### Realtime6162- Clients subscribe to collection or record changes via the SDK.63- Subscription access is governed by the same API rules as list/view.6465### Files6667- File fields store uploads in `pb_data/storage/`.68- Public static assets can be served from `pb_public/`.6970## Architecture decisions7172### Prefer direct client access7374PocketBase is designed for **client → PocketBase** communication with API rules enforcing security.7576Avoid wrapping PocketBase in SvelteKit/Next.js server routes unless necessary:7778- Adds double network hops and latency79- Complicates JWT/cookie state80- Concentrates traffic on one IP (rate limits)8182### Prefer JS hooks for privileged server logic8384When clients need elevated operations (payments, external APIs, admin-only mutations):85861. Add a custom route or record hook in `pb_hooks/` (**pocketbase-jsvm**)872. Call it from the client via `pb.send()` (**pocketbase-js-sdk**)8889Do **not** instantiate the JS SDK inside hooks to call the same server — use `$app` APIs directly.9091### When server-side SDK access is OK9293- CLI tools, admin scripts, mothership internal services94- Aggregations that cannot be expressed in rules or hooks95- Integrations that must stay off the client9697## PocketHost context9899This monorepo is the PocketHost platform. For hosting-specific details (FTP dirs, instance URLs, limits), see [pockethost-hosting.md](pockethost-hosting.md).100101## Official reference links102103- Collections & fields: https://pocketbase.io/docs/collections/104- API rules: https://pocketbase.io/docs/api-rules-and-filters/105- Authentication: https://pocketbase.io/docs/authentication/106- Migrations: https://pocketbase.io/docs/migrations/107- Files: https://pocketbase.io/docs/files-handling/
pockethost