pocketbase

package module
v0.0.0-...-04f853e Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2024 License: MIT Imports: 17 Imported by: 0

README

PocketBase Go SDK

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

Sample 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

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 <<<<<<< HEAD
  • Backupd - with create, restore, delete, upload, download and list all available downloads =======
  • Backups - with create, restore, delete, upload, download and list all available downloads

upstream/master

  • Other - feel free to create an issue or contribute

Usage and Examples

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

package main

import (
	"log"

	"github.com/habibrosyad/pocketbase-go-sdk"
)

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/habibrosyad/pocketbase-go-sdk"
)

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/habibrosyad/pocketbase-go-sdk"
)

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/habibrosyad/pocketbase-go-sdk"
)

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/habibrosyad/pocketbase-go-sdk"
)

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/habibrosyad/pocketbase-go-sdk"
)

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/habibrosyad/pocketbase-go-sdk"
)

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/habibrosyad/pocketbase-go-sdk"
)

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 

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

type AuthProvider 

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 

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 

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

type AuthWithPasswordResponse 

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

type Backup 

type Backup struct {
	*Client
}

func (Backup) Create 

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

Create initializes a new backup.

func (Backup) Delete 

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 

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

FullList returns list with all available backup files.

func (Backup) GetDownloadURL 

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 

func (b Backup) Restore(key string) error

Restore initializes an app data restore from an existing backup.

func (Backup) Upload 

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 

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 

func (c *Client) Files() Files

func (*Client) FullList 

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 

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

func (*Client) OneTo 

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

func (*Client) Settings 

func (c *Client) Settings() Settings

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 

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 

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 

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 

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 

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

ConfirmEmailChange confirms auth record's new email address.

func (*Collection[T]) ConfirmPasswordReset 

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

ConfirmPasswordReset confirms auth record password reset request.

func (*Collection[T]) ConfirmVerification 

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 

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 

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

ListAuthMethods returns all available collection auth methods.

func (*Collection[T]) ListExternalAuths 

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 

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 

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

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

func (*Collection[T]) RequestPasswordReset 

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

RequestPasswordReset sends auth record password reset request

func (*Collection[T]) RequestVerification 

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 

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 

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

type EmailTemplate 

type EmailTemplate struct {
	Body    string `json:"body"`
	Subject string `json:"subject"`
}

type Event 

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

type ExternalAuthRequest 

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 

type Files struct {
	*Client
}

func (Files) GetToken 

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

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

type MetaConfig 

type MetaConfig struct {
	AppName                    string        `json:"appName"`
	AppUrl                     string        `json:"appUrl"`
	SenderName                 string        `json:"senderName"`
	SenderAddress              string        `json:"senderAddress"`
	VerificationTemplate       EmailTemplate `json:"verificationTemplate"`
	ResetPasswordTemplate      EmailTemplate `json:"resetPasswordTemplate"`
	ConfirmEmailChangeTemplate EmailTemplate `json:"confirmEmailChangeTemplate"`
}

type ParamsList 

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

type Record 

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 

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 

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 ResponseSettingsAll 

type ResponseSettingsAll struct {
	Meta *MetaConfig `json:"meta"`
	Smtp *SmtpConfig `json:"smtp"`
}

type Settings 

type Settings struct {
	*Client
}

func (Settings) All 

func (s Settings) All() (ResponseSettingsAll, error)

All returns all settings.

func (Settings) Update 

func (s Settings) Update(body any) (ResponseSettingsAll, error)

type SmtpConfig 

type SmtpConfig struct {
	Enabled    bool   `json:"enabled"`
	Host       string `host:"host"`
	Port       int    `json:"port"`
	Username   string `json:"username"`
	Password   string `json:"password"`
	Tls        bool   `json:"tls"`
	AuthMethod string `json:"authMethod"`
	LocalName  string `json:"localName"`
}

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.