PocketBase is an open-source Go backend framework and standalone application that combines an embedded SQLite database, realtime subscriptions, file storage, authentication, and an admin dashboard into a single executable. This page provides a high-level introduction to PocketBase's architecture, deployment models, and core subsystems.
For detailed information about specific subsystems, see:
PocketBase is a complete backend solution that provides:
The codebase is written in Go and distributed as both a standalone executable and a Go library/framework that developers can embed in their applications.
Sources: README.md13-18 go.mod25 ui/.env15 CHANGELOG.md105-108
PocketBase supports two primary deployment approaches:
The prebuilt executable allows extension through JavaScript files in the pb_hooks directory without requiring Go compilation. Start the application with ./pocketbase serve. The prebuilt binaries are based on the logic found in the examples/base/main.go file and include the JSVM plugin by default.
Sources: README.md38-43 CONTRIBUTING.md33-40
Developers can import github.com/pocketbase/pocketbase as a library to build custom applications with full access to the Go API. This allows adding custom business logic and creating application-specific endpoints.
Minimal framework usage pattern:
Sources: README.md45-89 pocketbase.go65-87
Diagram: PocketBase Application Structure with Code Entities
The PocketBase struct pocketbase.go33-44 embeds core.App core/app.go28 which is implemented by BaseApp. The BaseApp serves as the central orchestrator managing:
data.db and auxiliary.db.core.Settings.app.Cron().Sources: pocketbase.go33-44 core/log_query.go11-13 core/log_query.go62
Diagram: Application Initialization Sequence
The initialization process follows these stages:
pocketbase.New() pocketbase.go65 or pocketbase.NewWithConfig().app.Bootstrap() triggers the initialization of internal systems including directory creation and database connectivity.data.db and auxiliary.db connections using modernc.org/sqlite.app.Start().Sources: pocketbase.go65-87 README.md65-81 modernc_versions_check.go28-32
PocketBase provides two primary extension mechanisms: the Hook System and the JSVM Plugin.
The hook system provides event types covering the entire application lifecycle. Hooks are registered via methods on the App interface. These hooks allow intercepting requests, modifying data before persistence, or triggering side effects like sending emails.
| Hook Category | Examples | Usage |
|---|---|---|
| Application Events | OnBootstrap(), OnServe(), OnTerminate() | Lifecycle management |
| Model Events | OnModelCreate(), OnModelUpdate() | Generic model operations |
| Record Events | OnRecordCreate(), OnRecordUpdate() | Record CRUD operations |
| API Request Events | OnRecordAuthRequest() | HTTP request interception |
| Realtime Events | OnRealtimeConnectRequest() | SSE connections |
Sources: README.md68-75 CHANGELOG.md123-124 modernc_versions_check.go16-19
The JavaScript VM Plugin enables extending PocketBase with JavaScript files. The prebuilt executable enables this by default, allowing developers to write business logic in .js or .ts files that are executed by an embedded Goja-based VM. It includes a pooled executor pattern for high performance.
Sources: README.md43 go.mod8-9 CHANGELOG.md12-13
PocketBase uses two SQLite databases to isolate application data from system metadata:
The system uses modernc.org/sqlite go.mod25 and implements a connection strategy to handle concurrency. For example, DeleteOldLogs directly interacts with the auxNonconcurrentDB to perform maintenance on the auxiliary store core/log_query.go62
Sources: core/log_query.go11-13 core/log_query.go58-65 CHANGELOG.md89
modernc.org/sqlite v1.54.0 modernc_versions_check.go13modernc.org/libc v1.74.1 modernc_versions_check.go14Sources: go.mod1-26 CHANGELOG.md20 .github/workflows/release.yaml23-31 README.md102-121
Refresh this wiki