kv

Documentation

Overview

Package kv provides a key-value database that can be used to store and retrieve data.

The key-value database is backed by BoltDB, and is shared between all VUs. It is persisted to disk, so data stored in the database will be available across test runs.

The database is opened when the first KV instance is created, and closed when the last KV instance is closed.

Index

• Constants
• Variables
• type Error
  • func NewError(name ErrorName, message string) *Error
  • func (e *Error) Error() string
• type ErrorName
• type KV
  • func NewKV(vu modules.VU, db *db) *KV
  • func (k *KV) Clear() *sobek.Promise
  • func (k *KV) Close() error
  • func (k *KV) Delete(key sobek.Value) *sobek.Promise
  • func (k *KV) Get(key sobek.Value) *sobek.Promise
  • func (k *KV) List(options sobek.Value) *sobek.Promise
  • func (k *KV) Set(key sobek.Value, value sobek.Value) *sobek.Promise
  • func (k *KV) Size() *sobek.Promise
• type ListEntry
• type ListOptions
  • func ImportListOptions(rt *sobek.Runtime, options sobek.Value) ListOptions
• type ModuleInstance
  • func (mi *ModuleInstance) Exports() modules.Exports
  • func (mi *ModuleInstance) NewKV(_ sobek.ConstructorCall) *sobek.Object
  • func (mi *ModuleInstance) OpenKv() *sobek.Object
• type RootModule
  • func New() *RootModule
  • func (rm *RootModule) NewModuleInstance(vu modules.VU) modules.Instance

Constants

const (
	// DatabaseNotOpenError is emitted when the database is accessed before it is opened
	// or after it is closed.
	DatabaseNotOpenError ErrorName = "DatabaseNotOpenError"

	// DatabaseAlreadyOpenError is emitted when the database is opened more than once.
	DatabaseAlreadyOpenError = "DatabaseAlreadyOpenError"

	// BucketNotFoundError is emitted when the bucket is not found in the database.
	BucketNotFoundError = "BucketNotFoundError"

	// BucketExistsError is emitted when the bucket already exists in the database.
	BucketExistsError = "BucketExistsError"

	// KeyNotFoundError is emitted when the key is not found in the bucket.
	KeyNotFoundError = "KeyNotFoundError"

	// KeyRequiredError is emitted when inserting an empty key.
	KeyRequiredError = "KeyRequiredError"

	// KeyTooLargeError is emitted when the key is too large.
	KeyTooLargeError = "KeyTooLargeError"

	// ValueTooLargeError is emitted when the value is too large.
	ValueTooLargeError = "ValueTooLargeError"
)

const (
	// DefaultKvPath is the default path to the KV store
	DefaultKvPath = ".k6.kv"

	// DefaultKvBucket is the default bucket name for the KV store
	DefaultKvBucket = "k6"
)

Variables

var ErrStop = errors.New("stop")

ErrStop is used to stop a BoltDB iteration.

Types

type Error

type Error struct {
	// Name contains one of the strings associated with an error name.
	Name ErrorName `json:"name"`

	// Message represents message or description associated with the given error name.
	Message string `json:"message"`
}

Error represents a custom error emitted by the kv module

func NewError

func NewError(name ErrorName, message string) *Error

NewError returns a new Error instance.

func (*Error) Error

func (e *Error) Error() string

Error implements the `error` interface

type ErrorName

type ErrorName string

ErrorName represents the name of an error

type KV

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

KV is a key-value database that can be used to store and retrieve data.

Keys are always strings, and values can be any JSON-serializable value. Keys are ordered lexicographically. Keys are unique within a database, and the last value set for a given key is the one that is returned when reading the key.

func NewKV

func NewKV(vu modules.VU, db *db) *KV

NewKV returns a new KV instance.

func (*KV) Clear

func (k *KV) Clear() *sobek.Promise

Clear deletes all the keys in the store.

func (*KV) Close

func (k *KV) Close() error

Close closes the KV instance.

func (*KV) Delete

func (k *KV) Delete(key sobek.Value) *sobek.Promise

Delete deletes a key from the store.

func (*KV) Get

func (k *KV) Get(key sobek.Value) *sobek.Promise

Get returns the value of a key in the store.

func (*KV) List

func (k *KV) List(options sobek.Value) *sobek.Promise

List returns all the key-value pairs in the store.

The returned list is ordered lexicographically by key. The returned list is limited to 1000 entries by default. The returned list can be limited to a maximum number of entries by passing a limit option. The returned list can be limited to keys that start with a given prefix by passing a prefix option. See ListOptions for more details

func (*KV) Set

func (k *KV) Set(key sobek.Value, value sobek.Value) *sobek.Promise

Set sets the value of a key in the store.

If the key does not exist, it is created. If the key already exists, its value is overwritten.

func (*KV) Size

func (k *KV) Size() *sobek.Promise

Size returns the number of keys in the store.

type ListEntry

type ListEntry struct {
	Key   string `json:"key"`
	Value any    `json:"value"`
}

ListEntry is a key-value pair returned by KV.List().

type ListOptions

type ListOptions struct {
	// Prefix is used to select all the keys that start
	// with the given prefix.
	Prefix string `json:"prefix"`

	// Limit is the maximum number of entries to return.
	Limit int64 `json:"limit"`
	// contains filtered or unexported fields
}

ListOptions are the options that can be passed to KV.List().

func ImportListOptions

func ImportListOptions(rt *sobek.Runtime, options sobek.Value) ListOptions

ImportListOptions instantiates a ListOptions from a sobek.Value.

type ModuleInstance

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

ModuleInstance represents an instance of the JS module.

func (*ModuleInstance) Exports

func (mi *ModuleInstance) Exports() modules.Exports

Exports implements the modules.Instance interface and returns the exports of the JS module.

func (*ModuleInstance) NewKV

func (mi *ModuleInstance) NewKV(_ sobek.ConstructorCall) *sobek.Object

NewKV implements the modules.Instance interface and returns a new KV instance.

func (*ModuleInstance) OpenKv

func (mi *ModuleInstance) OpenKv() *sobek.Object

OpenKv opens the KV store and returns a KV instance.

type RootModule

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

RootModule is the global module instance that will create Client instances for each VU.

func New

func New() *RootModule

New returns a pointer to a new RootModule instance

func (*RootModule) NewModuleInstance

func (rm *RootModule) NewModuleInstance(vu modules.VU) modules.Instance

NewModuleInstance implements the modules.Module interface and returns a new instance for each VU.