gh-whamp-whamp-claude-tools-pocketbase-plugin/skills/pocketbase/references/core/getting_started.md

Getting Started with PocketBase

Overview

PocketBase is an open-source backend consisting of:

• SQLite database with real-time subscriptions
• Built-in Admin Dashboard UI (single-page application)
• Authentication (email/password, OAuth2, magic link)
• File storage with automatic image resizing
• RESTful APIs with CORS support
• WebSocket for real-time updates
• Admin dashboard for data management

Quick Setup

Option 1: Download Binary

# Download latest release
wget https://github.com/pocketbase/pocketbase/releases/latest/download/pocketbase_0.20.0_linux_amd64.zip

# Unzip
unzip pocketbase_0.20.0_linux_amd64.zip

# Serve on port 8090
./pocketbase serve --http=0.0.0.0:8090

Visit http://127.0.0.1:8090/_/ to access the admin dashboard.

💡 Want to master the PocketBase CLI? See the comprehensive CLI Commands Guide for detailed information on serve, migrate, superuser, and all CLI commands.

Option 2: Docker

docker run -d \
  -v pb_data:/pb_data \
  -p 8090:8090 \
  --name pocketbase \
  ghcr.io/pocketbase/pocketbase:latest serve --http=0.0.0.0:8090

Option 3: Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  pocketbase:
    image: ghcr.io/pocketbase/pocketbase:latest
    command: serve --http=0.0.0.0:8090
    volumes:
      - ./pb_data:/pb_data
    ports:
      - "8090:8090"

Run:

docker-compose up -d

First Steps in Admin Dashboard

1. Create Admin Account

   • Navigate to http://localhost:8090/_/
   • Enter email and password
   • Click "Create and Login"

2. Configure Settings

   • Go to Settings → CORS
   • Add your frontend domain (e.g., http://localhost:3000)
   • Click "Save"

3. Create Your First Collection

   • Go to Collections → New Collection
   • Choose between:
     • Base collection - flexible schema
     • Auth collection - for user management
     • View collection - read-only computed data

Basic Concepts

Collections

Collections are like tables in a traditional database. Each collection has:

• Schema - fields and their types
• Rules - access control (read, write, delete)
• Indexes - performance optimization
• Options - additional settings

Records

Records are individual entries in a collection, similar to rows in a table. Each record:

• Has a unique id
• Contains data based on collection schema
• Has built-in fields: id, created, updated

Authentication

User accounts can be created through:

• Email/Password registration
• OAuth2 providers (Google, GitHub, etc.)
• Magic link authentication

Files

File fields allow:

• Single or multiple file uploads
• Automatic thumbnail generation
• MIME type restrictions
• Size limits

Frontend Integration

JavaScript SDK

<script src="https://cdn.jsdelivr.net/npm/pocketbase@latest/dist/pocketbase.umd.js"></script>
<script>
  const pb = new PocketBase('http://127.0.0.1:8090');

  // Example: Register user
  const authData = await pb.collection('users').create({
    email: 'test@example.com',
    password: 'password123',
    passwordConfirm: 'password123'
  });

  // Example: Login
  const authData = await pb.collection('users').authWithPassword(
    'test@example.com',
    'password123'
  );

  // Example: Create record
  const record = await pb.collection('posts').create({
    title: 'My First Post',
    content: 'Hello world!'
  });
</script>

React Integration

npm install pocketbase

import PocketBase from 'pocketbase';

const pb = new PocketBase('http://127.0.0.1:8090');

// React hook for auth state
function useAuth() {
  const [user, setUser] = React.useState(pb.authStore.model);

  React.useEffect(() => {
    const unsub = pb.authStore.onChange(() => {
      setUser(pb.authStore.model);
    });

    return () => unsub();
  }, []);

  return { user };
}

// React component
function Posts() {
  const [posts, setPosts] = React.useState([]);

  React.useEffect(() => {
    loadPosts();

    // Subscribe to real-time updates
    pb.collection('posts').subscribe('*', () => {
      loadPosts();
    });

    return () => pb.collection('posts').unsubscribe();
  }, []);

  async function loadPosts() {
    const records = await pb.collection('posts').getList(1, 50);
    setPosts(records.items);
  }

  return posts.map(post => <div key={post.id}>{post.title}</div>);
}

Next Steps

• Schema Design - Define your data structure (see collections.md)
• Authentication - Set up user management (see authentication.md)
• Security Rules - Control data access (see security_rules.md)
• API Integration - Build your frontend (see api_records.md)
• Production Setup - Deploy to production (see going_to_production.md)

Common First Tasks

Task: Create a Blog

1. Create posts collection (auth collection)
2. Add fields: title, content, published (bool)
3. Set rules: public read, author write
4. Create first post via Admin UI or API

Task: User Profiles

1. Users collection already exists (auth collection)
2. Add profile fields: name, bio, avatar
3. Set rules: user can update own profile
4. Build profile page in frontend

Task: Comments System

1. Create comments collection (base collection)
2. Add fields: post, author, content
3. Create relation to posts collection
4. Set rules: public read, authenticated write

Troubleshooting

Can't access admin dashboard

• Check if PocketBase is running
• Verify port 8090 is not blocked
• Try http://127.0.0.1:8090/_/ instead of localhost

CORS errors in frontend

• Go to Settings → CORS
• Add your frontend domain
• Save changes

Can't create records

• Check collection rules
• Verify user is authenticated
• Check required fields are provided

File uploads failing

• Check file size limits
• Verify MIME types allowed
• Ensure user has create permissions

Resources

• Official Docs
• Examples
• Discord Community
• GitHub Repository