accessory

README

go-accessory

accessory is a database client for communication with supported database servers, and some patterns for using databases in a multi-threaded and multi-host environment.

It provides a simple binding with go structures.

Database Connections

There are currently two implementations of a database connection. They are:

• MongoDB
• sqlite

Both are "in development" and require testing. In order to create a direct database connection, use one of these:

Import	Constructor	Description
github.com/mutablelogic/go-accessory/pkg/mongodb	mongodb.New(ctx, url, opts...)	Create a MongoDB connection to a remote server
github.com/mutablelogic/go-accessory/pkg/sqlite	sqlite.New(ctx, url, opts...)	Open a sqlite connection to file or in-memory database

In either case, the url is a string that is parsed by the database driver, which should be of scheme mongodb://, mongodb+srv://, file:// or sqlite://. The opts are a list of options that are passed to the database driver (see the documentation for the driver for details).

Mapping Collections to Structures

TODO

Database Operations

TODO

Connection Pools

TODO

Task Queues

TODO

Documentation

Index

• type Auth
• type AuthToken
• type Collection
• type Conn
• type CreateTable
• type Cursor
• type Database
• type Filter
• type Name
• type Pool
• type Query
• type QueryFlag
  • func (v QueryFlag) FlagString() string
  • func (v QueryFlag) Is(f QueryFlag) bool
  • func (v QueryFlag) String() string
• type Sort
• type Tag
  • func (t Tag) String() string
• type TagType
• type Task
• type TaskQueue
• type WorkerFunc

Types

type Auth

type Auth interface {
	// Auth implements the connection pool
	Pool

	// Create a new byte16 token with the given name, token duration and scopes
	CreateByte16(context.Context, string, time.Duration, ...string) (string, error)

	// List returns all tokens in access order, with the latest token accessed first
	List(context.Context, func(AuthToken)) error

	// Expire a token with the given name. When argument is set to
	// true, the token is deleted from the database, otherwise it is disabled
	Expire(context.Context, string, bool) error

	// Return no error if the token with the given name exists and not expired,
	// and has one of the given scopes. Returns ErrNotFound if the token
	// with the given name does not exist, ErrExpired if the token has
	// expired, or ErrUnauthorized if the token does not have any of the
	// given scopes.
	Valid(context.Context, string, ...string) error

	// ValidByValue returns the name of a token with the given value, and
	// if any of the scopes match. It will return ErrNotFound if no token
	// with the given value exists, ErrExpired if the token has expired or
	// ErrNotAuthorized if the token does not have any of the given scopes. It
	// updates the access_at field of the token if found
	ValidByValue(context.Context, string, ...string) (string, error)

	// UpdateExpiry updates the duration of a token's life with the given name,
	// or removes the expiry if duration is 0 and updates the access_at field
	// of the token
	UpdateExpiry(context.Context, string, time.Duration) error

	// UpdateScope sets the scopes of a token with the given name and updates
	// the access_at field of the token
	UpdateScope(context.Context, string, ...string) error
}

Auth represents authorzation storage

type AuthToken

type AuthToken interface {
	// Return the name of the token
	Name() string

	// Return the token type (currently only 'byte16' is supported)
	Type() string

	// Return the scopes of the token
	Scope() []string

	// Return the last access time for the token
	AccessAt() time.Time

	// Return the expiry time for the token, or time.Zero if there
	// is no expiry
	ExpireAt() time.Time

	// Return ErrExpired if the token has expired, or ErrNotAuthorized if
	// any given scopes are not in the token's scopes. Otherwise return nil
	Valid(...string) error
}

AuthToken represents an authorization token

type Collection

type Collection interface {
	// Return the name of the collection
	Name() string

	// Delete zero or one documents and returns the number of deleted documents (which should be
	// zero or one. The filter argument is used to determine a document to delete. If there is more than
	// one filter, they are ANDed together
	Delete(context.Context, ...Filter) (int64, error)

	// DeleteMany deletes zero or more documents and returns the number of deleted documents.
	DeleteMany(context.Context, ...Filter) (int64, error)

	// Find selects a single document based on filter and sort parameters.
	// It returns ErrNotFound if no document is found
	Find(context.Context, Sort, ...Filter) (any, error)

	// FindMany returns an iterable cursor based on filter and sort parameters.
	// It returns ErrNotFound if no document is found
	FindMany(context.Context, Sort, ...Filter) (Cursor, error)

	// Update zero or one document with given values and return the number
	// of documents matched and modified, neither of which should be more than one.
	Update(context.Context, any, ...Filter) (int64, int64, error)

	// Update zero or more document with given values and return the number
	// of documents matched and modified, neither of which should be more than one.
	UpdateMany(context.Context, any, ...Filter) (int64, int64, error)

	// FindUpdate selects a single document based on filter and sort parameters,
	// updates the document with the given values and returns the document as it appeared
	// before updating, or ErrNotFound if no document is found and updated.
	FindUpdate(context.Context, any, Sort, ...Filter) (any, error)
}

type Conn

type Conn interface {
	io.Closer

	// You can call all database operations on the client instance, which will
	// use the default database or return an error if no default database
	// is set
	Database

	// Return the default timeout for the client
	Timeout() time.Duration

	// Ping the client, return an error if not reachable
	Ping(context.Context) error

	// Return a database object for a specific database
	Database(string) Database

	// Return all existing databases on the server
	Databases(context.Context) ([]Database, error)

	// Perform operations within a transaction. Rollback or apply
	// changes to the database depending on error return.
	Do(context.Context, func(context.Context) error) error

	// Return a filter specification
	F() Filter

	// Return a sort specification
	S() Sort
}

