README
¶
PocketBase is an open source Go backend, consisting of:
- embedded database (SQLite) with realtime subscriptions
- built-in files and users management
- convenient Admin dashboard UI
- and simple REST-ish API
For documentation and examples, please visit https://pocketbase.io/docs.
⚠️ Although the web API definitions are considered stable, please keep in mind that PocketBase is still under active development and therefore full backward compatibility is not guaranteed before reaching v1.0.0.
API SDK clients
The easiest way to interact with the API is to use one of the official SDK clients:
- JavaScript - pocketbase/js-sdk (browser and node)
- Dart - pocketbase/dart-sdk (web, mobile, desktop)
Overview
PocketBase could be used as a standalone app or as a Go framework/toolkit that enables you to build your own custom app specific business logic and still have a single portable executable at the end.
Installation
# go 1.18+
go get github.com/pocketbase/pocketbase
For Windows, you may have to use go 1.19+ due to an incorrect js mime type in the Windows Registry (see issue#6).
Example
package main
import (
"log"
"net/http"
"github.com/labstack/echo/v5"
"github.com/pocketbase/pocketbase"
"github.com/pocketbase/pocketbase/apis"
"github.com/pocketbase/pocketbase/core"
)
func main() {
app := pocketbase.New()
app.OnBeforeServe().Add(func(e *core.ServeEvent) error {
// add new "GET /api/hello" route to the app router (echo)
e.Router.AddRoute(echo.Route{
Method: http.MethodGet,
Path: "/api/hello",
Handler: func(c echo.Context) error {
return c.String(200, "Hello world!")
},
Middlewares: []echo.MiddlewareFunc{
apis.RequireAdminOrUserAuth(),
},
})
return nil
})
if err := app.Start(); err != nil {
log.Fatal(err)
}
}
Running and building
Running/building the application is the same as for any other Go program, aka. just go run and go build.
PocketBase embeds SQLite, but doesn't require CGO.
If CGO is enabled, it will use mattn/go-sqlite3 driver, otherwise - modernc.org/sqlite. You can enable and disable CGO by setting the CGO_ENABLED environment variable to 1 or 0 respectively.
Enable CGO only if you really need to squeeze the read/write query performance at the expense of complicating cross compilation.
To build the minimal standalone executable, like the prebuilt ones in the releases page, you can simply run go build inside the examples/base directory.
Testing
PocketBase comes with mixed bag of unit and integration tests.
To run them, use the default go test command:
go test ./...
Check also the Testing guide to learn how to write your own custom application tests.
Security
If you discover a security vulnerability within PocketBase, please send an e-mail to support at pocketbase.io.
All reports will be promptly addressed and you'll be credited accordingly.
Contributing
PocketBase is free and open source project licensed under the MIT License.
You could help continuing its development by:
Please note that PocketBase was initially created to serve as a new backend for my other open source project - Presentator (see #183), so all feature requests will be first aligned with what we need for Presentator v3.
Documentation
¶
Index ¶
- Variables
- type PocketBase
- func (pb *PocketBase) DefaultDataDir(val string) *PocketBase
- func (pb *PocketBase) DefaultDebug(val bool) *PocketBase
- func (pb *PocketBase) DefaultEncryptionEnv(val string) *PocketBase
- func (pb *PocketBase) Execute() error
- func (pb *PocketBase) ShowStartBanner(val bool) *PocketBase
- func (pb *PocketBase) Start() error
Constants ¶
This section is empty.
Variables ¶
var Version = "(untracked)"
Version of PocketBase
Functions ¶
This section is empty.
Types ¶
type PocketBase ¶
type PocketBase struct {
// RootCmd is the main cli command
RootCmd *cobra.Command
// contains filtered or unexported fields
}
PocketBase defines a PocketBase app launcher.
It implements core.App via embedding and all of interface methods could be accessed directly through the instance (eg. PocketBase.DataDir()).
func New ¶
func New() *PocketBase
New creates a new PocketBase instance.
Note that the application will not be initialized/bootstrapped yet, aka. DB connections, migrations, app settings, etc. will not be accessible. Everything will be initialized when Start() is executed. If you want to initialize the application before calling Start(), then you'll have to manually call Bootstrap().
func (*PocketBase) DefaultDataDir ¶
func (pb *PocketBase) DefaultDataDir(val string) *PocketBase
DefaultDataDir sets the default --dir flag value.
func (*PocketBase) DefaultDebug ¶
func (pb *PocketBase) DefaultDebug(val bool) *PocketBase
DefaultDebug sets the default --debug flag value.
func (*PocketBase) DefaultEncryptionEnv ¶
func (pb *PocketBase) DefaultEncryptionEnv(val string) *PocketBase
DefaultEncryptionEnv sets the default --encryptionEnv flag value.
func (*PocketBase) Execute ¶
func (pb *PocketBase) Execute() error
Execute initializes the application (if not already) and executes the pb.RootCmd with graceful shutdown support.
This method differs from pb.Start() by not registering the default system commands!
func (*PocketBase) ShowStartBanner ¶
func (pb *PocketBase) ShowStartBanner(val bool) *PocketBase
ShowStartBanner shows/hides the web server start banner.
func (*PocketBase) Start ¶
func (pb *PocketBase) Start() error
Start starts the application, aka. registers the default system commands (serve, migrate, version) and executes pb.RootCmd.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apis implements the default PocketBase api services and middlewares.
|
Package apis implements the default PocketBase api services and middlewares. |
|
Package core is the backbone of PocketBase.
|
Package core is the backbone of PocketBase. |
|
Package daos handles common PocketBase DB model manipulations.
|
Package daos handles common PocketBase DB model manipulations. |
|
examples
|
|
|
Package models implements various services used for request data validation and applying changes to existing DB models through the app Dao.
|
Package models implements various services used for request data validation and applying changes to existing DB models through the app Dao. |
|
validators
Package validators implements custom shared PocketBase validators.
|
Package validators implements custom shared PocketBase validators. |
|
Package mails implements various helper methods for sending user and admin emails like forgotten password, verification, etc.
|
Package mails implements various helper methods for sending user and admin emails like forgotten password, verification, etc. |
|
Package migrations contains the system PocketBase DB migrations.
|
Package migrations contains the system PocketBase DB migrations. |
|
Package models implements all PocketBase DB models.
|
Package models implements all PocketBase DB models. |
|
schema
Package schema implements custom Schema and SchemaField datatypes for handling the Collection schema definitions.
|
Package schema implements custom Schema and SchemaField datatypes for handling the Collection schema definitions. |
|
Package resolvers contains custom search.FieldResolver implementations.
|
Package resolvers contains custom search.FieldResolver implementations. |
|
Package tests provides common helpers and mocks used in PocketBase application tests.
|
Package tests provides common helpers and mocks used in PocketBase application tests. |
|
Package tokens implements various user and admin tokens generation methods.
|
Package tokens implements various user and admin tokens generation methods. |
|
tools
|
|
|
Package ui handles the PocketBase Admin frontend embedding.
|
Package ui handles the PocketBase Admin frontend embedding. |