Skip to Content
MetaGap Analysis

Last Updated: 3/9/2026

PocketBase Documentation Gap Analysis

Overview

This analysis identifies gaps between the PocketBase codebase and existing documentation, with recommendations for improvement.

Analysis Date: 2024 Repository: pocketbase/pocketbase Documentation Source: pocketbase.io/docs Total Existing Articles: 49

Executive Summary

Current Documentation Coverage

The existing documentation covers:

  • ✅ API Endpoints: Comprehensive coverage (Records, Collections, Files, Backups, Health, Logs, Realtime, Settings, Crons)
  • ✅ JavaScript SDK: Good coverage (Overview, Collections, Records, Database, Event Hooks, Migrations, etc.)
  • ✅ Go Framework: Good coverage (Overview, Collections, Records, Database, Event Hooks, Migrations, etc.)
  • ✅ Getting Started: Basic guides (Authentication, Files, Relations, Production)
  • ✅ Core Concepts: Collections, Authentication, Files handling

Key Gaps Identified

  1. Core Package Documentation (HIGH PRIORITY)
  2. Field Types Reference (HIGH PRIORITY)
  3. Tools Package (MEDIUM PRIORITY)
  4. Advanced Use Cases (MEDIUM PRIORITY)
  5. Migration Guides (LOW PRIORITY)

Detailed Gap Analysis

1. Core Package Documentation (HIGH PRIORITY)

Current State

  • Limited documentation on core package internals
  • No comprehensive field types reference
  • Missing validator documentation

Identified Gaps

Field Interface & Types

  • Missing: Comprehensive guide on the Field interface
  • Found in code: core/field.go defines:
    • Field interface with methods: GetId(), SetId(), GetName(), Type(), ColumnType(), PrepareValue(), ValidateValue(), ValidateSettings()
    • 15+ field types: Text, Number, Boolean, Email, URL, Date, Autodate, Select, File, Relation, JSON, Editor, Password, GeoPoint
    • Field modifiers: SetterFinder, GetterFinder, DriverValuer, MultiValuer, RecordInterceptor
    • System field names constants

Recommended Documentation:

  • “Field Types Reference” - Complete guide to all field types
  • “Custom Field Types” - How to create custom fields
  • “Field Validation” - Built-in validators and custom validation
  • “Field Interceptors” - Using RecordInterceptor for custom logic

Record Model Extensions

  • Missing: Advanced Record manipulation guide
  • Found in code:
    • core/record_model.go: Record struct with Get/Set methods
    • core/record_proxy.go: RecordProxy for typed access
    • core/record_tokens.go: Token generation
    • core/record_field_resolver.go: Field resolution and expansion

Recommended Documentation:

  • “Working with Records (Advanced)” - Deep dive into Record API
  • “Record Proxies” - Type-safe record access
  • “Field Resolvers” - Custom field resolution logic

Collection Management

  • Missing: Programmatic collection management guide
  • Found in code:
    • core/collection_model.go: Collection struct
    • core/collection_import.go: Collection import/export
    • core/collection_validate.go: Collection validation
    • Auth, Base, and View collection options

Recommended Documentation:

  • “Collections (Programmatic)” - Creating/updating collections in code
  • “Collection Types” - Auth vs Base vs View collections
  • “Collection Import/Export” - Backup and restore strategies

Database Operations

  • Missing: Advanced database query patterns
  • Found in code:
    • core/db.go: Database connection management
    • core/db_builder.go: Query builder
    • core/db_tx.go: Transaction handling
    • core/db_retry.go: Retry logic

Recommended Documentation:

  • “Database Queries (Advanced)” - Complex queries and joins
  • “Transactions” - Managing database transactions
  • “Connection Pooling” - Concurrent vs non-concurrent DB

2. API Package Documentation (MEDIUM PRIORITY)

Current State

  • Good API endpoint documentation
  • Missing middleware documentation
  • Limited custom endpoint examples

Identified Gaps

Middlewares

  • Found in code: apis/middlewares*.go
    • Body limit middleware
    • CORS middleware
    • Gzip middleware
    • Rate limit middleware

Recommended Documentation:

  • “Middlewares” - Built-in and custom middleware
  • “Rate Limiting” - Configuration and custom rules
  • “CORS Configuration” - Cross-origin setup

Custom Endpoints

  • Missing: Comprehensive guide on custom API endpoints
  • Found in code: apis/base.go, apis/serve.go

Recommended Documentation:

  • “Custom API Endpoints” - Creating custom routes
  • “Request/Response Handling” - Working with RequestEvent

3. Tools Package Documentation (MEDIUM PRIORITY)

Current State

  • No documentation on utility packages
  • Missing common patterns and helpers

Identified Gaps

