database

Documentation

Index

• Constants
• Variables
• func AtomicClear(readerDB Iteratee, deleterDB KeyValueDeleter) error
• func AtomicClearPrefix(readerDB Iteratee, deleterDB KeyValueDeleter, prefix []byte) error
• func Clear(db Database, writeSize int) error
• func ClearPrefix(db Database, prefix []byte, writeSize int) error
• func Count(db Iteratee) (int, error)
• func GetBool(db KeyValueReader, key []byte) (bool, error)
• func GetID(db KeyValueReader, key []byte) (ids.ID, error)
• func GetTimestamp(db KeyValueReader, key []byte) (time.Time, error)
• func GetUInt32(db KeyValueReader, key []byte) (uint32, error)
• func GetUInt64(db KeyValueReader, key []byte) (uint64, error)
• func PackUInt32(val uint32) []byte
• func PackUInt64(val uint64) []byte
• func ParseTimestamp(b []byte) (time.Time, error)
• func ParseUInt32(b []byte) (uint32, error)
• func ParseUInt64(b []byte) (uint64, error)
• func PutBool(db KeyValueWriter, key []byte, b bool) error
• func PutID(db KeyValueWriter, key []byte, val ids.ID) error
• func PutTimestamp(db KeyValueWriter, key []byte, val time.Time) error
• func PutUInt32(db KeyValueWriter, key []byte, val uint32) error
• func PutUInt64(db KeyValueWriter, key []byte, val uint64) error
• func Size(db Iteratee) (int, error)
• func WithDefault[V any](get func(KeyValueReader, []byte) (V, error), db KeyValueReader, key []byte, ...) (V, error)
• type Batch
• type BatchOp
• type BatchOps
  • func (b *BatchOps) Delete(key []byte) error
  • func (b *BatchOps) Put(key, value []byte) error
  • func (b *BatchOps) Replay(w KeyValueWriterDeleter) error
  • func (b *BatchOps) Reset()
  • func (b *BatchOps) Size() int
• type Batcher
• type Compacter
• type Database
• type Iteratee
• type Iterator
• type IteratorError
  • func (i *IteratorError) Error() error
  • func (*IteratorError) Key() []byte
  • func (*IteratorError) Next() bool
  • func (*IteratorError) Release()
  • func (*IteratorError) Value() []byte
• type KeyValueDeleter
• type KeyValueReader
• type KeyValueReaderWriter
• type KeyValueReaderWriterDeleter
• type KeyValueWriter
• type KeyValueWriterDeleter

Constants

const (
	// If, when a batch is reset, the cap(batch)/len(batch) > MaxExcessCapacityFactor,
	// the underlying array's capacity will be reduced by a factor of capacityReductionFactor.
	// Higher value for MaxExcessCapacityFactor --> less aggressive array downsizing --> less memory allocations
	// but more unnecessary data in the underlying array that can't be garbage collected.
	// Higher value for CapacityReductionFactor --> more aggressive array downsizing --> more memory allocations
	// but less unnecessary data in the underlying array that can't be garbage collected.
	MaxExcessCapacityFactor = 4
	CapacityReductionFactor = 2
)

const (
	Uint64Size = 8 // bytes
	BoolSize   = 1 // bytes
	BoolFalse  = 0x00
	BoolTrue   = 0x01
)

Variables

var (
	ErrClosed   = errors.New("closed")
	ErrNotFound = errors.New("not found")
)

common errors

Functions

func AtomicClear

func AtomicClear(readerDB Iteratee, deleterDB KeyValueDeleter) error

func AtomicClearPrefix

func AtomicClearPrefix(readerDB Iteratee, deleterDB KeyValueDeleter, prefix []byte) error

AtomicClearPrefix deletes from [deleterDB] all keys in [readerDB] that have the given [prefix].

func Clear

func Clear(db Database, writeSize int) error

Remove all key-value pairs from [db]. Writes each batch when it reaches [writeSize].

func ClearPrefix

func ClearPrefix(db Database, prefix []byte, writeSize int) error

Removes all keys with the given [prefix] from [db]. Writes each batch when it reaches [writeSize].

func Count

func Count(db Iteratee) (int, error)

func GetBool

func GetBool(db KeyValueReader, key []byte) (bool, error)