Conn represents a connection to a database server. Open a connection to the client with

mongodb.Open(context.Context, string, ...ClientOpt) (Client, error)

which returns a client object. The client options can be used to set the default database:

clientopt := mongodb.WithDatabase(string)

You can set the operation timeout using the following option:

clientopt := mongodb.WithTimeout(time.Duration)

You can map a go struct intstance to a collection name:

clientopt := mongodb.WithCollection(any, string)

and you can set up a trace function to record operation timings:

clientopt := mongodb.WithTrace(func(context.Context, time.Duration))

type CreateTable

type CreateTable interface {
	Query
}

type Cursor

type Cursor interface {
	io.Closer

	// Find next document in the result set and return the document. Will
	// return (nil, io.EOF) when no more documents are available.
	Next(context.Context) (any, error)
}

Cursor represents an iterable cursor to a result set

type Database

type Database interface {
	// Return the name of the database
	Name() string

	// Return a collection object for a specific struct
	Collection(any) Collection

	// Insert documents of the same type to the database. The document key is updated
	// if the document is writable.
	Insert(context.Context, ...any) error
}

Database represents a specific database on the server on which operations can be performed.

type Filter

type Filter interface {
	// Match a document primary key. For MongoDB, this can be an ObjectID represented in HEX, or
	// other string.
	Key(string) error

	// Eq matches a field with an expression
	Eq(string, any) error
}

type Name

type Name interface {
	Query

	// Use a specific alias name
	As(string) Name

	// Use a specific schema name
	WithSchema(string) Name

	// Set a declared type
	WithType(string) Name

	// Transform into a CreateTable query with columns. Use TEMPORARY, IF_NOT_EXISTS, STRICT
	// and WITHOUT_ROWID flags to modify the table creation.
	CreateTable(...Name) CreateTable
}

Name represents an SQL name (table name, column name)

type Pool

type Pool interface {
	io.Closer

	// Get a connection from the pool, or return nil
	// if a connection could not be created
	Get() Conn

	// Release a connection back to the pool
	Put(Conn)

	// Return size of pool
	Size() int
}

Pool represents a connection pool. You can create a connection pool with the following code:

pool := pool.New(ctx, uri, opts...)

where uri is a mongodb:// URI and opts are pool options. You can set the maximum size of the pool with the following option:

opts := pool.WithMaxSize(int)

type Query

type Query interface {
	// Return the SQL query that can be executed
	Query() string

	// Set flags for any query
	With(QueryFlag) Query
}

Query represents any kind of SQL Query

type QueryFlag

type QueryFlag uint

const (
	NOT_NULL QueryFlag = 1 << iota
	PRIMARY_KEY
	UNIQUE_KEY
	ASC
	DESC
	ON_CONFLICT_ROLLBACK
	ON_CONFLICT_ABORT
	ON_CONFLICT_FAIL
	ON_CONFLICT_IGNORE
	ON_CONFLICT_REPLACE
	AUTO_INCREMENT
	TEMPORARY
	IF_NOT_EXISTS
	STRICT
	WITHOUT_ROWID
	NONE           QueryFlag = 0
	QUERY_MIN                = NOT_NULL
	QUERY_MAX                = WITHOUT_ROWID
	QUERY_CONFLICT           = ON_CONFLICT_ROLLBACK | ON_CONFLICT_ABORT | ON_CONFLICT_FAIL | ON_CONFLICT_IGNORE | ON_CONFLICT_REPLACE
	QUERY_SORT               = ASC | DESC
)

func (QueryFlag) FlagString

func (v QueryFlag) FlagString() string

func (QueryFlag) Is

func (v QueryFlag) Is(f QueryFlag) bool

func (QueryFlag) String

func (v QueryFlag) String() string

type Sort

type Sort interface {
	// Add ascending sort order fields
	Asc(...string) error

	// Add descending sort order fields
	Desc(...string) error

	// Limit the number of documents returned
	Limit(int64) error
}

Sort represents a sort specification for a query

type Tag

type Tag struct {
	Type  TagType
	Value any
}

Tag represents some task metadata, including Priority and ScheduledAt

func (Tag) String

func (t Tag) String() string

type TagType

type TagType string

const (
	TaskPriority    TagType = "priority"     // int: The priority of the task (higher is more important)
	TaskCreatedAt   TagType = "created_at"   // time.Time: The time the task was created
	TaskScheduledAt TagType = "scheduled_at" // time.Time: The time the task is scheduled to be executed
	TaskExpiresAt   TagType = "expires_at"   // time.Time: When the task expires (if not executed before this time)
	TaskAge         TagType = "age"          // time.Duration: The maximum age of the task (how long it has been in the queue)
	TaskRetryCount  TagType = "retry_count"  // int: The number of times the task has been retried
	TaskLastError   TagType = "last_error"   // string: The last task error
)

type Task

type Task interface {
	Key() string       // A unique identifier for the task
	Namespace() string // Return the namespace of the task
	Tags() []Tag       // Return all metadata tags
}

Task represents a task

type TaskQueue

type TaskQueue interface {
	// Schedule a new task to be executed, and return it
	New(context.Context, ...Tag) (Task, error)

	// Run the queue to retain tasks and execute them
	Run(context.Context, WorkerFunc) error
}

TaskQueue represents a set of tasks to be executed in order. Create a TaskQueue using:

queue := taskqueue.NewQueue(conn, namespace)

type WorkerFunc

type WorkerFunc func(context.Context, Task) error

WorkerFunc is used for executing tasks. When an error is returned, the task should be retried at some later date, or released if the error indicates the task should not be retried.