kv

Documentation

Overview

Package kv provides an abstraction over hierarchical key-value stores.

Index

• Variables
• func CreateBucket(ctx context.Context, tx Tx, key Key) error
• func Each(ctx context.Context, tx Tx, fnc func(k Key, v Value) error, ...) error
• func Register(reg Registration)
• func Seek(ctx context.Context, it Iterator, key Key) bool
• func Update(ctx context.Context, kv KV, update func(tx Tx) error) error
• func View(ctx context.Context, kv KV, view func(tx Tx) error) error
• type ByKey
  • func (s ByKey) Len() int
  • func (s ByKey) Less(i, j int) bool
  • func (s ByKey) Swap(i, j int)
• type Getter
• type Iterator
  • func ApplyIteratorOptions(it Iterator, opts []IteratorOption) Iterator
• type IteratorOption
• type IteratorOptionFunc
  • func (opt IteratorOptionFunc) Apply(it Iterator) Iterator
• type KV
• type Key
  • func SKey(parts ...string) Key
  • func (k Key) Append(parts Key) Key
  • func (k Key) AppendBytes(parts ...[]byte) Key
  • func (k Key) Clone() Key
  • func (k Key) Compare(k2 Key) int
  • func (k Key) HasPrefix(pref Key) bool
• type OpenPathFunc
• type Pair
• type PrefixIterator
• type Registration
  • func ByName(name string) *Registration
  • func List() []Registration
• type Seeker
• type Tx
• type Value
  • func GetBatch(ctx context.Context, tx Getter, keys []Key) ([]Value, error)
  • func (v Value) Clone() Value

Variables

var (
	// ErrNotFound is returned then a key was not found in the database.
	ErrNotFound = errors.New("kv: not found")
	// ErrReadOnly is returned when write operation is performed on read-only database or transaction.
	ErrReadOnly = errors.New("kv: read only")
	// ErrConflict is returned when write operation performed be current transaction cannot be committed
	// because of another concurrent write. Caller must restart the transaction.
	ErrConflict = errors.New("kv: read only")
)

Functions

func CreateBucket

func CreateBucket(ctx context.Context, tx Tx, key Key) error

CreateBucket is a helper to create buckets upfront without writing any key-value pairs to it.

func Each

func Each(ctx context.Context, tx Tx, fnc func(k Key, v Value) error, opts ...IteratorOption) error

Each is a helper to enumerate all key-value pairs with a specific prefix. See Iterator for rules of using returned values.

func Register

func Register(reg Registration)

Register globally registers a database driver.

func Seek

func Seek(ctx context.Context, it Iterator, key Key) bool

Seek the iterator to a given key. If the key does not exist, the next key is used. Function returns false if there is no key greater or equal to a given one.

func Update

func Update(ctx context.Context, kv KV, update func(tx Tx) error) error

Update is a helper to open a read-write transaction and update the database. The update function may be called multiple times in case of conflicts with other writes.

func View

func View(ctx context.Context, kv KV, view func(tx Tx) error) error

View is a helper to open a read-only transaction to read the database.

Types

type ByKey

type ByKey []Key

ByKey sorts keys in ascending order.

func (ByKey) Len

func (s ByKey) Len() int

func (ByKey) Less

func (s ByKey) Less(i, j int) bool

func (ByKey) Swap

func (s ByKey) Swap(i, j int)

type Getter

type Getter interface {
	// Get fetches a value for a single key from the database.
	// It return ErrNotFound if key does not exists.
	Get(ctx context.Context, key Key) (Value, error)
}

type Iterator

type Iterator interface {
	base.Iterator
	// Reset the iterator to the starting state. Closed iterator can not reset.
	Reset()
	// Key return current key. Returned value will become invalid on Next or Close.
	// Caller should not modify or store the value - use Clone.
	Key() Key
	// Val return current value. Returned value will become invalid on Next or Close.
	// Caller should not modify or store the value - use Clone.
	Val() Value
}

Iterator is an iterator over hierarchical key-value store.

func ApplyIteratorOptions

