pocketbase

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 3, 2024 License: MIT Imports: 17 Imported by: 0

README

PocketBase

Project

This repository contains community-maintained Go SDK for Pocketbase API. Not all endpoints are covered yet, if you need some particular endpoint or feature, please feel free to open a Pull Request. It's well-tested and used in production in:

Compatibility

  • v0.22.0 version of SDK is compatible with Pocketbase v0.22.x
  • v0.21.0 version of SDK is compatible with Pocketbase v0.21.x
  • v0.20.0 version of SDK is compatible with Pocketbase v0.20.x
  • v0.19.0 version of SDK is compatible with Pocketbase v0.19.x
  • v0.13.0 version of SDK is compatible with Pocketbase v0.13.x and higher
  • v0.12.0 version of SDK is compatible with Pocketbase v0.12.x
  • v0.11.0 version of SDK is compatible with Pocketbase v0.11.x
  • v0.10.1 version of SDK is compatible with Pocketbase v0.10.x
  • v0.9.2 version of SDK is compatible with Pocketbase v0.9.x (SSE & generics support introduced)
  • v0.8.0 version of SDK is compatible with Pocketbase v0.8.x

PocketBase

Pocketbase is a simple, self-hosted, open-source, no-code, database for your personal data. It's a great alternative to Airtable, Notion, and Google Sheets. Source code is available on GitHub

Currently supported operations

This SDK doesn't have feature parity with official SDKs and supports the following operations:

  • Authentication - anonymous, admin and user via email/password
  • Create
  • Update
  • Delete
  • List - with pagination, filtering, sorting
  • Backups - with create, restore, delete, upload, download and list all available downloads
  • Other - feel free to create an issue or contribute

Usage & examples

Simple list example without authentication (assuming your collections are public):

package main

import (
	"log"

	"github.com/pluja/pocketbase"
)