Available Tools (from tools/ directory):

  • archive - Archive operations
  • auth - Authentication utilities
  • cron - Cron job scheduling
  • dbutils - Database utilities
  • filesystem - File system operations
  • hook - Hook system
  • inflector - String inflection
  • list - List utilities
  • logger - Logging
  • mailer - Email sending
  • osutils - OS utilities
  • picker - Data picker
  • router - Routing utilities
  • routine - Goroutine helpers
  • search - Search utilities
  • security - Security helpers
  • store - Key-value store
  • subscriptions - Realtime subscriptions
  • template - Template rendering
  • tokenizer - Token parsing
  • types - Type utilities

Recommended Documentation:

  • “Utility Packages” - Overview of all tools
  • “Filesystem Operations” - File upload/download patterns
  • “Mailer” - Email templates and sending
  • “Cron Jobs” - Scheduled tasks
  • “Security Helpers” - Encryption, hashing, random generation

4. Advanced Use Cases (MEDIUM PRIORITY)

Missing Guides

Multi-tenancy

  • No guide on implementing multi-tenant applications
  • Missing isolation patterns

Recommended Documentation:

  • “Multi-Tenancy Patterns” - Implementing tenant isolation
  • “Data Isolation” - Collection-level vs record-level

Performance Optimization

  • Limited performance tuning documentation
  • Missing indexing strategies

Recommended Documentation:

  • “Performance Tuning” - Optimization strategies
  • “Indexing Best Practices” - When and how to index
  • “Query Optimization” - Writing efficient queries

Testing

  • Basic testing guide exists
  • Missing integration testing patterns

Recommended Documentation:

  • “Testing Strategies” - Unit, integration, and E2E testing
  • “Test Helpers” - Using ApiScenario and test utilities

Security

  • Basic authentication covered
  • Missing advanced security topics

Recommended Documentation:

  • “Security Best Practices” - Comprehensive security guide
  • “API Rules Patterns” - Common access control patterns
  • “Rate Limiting Strategies” - Protecting your API

5. Migration and Changelog (LOW PRIORITY)

Current State

  • Excellent CHANGELOG.md with detailed version history
  • v0.23 upgrade guides exist

Identified Gaps

Version Migration

  • Missing: Migration guides for older versions
  • Exists: CHANGELOG.md with comprehensive history from v0.8 to v0.36+

Recommended Documentation:

  • “Migration Guides” - Step-by-step version upgrades
  • “Breaking Changes” - Summary of breaking changes by version

Field Types Inventory

Core Field Types (from core/field_*.go)

  1. Text Field (field_text.go)

    • Basic text storage
    • Min/max length validation
    • Pattern matching
    • Autogenerate option

  2. Number Field (field_number.go)

    • Integer and float support
    • Min/max value validation
    • OnlyInt option

  3. Boolean Field (field_bool.go)

    • True/false values

  4. Email Field (field_email.go)

    • Email validation
    • Unique constraint support

  5. URL Field (field_url.go)

    • URL validation
    • HTTP/HTTPS enforcement

  6. Date Field (field_date.go)

    • Date/time storage
    • Format validation

  7. Autodate Field (field_autodate.go)

    • Auto-populated timestamps
    • onCreate/onUpdate triggers

  8. Select Field (field_select.go)

    • Predefined options
    • Single/multiple selection
    • MaxSelect option

  9. File Field (field_file.go)

    • File upload handling
    • MaxSelect for multiple files
    • MaxSize validation
    • MIME type restrictions
    • Thumb sizes

  10. Relation Field (field_relation.go)

    • References to other collections
    • Single/multiple relations
    • Cascade delete options
    • DisplayFields

  11. JSON Field (field_json.go)

    • Arbitrary JSON storage
    • MaxSize validation

  12. Editor Field (field_editor.go)

    • Rich text content
    • MaxSize validation
    • Convertible to HTML

  13. Password Field (field_password.go)

    • Bcrypt hashing
    • Min/max length
    • Pattern validation
    • Cost factor

  14. GeoPoint Field (field_geo_point.go) ⭐ NEW in v0.27

    • Geographic coordinates
    • Longitude/latitude storage
    • Distance calculations

Recent Features Requiring Documentation

From CHANGELOG Analysis

v0.36.x (Latest)

  • strftime() date formatting function
  • Query optimization improvements
  • JSVM unmarshal helper

v0.35.x

  • Nullable helpers: nullString(), nullInt(), nullFloat(), nullBool(), nullArray(), nullObject()

v0.34.x

  • @request.body.someField:changed modifier
  • Cron jobs API and UI

v0.33.x

  • Auth alert {ALERT_INFO} placeholder
  • Extra ID characters validation

v0.32.x

  • Enhanced List/Search API rules checks
  • Client-side filter security improvements

v0.31.x

  • Multiple relation fields visualization
  • Ed25519 OIDC support

v0.30.x

  • Lark OAuth2 provider
  • $os.Root JSVM bindings

v0.29.x

  • Box.com OAuth2 provider
  • Custom network listeners

v0.28.x

  • toBytes() JSVM helper
  • GetReuploadableFile() method

v0.27.x

  • GeoPoint field ⭐
  • geoDistance() function
  • Create API rule optimization

Priority Recommendations