func GetID

func GetID(db KeyValueReader, key []byte) (ids.ID, error)

func GetTimestamp

func GetTimestamp(db KeyValueReader, key []byte) (time.Time, error)

func GetUInt32

func GetUInt32(db KeyValueReader, key []byte) (uint32, error)

func GetUInt64

func GetUInt64(db KeyValueReader, key []byte) (uint64, error)

func PackUInt32

func PackUInt32(val uint32) []byte

func PackUInt64

func PackUInt64(val uint64) []byte

func ParseTimestamp

func ParseTimestamp(b []byte) (time.Time, error)

func ParseUInt32

func ParseUInt32(b []byte) (uint32, error)

func ParseUInt64

func ParseUInt64(b []byte) (uint64, error)

func PutBool

func PutBool(db KeyValueWriter, key []byte, b bool) error

func PutID

func PutID(db KeyValueWriter, key []byte, val ids.ID) error

func PutTimestamp

func PutTimestamp(db KeyValueWriter, key []byte, val time.Time) error

func PutUInt32

func PutUInt32(db KeyValueWriter, key []byte, val uint32) error

func PutUInt64

func PutUInt64(db KeyValueWriter, key []byte, val uint64) error

func Size

func Size(db Iteratee) (int, error)

func WithDefault

func WithDefault[V any](
	get func(KeyValueReader, []byte) (V, error),
	db KeyValueReader,
	key []byte,
	def V,
) (V, error)

WithDefault returns the value at [key] in [db]. If the key doesn't exist, it returns [def].

Types

type Batch

type Batch interface {
	KeyValueWriterDeleter

	// Size retrieves the amount of data queued up for writing, this includes
	// the keys, values, and deleted keys.
	Size() int

	// Write flushes any accumulated data to disk.
	Write() error

	// Reset resets the batch for reuse.
	Reset()

	// Replay replays the batch contents in the same order they were written
	// to the batch.
	Replay(w KeyValueWriterDeleter) error

	// Inner returns a Batch writing to the inner database, if one exists. If
	// this batch is already writing to the base DB, then itself should be
	// returned.
	Inner() Batch
}

Batch is a write-only database that commits changes to its host database when Write is called. A batch cannot be used concurrently.

type BatchOp

type BatchOp struct {
	Key    []byte
	Value  []byte
	Delete bool
}

type BatchOps

type BatchOps struct {
	Ops []BatchOp
	// contains filtered or unexported fields
}

func (*BatchOps) Delete

func (b *BatchOps) Delete(key []byte) error

func (*BatchOps) Put

func (b *BatchOps) Put(key, value []byte) error

func (*BatchOps) Replay

func (b *BatchOps) Replay(w KeyValueWriterDeleter) error

func (*BatchOps) Reset

func (b *BatchOps) Reset()

func (*BatchOps) Size

func (b *BatchOps) Size() int

type Batcher

type Batcher interface {
	// NewBatch creates a write-only database that buffers changes to its host db
	// until a final write is called.
	NewBatch() Batch
}

Batcher wraps the NewBatch method of a backing data store.

type Compacter

type Compacter interface {
	// Compact the underlying DB for the given key range.
	// Specifically, deleted and overwritten versions are discarded,
	// and the data is rearranged to reduce the cost of operations
	// needed to access the data. This operation should typically only
	// be invoked by users who understand the underlying implementation.
	//
	// A nil start is treated as a key before all keys in the DB.
	// And a nil limit is treated as a key after all keys in the DB.
	// Therefore if both are nil then it will compact entire DB.
	//
	// Note: [start] and [limit] are safe to modify and read after calling Compact.
	Compact(start []byte, limit []byte) error
}

Compacter wraps the Compact method of a backing data store.

type Database

type Database interface {
	KeyValueReaderWriterDeleter
	Batcher
	Iteratee
	Compacter
	io.Closer
	health.Checker
}

Database contains all the methods required to allow handling different key-value data stores backing the database.

type Iteratee

