db

package
v7.1.0-beta+incompatible Latest Latest
Warning

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

 Go to latest Published: Jan 30, 2020 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrDiscarded = errors.New("transaction has already been discarded")
	ErrCommitted = errors.New("transaction has already been committed")
)

Functions

This section is empty.

Types

type AlreadyExistsError 

type AlreadyExistsError struct {
	ID []byte
}

AlreadyExistsError is returned whenever a model with a specific ID should not already exists in the database but it does.

func (AlreadyExistsError) Error 

func (e AlreadyExistsError) Error() string

type Collection 

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

Collection represents a set of a specific type of model.

func (*Collection) AddIndex 

func (c *Collection) AddIndex(name string, getter func(Model) []byte) *Index

AddIndex creates and returns a new index. name is an arbitrary, unique name for the index. getter is a function that accepts a model and returns the value for this particular index. For example, if you wanted to add an index on a struct field, getter should return the value of that field. After AddIndex is called, any new models in this collection that are inserted will be indexed. Any models inserted prior to calling AddIndex will *not* be indexed. Note that in order to function correctly, indexes must be based on data that is actually saved to the database (e.g. exported struct fields).

func (*Collection) AddMultiIndex 

func (c *Collection) AddMultiIndex(name string, getter func(Model) [][]byte) *Index

AddMultiIndex is like AddIndex but has the ability to index multiple values for the same model. For methods like FindWithRange and FindWithValue, the model will be included in the results if *any* of the values returned by the getter function satisfy the constraints. It is useful for representing one-to-many relationships. Any models inserted prior to calling AddMultiIndex will *not* be indexed. Note that in order to function correctly, indexes must be based on data that is actually saved to the database (e.g. exported struct fields).

func (*Collection) Count 

func (c *Collection) Count() (int, error)

Count returns the number of models in the collection.

func (*Collection) Delete 

func (c *Collection) Delete(id []byte) error

Delete deletes the model with the given ID from the database. It returns an error if the model doesn't exist in the database.

func (*Collection) FindAll 

func (c *Collection) FindAll(models interface{}) error

FindAll finds all models for the collection and scans the results into the given models. models should be a pointer to an empty slice of a concrete model type (e.g. *[]myModelType).

func (*Collection) FindByID 

func (c *Collection) FindByID(id []byte, model Model) error

FindByID finds the model with the given ID and scans the results into the given model. As in the Unmarshal and Decode methods in the encoding/json package, model must be settable via reflect. Typically, this means you should pass in a pointer.

func (*Collection) GetSnapshot 

func (c *Collection) GetSnapshot() (*Snapshot, error)

GetSnapshot returns a latest snapshot of the underlying DB. The content of snapshot are guaranteed to be consistent. The snapshot must be released after use, by calling Release method.

func (*Collection) Insert 

func (c *Collection) Insert(model Model) error

Insert inserts the given model into the database. It returns an error if a model with the same id already exists.

func (*Collection) Name 

func (c *Collection) Name() string

Name returns the name of the collection.

func (*Collection) NewQuery 

func (c *Collection) NewQuery(filter *Filter) *Query

New Query creates and returns a new query with the given filter. By default, a query will return all models that match the filter in ascending byte order according to their index values. The query offers methods that can be used to change this (e.g. Reverse and Max). The query is lazily executed, i.e. it does not actually touch the database until they are run. In general, queries have a runtime of O(N) where N is the number of models that are returned by the query, but using some features may significantly change this.

func (*Collection) OpenTransaction 

func (c *Collection) OpenTransaction() *Transaction

OpenTransaction opens and returns a new transaction for the collection. While the transaction is open, no other state changes (e.g. Insert, Update, or Delete) can be made to the collection (but concurrent reads are still allowed).

Transactions are atomic, meaning that either: 

(1) The transaction will succeed and *all* queued operations will be
applied, or
(2) the transaction will fail or be discarded, in which case *none* of
the queued operations will be applied.

The transaction must be closed once done, either by committing or discarding the transaction. No changes will be made to the database state until the transaction is committed.

func (*Collection) Update 

func (c *Collection) Update(model Model) error

Update updates an existing model in the database. It returns an error if the given model doesn't already exist.

type ConflictingOperationsError 

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

ConflictingOperationsError is returned when two conflicting operations are attempted within the same transaction