Immediate (Next Sprint)

  1. Field Types Reference - Complete guide with examples for all 14 field types
  2. GeoPoint Field Guide - New in v0.27, needs documentation
  3. Advanced Record Operations - Get/Set modifiers, proxies, field resolvers

Short-term (1-2 months)

  1. Programmatic Collection Management - Creating collections in code
  2. Middleware Guide - Built-in and custom middleware
  3. Tools Package Overview - Document utility packages
  4. Security Best Practices - Comprehensive security guide

Medium-term (3-6 months)

  1. Performance Tuning Guide - Optimization strategies
  2. Multi-Tenancy Patterns - Implementing tenant isolation
  3. Advanced Testing - Integration and E2E testing
  4. Custom Field Types - Creating custom fields
  5. Migration Guides - Version upgrade paths

Code Examples Needed

High Priority Examples

  1. All Field Types - Creation and configuration examples
  2. GeoPoint Usage - Distance queries and filtering
  3. Record Proxies - Type-safe record access
  4. Custom Middlewares - Request/response modification
  5. Transaction Handling - Multi-operation transactions
  6. Rate Limiting - Custom rate limit rules
  7. File Upload Patterns - Single and multiple files
  8. Relation Expansion - Deep expansion examples

Medium Priority Examples

  1. Custom Validators - Field-level validation
  2. Collection Import/Export - Backup strategies
  3. Cron Jobs - Scheduled task patterns
  4. Email Templates - Custom mail templates
  5. OAuth2 Customization - Provider configuration
  6. View Collections - Complex SQL views

Documentation Structure Recommendations

Proposed New Sections

/docs
  /getting-started (existing)
    - how-to-use
    - authentication
    - files-handling
    - working-with-relations
    - going-to-production
    - use-as-framework ✨ ENHANCE

  /core-concepts (NEW)
    - collections
    - records
    - fields
    - authentication
    - realtime
    - files

  /field-types (NEW) ⭐ HIGH PRIORITY
    - overview
    - text
    - number
    - boolean
    - email
    - url
    - date
    - autodate
    - select
    - file
    - relation
    - json
    - editor
    - password
    - geopoint ✨ NEW
    - custom-fields

  /api (existing)
    - api-records
    - api-collections
    - api-files
    - api-backups
    - api-health
    - api-logs
    - api-realtime
    - api-settings
    - api-crons
    - api-rules-and-filters

  /go (existing)
    - go-overview
    - go-collections ✨ ENHANCE
    - go-records ✨ ENHANCE
    - go-database ✨ ENHANCE
    - go-event-hooks
    - go-routing
    - go-migrations
    - go-testing
    - go-realtime
    - go-filesystem
    - go-sending-emails
    - go-rendering-templates
    - go-logging
    - go-jobs-scheduling
    - go-console-commands
    - go-miscellaneous
    - go-record-proxy (NEW)

  /javascript (existing)
    - js-overview
    - js-collections
    - js-records
    - js-database
    - js-event-hooks
    - js-routing
    - js-migrations
    - js-realtime
    - js-filesystem
    - js-sending-emails
    - js-sending-http-requests
    - js-rendering-templates
    - js-logging
    - js-jobs-scheduling
    - js-console-commands

  /advanced (NEW) ⭐ MEDIUM PRIORITY
    - performance-tuning
    - multi-tenancy
    - custom-fields
    - custom-middlewares
    - transactions
    - security-best-practices
    - testing-strategies

  /tools (NEW) ⭐ MEDIUM PRIORITY
    - overview
    - filesystem
    - mailer
    - cron
    - security
    - store
    - logger

  /migration (NEW)
    - upgrading
    - breaking-changes
    - version-guides

Metrics

Current Documentation

  • Total Articles: 49
  • API Documentation: 10 articles
  • Go Documentation: 17 articles
  • JavaScript Documentation: 16 articles
  • Getting Started: 5 articles
  • Other: 1 article (README)
  • Field Types: +16 articles
  • Core Concepts: +6 articles
  • Advanced Topics: +8 articles
  • Tools: +8 articles
  • Migration: +3 articles
  • Enhancements: ~10 existing articles

Total New Content: ~40 articles Total After Completion: ~89 articles

Conclusion

The existing PocketBase documentation provides excellent coverage of API endpoints and basic usage patterns for both Go and JavaScript. However, there are significant opportunities to improve documentation around:

  1. Core internals - Field types, validators, record operations
  2. Advanced patterns - Multi-tenancy, performance, security
  3. Utility packages - Tools and helpers
  4. New features - GeoPoint fields, recent CHANGELOG additions

By addressing these gaps, PocketBase documentation will become more comprehensive and enable developers to build more sophisticated applications with confidence.

Next Steps

  1. ✅ Review and approve this gap analysis
  2. 📝 Create detailed outlines for priority articles
  3. ✍️ Write and publish high-priority documentation
  4. 🔄 Establish documentation update process for new releases
  5. 📊 Track documentation coverage metrics
README