kv

Documentation

Overview

Package kv provides a uniform API for key-value databases supporting snapshots and transactions. The API is designed to be minimal, unambiguous, and well-defined, enabling multiple database backends to implement adapters for this interface.

Keys are represented as strings. The empty string is not a valid key, so that it can be used to denote the beginning and/or end of key ranges.

Values are represented as io.Reader objects, so that database implementations can stream large values or may provide additional metadata with the values.

Index

• type Database
  • func DatabaseFrom[T Transaction, S Snapshot](db GenericDatabase[T, S]) Database
• type Deleter
• type GenericDatabase
• type Getter
• type Ranger
• type ReadWriter
• type Reader
• type Setter
• type Snapshot
• type Transaction
• type Writer

Types

type Database

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

Database interface type defines methods required on all key-value databases.

func DatabaseFrom

func DatabaseFrom[T Transaction, S Snapshot](db GenericDatabase[T, S]) Database

DatabaseFrom is a helper function that can create non-generic Database interface object for different database implementations each with their own concrete return types for NewTransaction and NewSnapshot methods.

type Deleter

type Deleter interface {
	// Delete removes a key-value pair. Returns os.ErrInvalid if the key is empty
	// and os.ErrNotExist if the key does not exist or a non-nil error if the
	// operation fails.
	Delete(ctx context.Context, key string) error
}

Deleter defines an interface for removing key-value pairs.

type GenericDatabase

type GenericDatabase[T Transaction, S Snapshot] interface {
	NewTransaction(context.Context) (T, error)
	NewSnapshot(context.Context) (S, error)
}

GenericDatabase interface is similar to the Database interface, but uses generic type arguments to represent database specific concrete types for NewTransaction and NewSnapshot methods. DatabaseFrom function can be used to convert a GenericDatabase to a non-generic Database interface.

type Getter

type Getter interface {
	// Get retrieves the value for a given key. Returns os.ErrInvalid if the key
	// is empty and os.ErrNotExist if the key is not found or a non-nil error if
	// the operation fails.
	Get(ctx context.Context, key string) (io.Reader, error)
}

Getter defines an interface for retrieving key-value pairs.

type Ranger

type Ranger interface {
	// Ascend returns an iterator over key-value pairs in ascending order within
	// the range defined by begin and end.
	//
	//  - If begin and end are both empty, range includes all pairs in the database.
	//  - If begin is empty, range begins at the smallest key.
	//  - If end is empty, range ends after the largest key.
	//  - If both are non-empty, begin must be less than or equal to end, or
	//    os.ErrInvalid is returned.
	//
	// The range includes the begin key and excludes the end key. Errors are
	// stored in errp.
	Ascend(ctx context.Context, beg, end string, errp *error) iter.Seq2[string, io.Reader]

	// Descend is similar to Ascend but iterates in the descending order.
	Descend(ctx context.Context, beg, end string, errp *error) iter.Seq2[string, io.Reader]
}

Ranger defines an interface for iterating over key-value pairs within a specified range.

type ReadWriter

type ReadWriter interface {
	Reader
	Writer
}

ReadWriter combines Reader and Writer interfaces for full key-value pair access.

type Reader

type Reader interface {
	Getter
	Ranger
}

Reader combines interfaces for reading key-value pairs.

type Setter

type Setter interface {
	// Set creates or updates a key-value pair. Returns os.ErrInvalid if the key
	// is empty or value is nil and returns a non-nil error if the operation
	// fails.
	Set(ctx context.Context, key string, value io.Reader) error
}

Setter defines an interface for creating or updating key-value pairs.

type Snapshot

type Snapshot interface {
	Reader

	// Discard releases resources associated with the snapshot. Returns a non-nil
	// error if the operation fails.
	Discard(ctx context.Context) error
}

Snapshot represents a read-only view of the database at a specific point in time.

type Transaction

type Transaction interface {
	ReadWriter

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

	// Commit validates all reads and writes for conflicts and atomically applies
	// changes to the key-value store. Returns nil on success or if the
	// transaction has already committed. Returns non-nil error if transaction
	// commit has failed or was already rolled back.
	//
	// In case of remote databases, this function MUST NOT return a non-nil error
	// ever (eg: timeout) if the transaction was committed, but success response
	// is lost due to network issues/delays. Database client SHOULD internally
	// retry forever (as necessary) to confirm the final status of the
	// transaction.
	Commit(ctx context.Context) error
}

Transaction represents a read-write transaction with atomic operations.

type Writer

type Writer interface {
	Setter
	Deleter
}

Writer combines interfaces for modifying key-value pairs.