func main() {
	client := pocketbase.NewClient("http://localhost:8090")

	// You can list with pagination:
	response, err := client.List("posts_public", pocketbase.ParamsList{
		Page: 1, Size: 10, Sort: "-created", Filters: "field~'test'",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Print(response.TotalItems)

	// Or you can use the FullList method (v0.0.7)
	response, err := client.FullList("posts_public", pocketbase.ParamsList{
		Sort: "-created", Filters: "field~'test'",
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Print(response.TotalItems)
}

Creating an item with admin user (auth via email/pass). Please note that you can pass map[string]any or struct with JSON tags as a payload:

package main

import (
	"log"

	"github.com/pluja/pocketbase"
)

func main() {
	client := pocketbase.NewClient("http://localhost:8090", 
		pocketbase.WithAdminEmailPassword("admin@admin.com", "admin@admin.com"))
	response, err := client.Create("posts_admin", map[string]any{
		"field": "test",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Print(response.ID)
}

For even easier interaction with collection results as user-defined types, you can go with CollectionSet:

package main

import (
	"log"

	"github.com/pluja/pocketbase"
)

type post struct {
	ID      string
	Field   string
	Created string
}

func main() {
	client := pocketbase.NewClient("http://localhost:8090")
	collection := pocketbase.CollectionSet[post](client, "posts_public")

	// List with pagination
	response, err := collection.List(pocketbase.ParamsList{
		Page: 1, Size: 10, Sort: "-created", Filters: "field~'test'",
	})
	if err != nil {
		log.Fatal(err)
	}

	// FullList also available for collections:
	response, err := collection.FullList(pocketbase.ParamsList{
		Sort: "-created", Filters: "field~'test'",
	})
	if err != nil {
		log.Fatal(err)
	}
	
    log.Printf("%+v", response.Items)
}

Realtime API via Server-Sent Events (SSE) is also supported:

package main

import (
	"log"

	"github.com/pluja/pocketbase"
)

type post struct {
	ID      string
	Field   string
	Created string
}

func main() {
	client := pocketbase.NewClient("http://localhost:8090")
	collection := pocketbase.CollectionSet[post](client, "posts_public")
	response, err := collection.List(pocketbase.ParamsList{
		Page: 1, Size: 10, Sort: "-created", Filters: "field~'test'",
	})
	if err != nil {
		log.Fatal(err)
	}
	
	stream, err := collection.Subscribe()
	if err != nil {
		log.Fatal(err)
	}
	defer stream.Unsubscribe()
	<-stream.Ready()
	for ev := range stream.Events() {
		log.Print(ev.Action, ev.Record)
	}
}

You can fetch a single record by its ID using the One method to get the raw map, or the OneTo method to unmarshal directly into a custom struct.

Here's an example of fetching a single record as a map:

package main

import (
	"log"

	"github.com/pluja/pocketbase"
)

func main() {
	client := pocketbase.NewClient("http://localhost:8090")

	// Fetch a single record by ID
	record, err := client.One("posts_public", "record_id")
	if err != nil {
		log.Fatal(err)
	}

	// Access the record fields
	log.Print(record["field"])
}

You can fetch and unmarshal a single record directly into your custom struct using OneTo:

package main

import (
	"log"

	"github.com/pluja/pocketbase"
)

type Post struct {
	ID    string `json:"id"`
	Field string `json:"field"`
}

func main() {
	client := pocketbase.NewClient("http://localhost:8090")

	// Fetch a single record by ID and unmarshal into struct
	var post Post
	err := client.OneTo("posts", "post_id", &post)
	if err != nil {
		log.Fatal(err)
	}

	// Access the struct fields
	log.Printf("Fetched Post: %+v\n", post)
}

Trigger to create a new backup.

package main

import (
	"log"

	"github.com/pluja/pocketbase"
)

func main() {
	client := pocketbase.NewClient("http://localhost:8090", 
		pocketbase.WithAdminEmailPassword("admin@admin.com", "admin@admin.com"))
	err := client.Backup().Create("foobar.zip")
	if err != nil {
	    log.Println("create new backup failed")
		log.Fatal(err)
	}
}

Authenticate user from collection

package main

import (
	"log"

	"github.com/pluja/pocketbase"
)

type User struct {
	AuthProviders    []interface{} `json:"authProviders"`
	UsernamePassword bool          `json:"usernamePassword"`
	EmailPassword    bool          `json:"emailPassword"`
	OnlyVerified     bool          `json:"onlyVerified"`
}

func main() {
	client := pocketbase.NewClient("http://localhost:8090")
	response, err := pocketbase.CollectionSet[User](client, "users").AuthWithPassword("user", "user@user.com")
	if err != nil {
		log.Println("user-authentication failed")
		log.Fatal(err)
		return
	}
	log.Println("authentication successful")
	log.Printf("JWT-token: %s\n", response.Token)
}

More examples can be found in:

Development

Makefile targets

  • make serve - builds all binaries and runs local PocketBase server, it will create collections and sample data based on migration files
  • make test - runs tests (make sure that PocketBase server is running - make serve before)
  • make check - runs linters and security checks (run this before commit)
  • make build - builds all binaries (examples and PocketBase server)
  • make help - shows help and other targets

Contributing

  • Go 1.21+ (for making changes in the Go code)
  • While developing use WithDebug() client option to see HTTP requests and responses
  • Make sure that all checks are green (run make check before commit)
  • Make sure that all tests pass (run make test before commit)
  • Create a PR with your changes and wait for review

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalidResponse = errors.New("invalid response")

Functions

This section is empty.

Types

type AuthMethod added in v0.0.10 

type AuthMethod struct {
	AuthProviders    []AuthProvider `json:"authProviders"`
	UsernamePassword bool           `json:"usernamePassword"`
	EmailPassword    bool           `json:"emailPassword"`
	OnlyVerified     bool           `json:"onlyVerified"`
}

type AuthProvider added in v0.0.10 

type AuthProvider struct {
	Name                string `json:"name"`
	DisplayName         string `json:"displayName"`
	State               string `json:"state"`
	AuthURL             string `json:"authUrl"`
	CodeVerifier        string `json:"codeVerifier"`
	CodeChallenge       string `json:"codeChallenge"`
	CodeChallengeMethod string `json:"codeChallengeMethod"`
}

type AuthRefreshResponse added in v0.0.10 

type AuthRefreshResponse struct {
	Record struct {
		Avatar          string `json:"avatar"`
		CollectionID    string `json:"collectionId"`
		CollectionName  string `json:"collectionName"`
		Created         string `json:"created"`
		Email           string `json:"email"`
		EmailVisibility bool   `json:"emailVisibility"`
		ID              string `json:"id"`
		Name            string `json:"name"`
		Updated         string `json:"updated"`
		Username        string `json:"username"`
		Verified        bool   `json:"verified"`
	} `json:"record"`
	Token string `json:"token"`
}

type AuthWithOauth2Response added in v0.0.10 

type AuthWithOauth2Response struct {
	Token string `json:"token"`
}

type AuthWithPasswordResponse added in v0.0.10 

type AuthWithPasswordResponse struct {
	Record Record `json:"record"`
	Token  string `json:"token"`
}

type Backup added in v0.0.9 

type Backup struct {
	*Client
}

func (Backup) Create added in v0.0.9 

func (b Backup) Create(key ...string) error

Create initializes a new backup.

func (Backup) Delete added in v0.0.9 

func (b Backup) Delete(key string) error

Delete deletes a single backup file.

Example: 

file, _ := os.Open("./backups/pb_backup.zip")
defer file.Close()
_ = defaultClient.Backup().Upload("mybackup.zip", file)

func (Backup) FullList added in v0.0.9 

func (b Backup) FullList() ([]ResponseBackupFullList, error)

FullList returns list with all available backup files.

func (Backup) GetDownloadURL added in v0.0.9 

func (b Backup) GetDownloadURL(token string, key string) (string, error)

GetDownloadToken builds a download url for a single existing backup using an admin file token and the backup file key.

The file token can be generated via `client.Files().GetToken()`.

func (Backup) Restore added in v0.0.9 

func (b Backup) Restore(key string) error

Restore initializes an app data restore from an existing backup.

func (Backup) Upload added in v0.0.9 

func (b Backup) Upload(key string, reader io.Reader) error

Upload uploads an existing backup file.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(url string, opts ...ClientOption) *Client

func (*Client) AuthStore 

func (c *Client) AuthStore() authStore

func (*Client) Authorize 

func (c *Client) Authorize() error

func (*Client) Backup added in v0.0.9 

func (c *Client) Backup() Backup

func (*Client) Create 

func (c *Client) Create(collection string, body any) (ResponseCreate, error)

func (*Client) Delete 

func (c *Client) Delete(collection string, id string) error

func (*Client) Files added in v0.0.9 

func (c *Client) Files() Files

func (*Client) FullList added in v0.0.7 

func (c *Client) FullList(collection string, params ParamsList) (ResponseList[map[string]any], error)

func (*Client) List 

func (c *Client) List(collection string, params ParamsList) (ResponseList[map[string]any], error)

func (*Client) One added in v0.1.0 

func (c *Client) One(collection string, id string) (map[string]any, error)

func (*Client) OneTo added in v0.1.0 

func (c *Client) OneTo(collection string, id string, result any) error

func (*Client) Update 

func (c *Client) Update(collection string, id string, body any) error

type ClientOption 

type ClientOption func(*Client)

func WithAdminEmailPassword 

func WithAdminEmailPassword(email, password string) ClientOption

func WithAdminToken 

func WithAdminToken(token string) ClientOption

func WithDebug 

func WithDebug() ClientOption

func WithUserEmailPassword 

func WithUserEmailPassword(email, password string) ClientOption

func WithUserEmailPasswordAndCollection added in v0.0.8 

func WithUserEmailPasswordAndCollection(email, password, collection string) ClientOption

func WithUserToken 

func WithUserToken(token string) ClientOption

type Collection 

type Collection[T any] struct {
	*Client
	Name               string
	BaseCollectionPath string
}

func CollectionSet 

func CollectionSet[T any](client *Client, collection string) *Collection[T]

func (*Collection[T]) AuthRefresh added in v0.0.10 

func (c *Collection[T]) AuthRefresh() (AuthRefreshResponse, error)

AuthRefresh refreshes the current authenticated record instance and * returns a new token and record data.

func (*Collection[T]) AuthWithOAuth2Code added in v0.0.10 

func (c *Collection[T]) AuthWithOAuth2Code(provider string, code string, codeVerifier string, redirectURL string) (AuthWithOauth2Response, error)

AuthWithOAuth2Code authenticate a single auth collection record with OAuth2 code.

If you don't have an OAuth2 code you may also want to check `authWithOAuth2` method.

On success, this method also automatically updates the client's AuthStore data and returns: - the authentication token via the model - the authenticated record model - the OAuth2 account data (eg. name, email, avatar, etc.)

func (*Collection[T]) AuthWithPassword added in v0.0.10 

func (c *Collection[T]) AuthWithPassword(username string, password string) (AuthWithPasswordResponse, error)

AuthWithPassword authenticate a single auth collection record via its username/email and password.

On success, this method also automatically updates the client's AuthStore data and returns: - the authentication token via the AuthWithPasswordResponse - the authenticated record model

func (*Collection[T]) ConfirmEmailChange added in v0.0.10 

func (c *Collection[T]) ConfirmEmailChange(emailChangeToken string, password string) error

ConfirmEmailChange confirms auth record's new email address.

func (*Collection[T]) ConfirmPasswordReset added in v0.0.10 

func (c *Collection[T]) ConfirmPasswordReset(passwordResetToken string, password string, passwordConfirm string) error

ConfirmPasswordReset confirms auth record password reset request.

func (*Collection[T]) ConfirmVerification added in v0.0.10 

func (c *Collection[T]) ConfirmVerification(verificationToken string) error

ConfirmVerification confirms auth record email verification request.

If the current `client.authStore.model` matches with the auth record from the token, then on success the `client.authStore.model.verified` will be updated to `true`.

func (*Collection[T]) Create 

func (c *Collection[T]) Create(body T) (ResponseCreate, error)

func (*Collection[T]) Delete 

func (c *Collection[T]) Delete(id string) error

func (*Collection[T]) FullList added in v0.0.7 

func (c *Collection[T]) FullList(params ParamsList) (ResponseList[T], error)

func (*Collection[T]) List 

func (c *Collection[T]) List(params ParamsList) (ResponseList[T], error)

func (*Collection[T]) ListAuthMethods added in v0.0.10 

func (c *Collection[T]) ListAuthMethods() (AuthMethod, error)

ListAuthMethods returns all available collection auth methods.

func (*Collection[T]) ListExternalAuths added in v0.0.10 

func (c *Collection[T]) ListExternalAuths(recordID string) ([]ExternalAuthRequest, error)

ListExternalAuths lists all linked external auth providers for the specified auth record.

func (*Collection[T]) One 

func (c *Collection[T]) One(id string) (T, error)

func (*Collection[T]) OneWithParams added in v0.0.6 

func (c *Collection[T]) OneWithParams(id string, params ParamsList) (T, error)

Get one record with params (only fields and expand supported)

func (*Collection[T]) RequestEmailChange added in v0.0.10 

func (c *Collection[T]) RequestEmailChange(newEmail string) error

RequestEmailChange sends an email change request to the authenticated record model.

func (*Collection[T]) RequestPasswordReset added in v0.0.10 

func (c *Collection[T]) RequestPasswordReset(email string) error

RequestPasswordReset sends auth record password reset request

func (*Collection[T]) RequestVerification added in v0.0.10 

func (c *Collection[T]) RequestVerification(email string) error

RequestVerification sends auth record verification email request.

func (*Collection[T]) Subscribe 

func (c *Collection[T]) Subscribe(targets ...string) (*Stream[T], error)

func (*Collection[T]) SubscribeWith 

func (c *Collection[T]) SubscribeWith(opts SubscribeOptions, targets ...string) (*Stream[T], error)

func (*Collection[T]) UnlinkExternalAuth added in v0.0.10 

func (c *Collection[T]) UnlinkExternalAuth(recordID string, provider string) error

UnlinkExternalAuth unlink a single external auth provider from the specified auth record.

func (*Collection[T]) Update 

func (c *Collection[T]) Update(id string, body T) error

type CreateRequest added in v0.0.9 

type CreateRequest struct {
	Name string `json:"name"`
}

type Event 

type Event[T any] struct {
	Action string `json:"action"`
	Record T      `json:"record"`
	Error  error  `json:"-"`
}

type ExternalAuthRequest added in v0.0.10 

type ExternalAuthRequest struct {
	ID           string `json:"id"`
	Created      string `json:"created"`
	Updated      string `json:"updated"`
	RecordID     string `json:"recordId"`
	CollectionID string `json:"collectionId"`
	Provider     string `json:"provider"`
	ProviderID   string `json:"providerId"`
}

type Files added in v0.0.9 

type Files struct {
	*Client
}

func (Files) GetToken added in v0.0.9 

func (f Files) GetToken() (string, error)

GetToken requests a new private file access token for the current auth model (admin or record).

type ParamsList 

type ParamsList struct {
	Page    int
	Size    int
	Filters string
	Sort    string
	Expand  string
	Fields  string
	// contains filtered or unexported fields
}

type Record added in v0.0.10 

type Record struct {
	Avatar          string `json:"avatar"`
	CollectionID    string `json:"collectionId"`
	CollectionName  string `json:"collectionName"`
	Created         string `json:"created"`
	Email           string `json:"email"`
	EmailVisibility bool   `json:"emailVisibility"`
	ID              string `json:"id"`
	Name            string `json:"name"`
	Updated         string `json:"updated"`
	Username        string `json:"username"`
	Verified        bool   `json:"verified"`
}

type ResponseBackupFullList added in v0.0.9 

type ResponseBackupFullList struct {
	Key      string `json:"key"`
	Size     int    `json:"size"`
	Modified string `json:"modified"`
}

type ResponseCreate 

type ResponseCreate struct {
	ID      string `json:"id"`
	Created string `json:"created"`
	Field   string `json:"field"`
	Updated string `json:"updated"`
}

type ResponseGetToken added in v0.0.9 

type ResponseGetToken struct {
	Token string `json:"token"`
}

type ResponseList 

type ResponseList[T any] struct {
	Page       int `json:"page"`
	PerPage    int `json:"perPage"`
	TotalItems int `json:"totalItems"`
	TotalPages int `json:"totalPages"`
	Items      []T `json:"items"`
}

type Stream 

type Stream[T any] struct {
	// contains filtered or unexported fields
}

func (*Stream[T]) Events 

func (s *Stream[T]) Events() <-chan Event[T]

func (*Stream[T]) Ready 

func (s *Stream[T]) Ready() <-chan struct{}

func (*Stream[T]) Unsubscribe 

func (s *Stream[T]) Unsubscribe()

func (*Stream[T]) WaitAuthReady deprecated 

func (s *Stream[T]) WaitAuthReady() error

Deprecated: use <-stream.Ready() instead of

type SubscribeOptions 

type SubscribeOptions struct {
	ReconnectStrategy backoff.BackOff
}

type SubscriptionsSet 

type SubscriptionsSet struct {
	ClientID      string   `json:"clientId"`
	Subscriptions []string `json:"subscriptions"`
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
pocketbase

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.