skv

README

skv

skv is a Simple Key-Value store for Go.

Check the blog post for a description of skv internals.

Package documentation is available here.

Follow us on Twitter for updates! @therapidloop

Documentation

Overview

Package skv provides a simple persistent key-value store for Go values. It can store a mapping of string to any gob-encodable Go value. It is lightweight and performant, and ideal for use in low-traffic websites, utilities and the like.

The API is very simple - you can Put(), Get() or Delete() entries. These methods are goroutine-safe.

skv uses BoltDB for storage and the encoding/gob package for encoding and decoding values. There are no other dependencies.

Index

• Variables
• type KVStore
  • func Open(path string) (*KVStore, error)
  • func (kvs *KVStore) Close() error
  • func (kvs *KVStore) Delete(key string) error
  • func (kvs *KVStore) Get(key string, value interface{}) error
  • func (kvs *KVStore) List(ty reflect.Type) (map[string]interface{}, error)
  • func (kvs *KVStore) Put(key string, value interface{}) error

Variables

var (
	// ErrNotFound is returned when the key supplied to a Get or Delete
	// method does not exist in the database.
	ErrNotFound = errors.New("skv: key not found")

	// ErrBadValue is returned when the value supplied to the Put method
	// is nil.
	ErrBadValue = errors.New("skv: bad value")
)

Types

type KVStore

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

KVStore represents the key value store. Use the Open() method to create one, and Close() it when done.

func Open

func Open(path string) (*KVStore, error)

Open a key-value store. "path" is the full path to the database file, any leading directories must have been created already. File is created with mode 0640 if needed.

Because of BoltDB restrictions, only one process may open the file at a time. Attempts to open the file from another process will fail with a timeout error.

func (*KVStore) Close

func (kvs *KVStore) Close() error

Close closes the key-value store file.

func (*KVStore) Delete

func (kvs *KVStore) Delete(key string) error

Delete the entry with the given key. If no such key is present in the store, it returns ErrNotFound.

store.Delete("key42")

func (*KVStore) Get

func (kvs *KVStore) Get(key string, value interface{}) error

Get an entry from the store. "value" must be a pointer-typed. If the key is not present in the store, Get returns ErrNotFound.

type MyStruct struct {
    Numbers []int
}
var val MyStruct
if err := store.Get("key42", &val); err == skv.ErrNotFound {
    // "key42" not found
} else if err != nil {
    // an error occurred
} else {
    // ok
}

The value passed to Get() can be nil, in which case any value read from the store is silently discarded.

if err := store.Get("key42", nil); err == nil {
    fmt.Println("entry is present")
}

func (*KVStore) List

func (kvs *KVStore) List(ty reflect.Type) (map[string]interface{}, error)

List all entry values from the store. In case of there are not entries, it will return nil.

func (*KVStore) Put

func (kvs *KVStore) Put(key string, value interface{}) error

Put an entry into the store. The passed value is gob-encoded and stored. The key can be an empty string, but the value cannot be nil - if it is, Put() returns ErrBadValue.

err := store.Put("key42", 156)
err := store.Put("key42", "this is a string")
m := map[string]int{
    "harry": 100,
    "emma":  101,
}
err := store.Put("key43", m)