protavo

Documentation

Overview

Package protavo is an embedded, Protocol Buffers based document store.

Index

• func Delete(doc *document.Document) driver.Operation
• func DeleteNamespace() driver.Operation
• func DeleteWhere(fn driver.DeleteWhereFunc, f ...filter.Condition) driver.Operation
• func FetchAll(fn driver.FetchFunc) driver.ReadOnlyOperation
• func FetchWhere(fn driver.FetchFunc, f ...filter.Condition) driver.ReadOnlyOperation
• func ForceSave(doc *document.Document) driver.Operation
• func HasKeys(keys ...string) filter.Condition
• func HasUniqueKeyIn(keys ...string) filter.Condition
• func IsDuplicateKeyError(err error) bool
• func IsOneOf(ids ...string) filter.Condition
• func IsOptimisticLockError(err error) bool
• func Save(doc *document.Document) driver.Operation
• type DB
  • func NewDB(d driver.Driver) (*DB, error)
  • func (db *DB) BeginRead(ctx context.Context) (driver.ReadTx, error)
  • func (db *DB) BeginWrite(ctx context.Context) (driver.WriteTx, error)
  • func (db *DB) Close() error
  • func (db *DB) Delete(ctx context.Context, docs ...*document.Document) error
  • func (db *DB) DeleteByID(ctx context.Context, ids ...string) ([]string, error)
  • func (db *DB) DeleteNamespace(ctx context.Context) error
  • func (db *DB) DeleteWhere(ctx context.Context, f ...filter.Condition) ([]string, error)
  • func (db *DB) FetchAll(ctx context.Context, fn driver.FetchFunc) error
  • func (db *DB) FetchWhere(ctx context.Context, fn driver.FetchFunc, f ...filter.Condition) error
  • func (db *DB) ForceDelete(ctx context.Context, docs ...*document.Document) ([]string, error)
  • func (db *DB) ForceSave(ctx context.Context, docs ...*document.Document) error
  • func (db *DB) Load(ctx context.Context, id string) (*document.Document, bool, error)
  • func (db *DB) LoadAll(ctx context.Context, ids ...string) ([]*document.Document, error)
  • func (db *DB) LoadByUniqueKey(ctx context.Context, u string) (*document.Document, bool, error)
  • func (db *DB) LoadMany(ctx context.Context, ids ...string) ([]*document.Document, error)
  • func (db *DB) LoadManyWhere(ctx context.Context, f ...filter.Condition) ([]*document.Document, error)
  • func (db *DB) LoadWhere(ctx context.Context, f ...filter.Condition) (*document.Document, bool, error)
  • func (db *DB) Namespace(ns string) *DB
  • func (db *DB) Read(ctx context.Context, ops ...driver.ReadOnlyOperation) error
  • func (db *DB) Save(ctx context.Context, docs ...*document.Document) error
  • func (db *DB) Write(ctx context.Context, ops ...driver.Operation) error
• type DuplicateKeyError
  • func (e *DuplicateKeyError) Error() string
• type OptimisticLockError
  • func (e *OptimisticLockError) Error() string

Examples

• FetchAll
• FetchWhere

Functions

func Delete

func Delete(doc *document.Document) driver.Operation

Delete returns an operation that removes a document.

The Revision field of the document must be equal to the revision of that document as currently persisted; otherwise, an OptimisticLockError is returned.

It is not an error to delete a non-existent document, provided the given revision is 0.

The returned operation can be executed atomically with other operations using DB.Write(). DB.Delete() is a convenience method for deleting multiple documents.

func DeleteNamespace

func DeleteNamespace() driver.Operation

DeleteNamespace returns an operation that deletes the namespace and all documents within it.

func DeleteWhere

func DeleteWhere(
	fn driver.DeleteWhereFunc,
	f ...filter.Condition,
) driver.Operation

DeleteWhere returns an operation that atomically removes the documents that match the given filter conditions without checking the current revisions.

If fn is non-nil, it is invoked for each of the deleted documents.

The returned operation can be executed atomically with other operations using DB.Write(). DB.DeleteWhere() is a convenience method for performing a single DeleteWhere operation.

func FetchAll

func FetchAll(fn driver.FetchFunc) driver.ReadOnlyOperation

FetchAll returns an operation that calls fn once for every document.

It stops iterating if fn returns false or a non-nil error.

The returned operation can be executed atomically with other operations using DB.Read() or DB.Write(). DB.FetchAll() is a convenience method for performing a single FetchAll operation.

Example

// First, initialize a database. We'll use the BoltDB driver for examples.
db, err := protavobolt.OpenTemp(0600, nil)
if err != nil {
	panic(err)
}
defer db.Close()

// Next, save some documents so we have something to fetch.
if err := db.Save(
	context.Background(),
	&document.Document{
		ID:      "person:1",
		Content: document.StringContent("Alice"),
	},
	&document.Document{
		ID:      "person:2",
		Content: document.StringContent("Bob"),
	},
); err != nil {
	panic(err)
}

