Quickstart

Get your PocketBase backend running in minutes and create your first collection.

This guide walks you through installing PocketBase, starting the server, and creating your first database collection. You’ll have a working REST API in under 5 minutes.

Prerequisites

No dependencies required! PocketBase is a single executable that runs on macOS, Linux, Windows, and FreeBSD.

Start your first instance

1. Download and extract

   Download the latest release for your platform from GitHub:

   macOS/Linux

   # Download (replace VERSION with the latest version)
   wget https://github.com/pocketbase/pocketbase/releases/download/vVERSION/pocketbase_VERSION_linux_amd64.zip
   
   # Extract
   unzip pocketbase_VERSION_linux_amd64.zip
   
   # Make executable
   chmod +x pocketbase
   
2. Start the server

   Run PocketBase with the serve command:

   ./pocketbase serve
   

   You’ll see output like this:

   Server started at: http://127.0.0.1:8090
     - REST API: http://127.0.0.1:8090/api/
     - Admin UI: http://127.0.0.1:8090/_/
   

   PocketBase creates a pb_data directory to store your database and uploaded files. You can customize this with the --dir flag.

3. Create your admin account

   Open your browser and navigate to:

   http://127.0.0.1:8090/_/
   

   You’ll be prompted to create an admin account. Fill in your email and password—this account lets you manage your database through the Admin UI.

4. Create your first collection

   In the Admin UI:

   1. Click New Collection in the sidebar
   2. Choose Base collection (for regular database records)
   3. Name it posts
   4. Click Create

   Now add some fields:

   • Click New field and select Plain text
   • Name: title, Check Required
   • Add another Editor field named content
   • Click Save

   PocketBase automatically adds id, created, and updated fields to every collection.

5. Test your API

   Your REST API is automatically available. Try creating a record:

   curl -X POST http://127.0.0.1:8090/api/collections/posts/records \
     -H "Content-Type: application/json" \
     -d '{
       "title": "My first post",
       "content": "Hello from PocketBase!"
     }'
   

   Fetch all records:

   curl http://127.0.0.1:8090/api/collections/posts/records
   

   You should see your newly created post in the JSON response.

Build with the Go library

If you want to extend PocketBase with custom logic, you can use it as a Go library. Here’s a minimal example based on the official source:

1. Set up your Go project

   mkdir myapp && cd myapp
   go mod init myapp
   
2. Create main.go

   Create a main.go file with this code from the PocketBase examples:

   main.go

   package main
   
   import (
       "log"
   
       "github.com/pocketbase/pocketbase"
       "github.com/pocketbase/pocketbase/core"
   )
   
   func main() {
       app := pocketbase.New()
   
       app.OnServe().BindFunc(func(se *core.ServeEvent) error {
           // registers new "GET /hello" route
           se.Router.GET("/hello", func(re *core.RequestEvent) error {
               return re.String(200, "Hello world!")
           })
   
           return se.Next()
       })
   
       if err := app.Start(); err != nil {
           log.Fatal(err)
       }
   }
   

   This example:

   • Creates a new PocketBase instance with pocketbase.New()
   • Hooks into the OnServe() event to add a custom route
   • Registers a GET /hello endpoint that returns “Hello world!”
   • Starts the application with app.Start()
3. Install dependencies and run

   go mod tidy
   go run main.go serve
   

   Your server starts with both the standard PocketBase API and your custom /hello route.

4. Test your custom route

   curl http://127.0.0.1:8090/hello
   

   You should see: Hello world!

5. Build for production

   Create a statically linked executable:

   CGO_ENABLED=0 go build
   

   Then deploy your single binary:

   ./myapp serve
   

Advanced example with plugins

The official PocketBase executable (from releases) is built with additional plugins. Here’s what the full examples/base/main.go includes:

JavaScript hooks

// Enable JavaScript hooks from pb_hooks directory
jsvm.MustRegister(app, jsvm.Config{
    MigrationsDir: migrationsDir,
    HooksDir:      hooksDir,
    HooksWatch:    hooksWatch,
    HooksPoolSize: hooksPool,
})

The prebuilt executables include all these plugins, allowing you to extend PocketBase with JavaScript without writing Go code.

Common commands

PocketBase includes several built-in commands:

Command	Description
serve	Start the HTTP server (default port: 8090)
superuser	Create or update a superuser account
migrate	Run database migrations (when using Go library)
--help	Show available commands and flags

Create a superuser via CLI

./pocketbase superuser create [e-mail] password123

Use a custom port

./pocketbase serve --http=0.0.0.0:3000

Enable development mode

./pocketbase serve --dev

Development mode enables:

• Verbose logging to console
• SQL query logging
• Detailed error messages

Don’t use --dev in production—it exposes sensitive information in logs.

SDK integration

Connect to your PocketBase API from the frontend using the official SDKs:

JavaScript

import PocketBase from 'pocketbase';

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

// Create a record
const record = await pb.collection('posts').create({
    title: 'My first post',
    content: 'Hello from PocketBase!'
});

// Fetch records
const records = await pb.collection('posts').getFullList();

// Subscribe to realtime changes
pb.collection('posts').subscribe('*', (e) => {
    console.log(e.action); // create, update, delete
    console.log(e.record);
});

Next steps

Database collections

Learn about collection types, fields, and relations

Authentication

Set up user authentication and OAuth2 providers

File uploads

Handle file uploads and image transformations

Extend with Go

Add custom business logic and API routes

Troubleshooting

Port already in use

If port 8090 is busy, specify a different port:

./pocketbase serve --http=0.0.0.0:8091

Permission denied on Linux/macOS

Make the executable runnable:

chmod +x pocketbase

Database locked error

This happens if multiple PocketBase instances try to access the same pb_data directory. Only run one instance per data directory, or use different --dir paths:

./pocketbase serve --dir=./pb_data_instance1

For production deployments, consider using process managers like systemd, Docker, or PM2 to keep PocketBase running reliably.