Quickstart

PocketBase Plugin Skill

PocketBase open-source backend as a single file with Go-based SQLite database, real-time subscriptions, and built-in admin UI.

Quick Start

# Install pocketbase binary
# macOS: brew install pocketbase
# Linux: Download from https://pocketbase.io/docs

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"

# Start server (development mode)
sc pocketbase self serve

# Or background with logging
nohup sc pocketbase self serve > /tmp/pocketbase.log 2>&1 &

Core Commands

Server Management

# Start development server
sc pocketbase self serve

# Stop server
sc pocketbase server stop

# Restart server
sc pocketbase server restart

# Check server status
sc pocketbase server status

# Health check
sc pocketbase health check

# Check version
sc pocketbase --version

# View help
sc pocketbase --help

Migration Management (Non-Interactive)

# Create migration file
sc pocketbase migration create add_user_fields

# Apply pending migrations
sc pocketbase migration up --force

# Revert last migration
sc pocketbase migration down 1 --force

Collection Management

# Set auth credentials
export POCKETBASE_EMAIL="admin@example.com"
export POCKETBASE_PASSWORD="password123"
export POCKETBASE_URL="http://127.0.0.1:8090"

# List all collections (table format)
sc pocketbase collection list

# List collections (JSON format)
sc pocketbase collection list --json

# Filter collections
sc pocketbase collection list --filter=todo

# Create new collection
sc pocketbase collection create mycollection
sc pocketbase collection create users auth  # for auth collection

# Delete collection (by name or ID - automatic resolution)
sc pocketbase collection delete todos        # Uses name
sc pocketbase collection delete pbc_123456   # Uses ID

Database Operations

# Run migrations
sc pocketbase migrate up

# Create migration file
sc pocketbase migrate create add_user_fields

# Revert migrations
sc pocketbase migrate down 1

# Sync migrations history
sc pocketbase migrate history-sync

Superuser Management

# Create superuser
sc pocketbase superuser create admin@example.com password123

# Update superuser password
sc pocketbase superuser update admin@example.com newpassword123

# Delete superuser
sc pocketbase superuser delete admin@example.com

# Create OTP for superuser
sc pocketbase superuser otp admin@example.com

Passthrough Commands

Any pocketbase CLI command works via passthrough:

sc pocketbase serve --dev
sc pocketbase migrate up
sc pocketbase superuser upsert email@domain.com password123

New Features & Improvements

Automation-Ready Migrations

• Non-interactive mode: Use --force flag to skip confirmation prompts
• Automated workflows: Perfect for CI/CD pipelines and scripts
• Template generation: Migration files created with proper structure

Enhanced Server Management

• Process monitoring: PID file tracking and health monitoring
• Auto-restart: Server automatically restarts on crashes (up to 3 attempts)
• Graceful shutdown: Proper SIGTERM/SIGKILL handling
• Health checks: Built-in health monitoring with response times

Smart Collection Operations

• Name resolution: Use collection names instead of IDs (automatic ID lookup)
• Retry logic: Automatic retry with exponential backoff for transient failures
• Better formatting: Table and JSON output formats with filtering

Resilient HTTP Client

• Automatic retry: Handles connection failures gracefully
• Exponential backoff: 1s → 2s → 4s → 8s retry delays
• Smart error detection: Only retries on transient network errors

Caveats & Pitfalls

1. Server Process Management

Issue: Long-running server commands timeout in supercli's default execution model.

Solution: Use background execution or new server management commands:

# Good: Use dedicated server commands
sc pocketbase self serve
sc pocketbase server stop
sc pocketbase server restart
sc pocketbase server status

# Or background with logging
nohup sc pocketbase self serve > /tmp/pocketbase.log 2>&1 &

# Monitor logs
tail -f /tmp/pocketbase.log

# Check health
sc pocketbase health check

Status: ✅ Resolved - New server management commands with process monitoring

2. Binary Installation

Issue: brew install pocketbase only works on macOS. Linux requires manual download.

Solution: Download directly from GitHub releases:

# Linux AMD64
curl -LO https://github.com/pocketbase/pocketbase/releases/download/v0.23.5/pocketbase_0.23.5_linux_amd64.zip
unzip pocketbase_0.23.5_linux_amd64.zip
chmod +x pocketbase
mv pocketbase ~/.local/bin/

3. Collection Schema Creation

Issue: Admin API schema creation via curl is complex and error-prone. PocketBase expects specific field formats.

Solution: Use PocketBase migrations for schema changes:

// pb_migrations/TIMESTAMP_schema_name.js
migrate((app) => {
  const collection = app.findCollectionByNameOrId("mycollection");
  
  const titleField = new TextField({
    "name": "title",
    "required": true,
    "presentable": true
  });
  collection.fields.push(titleField);
  
  app.save(collection);
}, (app) => {
  // Revert logic
  const collection = app.findCollectionByNameOrId("mycollection");
  collection.removeField("title");
  app.save(collection);
});

Then apply: sc pocketbase migration up --force

Status: ✅ Improved - Non-interactive migration mode available

4. Authentication Required

Issue: Most API operations require superuser authentication, not just basic HTTP access.

Solution: Set environment variables for collection management:

export POCKETBASE_EMAIL="admin@example.com"
export POCKETBASE_PASSWORD="password123"
export POCKETBASE_URL="http://127.0.0.1:8090"

5. Collection ID vs Name

Issue: Operations like delete require collection ID (pbc_*), not name.

