daos

package
v0.0.0-...-710d95f Latest Latest
Warning

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

Go to latest
Published: Sep 16, 2023 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package daos handles common PocketBase DB model manipulations.

Think of daos as DB repository and service layer in one.

Index

Constants

View Source
const MaxExpandDepth = 6

MaxExpandDepth specifies the max allowed nested expand depth path.

Variables

This section is empty.

Functions

This section is empty.

Types

type Dao

type Dao struct {

	// MaxLockRetries specifies the default max "database is locked" auto retry attempts.
	MaxLockRetries int

	// ModelQueryTimeout is the default max duration of a running ModelQuery().
	//
	// This field has no effect if an explicit query context is already specified.
	ModelQueryTimeout time.Duration

	// write hooks
	BeforeCreateFunc func(eventDao *Dao, m models.Model, action func() error) error
	AfterCreateFunc  func(eventDao *Dao, m models.Model) error
	BeforeUpdateFunc func(eventDao *Dao, m models.Model, action func() error) error
	AfterUpdateFunc  func(eventDao *Dao, m models.Model) error
	BeforeDeleteFunc func(eventDao *Dao, m models.Model, action func() error) error
	AfterDeleteFunc  func(eventDao *Dao, m models.Model) error
	// contains filtered or unexported fields
}

Dao handles various db operations.

You can think of Dao as a repository and service layer in one.

func New

func New(db dbx.Builder) *Dao

New creates a new Dao instance with the provided db builder (for both async and sync db operations).

func NewMultiDB

func NewMultiDB(concurrentDB, nonconcurrentDB dbx.Builder) *Dao

New creates a new Dao instance with the provided dedicated async and sync db builders.

func (*Dao) AdminQuery

func (dao *Dao) AdminQuery() *dbx.SelectQuery

AdminQuery returns a new Admin select query.

func (*Dao) CanAccessRecord

func (dao *Dao) CanAccessRecord(record *models.Record, requestInfo *models.RequestInfo, accessRule *string) (bool, error)

CanAccessRecord checks if a record is allowed to be accessed by the specified requestInfo and accessRule.

Rule and db checks are ignored in case requestInfo.Admin is set.

The returned error indicate that something unexpected happened during the check (eg. invalid rule or db error).

The method always return false on invalid access rule or db error.

Example:

requestInfo := apis.RequestInfo(c /* echo.Context */)
record, _ := dao.FindRecordById("example", "RECORD_ID")
rule := types.Pointer("@request.auth.id != '' || status = 'public'")
// ... or use one of the record collection's rule, eg. record.Collection().ViewRule

if ok, _ := dao.CanAccessRecord(record, requestInfo, rule); ok { ... }

func (*Dao) Clone

func (dao *Dao) Clone() *Dao

Clone returns a new Dao with the same configuration options as the current one.

func (*Dao) CollectionQuery

func (dao *Dao) CollectionQuery() *dbx.SelectQuery

CollectionQuery returns a new Collection select query.

func (*Dao) ConcurrentDB

func (dao *Dao) ConcurrentDB() dbx.Builder

ConcurrentDB returns the dao concurrent (aka. multiple open connections) db builder (*dbx.DB or *dbx.TX).

In a transaction the concurrentDB and nonconcurrentDB refer to the same *dbx.TX instance.

func (*Dao) CreateViewSchema

func (dao *Dao) CreateViewSchema(selectQuery string) (schema.Schema, error)

CreateViewSchema creates a new view schema from the provided select query.

There are some caveats: - The select query must have an "id" column. - Wildcard ("*") columns are not supported to avoid accidentally leaking sensitive data.

func (*Dao) DB

func (dao *Dao) DB() dbx.Builder

DB returns the default dao db builder (*dbx.DB or *dbx.TX).

Currently the default db builder is dao.concurrentDB but that may change in the future.

func (*Dao) Delete

func (dao *Dao) Delete(m models.Model) error

Delete deletes the provided model.

func (*Dao) DeleteAdmin

func (dao *Dao) DeleteAdmin(admin *models.Admin) error

DeleteAdmin deletes the provided Admin model.

Returns an error if there is only 1 admin.

func (*Dao) DeleteCollection

func (dao *Dao) DeleteCollection(collection *models.Collection) error

DeleteCollection deletes the provided Collection model. This method automatically deletes the related collection records table.

