Embed PocketBase with Go
Create a Go application, initialize PocketBase, configure it, and start the server.
This tutorial builds a Go program that embeds PocketBase, registers the application, and starts its server. You will finish with a process that owns the PocketBase lifecycle and can be extended with routes, hooks, migrations, and other Go code.
Before you begin
Install Go and create a Go module. Add the PocketBase module at the version selected for your application. Keep the application data directory outside source control when it contains local data.
Start from an empty application directory and make sure the Go toolchain can download the module. You should be able to run go version and have a writable location for the data directory. This guide is useful when Go code needs to own PocketBase startup.
Build the application
Run:
mkdir my-pocketbase-app
cd my-pocketbase-app
go mod init example.com/my-pocketbase-app
go get github.com/pocketbase/pocketbaseThe module now declares PocketBase as a dependency.
Create main.go:
package main
import ( "log"; "github.com/pocketbase/pocketbase" )
func main() { app := pocketbase.New(); if err := app.Start(); err != nil { log.Fatal(err) } }New creates the instance but does not bootstrap database connections, migrations, or settings. Start performs initialization as part of starting the application.
Run go run . serve. The process starts PocketBase with the default configuration. The default data directory falls back to pb_data relative to the executable when no custom directory is configured.
Use pocketbase.NewWithConfig for custom settings:
app := pocketbase.NewWithConfig(pocketbase.Config{DefaultDataDir: "./data", DefaultDev: true})The configuration supports a data directory, encryption environment, query timeout, database connection limits, and a custom database connector.
Stop and start the process again. A successful restart shows that the embedded application owns initialization and serving.
Register routes and lifecycle behavior before Start. The example application also registers JavaScript VM and migration plugins before starting, allowing one Go binary to host hooks and migrations.
go run . serve starts without an initialization error and responds through its PocketBase server, the embedded setup is complete.Troubleshoot startup
If the module cannot resolve PocketBase, check the module path in go.mod and run go get github.com/pocketbase/pocketbase again from the module directory. If startup fails after changing the data location, confirm that the configured directory is writable and that the process is using the intended DefaultDataDir. If a restart does not reach the serving state, inspect the initialization error before adding routes or plugins; Start performs application initialization.
Next step
Once the process starts reliably, register custom behavior before Start. Continue with Go routes, middleware, and templates, or review Go records and database operations.
Next, add endpoints with Go routes, middleware, and templates, or use Go records and database operations.