// Next, we use FetchAll to (rather inefficiently) count the total number of
// people in our database.
count := 0

if err := db.Read(
	context.Background(),
	FetchAll(
		func(doc *document.Document) (bool, error) {
			count++
			return true, nil
		},
	),
); err != nil {
	panic(err)
}

fmt.Printf("found %d documents\n", count)

Output:

found 2 documents

func FetchWhere

func FetchWhere(fn driver.FetchFunc, f ...filter.Condition) driver.ReadOnlyOperation

FetchWhere returns an operation that calls fn once for each document that matches the given filter conditions.

It stops iterating if fn returns false or a non-nil error.

The returned operation can be executed atomically with other operations using DB.Read() or DB.Write(). DB.FetchWhere() is a convenience method for performing a single FetchWhere operation.

Example

// First, initialize a database. We'll use the BoltDB driver for examples.
db, err := protavobolt.OpenTemp(0600, nil)
if err != nil {
	panic(err)
}
defer db.Close()

// Next, save some documents so we have something to fetch.
if err := db.Save(
	context.Background(),
	&document.Document{
		ID: "person:1",
		Keys: map[string]document.KeyType{
			"hobby:cycling": document.SharedKey,
		},
		Content: document.StringContent("Alice"),
	},
	&document.Document{
		ID: "person:2",
		Keys: map[string]document.KeyType{
			"hobby:cycling": document.SharedKey,
			"hobby:origami": document.SharedKey,
		},
		Content: document.StringContent("Bob"),
	},
	&document.Document{
		ID: "person:3",
		Keys: map[string]document.KeyType{
			"hobby:origami": document.SharedKey,
		},
		Content: document.StringContent("Carlos"),
	},
); err != nil {
	panic(err)
}

// Next, we use FetchWhere to (rather inefficiently) count the number of
// people that enjoy Origami.
count := 0

if err := db.Read(
	context.Background(),
	FetchWhere(
		func(doc *document.Document) (bool, error) {
			count++
			return true, nil
		},
		HasKeys("hobby:origami"),
	),
); err != nil {
	panic(err)
}

fmt.Printf("found %d documents\n", count)

Output:

found 2 documents

func ForceSave

func ForceSave(doc *document.Document) driver.Operation

ForceSave returns an operation that creates or updates a document without checking the current revision.

doc is updated with its new revision and timestamp.

The returned operation can be executed atomically with other operations using DB.Write(). DB.ForceSave() is a convenience method for force-saving multiple documents.

func HasKeys

func HasKeys(keys ...string) filter.Condition

HasKeys matches documents that have all of the given keys, regardless of key type.

Note that the parameters to this condition form a logical AND. That is, a document is required to have ALL of the keys in order to match.

func HasUniqueKeyIn

func HasUniqueKeyIn(keys ...string) filter.Condition

HasUniqueKeyIn matches all of the documents that have one of the given unique keys.

func IsDuplicateKeyError

func IsDuplicateKeyError(err error) bool

IsDuplicateKeyError returns true if err represents a duplicate key error.

func IsOneOf

func IsOneOf(ids ...string) filter.Condition

IsOneOf matches all of the documents with the given IDs.

func IsOptimisticLockError

func IsOptimisticLockError(err error) bool

IsOptimisticLockError returns true if err represents an optimistic lock failure.

func Save

func Save(doc *document.Document) driver.Operation

Save returns an operation that creates or updates a document.

The Revision field of the document must be equal to the revision of that document as currently persisted; otherwise, an OptimisticLockError is returned.

New documents must have a revision of 0.

doc is updated with its new revision and timestamp.

The returned operation can be executed atomically with other operations using DB.Write(). DB.Save() is a convenience method for saving multiple documents.

Types

type DB

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

DB is a Protocol Buffers based document store.

Most of the methods on *DB are convenience methods for performing common tasks and single-operation transactions.

Transactions can also be composed of multiple operations using DB.Read() or DB.Write() and the core operation functions:

• FetchAll()
• FetchWhere()
• Save()
• ForceSave()
• Delete()
• ForceDelete()

func NewDB

func NewDB(d driver.Driver) (*DB, error)

NewDB returns a new DB that uses the given driver.

func (*DB) BeginRead

func (db *DB) BeginRead(ctx context.Context) (driver.ReadTx, error)

BeginRead starts a new read-only transaction.

This is a low-level interface to a transaction. Consider using DB.Read() instead.

func (*DB) BeginWrite

func (db *DB) BeginWrite(ctx context.Context) (driver.WriteTx, error)

BeginWrite starts a new transaction.

This is a low-level interface to a transaction. Consider using DB.Write() instead.

func (*DB) Close

func (db *DB) Close() error

Close closes the DB and the underlying driver, freeing resources and preventing any further operations.

func (*DB) Delete