NB! The collection cannot be deleted, if: - is system collection (aka. collection.System is true) - is referenced as part of a relation field in another collection

func (*Dao) DeleteExternalAuth

func (dao *Dao) DeleteExternalAuth(model *models.ExternalAuth) error

DeleteExternalAuth deletes the provided ExternalAuth model.

func (*Dao) DeleteOldRequests

func (dao *Dao) DeleteOldRequests(createdBefore time.Time) error

DeleteOldRequests delete all requests that are created before createdBefore.

func (*Dao) DeleteParam

func (dao *Dao) DeleteParam(param *models.Param) error

DeleteParam deletes the provided Param model.

func (*Dao) DeleteRecord

func (dao *Dao) DeleteRecord(record *models.Record) error

DeleteRecord deletes the provided Record model.

This method will also cascade the delete operation to all linked relational records (delete or unset, depending on the rel settings).

The delete operation may fail if the record is part of a required reference in another record (aka. cannot be deleted or unset).

func (*Dao) DeleteTable

func (dao *Dao) DeleteTable(tableName string) error

DeleteTable drops the specified table.

This method is a no-op if a table with the provided name doesn't exist.

Be aware that this method is vulnerable to SQL injection and the "tableName" argument must come only from trusted input!

func (*Dao) DeleteView

func (dao *Dao) DeleteView(name string) error

DeleteView drops the specified view name.

This method is a no-op if a view with the provided name doesn't exist.

Be aware that this method is vulnerable to SQL injection and the "name" argument must come only from trusted input!

func (*Dao) ExpandRecord

func (dao *Dao) ExpandRecord(record *models.Record, expands []string, optFetchFunc ExpandFetchFunc) map[string]error

ExpandRecord expands the relations of a single Record model.

If optFetchFunc is not set, then a default function will be used that returns all relation records.

Returns a map with the failed expand parameters and their errors.

func (*Dao) ExpandRecords

func (dao *Dao) ExpandRecords(records []*models.Record, expands []string, optFetchFunc ExpandFetchFunc) map[string]error

ExpandRecords expands the relations of the provided Record models list.

If optFetchFunc is not set, then a default function will be used that returns all relation records.

Returns a map with the failed expand parameters and their errors.

func (*Dao) ExternalAuthQuery

func (dao *Dao) ExternalAuthQuery() *dbx.SelectQuery

ExternalAuthQuery returns a new ExternalAuth select query.

func (*Dao) FindAdminByEmail

func (dao *Dao) FindAdminByEmail(email string) (*models.Admin, error)

FindAdminByEmail finds the admin with the provided email address.

func (*Dao) FindAdminById

func (dao *Dao) FindAdminById(id string) (*models.Admin, error)

FindAdminById finds the admin with the provided id.

func (*Dao) FindAdminByToken

func (dao *Dao) FindAdminByToken(token string, baseTokenKey string) (*models.Admin, error)

FindAdminByToken finds the admin associated with the provided JWT token.

Returns an error if the JWT token is invalid or expired.

func (*Dao) FindAllExternalAuthsByRecord

func (dao *Dao) FindAllExternalAuthsByRecord(authRecord *models.Record) ([]*models.ExternalAuth, error)

FindAllExternalAuthsByRecord returns all ExternalAuth models linked to the provided auth record.

func (*Dao) FindAuthRecordByEmail

func (dao *Dao) FindAuthRecordByEmail(collectionNameOrId string, email string) (*models.Record, error)

FindAuthRecordByEmail finds the auth record associated with the provided email.

Returns an error if it is not an auth collection or the record is not found.

func (*Dao) FindAuthRecordByToken

func (dao *Dao) FindAuthRecordByToken(token string, baseTokenKey string) (*models.Record, error)

FindAuthRecordByToken finds the auth record associated with the provided JWT token.

Returns an error if the JWT token is invalid, expired or not associated to an auth collection record.

func (*Dao) FindAuthRecordByUsername

func (dao *Dao) FindAuthRecordByUsername(collectionNameOrId string, username string) (*models.Record, error)

FindAuthRecordByUsername finds the auth record associated with the provided username (case insensitive).

Returns an error if it is not an auth collection or the record is not found.

func (*Dao) FindById

func (dao *Dao) FindById(m models.Model, id string) error

