kvb

README

KVB is an Sqlite3-backed embedded local key value store for Go, focusing on simplicity and data integrity. It currently hardcodes the CGO-free Sqlite3 library github.com/ncruces/go-sqlite3 in WAL mode as backend. This key-value store uses []byte slices as values and strings as keys and is therefore encoding neutral. There is an otherwise identical key-value store called kvstore that uses GOB encoding instead.

Installation

go get https://github.com/rasteric/kvb

Development takes place at the main branch so you need to make sure to always get a release, not the current state of main.

Quick Start

package main

import (
	"errors"
	"fmt"
	"log"
	"os"

	"github.com/rasteric/kvb"
)

func main() {
	db := kvb.New()
	path, err := os.MkdirTemp("", "kvb-test")
	if err != nil {
		panic(err)
	}
	err = db.Open(path)
	if err != nil {
		panic(err)
	}
	// make sure the test dir is cleaned up afterwards
	defer func() {
		err := db.Close()
		if err != nil {
			log.Println(err)
		}
		os.RemoveAll(path)
	}()

	// checking a key value pair doesn't exist
	if _, err := db.Get("hello"); errors.Is(err, kvb.NotFoundErr) {
		fmt.Println(`there is no key "hello"`)
	} else {
		fmt.Println(err)
	}

	// setting a key value pair
	err = db.Set("example", []byte("hello world!"))
	if err != nil {
		panic(err)
	}

	// getting the value for a key
	s, err := db.Get("example")
	if err != nil {
		panic(err)
	}
	fmt.Println(s)

	// setting a default and key info
	err = db.SetDefault("example", []byte("have a nice day!"), kvb.KeyInfo{Description: "an example key",
		Category: "testing"})
	if err != nil {
		panic(err)
	}

	// reverting a key value to its default
	if err := db.Revert("example"); err != nil {
		panic(err)
	}

	s, _ = db.Get("example")
	fmt.Println(s)
}

See the tests for more examples. Notice that kvb.NotFoundErr is returned when a get operation fails. Since all kinds of errors can occur with file-based databases, this API was chosen instead of the more common value, ok:=db.Get(key) from maps and other key value stores. Check for the error with errors.Is(err,kvb.NotFoundErr) to distinguish it from other errors. Use SetDefault to set a default, in case of which the default is returned if no value was set.

Documentation

All API calls are in the following interface:

type KeyValueStore interface {
	Open(path string) error                   // open the database at directory path
	Close() error                             // close the database
	Set(key string, value []byte) error       // set the key to the given value, which must be gob serializable
	Get(key string) ([]byte, error)           // get the value for key, NotFoundErr if there is no key
	SetMany(map[string][]byte) error          // set all key-value pairs in the map in one transaction
	GetAll(limit int) (map[string][]byte, error) // get all key-value pairs as a map
	Revert(key string) error                  // revert key to its default
	Info(key string) (KeyInfo, bool)          // returns key information for a key if it is present
	Delete(key string) error                  // remove the key and value for the key
	DeleteMany(keys []string) error           // remove all the given keys in one transaction
	SetDefault(key string,                    // set a default and info for a key
		value []byte,
		info KeyInfo) error
}

The path argument to Open needs to be a directory whose name is the name you wish the database to have. This is so because the a key-value store may write more than one file, for example the write-ahead log in addition to the database. The actual sqlite database s called kvb.sqlite in the default implementation.

License

This library is MIT licensed and free for commercial and personal use as long as the license conditions are satisfied. See the accompanying LICENSE file for more information.

Documentation

Index

• Variables
• type BinaryKeyValueStore
• type KVB
  • func New() *KVB
  • func (db *KVB) Close() error
  • func (db *KVB) Delete(key string) error
  • func (db *KVB) DeleteMany(keys []string) error
  • func (db *KVB) Get(key string) ([]byte, error)
  • func (db *KVB) GetAll(limit int) (map[string][]byte, error)
  • func (db *KVB) HasKey(key string) bool
  • func (db *KVB) Info(key string) (KeyInfo, bool)
  • func (db *KVB) Open(path string) error
  • func (db *KVB) Revert(key string) error
  • func (db *KVB) Set(key string, value []byte) error
  • func (db *KVB) SetDefault(key string, value []byte, info KeyInfo) error
  • func (db *KVB) SetMany(pairs map[string][]byte) error
