backend

Documentation

Index

• Constants
• func IsClosed(err error) bool
• func IsNotFound(err error) bool
• type Backend
  • func Open(path string, tuning Tuning) (Backend, error)
  • func OpenLevelDB(location string, tuning Tuning) (Backend, error)
  • func OpenLevelDBAuto(location string) (Backend, error)
  • func OpenLevelDBMemory() Backend
  • func OpenLevelDBRO(location string) (Backend, error)
  • func OpenMemory() Backend
• type CommitHook
• type Iterator
• type ReadTransaction
• type Reader
• type Tuning
• type WriteTransaction
• type Writer

Constants

const (
	KiB = 10
	MiB = 20
)

Functions

func IsClosed

func IsClosed(err error) bool

func IsNotFound

func IsNotFound(err error) bool

Types

type Backend

type Backend interface {
	Reader
	Writer
	NewReadTransaction() (ReadTransaction, error)
	NewWriteTransaction(hooks ...CommitHook) (WriteTransaction, error)
	Close() error
	Compact() error
	Location() string
}

The Backend interface represents the main database handle. It supports both read/write operations and opening read-only or writable transactions. Depending on the actual implementation, individual read/write operations may be implicitly wrapped in transactions, making them perform quite badly when used repeatedly. For bulk operations, consider always using a transaction of the appropriate type. The transaction isolation level is "read committed" - there are no dirty reads. Location returns the path to the database, as given to Open. The returned string is empty for a db in memory.

func Open

func Open(path string, tuning Tuning) (Backend, error)

func OpenLevelDB

func OpenLevelDB(location string, tuning Tuning) (Backend, error)

OpenLevelDB attempts to open the database at the given location, and runs recovery on it if opening fails. Worst case, if recovery is not possible, the database is erased and created from scratch.

func OpenLevelDBAuto

func OpenLevelDBAuto(location string) (Backend, error)

OpenLevelDBAuto is OpenLevelDB with TuningAuto tuning.

func OpenLevelDBMemory

func OpenLevelDBMemory() Backend

OpenLevelDBMemory returns a new Backend referencing an in-memory database.

func OpenLevelDBRO

func OpenLevelDBRO(location string) (Backend, error)

OpenLevelDBRO attempts to open the database at the given location, read only.

func OpenMemory

func OpenMemory() Backend

type CommitHook

type CommitHook func(WriteTransaction) error

CommitHook is a function that is executed before a WriteTransaction is committed or before it is flushed to disk, e.g. on calling CheckPoint. The transaction can be accessed via a closure.

type Iterator

type Iterator interface {
	Next() bool
	Key() []byte
	Value() []byte
	Error() error
	Release()
}

The Iterator interface specifies the operations available on iterators returned by NewPrefixIterator and NewRangeIterator. The iterator pattern is to loop while Next returns true, then check Error after the loop. Next will return false when iteration is complete (Error() == nil) or when there is an error preventing iteration, which is then returned by Error(). For example:

it, err := db.NewPrefixIterator(nil)
if err != nil {
    // problem preventing iteration
}
defer it.Release()
for it.Next() {
    // ...
}
if err := it.Error(); err != nil {
    // there was a database problem while iterating
}

An iterator must be Released when no longer required. The Error method can be called either before or after Release with the same results. If an iterator was created in a transaction (whether read-only or write) it must be released before the transaction is released (or committed).

type ReadTransaction

type ReadTransaction interface {
	Reader
	Release()
}

The ReadTransaction interface specifies the operations on read-only transactions. Every ReadTransaction must be released when no longer required.

type Reader

type Reader interface {
	Get(key []byte) ([]byte, error)
	NewPrefixIterator(prefix []byte) (Iterator, error)
	NewRangeIterator(first, last []byte) (Iterator, error)
}

The Reader interface specifies the read-only operations available on the main database and on read-only transactions (snapshots). Note that when called directly on the database handle these operations may take implicit transactions and performance may suffer.

type Tuning

type Tuning int

const (
	// N.b. these constants must match those in lib/config.Tuning!
	TuningAuto Tuning = iota
	TuningSmall
	TuningLarge
)

type WriteTransaction

type WriteTransaction interface {
	ReadTransaction
	Writer
	Checkpoint() error
	Commit() error
}

The WriteTransaction interface specifies the operations on writable transactions. Every WriteTransaction must be either committed or released (i.e., discarded) when no longer required. No further operations must be performed after release or commit (regardless of whether commit succeeded), with one exception -- it's fine to release an already committed or released transaction.

A Checkpoint is a potential partial commit of the transaction so far, for purposes of saving memory when transactions are in-RAM. Note that transactions may be checkpointed *anyway* even if this is not called, due to resource constraints, but this gives you a chance to decide when. If, and only if, calling Checkpoint will result in a partial commit/flush, the CommitHooks passed to Backend.NewWriteTransaction are called before committing. If any of those returns an error, committing is aborted and the error bubbled.

type Writer

type Writer interface {
	Put(key, val []byte) error
	Delete(key []byte) error
}

The Writer interface specifies the mutating operations available on the main database and on writable transactions. Note that when called directly on the database handle these operations may take implicit transactions and performance may suffer.