type Iteratee interface {
	// NewIterator creates an iterator over the entire keyspace contained within
	// the key-value database.
	NewIterator() Iterator

	// NewIteratorWithStart creates an iterator over a subset of database
	// content starting at a particular initial key.
	NewIteratorWithStart(start []byte) Iterator

	// NewIteratorWithPrefix creates an iterator over a subset of database
	// content with a particular key prefix.
	NewIteratorWithPrefix(prefix []byte) Iterator

	// NewIteratorWithStartAndPrefix creates an iterator over a subset of
	// database content with a particular key prefix starting at a specified
	// key.
	NewIteratorWithStartAndPrefix(start, prefix []byte) Iterator
}

Iteratee wraps the NewIterator methods of a backing data store.

type Iterator

type Iterator interface {
	// Next moves the iterator to the next key/value pair. It returns whether
	// the iterator successfully moved to a new key/value pair.
	// The iterator may return false if the underlying database has been closed
	// before the iteration has completed, in which case future calls to Error()
	// must return [ErrClosed].
	Next() bool

	// Error returns any accumulated error. Exhausting all the key/value pairs
	// is not considered to be an error.
	// Error should be called after all key/value pairs have been exhausted ie.
	// after Next() has returned false.
	Error() error

	// Key returns the key of the current key/value pair, or nil if done.
	// If the database is closed, must still report the current contents.
	// Behavior is undefined after Release is called.
	Key() []byte

	// Value returns the value of the current key/value pair, or nil if done.
	// If the database is closed, must still report the current contents.
	// Behavior is undefined after Release is called.
	Value() []byte

	// Release releases associated resources. Release should always succeed and
	// can be called multiple times without causing error.
	Release()
}

Iterator iterates over a database's key/value pairs.

When it encounters an error any seek will return false and will yield no key/ value pairs. The error can be queried by calling the Error method. Calling Release is still necessary.

An iterator must be released after use, but it is not necessary to read an iterator until exhaustion. An iterator is not safe for concurrent use, but it is safe to use multiple iterators concurrently.

type IteratorError

type IteratorError struct {
	Err error
}

IteratorError does nothing and returns the provided error

func (*IteratorError) Error

func (i *IteratorError) Error() error

func (*IteratorError) Key

func (*IteratorError) Key() []byte

func (*IteratorError) Next

func (*IteratorError) Next() bool

func (*IteratorError) Release

func (*IteratorError) Release()

func (*IteratorError) Value

func (*IteratorError) Value() []byte

type KeyValueDeleter

type KeyValueDeleter interface {
	// Delete removes the key from the key-value data store.
	//
	// Note: [key] is safe to modify and read after calling Delete.
	Delete(key []byte) error
}

KeyValueDeleter wraps the Delete method of a backing data store.

type KeyValueReader

type KeyValueReader interface {
	// Has retrieves if a key is present in the key-value data store.
	//
	// Note: [key] is safe to modify and read after calling Has.
	Has(key []byte) (bool, error)

	// Get retrieves the given key if it's present in the key-value data store.
	// Returns ErrNotFound if the key is not present in the key-value data store.
	//
	// Note: [key] is safe to modify and read after calling Get.
	// The returned byte slice is safe to read, but cannot be modified.
	Get(key []byte) ([]byte, error)
}

KeyValueReader wraps the Has and Get method of a backing data store.

type KeyValueReaderWriter

type KeyValueReaderWriter interface {
	KeyValueReader
	KeyValueWriter
}

KeyValueReaderWriter allows read/write access to a backing data store.

type KeyValueReaderWriterDeleter

type KeyValueReaderWriterDeleter interface {
	KeyValueReader
	KeyValueWriter
	KeyValueDeleter
}

KeyValueReaderWriterDeleter allows read/write/delete access to a backing data store.

type KeyValueWriter

type KeyValueWriter interface {
	// Put inserts the given value into the key-value data store.
	//
	// Note: [key] and [value] are safe to modify and read after calling Put.
	//
	// If [value] is nil or an empty slice, then when it's retrieved
	// it may be nil or an empty slice.
	//
	// Similarly, a nil [key] is treated the same as an empty slice.
	Put(key []byte, value []byte) error
}

KeyValueWriter wraps the Put method of a backing data store.

type KeyValueWriterDeleter

type KeyValueWriterDeleter interface {
	KeyValueWriter
	KeyValueDeleter
}

KeyValueWriterDeleter allows write/delete access to a backing data store.