flat

Documentation

Overview

Package flat provides an abstraction over flat key-value stores.

Index

• Variables
• func Each(ctx context.Context, tx Tx, fnc func(k Key, v Value) error, ...) error
• func KeyUnescape(k Key) kv.Key
• 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 Upgrade(flat KV) kv.KV
• func UpgradeOpenPath(open OpenPathFunc) kv.OpenPathFunc
• func View(ctx context.Context, kv KV, view func(tx Tx) error) error
• type Getter
• type Iterator
  • func ApplyIteratorOptions(it Iterator, opts []IteratorOption) Iterator
• type IteratorOption
• type IteratorOptionFunc
  • func (opt IteratorOptionFunc) ApplyFlat(it Iterator) Iterator
• type KV
• type Key
  • func KeyEscape(k kv.Key) Key
  • func (k Key) Clone() Key
• type OpenPathFunc
• type Pair
  • func (p Pair) String() string
• 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)

Variables

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

Functions

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 KeyUnescape

func KeyUnescape(k Key) kv.Key

KeyUnescape converts flat Key into kv.Key.

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 Upgrade

func Upgrade(flat KV) kv.KV

Upgrade upgrades flat KV to hierarchical KV.

func UpgradeOpenPath

func UpgradeOpenPath(open OpenPathFunc) kv.OpenPathFunc

UpgradeOpenPath automatically upgrades flat KV to hierarchical KV on open.

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 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 {
	// ApplyFlat option to the flat KV iterator. Implementation may wrap or replace the iterator.
	ApplyFlat(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) ApplyFlat

func (opt IteratorOptionFunc) ApplyFlat(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 flat key-value databases.

type Key

type Key []byte

Key is a flat binary key used in a database.

func KeyEscape

func KeyEscape(k kv.Key) Key

KeyEscape converts kv.Key to a flat Key.

func (Key) Clone

func (k Key) Clone() Key

Clone returns a copy of the key.

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.

func (Pair) String

func (p Pair) String() string

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 flat key-value store.

type Value

type Value = kv.Value

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.