Solution: Collection name resolution is now automatic:

# Both work now - name resolution is automatic
sc pocketbase collection delete todos        # Resolves name to ID
sc pocketbase collection delete pbc_1234567890   # Uses ID directly

Status: ✅ Resolved - Automatic name-to-ID resolution implemented

6. Development vs Production

Issue: Development mode (--dev) prints SQL queries and logs, not suitable for production.

Solution:

# Development (with logs)
sc pocketbase self serve

# Production (without --dev flag)
sc pocketbase serve

7. Data Directory Location

Issue: PocketBase creates pb_data directory in current working directory by default.

Solution: Specify data directory explicitly:

sc pocketbase serve --dir /path/to/data

8. Port Conflicts

Issue: Default port 8090 may conflict with other services.

Solution: Use custom HTTP port:

sc pocketbase serve --http 0.0.0.0:3000

9. Migration File Naming

Issue: Migration files need unique timestamps to avoid conflicts.

Solution: Use Unix timestamp in filename:

# Current timestamp in milliseconds
date +%s%3N  # e.g., 1778761000

# Create migration with timestamp
sc pocketbase migrate create 1778761000_add_fields

10. Relation Field Complexity

Issue: Relation fields require exact collection IDs and proper configuration.

Solution: Always reference collections by ID, not name:

const categoryField = new RelationField({
  "name": "category",
  "collectionId": "pbc_3292755704",  // Use exact ID
  "maxSelect": 1,
  "minSelect": 0,
  "presentable": true
});

Status: ⚠️ Unchanged - This is a PocketBase requirement

11. Server Stability

Issue: Server may stop unexpectedly during operations despite auto-restart improvements.

Solution: Use process managers for production:

# For production, use systemd or PM2
# Auto-restart is limited to 3 attempts
# Consider external monitoring for critical deployments

Status: ⚠️ Partially Resolved - Auto-restart implemented but external monitoring recommended

Best Practices

1. Environment Setup

# Add to .bashrc or .zshrc
export PATH="$HOME/.local/bin:$PATH"
export POCKETBASE_EMAIL="admin@example.com"
export POCKETBASE_PASSWORD="password123"
export POCKETBASE_URL="http://127.0.0.1:8090"

2. Database Schema Management

• Always use migrations for schema changes
• Test migrations in development first
• Keep migration files reversible
• Use descriptive migration names

3. Server Management

• Use process manager (systemd, PM2) for production
• Monitor logs for errors
• Set up proper backup strategy for pb_data directory
• Use environment variables for configuration

4. API Rules

• Set appropriate API rules in admin UI for security
• Use @request.auth.id for authenticated requests
• Test API rules before deploying
• Document your API rule patterns

5. Development Workflow

# 1. Start server
sc pocketbase self serve

# 2. Create migration for schema changes
sc pocketbase migrate create feature_name

# 3. Edit migration file
vim pb_migrations/TIMESTAMP_feature_name.js

# 4. Apply migration
sc pocketbase migrate up

# 5. Test in admin UI
open http://127.0.0.1:8090/_/

# 6. If needed, revert migration
sc pocketbase migrate down 1

Troubleshooting

Server Won't Start

# Check if pocketbase binary exists
which pocketbase

# Check if port is in use
lsof -i :8090

# Try different port
sc pocketbase serve --http 0.0.0.0:3000

Migration Errors

# Check migration status
sc pocketbase migrate history-sync

# Revert failed migration
sc pocketbase migrate down 1

# Fix migration file and reapply
sc pocketbase migrate up

Collection Management Issues

# Verify authentication
curl -X POST http://127.0.0.1:8090/api/collections/_superusers/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity":"admin@example.com","password":"password123"}'

# Check server logs
tail -f /tmp/pocketbase.log

Data Not Persisting

# Check data directory permissions
ls -la pb_data/

# Ensure data directory is writable
chmod -R 755 pb_data/

# Specify explicit data directory
sc pocketbase serve --dir ./pb_data

Admin UI Access

• Dashboard: http://127.0.0.1:8090/_/
• API: http://127.0.0.1:8090/api/
• Default Superuser: Created via CLI or admin UI on first visit

Plugin Architecture

The plugin uses:

• Process adapter for CLI passthrough commands
• Custom Node.js scripts for complex operations (collection-manager.js, serve.js)
• Environment variables for configuration (POCKETBASE_EMAIL, etc.)
• Migration files for schema management

Advanced Usage

Custom Hooks

// pb_hooks/main.go
package hooks

import (
    "github.com/pocketbase/pocketbase/apis"
    "github.com/pocketbase/pocketbase/tools/types"
)

func (e *BootstrapEvent) Bootstrap(e *BootstrapEvent) error {
    // Custom bootstrap logic
    return e.Next()
}

Real-time Subscriptions

// Client-side subscription
const pb = new PocketBase('http://127.0.0.1:8090');

pb.collection('todos').subscribe('*', function(e) {
    console.log(e.action, e.record);
});

Backup Strategy

# Backup data directory
tar -czf pocketbase-backup-$(date +%Y%m%d).tar.gz pb_data/

# Restore backup
tar -xzf pocketbase-backup-20240514.tar.gz

Resources

• Official Docs: https://pocketbase.io/docs/
• GitHub: https://github.com/pocketbase/pocketbase
• Examples: https://github.com/pocketbase/pocketbase/examples
• Community: https://pocketbase.io/docs/go-overview/