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.