FindById finds a single db record with the specified id and scans the result into m.

func (*Dao) FindCollectionByNameOrId

func (dao *Dao) FindCollectionByNameOrId(nameOrId string) (*models.Collection, error)

FindCollectionByNameOrId finds a single collection by its name (case insensitive) or id.

func (*Dao) FindCollectionReferences

func (dao *Dao) FindCollectionReferences(collection *models.Collection, excludeIds ...string) (map[*models.Collection][]*schema.SchemaField, error)

FindCollectionReferences returns information for all relation schema fields referencing the provided collection.

If the provided collection has reference to itself then it will be also included in the result. To exclude it, pass the collection id as the excludeId argument.

func (*Dao) FindCollectionsByType

func (dao *Dao) FindCollectionsByType(collectionType string) ([]*models.Collection, error)

FindCollectionsByType finds all collections by the given type.

func (*Dao) FindExternalAuthByProvider

func (dao *Dao) FindExternalAuthByProvider(provider, providerId string) (*models.ExternalAuth, error)

FindExternalAuthByProvider returns the first available ExternalAuth model for the specified provider and providerId.

func (*Dao) FindExternalAuthByRecordAndProvider

func (dao *Dao) FindExternalAuthByRecordAndProvider(authRecord *models.Record, provider string) (*models.ExternalAuth, error)

FindExternalAuthByRecordAndProvider returns the first available ExternalAuth model for the specified record data and provider.

func (*Dao) FindFirstRecordByData

func (dao *Dao) FindFirstRecordByData(
	collectionNameOrId string,
	key string,
	value any,
) (*models.Record, error)

FindFirstRecordByData returns the first found record matching the provided key-value pair.

func (*Dao) FindFirstRecordByFilter

func (dao *Dao) FindFirstRecordByFilter(
	collectionNameOrId string,
	filter string,
	params ...dbx.Params,
) (*models.Record, error)

FindFirstRecordByFilter returns the first available record matching the provided filter.

NB! Use the last params argument to bind untrusted user variables!

Example:

dao.FindFirstRecordByFilter("posts", "slug={:slug} && status='public'", dbx.Params{"slug": "test"})

func (*Dao) FindParamByKey

func (dao *Dao) FindParamByKey(key string) (*models.Param, error)

FindParamByKey finds the first Param model with the provided key.

func (*Dao) FindRecordById

func (dao *Dao) FindRecordById(
	collectionNameOrId string,
	recordId string,
	optFilters ...func(q *dbx.SelectQuery) error,
) (*models.Record, error)

FindRecordById finds the Record model by its id.

func (*Dao) FindRecordByViewFile

func (dao *Dao) FindRecordByViewFile(
	viewCollectionNameOrId string,
	fileFieldName string,
	filename string,
) (*models.Record, error)

FindRecordByViewFile returns the original models.Record of the provided view collection file.

func (*Dao) FindRecordsByExpr

func (dao *Dao) FindRecordsByExpr(collectionNameOrId string, exprs ...dbx.Expression) ([]*models.Record, error)

@todo consider to depricate as it may be easier to just use dao.RecordQuery()

FindRecordsByExpr finds all records by the specified db expression.

Returns all collection records if no expressions are provided.

Returns an empty slice if no records are found.

Example:

expr1 := dbx.HashExp{"email": "test@example.com"}
expr2 := dbx.NewExp("LOWER(username) = {:username}", dbx.Params{"username": "test"})
dao.FindRecordsByExpr("example", expr1, expr2)

func (*Dao) FindRecordsByFilter

func (dao *Dao) FindRecordsByFilter(
	collectionNameOrId string,
	filter string,
	sort string,
	limit int,
	offset int,
	params ...dbx.Params,
) ([]*models.Record, error)

FindRecordsByFilter returns limit number of records matching the provided string filter.

NB! Use the last "params" argument to bind untrusted user variables!

The sort argument is optional and can be empty string OR the same format used in the web APIs, eg. "-created,title".

If the limit argument is <= 0, no limit is applied to the query and all matching records are returned.

Example:

dao.FindRecordsByFilter(
	"posts",
	"title ~ {:title} && visible = {:visible}",
	"-created",
	10,
	0,
	dbx.Params{"title": "lorem ipsum", "visible": true}
)

func (*Dao) FindRecordsByIds