func (db *DB) Delete(ctx context.Context, docs ...*document.Document) error

Delete atomically removes multiple documents.

The Revision field of each document must be equal to the revision of that document as currently persisted; otherwise, an OptimisticLockError is returned.

It is not an error to delete a non-existent document, provided the given revision is 0.

func (*DB) DeleteByID

func (db *DB) DeleteByID(ctx context.Context, ids ...string) ([]string, error)

DeleteByID atomically removes multiple documents given only their IDs, and therefore without checking the current revisions.

It is not an error to delete a non-existent document. It returns the IDs of the deleted documents that did exist.

func (*DB) DeleteNamespace

func (db *DB) DeleteNamespace(ctx context.Context) error

DeleteNamespace unconditionally deletes the namespace and all documents and sub-namespaces within it.

func (*DB) DeleteWhere

func (db *DB) DeleteWhere(ctx context.Context, f ...filter.Condition) ([]string, error)

DeleteWhere atomically removes the documents that match the given filter conditions without checking the current revisions.

It returns the IDs of the deleted documents.

func (*DB) FetchAll

func (db *DB) FetchAll(ctx context.Context, fn driver.FetchFunc) error

FetchAll calls fn once for every document.

It stops iterating if fn returns false or a non-nil error.

func (*DB) FetchWhere

func (db *DB) FetchWhere(
	ctx context.Context,
	fn driver.FetchFunc,
	f ...filter.Condition,
) error

FetchWhere calls fn once for each document that matches the given filter conditions.

It stops iterating if fn returns false or a non-nil error.

func (*DB) ForceDelete

func (db *DB) ForceDelete(
	ctx context.Context,
	docs ...*document.Document,
) ([]string, error)

ForceDelete atomically removes multiple documents without checking the current revisions.

It is not an error to delete a non-existent document. It returns the IDs of the deleted documents that did exist.

func (*DB) ForceSave

func (db *DB) ForceSave(ctx context.Context, docs ...*document.Document) error

ForceSave atomically creates or updates multiple documents without checking the current revisions.

Each document in docs is updated with its new revision and timestamp.

func (*DB) Load

func (db *DB) Load(ctx context.Context, id string) (*document.Document, bool, error)

Load returns the document with the given ID.

It returns false if the document does not exist.

func (*DB) LoadAll

func (db *DB) LoadAll(ctx context.Context, ids ...string) ([]*document.Document, error)

LoadAll returns all of the documents.

func (*DB) LoadByUniqueKey

func (db *DB) LoadByUniqueKey(
	ctx context.Context,
	u string,
) (*document.Document, bool, error)

LoadByUniqueKey returns the document with the given unique key.

It returns false if the document does not exist.

func (*DB) LoadMany

func (db *DB) LoadMany(ctx context.Context, ids ...string) ([]*document.Document, error)

LoadMany returns the documents with the given IDs.

func (*DB) LoadManyWhere

func (db *DB) LoadManyWhere(ctx context.Context, f ...filter.Condition) ([]*document.Document, error)

LoadManyWhere returns the documents that match the given filter conditions.

func (*DB) LoadWhere

func (db *DB) LoadWhere(
	ctx context.Context,
	f ...filter.Condition,
) (*document.Document, bool, error)

LoadWhere returns the first document that matches the given filter conditions.

It returns false if there are no matching documents.

func (*DB) Namespace

func (db *DB) Namespace(ns string) *DB

Namespace returns a DB that operates on a sub-namespace of the current namespace.

func (*DB) Read

func (db *DB) Read(
	ctx context.Context,
	ops ...driver.ReadOnlyOperation,
) error

Read atomically executes a set of read operations.

The operations are executed in order.

func (*DB) Save

func (db *DB) Save(ctx context.Context, docs ...*document.Document) error

Save atomically creates or updates multiple documents.

The Revision field of each document must be equal to the revision of that document as currently persisted; otherwise, an OptimisticLockError is returned.

New documents must have a revision of 0.

Each document in docs is updated with its new revision and timestamp.

func (*DB) Write

func (db *DB) Write(
	ctx context.Context,
	ops ...driver.Operation,
) error

Write atomically executes a set of read/write operations.

The operations are executed in order.

type DuplicateKeyError

type DuplicateKeyError struct {
	DocumentID            string
	ConflictingDocumentID string
	UniqueKey             string
}

DuplicateKeyError is an error that occurs when an attempt is made to save a document with a unique key that is already used by a different document.

func (*DuplicateKeyError) Error

func (e *DuplicateKeyError) Error() string

type OptimisticLockError

type OptimisticLockError struct {
	DocumentID string
	GivenRev   uint64
	ActualRev  uint64
	Operation  string
}

OptimisticLockError is an error that occurs when an attempt to modify a document fails because the incorrect document revision was provided with the request.

func (*OptimisticLockError) Error

func (e *OptimisticLockError) Error() string