• type KeyInfo

Variables

var AlreadyOpenErr = errors.New(`database already open`)

var NoDefaultErr = errors.New(`no default value set for given key`)

var NotFoundErr = errors.New(`key not found`)

var NotOpenErr = errors.New(`key value store is closed`)

Types

type BinaryKeyValueStore

type BinaryKeyValueStore interface {
	Open(path string) error                      // open the database at directory path
	Close() error                                // close the database
	Set(key string, value []byte) error          // set the key to the given value, which must be gob serializable
	Get(key string) ([]byte, error)              // get the value for key, NotFoundErr if there is no key
	SetMany(map[string][]byte) error             // set all key-value pairs in the map in one transaction
	GetAll(limit int) (map[string][]byte, error) // get all key-value pairs as a map
	Revert(key string) error                     // revert key to its default
	Info(key string) (KeyInfo, bool)             // returns key information for a key if it is present
	Delete(key string) error                     // remove the key and value for the key
	DeleteMany(keys []string) error              // remove all the given keys in one transaction
	SetDefault(key string,
		value []byte,
		info KeyInfo) error
}

BinaryKeyValueStore is the interface for a key value database.

type KVB

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

KVB implements BinaryKeyValueStore interface with an sqlite database backend.

func New

func New() *KVB

New creates a new key value store that is not yet opened.

func (*KVB) Close

func (db *KVB) Close() error

Close closes the database.

func (*KVB) Delete

func (db *KVB) Delete(key string) error

Delete removes the key and value from the key value store.

func (*KVB) DeleteMany

func (db *KVB) DeleteMany(keys []string) error

DeleteMany removes all given keys in one transaction.

func (*KVB) Get

func (db *KVB) Get(key string) ([]byte, error)

Get gets the value for the given key, the default if no value for the key is stored but a default is present, and NotFoundErr if neither of them is present.

func (*KVB) GetAll

func (db *KVB) GetAll(limit int) (map[string][]byte, error)

GetAll returns all key-value pairs as a map. If limit is 0 or negative, all key value pairs are returned. Although this is usually not advisable, this method may be used in combination with SetMany to save and load maps, i.e., use the key value store merely for persistence and keep the data in memory.

func (*KVB) HasKey

func (db *KVB) HasKey(key string) bool

HasKey returns true if the key is set. Notice that the value and default for the key may still be nil, as nil can also be set as a value. If the database is not open, false is returned.

func (*KVB) Info

func (db *KVB) Info(key string) (KeyInfo, bool)

Info attempts to obtain information about the given key, returns false if none can be found. This method will also return false if an error occurs.

func (*KVB) Open

func (db *KVB) Open(path string) error

Open a database at the path specified when the database was created, which holds all database files. If directories to path/name do not exist, they are created recursively with Unix permissions 0755.

func (*KVB) Revert

func (db *KVB) Revert(key string) error

Revert reverts the value for the given key to its default. If no default has been set, NoDefaultErr is returned.

func (*KVB) Set

func (db *KVB) Set(key string, value []byte) error

Set sets the value for the given key, overwriting an existing value for the key if there is one.

func (*KVB) SetDefault

func (db *KVB) SetDefault(key string, value []byte, info KeyInfo) error

SetDefault sets a default value for the given key, as well as info and category.

func (*KVB) SetMany

func (db *KVB) SetMany(pairs map[string][]byte) error

SetMany sets all pairs in the given map in one transaction.

type KeyInfo

type KeyInfo struct {
	Description string
	Category    string
}

KeyInfo is provides information about a key. This is useful for preference systems.