func (dao *Dao) FindRecordsByIds(
	collectionNameOrId string,
	recordIds []string,
	optFilters ...func(q *dbx.SelectQuery) error,
) ([]*models.Record, error)

FindRecordsByIds finds all Record models by the provided ids. If no records are found, returns an empty slice.

func (*Dao) FindRequestById

func (dao *Dao) FindRequestById(id string) (*models.Request, error)

FindRequestById finds a single Request log by its id.

func (*Dao) FindSettings

func (dao *Dao) FindSettings(optEncryptionKey ...string) (*settings.Settings, error)

FindSettings returns and decode the serialized app settings param value.

The method will first try to decode the param value without decryption. If it fails and optEncryptionKey is set, it will try again by first decrypting the value and then decode it again.

Returns an error if it fails to decode the stored serialized param value.

func (*Dao) HasTable

func (dao *Dao) HasTable(tableName string) bool

HasTable checks if a table (or view) with the provided name exists (case insensitive).

func (*Dao) ImportCollections

func (dao *Dao) ImportCollections(
	importedCollections []*models.Collection,
	deleteMissing bool,
	afterSync func(txDao *Dao, mappedImported, mappedExisting map[string]*models.Collection) error,
) error

ImportCollections imports the provided collections list within a single transaction.

NB1! If deleteMissing is set, all local collections and schema fields, that are not present in the imported configuration, WILL BE DELETED (including their related records data).

NB2! This method doesn't perform validations on the imported collections data! If you need validations, use [forms.CollectionsImport].

func (*Dao) IsAdminEmailUnique

func (dao *Dao) IsAdminEmailUnique(email string, excludeIds ...string) bool

IsAdminEmailUnique checks if the provided email address is not already in use by other admins.

func (*Dao) IsCollectionNameUnique

func (dao *Dao) IsCollectionNameUnique(name string, excludeIds ...string) bool

IsCollectionNameUnique checks that there is no existing collection with the provided name (case insensitive!).

Note: case insensitive check because the name is used also as a table name for the records.

func (*Dao) IsRecordValueUnique

func (dao *Dao) IsRecordValueUnique(
	collectionNameOrId string,
	key string,
	value any,
	excludeIds ...string,
) bool

IsRecordValueUnique checks if the provided key-value pair is a unique Record value.

For correctness, if the collection is "auth" and the key is "username", the unique check will be case insensitive.

NB! Array values (eg. from multiple select fields) are matched as a serialized json strings (eg. `["a","b"]`), so the value uniqueness depends on the elements order. Or in other words the following values are considered different: `[]string{"a","b"}` and `[]string{"b","a"}`

func (*Dao) ModelQuery

func (dao *Dao) ModelQuery(m models.Model) *dbx.SelectQuery

ModelQuery creates a new preconfigured select query with preset SELECT, FROM and other common fields based on the provided model.

func (*Dao) NonconcurrentDB

func (dao *Dao) NonconcurrentDB() dbx.Builder

NonconcurrentDB returns the dao nonconcurrent (aka. single open connection) db builder (*dbx.DB or *dbx.TX).

In a transaction the concurrentDB and nonconcurrentDB refer to the same *dbx.TX instance.

func (*Dao) ParamQuery

func (dao *Dao) ParamQuery() *dbx.SelectQuery

ParamQuery returns a new Param select query.

func (*Dao) RecordQuery

func (dao *Dao) RecordQuery(collectionModelOrIdentifier any) *dbx.SelectQuery

RecordQuery returns a new Record select query from a collection model, id or name.

In case a collection id or name is provided and that collection doesn't actually exists, the generated query will be created with a cancelled context and will fail once an executor (Row(), One(), All(), etc.) is called.

func (*Dao) RequestQuery

func (dao *Dao) RequestQuery() *dbx.SelectQuery

RequestQuery returns a new Request logs select query.

func (*Dao) RequestsStats

func (dao *Dao) RequestsStats(expr dbx.Expression) ([]*RequestsStatsItem, error)

RequestsStats returns hourly grouped requests logs statistics.

func (*Dao) RunInTransaction

func (dao *Dao) RunInTransaction(fn func(txDao *Dao) error) error

RunInTransaction wraps fn into a transaction.

It is safe to nest RunInTransaction calls as long as you use the txDao.

func (*Dao) Save

