kv

Documentation

Overview

Package kv implements a persistent Key-Value store based on the open-source BadgerDB. The implementation supports namespacing keys and their values as well as using a global (shared) namespace. The entire storage system works asynchronously using mutexes to restrict access to a single goroutine at a time.

Index

• Constants
• Variables
• type Database
  • func New(path string, opts ...Opt) (*Database, error)
  • func (d *Database) Close() error
  • func (d *Database) Config() badger.Options
  • func (d *Database) Delete(key string) error
  • func (d *Database) Get(key string) (value []byte, err error)
  • func (d *Database) Has(key string) (bool, error)
  • func (d *Database) Namespaces() []string
  • func (d *Database) Path() string
  • func (d *Database) Set(key string, value []byte) error
  • func (d *Database) SetNamespace(ns string)
• type Opt
  • func WithBadgerOptions(opts badger.Options) Opt
  • func WithContext(ctx context.Context) Opt
  • func WithDiscardRatio(ratio float64) Opt
  • func WithNamespace(namespace string) Opt
  • func WithNamespaces(namespaces ...string) Opt
  • func WithPath(path string) Opt
• type Store

Constants

const (
	DefaultKVName       = "store"
	DefaultNamespace    = "default"
	DefaultDiscardRatio = 0.7
)

Variables

var (
	DefaultPath       = fmt.Sprintf("/tmp/%s", DefaultKVName)
	DefaultNamespaces = []string{DefaultNamespace}
)

Types

type Database

type Database struct {
	// contains filtered or unexported fields
}

Database is the central type for the persisted Key-Value database

func New

func New(path string, opts ...Opt) (*Database, error)

New instantiates a new key-value store and configures it with the given Opt configuration options

func (*Database) Close

func (d *Database) Close() error

Close closes an active connection to a database. This method must be called during program shutdown or else you risk corrupting the data. Additionally, we run garbage collection across the entire database before finally shutting down.

func (*Database) Config

func (d *Database) Config() badger.Options

Config returns the badger.Options the database was initialized with

func (*Database) Delete

func (d *Database) Delete(key string) error

Delete deletes a key from the database

func (*Database) Get

func (d *Database) Get(key string) (value []byte, err error)

Get implements the Store interface for Database. It retrieves a key from the database with the given OperationOpt options to configure the current operation. The operation itself is handled asynchronously, although the method itself is also thread-safe.

func (*Database) Has

func (d *Database) Has(key string) (bool, error)

Has checks if the database contains a key by trying to read the value at the given key via the use of Get. If the method returns an error it is determined that the value does not exist and the error from Get is propagated alongside a false return value. Otherwise, it does and a nil-error is returned.

func (*Database) Namespaces

func (d *Database) Namespaces() []string

Namespaces returns the current namespaces the database has been initialized with. The function cannot error since by default only the (single) "default" namespace will be returned if the DB is otherwise largely unconfigured.

func (*Database) Path

func (d *Database) Path() string

Path returns the filesystem path to the database

func (*Database) Set

func (d *Database) Set(key string, value []byte) error

Set implements the Store interface for Database. It sets a key within the database to a certain value with the given OperationOpt options to configure the current operation. The operation itself is handled asynchronously, although the method itself is also thread-safe.

func (*Database) SetNamespace

func (d *Database) SetNamespace(ns string)

SetNamespace ...

type Opt

type Opt func(k *Database)

Opt is a configuration option for the newly initialized Key-Value database

func WithBadgerOptions

func WithBadgerOptions(opts badger.Options) Opt

WithBadgerOptions ...

func WithContext

func WithContext(ctx context.Context) Opt

WithContext ...

func WithDiscardRatio

func WithDiscardRatio(ratio float64) Opt

WithDiscardRatio ...

func WithNamespace

func WithNamespace(namespace string) Opt

WithNamespace ...

func WithNamespaces

func WithNamespaces(namespaces ...string) Opt

WithNamespaces ...

func WithPath

func WithPath(path string) Opt

WithPath ...

type Store

type Store interface {
	// Get retrieves the value of a given key within the current namespace from
	// the BadgerDB database. If a different namespace is to be checked
	// SetNamespace must be used beforehand.
	Get(key string) (value []byte, err error)

	// Set updates or sets the value for a given key within the current namespace.
	// It takes the value as a byte-slice instead of a string or a different type
	// to offer more versatility. If a different namespace is to be checked
	// SetNamespace must be used beforehand.
	Set(key string, value []byte) error

	// Has checks whether a database key exists within the current namespace. If
	// a different namespace is to be checked SetNamespace must be used beforehand.
	Has(key string) (contains bool, err error)

	// Namespaces lists all currently registered namespaces in the Database
	Namespaces() []string

	// Delete removes a key within the current namespace along with all of its data.
	// This is a non-recoverable operation. If a different namespace is to be checked
	// SetNamespace must be used beforehand.
	Delete(key string) error

	// Close closes the underlying connection to the BadgerDB database. This would
	// preferably be used with a `defer` statement in the main function since the
	// database may be need for the entire duration of the program.
	Close() error

	// Path returns the filesystem path the database was initialized for. This value
	// equal to the options.Dir and options.ValueDir fields.
	Path() string

	// Config returns the entire configuration with which the BadgerDB database was
	// initialized.
	Config() badger.Options
}