func ApplyIteratorOptions(it Iterator, opts []IteratorOption) Iterator

ApplyIteratorOptions applies all iterator options.

type IteratorOption

type IteratorOption interface {
	// ApplyKV applies option to the KV iterator. Implementation may wrap or replace the iterator.
	ApplyKV(it Iterator) Iterator
}

IteratorOption is an additional option that affects iterator behaviour.

Implementations in generic KV package should assert for an optimized version of option (via interface assertion), and fallback to generic implementation if the store doesn't support this option natively.

type IteratorOptionFunc

type IteratorOptionFunc func(it Iterator) Iterator

IteratorOptionFunc is a function type that implements IteratorOption.

func (IteratorOptionFunc) Apply

func (opt IteratorOptionFunc) Apply(it Iterator) Iterator

type KV

type KV interface {
	base.DB
	Tx(ctx context.Context, rw bool) (Tx, error)
	View(ctx context.Context, fn func(tx Tx) error) error
	Update(ctx context.Context, fn func(tx Tx) error) error
}

KV is an interface for hierarchical key-value databases.

type Key

type Key [][]byte

Key is a hierarchical binary key used in a database.

func SKey

func SKey(parts ...string) Key

SKey is a helper for making string keys.

func (Key) Append

func (k Key) Append(parts Key) Key

Append key parts and return a new value. Value is not a deep copy, use Clone for this.

func (Key) AppendBytes

func (k Key) AppendBytes(parts ...[]byte) Key

AppendBytes is the same like Append, but accepts bytes slices.

func (Key) Clone

func (k Key) Clone() Key

Clone returns a copy of the key.

func (Key) Compare

func (k Key) Compare(k2 Key) int

Compare return 0 when keys are equal, -1 when k < k2 and +1 when k > k2.

func (Key) HasPrefix

func (k Key) HasPrefix(pref Key) bool

HasPrefix checks if a key has a given prefix.

type OpenPathFunc

type OpenPathFunc func(path string) (KV, error)

OpenPathFunc is a function for opening a database given a path.

type Pair

type Pair struct {
	Key Key
	Val Value
}

Pair is a key-value pair.

type PrefixIterator

type PrefixIterator interface {
	Iterator
	// WithPrefix implements WithPrefix iterator option.
	// Current iterator will be replaced with a new one and must not be used after this call.
	WithPrefix(pref Key) Iterator
}

PrefixIterator is an Iterator optimization to support WithPrefix option.

type Registration

type Registration struct {
	base.Registration
	OpenPath OpenPathFunc
}

Registration is an information about the database driver.

func ByName

func ByName(name string) *Registration

ByName returns a registered database driver by it's name.

func List

func List() []Registration

List enumerates all globally registered database drivers.

type Seeker

type Seeker interface {
	Iterator
	// Seek the iterator to a given key. If the key does not exist, the next key is used.
	// Function returns false if there is no key greater or equal to a given one.
	Seek(ctx context.Context, key Key) bool
}

type Tx

type Tx interface {
	base.Tx
	Getter
	// GetBatch fetches values for multiple keys from the database.
	// Nil element in the slice indicates that key does not exists.
	GetBatch(ctx context.Context, keys []Key) ([]Value, error)
	// Put writes a key-value pair to the database.
	// New value will immediately be visible by Get on the same Tx,
	// but implementation might buffer the write until transaction is committed.
	Put(ctx context.Context, k Key, v Value) error
	// Del removes the key from the database. See Put for consistency guaranties.
	Del(ctx context.Context, k Key) error
	// Scan starts iteration over key-value pairs. Returned results are affected by IteratorOption.
	Scan(ctx context.Context, opts ...IteratorOption) Iterator
}

Tx is a transaction over hierarchical key-value store.

type Value

type Value []byte

Value is a binary value stored in a database.

func GetBatch

func GetBatch(ctx context.Context, tx Getter, keys []Key) ([]Value, error)

GetBatch is an implementation of Tx.GetBatch for databases that has no native implementation for it.

func (Value) Clone

func (v Value) Clone() Value

Clone returns a copy of the value.