func (ConflictingOperationsError) Error 

func (e ConflictingOperationsError) Error() string

type DB 

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

DB is the top-level Database.

func Open 

func Open(path string) (*DB, error)

Open creates a new database using the given file path for permanent storage. It is not safe to have multiple DBs using the same file path.

func (*DB) CheckIntegrity 

func (db *DB) CheckIntegrity() error

func (*DB) Close 

func (db *DB) Close() error

Close closes the database. It is not safe to call Close if there are any other methods that have not yet returned. It is safe to call Close multiple times.

func (*DB) NewCollection 

func (db *DB) NewCollection(name string, typ Model) (*Collection, error)

NewCollection creates and returns a new collection with the given name and model type. You should create exactly one collection for each model type. The collection should typically be created once at the start of your application and re-used. NewCollection returns an error if a collection has already been created with the given name for this db.

func (*DB) OpenGlobalTransaction 

func (db *DB) OpenGlobalTransaction() *GlobalTransaction

OpenGlobalTransaction opens and returns a new global transaction. While the transaction is open, no other state changes (e.g. Insert, Update, or Delete) can be made to the database (but concurrent reads are still allowed). This includes all collections.

No new collections can be created while the global transaction is open. Calling NewCollection while the transaction is open will block until the transaction is committed or discarded.

Transactions are atomic, meaning that either: 

(1) The transaction will succeed and *all* queued operations will be
applied, or
(2) the transaction will fail or be discarded, in which case *none* of
the queued operations will be applied.

The transaction must be closed once done, either by committing or discarding the transaction. No changes will be made to the database state until the transaction is committed.

type Filter 

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

Filter determines which models to return in the query and what order to return them in.

type GlobalTransaction 

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

GlobalTransaction is an atomic database transaction across all collections which can be used to guarantee consistency.

func (*GlobalTransaction) Commit 

func (txn *GlobalTransaction) Commit() error

Commit commits the transaction. If error is not nil, then the transaction is discarded. A new transaction must be created if you wish to retry the operations.

Other methods should not be called after transaction has been committed.

func (*GlobalTransaction) Delete 

func (txn *GlobalTransaction) Delete(col *Collection, id []byte) error

Delete queues an operation to delete the model with the given ID from the given collection. It returns an error if the model doesn't exist in the database. The model will not actually be deleted until the transaction is committed.

func (*GlobalTransaction) Discard 

func (txn *GlobalTransaction) Discard() error

Discard discards the transaction.

Other methods should not be called after transaction has been discarded. However, it is safe to call Discard multiple times.

func (*GlobalTransaction) Insert 

func (txn *GlobalTransaction) Insert(col *Collection, model Model) error

Insert queues an operation to insert the given model into the given collection. It returns an error if a model with the same id already exists. The model will not actually be inserted until the transaction is committed.

func (*GlobalTransaction) Update 

func (txn *GlobalTransaction) Update(col *Collection, model Model) error

Update queues an operation to update an existing model in the given collection. It returns an error if the given model doesn't already exist. The model will not actually be updated until the transaction is committed.

type Index 

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

Index can be used to search for specific values or specific ranges of values for a collection.

func (*Index) All 

func (index *Index) All() *Filter

All returns a Filter which will match all models. It is useful for when you want to retrieve models in sorted order without excluding any of them.

func (*Index) Name 

func (index *Index) Name() string

Name returns the name of the index.

func (*Index) PrefixFilter 

func (index *Index) PrefixFilter(prefix []byte) *Filter

PrefixFilter returns a Filter which will match all models with an index value that starts with the given prefix.

func (*Index) RangeFilter 

func (index *Index) RangeFilter(start []byte, limit []byte) *Filter

RangeFilter returns a Filter which will match all models with an index value >= start and < limit.

func (*Index) ValueFilter 

func (index *Index) ValueFilter(val []byte) *Filter

ValueFilter returns a Filter which will match all models with an index value equal to the given value.

type Model 

type Model interface {
	// ID returns a unique identifier for this model.
	ID() []byte
}

Model is any type which can be inserted and retrieved from the database. The only requirement is an ID method. Because the db package uses reflect to encode/decode models, only exported struct fields will be saved and retrieved from the database.

type NotFoundError 

type NotFoundError struct {
	ID []byte
}

