kv

README

An uniform API for many different Key-Value Databases

This module defines an uniform API for key-value databases with snapshots and transactions. API is aimed to be simple, unambiguous and well-defined. Multiple database backends should be able to define adapters to support this API.

This package contains only the API interfaces and common utility functions. Real key-value databases implementing this API are defined in separate packages. For example, see github.com/bvkgo/kv/kvmemdb.

NOTES

Empty string "" is not a valid key

This API requires that empty string "" cannot be a valid key. Iterator API uses empty strings to indicate the end of key range.

Documentation

Index

• func Close(v Iterator) error
• func WithReadWriter(ctx context.Context, db Database, f func(context.Context, ReadWriter) error) error
• func WithReader(ctx context.Context, db Database, f func(context.Context, Reader) error) error
• type Database
• type Deleter
• type Getter
• type Iterator
• type Ranger
• type ReadWriter
• type Reader
• type Scanner
• type Setter
• type Snapshot
• type Transaction
• type Writer

Functions

func Close

func Close(v Iterator) error

Close is a helper function that invokes Close method on the input Iterator.

Some key-value store implementations may need to release resources, so this generalized helper function can be used without access to concrete data type of the underlying object.

func WithReadWriter

func WithReadWriter(ctx context.Context, db Database, f func(context.Context, ReadWriter) error) error

WithReadWriter runs the input function under a temporary transaction. Transaction is committed if the input function returns nil or rollback-ed otherwise.

func WithReader

func WithReader(ctx context.Context, db Database, f func(context.Context, Reader) error) error

WithReader runs the input function under a temporary snapshot.

Types

type Database

type Database interface {
	NewTransaction(ctx context.Context) (Transaction, error)
	NewSnapshot(ctx context.Context) (Snapshot, error)
}

type Deleter

type Deleter interface {
	// Delete removes a key-value pair. Returns nil on success.
	//
	// It may return nil or os.ErrNotExist if key doesn't exist.
	Delete(ctx context.Context, key string) error
}

type Getter

type Getter interface {
	// Get reads a key-value pair. Returns nil on success.
	//
	// It may return a nil io.Reader on success if backend supports it.
	Get(ctx context.Context, key string) (io.Reader, error)
}

type Iterator

type Iterator interface {
	// Fetch returns the key-value pair at the current iterator position or the
	// next position. If next parameter is true, iterator position is
	// pre-incremented (or pre-decremented) before fetching the key-value pair.
	//
	// Returns io.EOF when the iterator reaches to the end. Returns a non-nil
	// error if iterator encounters any failures and the same error is repeated
	// for all further calls.
	Fetch(ctx context.Context, next bool) (string, io.Reader, error)
}

Iterator represents a position in a range of key-value pairs visited by Ascend, Descend and Scan operations. If there is any error in reading a key-value pair, it is retained in the iterator and the iteration is stopped.

it, err := db.Ascend(ctx, "aaa", "zzz")
if err != nil {
  return err
}
defer kv.Close(it)

for k, v, err := it.Fetch(ctx, false); err == nil; k, v, err = it.Fetch(ctx, true) {
  ...
  if ... {
    break
  }
  ...
}

if _, _, err := it.Fetch(ctx, false); err != nil && !errors.Is(err, io.EOF) {
  return err
}

type Ranger

type Ranger interface {
	// Ascend returns key-value pairs of a range in ascending order through an
	// iterator. Range is determined by the `begin` and `end` parameters.
	//
	// The `begin` parameter identifies the smaller side key and the `end`
	// parameter identifies the larger side key. When they are both non-empty
	// `begin` must be lesser than the `end` or os.ErrInvalid is returned.
	//
	// When both `begin` and `end` are non-empty, then range starts at the
	// `begin` key (included) and stops before the `end` key (excluded).
	//
	// When both `begin` and `end` are empty, then all key-value pairs are part
	// of the range. They are returned in ascending order for `Ascend` and in
	// descending order for `Descend`.
	//
	// When `begin` is empty then it represents the smallest key and when `end`
	// is empty it represents the key-after the largest key (so that the largest
	// key is included in the range).
	Ascend(ctx context.Context, begin, end string) (Iterator, error)

	// Descend is same as `Ascend`, but returns the determined range in
	// descending order of the keys.
	Descend(ctx context.Context, begin, end string) (Iterator, error)
}

type ReadWriter

type ReadWriter interface {
	Reader
	Writer
}

type Reader

type Reader interface {
	Getter
	Ranger
	Scanner
}

type Scanner

type Scanner interface {
	// Scanner returns all key-value pairs through an iterator. No specific order
	// is guaranteed, but each key is visited exactly once.
	Scan(ctx context.Context) (Iterator, error)
}

type Setter

type Setter interface {
	// Set creates or updates a key-value pair. Returns nil on success.
	//
	// Depending on the backend, a nil io.Reader value may also be valid.
	Set(ctx context.Context, key string, value io.Reader) error
}

type Snapshot

type Snapshot interface {
	Reader

	Discard(ctx context.Context) error
}

type Transaction

type Transaction interface {
	ReadWriter

	// Rollback cancels a transaction without checking for conflicts. Returns nil
	// on success.
	//
	// Rollback may return os.ErrClosed if transaction is already committed or
	// rolled-back.
	Rollback(ctx context.Context) error

	// Commit validates all reads (and writes) performed by the transaction for
	// conflicts with other transactions and atomically applies all changes to
	// the backing key-value store. Returns nil if transaction is committed
	// successfully.
	//
	// Commit may return os.ErrClosed if transaction is already committed or
	// rolled-back.
	Commit(ctx context.Context) error
}

Transaction represents a read-write transaction.

type Writer

type Writer interface {
	Setter
	Deleter
}