database

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Apr 6, 2024 License: ISC Imports: 2 Imported by: 0

README

database

ISC License GoDoc

Package database provides a database for Kalibrium.

Overview

This package provides a database layer to store and retrieve data in a simple and efficient manner.

The current backend is ffldb, which makes use of leveldb, flat files, and strict checksums in key areas to ensure data integrity.

Implementors of additional backends are required to implement the following interfaces:

DataAccessor

This defines the common interface by which data gets accessed in a generic Kalibrium database. Both the Database and the Transaction interfaces (see below) implement it.

Database

This defines the interface of a database that can begin transactions and close itself.

Transaction

This defines the interface of a generic Kalibrium database transaction.

Note: Transactions provide data consistency over the state of the database as it was when the transaction started. There is NO guarantee that if one puts data into the transaction then it will be available to get within the same transaction.

Cursor

This iterates over database entries given some bucket.

Documentation

Overview

Package database provides a database for Kalibrium.

Overview

This package provides a database layer to store and retrieve data in a simple and efficient manner.

The current backend is ffldb, which makes use of leveldb, flat files, and strict checksums in key areas to ensure data integrity.

Implementors of additional backends are required to implement the following interfaces:

DataAccessor

This defines the common interface by which data gets accessed in a generic Kalibrium database. Both the Database and the Transaction interfaces (see below) implement it.

Database

This defines the interface of a database that can begin transactions and close itself.

Transaction

This defines the interface of a generic Kalibrium database transaction. Note: transactions provide data consistency over the state of the database as it was when the transaction started. There is NO guarantee that if one puts data into the transaction then it will be available to get within the same transaction.

Cursor

This iterates over database entries given some bucket.

Index

Constants

This section is empty.

Variables

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound denotes that the requested item was not found in the database.

Functions

func IsNotFoundError

func IsNotFoundError(err error) bool

IsNotFoundError checks whether an error is an ErrNotFound.

Types

type Bucket

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

Bucket is a helper type meant to combine buckets and sub-buckets that can be used to create database keys and prefix-based cursors.

func MakeBucket

func MakeBucket(path []byte) *Bucket

MakeBucket creates a new Bucket using the given path of buckets.

func (*Bucket) Bucket

func (b *Bucket) Bucket(bucketBytes []byte) *Bucket

Bucket returns the sub-bucket of the current bucket defined by bucketBytes.

func (*Bucket) Key

func (b *Bucket) Key(suffix []byte) *Key

Key returns a key in the current bucket with the given suffix.

func (*Bucket) Path

func (b *Bucket) Path() []byte

Path returns the full path of the current bucket.

type Cursor

type Cursor interface {
	// Next moves the iterator to the next key/value pair. It returns whether the
	// iterator is exhausted. Panics if the cursor is closed.
	Next() bool

	// First moves the iterator to the first key/value pair. It returns false if
	// such a pair does not exist. Panics if the cursor is closed.
	First() bool

	// Seek moves the iterator to the first key/value pair whose key is greater
	// than or equal to the given key. It returns ErrNotFound if such pair does not
	// exist.
	Seek(key *Key) error

	// Key returns the key of the current key/value pair, or ErrNotFound if done.
	// The caller should not modify the contents of the returned key, and
	// its contents may change on the next call to Next.
	Key() (*Key, error)

	// Value returns the value of the current key/value pair, or ErrNotFound if done.
	// The caller should not modify the contents of the returned slice, and its
	// contents may change on the next call to Next.
	Value() ([]byte, error)

	// Close releases associated resources.
	Close() error
}

Cursor iterates over database entries given some bucket.

type DataAccessor

type DataAccessor interface {
	// Put sets the value for the given key. It overwrites
	// any previous value for that key.
	Put(key *Key, value []byte) error

	// Get gets the value for the given key. It returns
	// ErrNotFound if the given key does not exist.
	Get(key *Key) ([]byte, error)

	// Has returns true if the database does contains the
	// given key.
	Has(key *Key) (bool, error)

	// Delete deletes the value for the given key. Will not
	// return an error if the key doesn't exist.
	Delete(key *Key) error

	// Cursor begins a new cursor over the given bucket.
	Cursor(bucket *Bucket) (Cursor, error)
}

DataAccessor defines the common interface by which data gets accessed in a generic Kalibrium database.

type Database

type Database interface {
	DataAccessor

	// Begin begins a new database transaction.
	Begin() (Transaction, error)

	// Compact compacts the database instance.
	Compact() error

	// Close closes the database.
	Close() error
}

Database defines the interface of a database that can begin transactions and close itself.

Important: This is not part of the DataAccessor interface because the Transaction interface includes it. Were we to merge Database with DataAccessor, implementors of the Transaction interface would be forced to implement methods such as Begin and Close, which is undesirable.

type Key

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

Key is a helper type meant to combine prefix and suffix into a single database key.

func (*Key) Bucket

func (k *Key) Bucket() *Bucket

Bucket returns the key bucket.

func (*Key) Bytes

func (k *Key) Bytes() []byte

Bytes returns the full key bytes that are consisted from the bucket path concatenated to the suffix.

func (*Key) String

func (k *Key) String() string

func (*Key) Suffix

func (k *Key) Suffix() []byte

Suffix returns the key suffix.

type Transaction

type Transaction interface {
	DataAccessor

	// Rollback rolls back whatever changes were made to the
	// database within this transaction.
	Rollback() error

	// Commit commits whatever changes were made to the database
	// within this transaction.
	Commit() error

	// RollbackUnlessClosed rolls back changes that were made to
	// the database within the transaction, unless the transaction
	// had already been closed using either Rollback or Commit.
	RollbackUnlessClosed() error
}

Transaction defines the interface of a generic Kalibrium database transaction.

Note: Transactions provide data consistency over the state of the database as it was when the transaction started. There is NO guarantee that if one puts data into the transaction then it will be available to get within the same transaction.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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