func (dao *Dao) Save(m models.Model) error

Save persists the provided model in the database.

If m.IsNew() is true, the method will perform a create, otherwise an update. To explicitly mark a model for update you can use m.MarkAsNotNew().

func (*Dao) SaveAdmin

func (dao *Dao) SaveAdmin(admin *models.Admin) error

SaveAdmin upserts the provided Admin model.

func (*Dao) SaveCollection

func (dao *Dao) SaveCollection(collection *models.Collection) error

SaveCollection persists the provided Collection model and updates its related records table schema.

If collecction.IsNew() is true, the method will perform a create, otherwise an update. To explicitly mark a collection for update you can use collecction.MarkAsNotNew().

func (*Dao) SaveExternalAuth

func (dao *Dao) SaveExternalAuth(model *models.ExternalAuth) error

SaveExternalAuth upserts the provided ExternalAuth model.

func (*Dao) SaveParam

func (dao *Dao) SaveParam(key string, value any, optEncryptionKey ...string) error

SaveParam creates or updates a Param model by the provided key-value pair. The value argument will be encoded as json string.

If `optEncryptionKey` is provided it will encrypt the value before storing it.

func (*Dao) SaveRecord

func (dao *Dao) SaveRecord(record *models.Record) error

SaveRecord persists the provided Record model in the database.

If record.IsNew() is true, the method will perform a create, otherwise an update. To explicitly mark a record for update you can use record.MarkAsNotNew().

func (*Dao) SaveRequest

func (dao *Dao) SaveRequest(request *models.Request) error

SaveRequest upserts the provided Request model.

func (*Dao) SaveSettings

func (dao *Dao) SaveSettings(newSettings *settings.Settings, optEncryptionKey ...string) error

SaveSettings persists the specified settings configuration.

If optEncryptionKey is set, then the stored serialized value will be encrypted with it.

func (*Dao) SaveView

func (dao *Dao) SaveView(name string, selectQuery string) error

SaveView creates (or updates already existing) persistent SQL view.

Be aware that this method is vulnerable to SQL injection and the "selectQuery" argument must come only from trusted input!

func (*Dao) SuggestUniqueAuthRecordUsername

func (dao *Dao) SuggestUniqueAuthRecordUsername(
	collectionNameOrId string,
	baseUsername string,
	excludeIds ...string,
) string

SuggestUniqueAuthRecordUsername checks if the provided username is unique and return a new "unique" username with appended random numeric part (eg. "existingName" -> "existingName583").

The same username will be returned if the provided string is already unique.

func (*Dao) SyncRecordTableSchema

func (dao *Dao) SyncRecordTableSchema(newCollection *models.Collection, oldCollection *models.Collection) error

SyncRecordTableSchema compares the two provided collections and applies the necessary related record table changes.

If `oldCollection` is null, then only `newCollection` is used to create the record table.

func (*Dao) TableColumns

func (dao *Dao) TableColumns(tableName string) ([]string, error)

TableColumns returns all column names of a single table by its name.

func (*Dao) TableIndexes

func (dao *Dao) TableIndexes(tableName string) (map[string]string, error)

TableIndexes returns a name grouped map with all non empty index of the specified table.

Note: This method doesn't return an error on nonexisting table.

func (*Dao) TableInfo

func (dao *Dao) TableInfo(tableName string) ([]*models.TableInfoRow, error)

TableInfo returns the `table_info` pragma result for the specified table.

func (*Dao) TotalAdmins

func (dao *Dao) TotalAdmins() (int, error)

TotalAdmins returns the number of existing admin records.

func (*Dao) Vacuum

func (dao *Dao) Vacuum() error

Vacuum executes VACUUM on the current dao.DB() instance in order to reclaim unused db disk space.

func (*Dao) WithoutHooks

func (dao *Dao) WithoutHooks() *Dao

WithoutHooks returns a new Dao with the same configuration options as the current one, but without create/update/delete hooks.

type ExpandFetchFunc

type ExpandFetchFunc func(relCollection *models.Collection, relIds []string) ([]*models.Record, error)

ExpandFetchFunc defines the function that is used to fetch the expanded relation records.

type RequestsStatsItem

type RequestsStatsItem struct {
	Total int            `db:"total" json:"total"`
	Date  types.DateTime `db:"date" json:"date"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL