Pocketbase

---
name: PocketBase
description: Build backends with PocketBase collections, auth, and realtime.
metadata: {"clawdbot":{"emoji":"📦","requires":{"bins":["pocketbase"]},"os":["linux","darwin","win32"]}}
---

## SDK Basics
- Import from `pocketbase` not `pocketbase/dist` — the dist path is internal and breaks on updates
- Always check `pb.authStore.isValid` before using `pb.authStore.model` — expired tokens return stale data without error
- After login, token is auto-attached to requests — no need to manually set Authorization headers

## Fetching Records
- Use `expand` parameter to load relations: `pb.collection('posts').getList(1, 20, { expand: 'author,comments' })`
- Expanded records appear in `record.expand.fieldName` — not directly on the record object
- Filter syntax is SQL-like but uses single quotes: `filter: "status = 'active' && created >= '2024-01-01'"`
- Combine conditions with `&&` and `||`, not `AND`/`OR` — SQL keywords don't work

## Authentication
- Users collection is `users` (lowercase) — `_users` or `Users` returns empty results
- `authWithPassword(email, password)` returns the full user record plus token
- OAuth flow: `authWithOAuth2({ provider: 'google' })` opens popup automatically in browser
- Logout requires both `pb.authStore.clear()` and invalidating server-side if using tokens elsewhere

## Realtime
- Subscribe with `pb.collection('posts').subscribe('*', callback)` — the `'*'` means all record changes
- Callback receives `{ action: 'create'|'update'|'delete', record }` — check action before processing
- Always unsubscribe on cleanup: `pb.collection('posts').unsubscribe()` — orphan subscriptions leak memory

## File Uploads
- Files require FormData, not JSON: `formData.append('document', file)` then pass to `create()`
- Get file URL with `pb.files.getURL(record, record.filename)` — don't construct URLs manually
- Multiple files to same field: append with same key multiple times

## Collection Rules
- Empty rule = blocked for everyone, `""` (empty string) rule = open to everyone — counterintuitive
- Use `@request.auth.id` to reference logged-in user, `@request.data` for submitted data
- Example restrict to owner: `@request.auth.id = user.id` in View/Update/Delete rules

## Hooks (pb_hooks/)
- JavaScript hooks go in `pb_hooks/*.pb.js` — the `.pb.js` extension is required
- Hooks run synchronously and block the request — keep them fast or use routines
- Access app with `$app`, event data with `e` — common: `e.record`, `e.httpContext`

## Admin API
- Admin endpoints need superuser auth, not regular user tokens
- Create admin token: `pb.admins.authWithPassword(email, password)`
- Admin operations use `pb.admins` or `pb.collections`, not `pb.collection()`