NotFoundError is returned whenever a model with a specific ID should be found in the database but it is not.

func (NotFoundError) Error 

func (e NotFoundError) Error() string

type Query 

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

Query is used to return certain results from the database.

func (*Query) Count 

func (q *Query) Count() (int, error)

Count returns the number of unique models that match the query. It does not return an error if no models match the query. Note that this method *does* respect q.Max. If the number of models that match the filter is greater than q.Max, it will stop counting and return q.Max.

func (*Query) Max 

func (q *Query) Max(max int) *Query

Max causes the query to only return up to max results. It is the analog of the LIMIT keyword in SQL: https://www.postgresql.org/docs/current/queries-limit.html

func (*Query) Offset 

func (q *Query) Offset(offset int) *Query

Offset causes the query to skip offset models when iterating through models that match the query. Note that queries which use an offset have a runtime of O(max(K, offset) + N), where N is the number of models returned by the query and K is the total number of keys in the corresponding index. Queries with a high offset can take a long time to run, regardless of the number of models returned. This is due to limitations of the underlying database. Offset is the analog of the OFFSET keyword in SQL: https://www.postgresql.org/docs/current/queries-limit.html

func (*Query) Reverse 

func (q *Query) Reverse() *Query

Reverse causes the query to return models in descending byte order according to their index values instead of the default (ascending byte order).

func (*Query) Run 

func (q *Query) Run(models interface{}) error

Run runs the query and scans the results into models. models should be a pointer to an empty slice of a concrete model type (e.g. *[]myModelType). It returns an error if models is the wrong type or there was a problem reading from the database. It does not return an error if no models match the query.

type Snapshot 

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

Snapshot is a frozen, read-only snapshot of a DB state at a particular point in time.

func (*Snapshot) Count 

func (s *Snapshot) Count() (int, error)

Count returns the number of models in the collection.

func (*Snapshot) FindAll 

func (s *Snapshot) FindAll(models interface{}) error

FindAll finds all models for the collection and scans the results into the given models. models should be a pointer to an empty slice of a concrete model type (e.g. *[]myModelType).

func (*Snapshot) FindByID 

func (s *Snapshot) FindByID(id []byte, model Model) error

FindByID finds the model with the given ID and scans the results into the given model. As in the Unmarshal and Decode methods in the encoding/json package, model must be settable via reflect. Typically, this means you should pass in a pointer.

func (*Snapshot) NewQuery 

func (s *Snapshot) NewQuery(filter *Filter) *Query

New Query creates and returns a new query with the given filter. By default, a query will return all models that match the filter in ascending byte order according to their index values. The query offers methods that can be used to change this (e.g. Reverse and Max). The query is lazily executed, i.e. it does not actually touch the database until they are run. In general, queries have a runtime of O(N) where N is the number of models that are returned by the query, but using some features may significantly change this.

func (*Snapshot) Release 

func (s *Snapshot) Release()

Release releases the snapshot. This will not release any ongoing queries, which will still finish unless the database is closed. Other methods should not be called after the snapshot has been released.

type Transaction 

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

Transaction is an atomic database transaction for a single collection which can be used to guarantee consistency.

func (*Transaction) Commit 

func (txn *Transaction) Commit() error

Commit commits the transaction. If error is not nil, then the transaction is discarded. A new transaction must be created if you wish to retry the operations.

Other methods should not be called after transaction has been committed.

func (*Transaction) Delete 

func (txn *Transaction) Delete(id []byte) error

Delete queues an operation to delete the model with the given ID from the database. It returns an error if the model doesn't exist in the database. The model will not actually be deleted until the transaction is committed.

func (*Transaction) Discard 

func (txn *Transaction) Discard() error

Discard discards the transaction.

Other methods should not be called after transaction has been discarded. However, it is safe to call Discard multiple times.

func (*Transaction) Insert 

func (txn *Transaction) Insert(model Model) error

Insert queues an operation to insert the given model into the database. It returns an error if a model with the same id already exists. The model will not actually be inserted until the transaction is committed.

func (*Transaction) Update 

func (txn *Transaction) Update(model Model) error

Update queues an operation to update an existing model in the database. It returns an error if the given model doesn't already exist. The model will not actually be updated until the transaction is committed.

Source Files

View all Source files

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.