PocketBase

How PocketBase is structured

PocketBase is engineered as a monolithic Go library and CLI tool that packages an embedded database, file storage manager, authentication system, real-time subscription engine, and administrative dashboard into a single portable binary. The repository is organized into distinct domain layers:

• core/: Contains the fundamental application kernel (core/app.go), database connection pooling and query builder abstractions (core/db.go), record validation models, migrations manager (core/migrations_runner.go), and event hook infrastructure (core/events.go).
• apis/: Exposes HTTP handlers for record CRUD operations (apis/record_crud.go), authentication methods including OAuth2 and MFA (apis/record_auth.go), file upload serving, batch requests, and real-time Server-Sent Events endpoints (apis/realtime.go).
• tools/: Independent utility packages covering routing (tools/router), filesystem access and S3 integration (tools/filesystem), JWT token handling, security utilities, and subscription managers.
• ui/: The browser-based superuser admin interface, packaged with Vite and embedded directly into the Go executable through ui/embed.go.
• plugins/: Optional extensions such as the embedded JavaScript runtime (plugins/jsvm) and automatic schema migration CLI commands (plugins/migratecmd).

Frontend

The administrative UI in ui/ allows administrators to configure collections, manage users, inspect API logs, and test database rules interactively. The frontend is bundled using Vite 8 (ui/package.json) and compiled into ui/dist/.

The admin application uses native JavaScript and CSS combined with specialized components such as Leaflet (leaflet version 1.9.4) for rendering geographic and point fields on interactive maps. Pre-built frontend bundles are committed to the repository and compiled directly into the binary using Go's //go:embed functionality in ui/embed.go. For headless deployments or resource-constrained environments, ui/embed_no_ui.go provides build tags to exclude the admin panel entirely.

Backend & APIs

The backend server is implemented in Go 1.27 (go.mod). Rather than relying on external web frameworks like Echo or Gin, modern PocketBase utilizes a specialized HTTP routing package (tools/router) that wraps Go's standard library net/http primitives while offering route grouping, path parameter extraction, and middleware chaining.

Every HTTP interaction is wrapped in event hooks (core/event_request.go). Developers can register custom interceptor hooks—either programmatically in Go via app.OnRecordCreate() or through the JavaScript VM plugin (plugins/jsvm/). The JS VM plugin utilizes Goja (github.com/dop251/goja), allowing teams to author TypeScript or JavaScript files in pb_hooks/ that execute synchronously within the request pipeline without requiring Node.js.

Data & persistence

Persistence is anchored on embedded SQLite:

• Database Engine: PocketBase uses modernc.org/sqlite, a pure Go transpilation of SQLite that runs without requiring CGO or native C library linking. The database runs with write-ahead logging (PRAGMA journal_mode=WAL) enabled, allowing concurrent read transactions while serializing writes cleanly.
• Query Building: Database queries are formulated using github.com/pocketbase/dbx, a lightweight query builder that translates parameterized filters into optimized SQL statements.
• File Storage: Uploaded attachments are managed through tools/filesystem. By default, files reside in local disk volumes (pb_data/storage), but the storage engine supports S3-compatible cloud backends (AWS S3, Cloudflare R2, MinIO) configured via admin settings or environment credentials.

Realtime / collaboration

Real-time synchronization in PocketBase is implemented over HTTP Server-Sent Events (apis/realtime.go, tools/subscriptions) rather than WebSockets. Clients connect to the /api/realtime endpoint, receiving a unique client ID.

When records are inserted, updated, or deleted, PocketBase evaluates the active subscriptions and applies collection-level API rules (row-level security) for the subscribed client. If the rule passes, an event containing the record payload is pushed immediately across the open SSE stream. This approach reduces connection complexity and works seamlessly through corporate proxies, firewalls, and HTTP/2 CDNs.

Build, test & deploy

• Cross-Compilation: Build configurations in .goreleaser.yaml compile statically linked binaries for dozens of architectures (Linux x86_64, ARM64, RISC-V, macOS Apple Silicon and Intel, FreeBSD, and Windows).
• Testing: The repository maintains automated test suites (tests/app.go, tests/api.go) covering authentication flows, transactional integrity, and rule evaluations executed via go test ./....
• Deployment: Deploying PocketBase requires uploading the single executable and running ./pocketbase serve --http="0.0.0.0:8090". The only persistent state is the pb_data directory, which holds SQLite database files, logs, and local file uploads.

Self-hosting notes

Operating PocketBase in production is remarkably straightforward:

1. Provision a single Linux server, virtual machine, or container (e.g., Fly.io, Hetzner, Railway).
2. Attach a persistent volume for the pb_data/ directory to preserve SQLite databases and uploaded media.
3. Run the binary as a systemd service or minimal Docker container.
4. Set up TLS termination using a reverse proxy (Caddy, Nginx) or utilize PocketBase's built-in Let's Encrypt automated certificate manager.

What to copy (and what not to)

Architectural lessons from PocketBase:

• Zero-dependency deployment: Eliminating CGO dependencies by choosing pure Go drivers allows true static binary distribution, drastically reducing operational friction and deployment complexity.
• Pragmatic embedded databases: For many small-to-medium applications, embedded SQLite in WAL mode delivers microsecond query latencies and eliminates network round-trips to external database clusters.
• SSE over WebSockets for unidirectional data push: Server-Sent Events offer a resilient, standard HTTP mechanism for streaming database mutations to clients without the framing and reconnection overhead of WebSockets.

Conversely, avoid using embedded SQLite architectures if your workload requires multi-region active-active writes or distributed multi-node horizontal scaling, as SQLite write locks are restricted to a single filesystem node.