VRIL-LABS PocketBase Best Practices
42 rules across 8 categories for PocketBase v0.36+, prioritized by impact.
When to Apply
- Designing collections and schema structures
- Implementing API rules for access control
- Setting up authentication (password, OAuth2, MFA)
- Using the PocketBase JavaScript SDK
- Optimizing queries with filtering, sorting, and expansion
- Implementing realtime subscriptions
- Handling file uploads and storage
- Deploying PocketBase to production
Categories by Priority
| Priority | Category | Impact | Rules |
|---|---|---|---|
| 1 | Collection Design | CRITICAL | coll-field-types, coll-auth-vs-base, coll-relations, coll-indexes, coll-view-collections, coll-geopoint |
| 2 | API Rules & Security | CRITICAL | rules-basics, rules-filter-syntax, rules-request-context, rules-cross-collection, rules-locked-vs-open |
| 3 | Authentication | CRITICAL | auth-password, auth-oauth2, auth-token-management, auth-mfa, auth-impersonation |
| 4 | SDK Usage | HIGH | sdk-initialization, sdk-auth-store, sdk-error-handling, sdk-auto-cancellation, sdk-filter-binding, sdk-field-modifiers, sdk-send-hooks |
| 5 | Query Performance | HIGH | query-pagination, query-expand, query-field-selection, query-batch-operations, query-n-plus-one, query-first-item, query-back-relations |
| 6 | Realtime | MEDIUM | realtime-subscribe, realtime-events, realtime-auth, realtime-reconnection |
| 7 | File Handling | MEDIUM | file-upload, file-serving, file-validation |
| 8 | Production & Deployment | MEDIUM | deploy-backup, deploy-configuration, deploy-reverse-proxy, deploy-sqlite-considerations, deploy-rate-limiting |
Quick Reference
Collection Design (CRITICAL)
- coll-field-types: Use appropriate field types (json for objects, select for enums)
- coll-auth-vs-base: Extend auth collection for users, base for non-auth data
- coll-relations: Use relation fields, not manual ID strings
- coll-indexes: Create indexes on frequently filtered/sorted fields
- coll-view-collections: Use views for complex aggregations
- coll-geopoint: Store coordinates as json field with lat/lng
API Rules (CRITICAL)
- rules-basics: Always set API rules; empty = public access
- rules-filter-syntax: Use @request.auth, @collection, @now in rules
- rules-request-context: Access request data via @request.body, @request.query
- rules-cross-collection: Use @collection.name.field for cross-collection checks
- rules-locked-vs-open: Start locked, open selectively
Authentication (CRITICAL)
- auth-password: Use authWithPassword for email/password login
- auth-oauth2: Configure OAuth2 providers via Admin UI
- auth-token-management: Store tokens securely, refresh before expiry
- auth-mfa: Enable MFA for sensitive applications
- auth-impersonation: Use impersonation for admin actions on behalf of users
SDK Usage (HIGH)
- sdk-initialization: Initialize client once, reuse instance
- sdk-auth-store: Use AsyncAuthStore for React Native/SSR
- sdk-error-handling: Catch ClientResponseError, check status codes
- sdk-auto-cancellation: Disable auto-cancel for concurrent requests
- sdk-filter-binding: Use filter binding to prevent injection
Query Performance (HIGH)
- query-expand: Expand relations to avoid N+1 queries
- query-field-selection: Select only needed fields
- query-pagination: Use cursor pagination for large datasets
- query-batch-operations: Batch creates/updates when possible
Realtime (MEDIUM)
- realtime-subscribe: Subscribe to specific records or collections
- realtime-events: Handle create, update, delete events separately
- realtime-auth: Realtime respects API rules automatically
- realtime-reconnection: Implement reconnection logic
File Handling (MEDIUM)
- file-upload: Use FormData for uploads, set proper content types
- file-serving: Use pb.files.getURL() for file URLs
- file-validation: Validate file types and sizes server-side
Deployment (MEDIUM)
- deploy-backup: Schedule regular backups of pb_data
- deploy-configuration: Use environment variables for config
- deploy-reverse-proxy: Put behind nginx/caddy in production
- deploy-sqlite-considerations: Optimize SQLite for production workloads
Detailed Rules
For complete rule documentation with code examples, see AGENTS.md.