DOCSEARCHbyAlgolia
Submit Docs

PocketBase Documentation

repository·master·Indexed 13 days ago

https://github.com/pocketbase/pocketbase

An open-source Go backend providing an embedded SQLite database with realtime subscriptions, file and user management, an Admin dashboard, and a REST-ish API. It can be used as a standalone executable or as a Go framework for building custom applications. Includes official JavaScript and Dart SDKs.

Tokens
16.6K
Snippets
68
Records
98
Agent score
99%

What's inside PocketBase

  1. Query JSON fields with exact values

    master

    In v0.20.3, the behavior for querying json fields was updated. PocketBase no longer applies COALESCE by default, allowing you to distinguish between null and empty strings ('').

    Behavior Example:

    • For the filter data = null, only records where data is json(null) will resolve to TRUE.
    • For the filter data = '', only records where data is json('') will resolve to TRUE.

  2. Use operator modifiers for multi-valued field conditions

    master

    Starting in v0.11.0, PocketBase supports both 'match-all' and 'multi-match' (at least one of) logic for multi-valued fields like select and relation in API rules.

    • Match-all (Default): The condition must be met by all items in the field.
    • Multi-match (At least one): Prefix the operator with ? to check if at least one item in the field matches the condition.

    Example: To check if a relation field someRelA.someRelB has a status of active:

    • someRelA.someRelB.status = "active" (All must be active)
    • someRelA.someRelB.status ?= "active" (At least one must be active)

    Note: If you are upgrading from an older version and want to preserve the old 'at least one' behavior, you must explicitly use the ? prefix.

    // At least one of condition
someRelA.someRelB.status ?= "active"

  3. Create read-only View collections from SQL

    master

    Introduced in v0.13.0, the "View" collection type allows you to create a read-only collection based on a custom SQL SELECT statement.

    Key features include:

    • Support for aggregations (COUNT(), MIN(), MAX(), GROUP BY, etc.)
    • Column and table aliases
    • CTEs and subquery expressions
    • Automatic relation field association
    • file fields proxying (up to 5 linked relations, e.g., view1 -> view2 -> ... -> base)
    • Support for filter, sort, and expand parameters
    • Support for List and View API rules

  5. Handle OAuth2 PKCE and Expiry

    master

    Updates in v0.20.0 improved OAuth2 support:

    • PKCE Support: New PKCE() and SetPKCE(enable) methods allow indicating if the PKCE flow is supported. This is currently configurable via the UI for OIDC providers.
    • Token Expiry: The OAuth2 user response now includes an optional expiry field containing the expiration time of the access token.
    • Multi-Collection Auth: A single OAuth2 user can now be used for authentication across multiple auth collections.
      • Note: Dao.FindExternalAuthByProvider(provider, providerId) was removed. Use the more generic Dao.FindFirstExternalAuthByExpr(expr) instead.

  7. Migrate from v0.7.x to v0.8.0

    master

    Version 0.8.0 introduced breaking changes by merging User models and the profiles collection into a unified 'auth' collection system. This allows for multiple auth collections with custom fields.

    Data Migration

    To migrate your database, use the upgrade command. Always back up your pb_data directory before proceeding.

    # 1. Backup your data
cp -r ./pb_data ./pb_data_backup

# 2. Run the upgrade command
./pocketbase08 upgrade

# 3. Start the application
./pocketbase08 serve

    What the upgrade command does:

    • Creates a new users collection by merging _users and profiles.
    • Converts user type fields to relation fields.
    • Updates filters: @collection.profiles.* and @request.user.* become @collection.users.* and @request.auth.*.
    • Appends 2 to schema field names and API filter rules that conflict with new system reserved names (e.g., collectionId becomes collectionId2).
    # make sure to have a copy of your pb_data in case something fails
cp -r ./pb_data ./pb_data_backup

# run the upgrade command
./pocketbase08 upgrade

# start the application as usual
./pocketbase08 serve

  9. Enable JavaScript app hooks via goja

    master

    PocketBase supports experimental JavaScript app hooks using the goja engine.

    Using the prebuilt executable: Simply create one or more *.pb.js files in the pb_hooks directory. These hooks are available by default.

    Using a custom Go build: If you are building PocketBase as a framework, you must manually register the jsvm plugin to enable dynamic scripting:

    jsvm.MustRegister(app core.App, config jsvm.Config{})

  10. Build PocketBase from source

    master

    To build a minimal standalone executable similar to the prebuilt releases, you can build the example base from the repository.

    Steps

    1. Install Go 1.25+.
    2. Clone the repository.
    3. Navigate to examples/base.
    4. Run the build command with your desired target architecture.
    5. Run the resulting binary with the serve command.

    Supported Build Targets (Pure Go SQLite driver)

    • Darwin: amd64, arm64
    • Linux: 386, amd64, arm, arm64, loong64, ppc64le, riscv64, s390x
    • FreeBSD: amd64, arm64
    • Windows: 386, amd64, arm64
    # Navigate to examples/base
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build
./base serve

  11. Migrate from Authentik to OpenID Connect (OIDC)

    master

    In v0.13.0, the Authentik integration was refactored into a generic "OpenID Connect" provider (oidc). This allows support for any OIDC provider (e.g., Okta, Keycloak).

    Migration Step: If you previously used Authentik, you must rename the provider key in your code to oidc. To enable multiple OIDC providers, use additional keys like oidc2 and oidc3.