keyvalue

Documentation

Index

• Constants
• Variables
• type Bucket
• type BucketView
• type Database
  • func CreateDatabase(filePath string, dbName string, ifNotExists bool) (Database, error)
  • func OpenDatabase(filePath string, dbName string) (Database, error)
• type DatabaseRegistry
• type DatabaseView
  • func OpenDatabaseView(filePath string, dbName string) (DatabaseView, error)
• type KeyValue

Constants

const (
	// READ_MODE is used when opening the database in read-only mode
	READ_MODE os.FileMode = 0400
	// READ_WRITE_MODE is used when opening the database in read-write mode
	READ_WRITE_MODE os.FileMode = 0600

	// CREATED is used as the key to store the database creation timestamp in the root database bucket
	CREATED = "created"
)

Variables

var (
	ErrFilePathIsBlank             = errors.New("Path must not be blank")
	ErrDatabaseNameMustNotBeBlank  = errors.New("Database name must not be blank.")
	ErrBucketNameMustNotBeBlank    = errors.New("Bucket name must not be blank.")
	ErrDatabaseBucketAlreadyExists = errors.New("Database bucket already exists")
)

Database related errors

Types

type Bucket

type Bucket interface {
	BucketView

	// Put sets the value for a key in the bucket. If the key exist then its previous value will be overwritten.
	// Supplied value must remain valid for the life of the transaction.
	// Returns an error if the key is blank, if the key is too large, or if the value is too large.
	Put(key string, value []byte) error

	// PutMultiple will put all values received on the data channel within the same transaction, i.e., either all or none will be stored.
	// The puts are performed async, and when the the puts are done, then the result will be communicated via the response channel.
	// Once nil is received on the data channel, then this signals the transaction was successfully committed.
	// If the transaction failed, then the error is returned on the response channel.
	PutMultiple(data <-chan *KeyValue) <-chan error

	// Delete removes the keys from the bucket. If the key does not exist then nothing is done and a nil error is returned.
	// All or none are deleted within the same transaction.
	Delete(keys ...string) error

	// CreateBucket creates a new bucket at the given key and returns the new bucket.
	// Returns an error if the key already exists, if the bucket name is blank, or if the bucket name is too long.
	CreateBucket(name string) (Bucket, error)

	// CreateBucketIfNotExists creates a new bucket if it doesn't already exist and returns a reference to it.
	// Returns an error if the bucket name is blank, or if the bucket name is too long.
	CreateBucketIfNotExists(name string) (Bucket, error)

	// DeleteBucket deletes a bucket at the given key. Returns an error if the bucket does not exists, or if the key represents a non-bucket value.
	DeleteBucket(name string) error

	// Buckets iterate through the top-level children buckets and returns them on the returned channel.
	// The cancel channel is used to terminate the iteration early by the client.
	Buckets(cancel <-chan struct{}) <-chan Bucket

	// Bucket returns the bucket for the specified name. If the bucket does not exist, then nil is returned.
	// If path is specified, then the bucket will traverse the path to locate the Bucket within its hierarchy.
	Bucket(path ...string) Bucket
}

Bucket represents a bucket of key-value pairs. Keys are strings, but values are simply bytes. Buckets can form a hierarchy of buckets.

type BucketView

type BucketView interface {
	// Name returns the Bucket name
	Name() string

	// Path returns the bucket's path location
	Path() []string

	// Exists returns true if the bucket exists. It might have been deleted.
	Exists() bool

	// Get returns the value for the specified key
	// If the key does not exist, or if the key actually refers to a child Bucket, then nil is returned
	// If bucket does not exist, then by definition, the bucket has no data and nil is returned.
	Get(key string) []byte

	// Keys returns the keys stored in this bucket. Keys are sorted, thus seek may be used to seek a position to start iterating.
	// seek is optional - if specified, then seek moves the cursor to a given key and returns it. If the key does not exist then the next key is used.
	Keys(seek string, cancel <-chan struct{}) <-chan string

	// KeyValues iterates through all key-value pairs and returns them via the channel.
	// The cancel channel is used to terminate the iteration early by the client.
	KeyValues(seek string, cancel <-chan struct{}) <-chan *KeyValue

	// BucketViews iterate through the top-level children buckets and returns via the returned channel.
	// The cancel channel is used to terminate the iteration early by the client.
	BucketViews(cancel <-chan struct{}) <-chan BucketView

	// BucketView returns the bucket for the specified path. If the bucket does not exist, then nil is returned.
	// The path is traversed to locate the Bucket within its hierarchy.
	BucketView(path ...string) BucketView
}

BucketView is a read-only view of the Bucket

type Database

type Database interface {
	Bucket

	// Created returns when the database was created, or an error if it cannot be determined
	Created() (time.Time, error)

	// Close releases all database resources. All transactions must be closed before closing the database.
	Close() error
}

Database provides a read-write view of the database

func CreateDatabase

func CreateDatabase(filePath string, dbName string, ifNotExists bool) (Database, error)

CreateDatabase creates a new database with the specified name at the specified path ifNotExists = true -> if the database already exists then no error is returned ifNotExists = true -> if the database already exists, then an error is returned

If the database file does not exist, then it will be created. The database existence is determined by the existence of a root bucket that matches the db name.

func OpenDatabase

func OpenDatabase(filePath string, dbName string) (Database, error)

OpenDatabase opens the database in read-write mode The filePath must point to a bbolt file. The file must have the following structure : - a root bucket must exist that matches the database name

type DatabaseRegistry

type DatabaseRegistry interface {
	// DatabaseNames returns names of databases that the registry is aware of
	DatabaseNames() []string

	// OpenDatabaseNames returns the names of databases that are currently open
	OpenDatabaseNames() []string

	// DatabaseView will return the specified database if it is registered.
	// NOTE: a database can only be opened in read-only mode or read-write mode, i.e., it is not allowed to open the database in both modes
	DatabaseView(name string) (DatabaseView, error)

	// Database will return the specified database if it is registered.
	// NOTE: a database can only be opened in read-only mode or read-write mode, i.e., it is not allowed to open the database in both modes
	Database(name string) (Database, error)

	// CloseAll closes all open databases
	CloseAll()
}

DatabaseRegistry is a database registry

type DatabaseView

type DatabaseView interface {
	BucketView

	// Created returns when the database was created, or an error if it cannot be determined
	Created() (time.Time, error)

	// Close releases all database resources. All transactions must be closed before closing the database.
	Close() error
}

DatabaseView provides a read-only view of the database

func OpenDatabaseView

func OpenDatabaseView(filePath string, dbName string) (DatabaseView, error)

OpenDatabaseView opens the database in read-only mode. No other process may open it in read-write mode. Read-only mode uses a shared lock to allow multiple processes to read from the database but it will block any processes from opening the database in read-write mode.

The path must point to a bbolt file. The file must have the following structure : - a root bucket must exist with the db name - the root 'db' bucket must contain a key named 'name', which is the database name

type KeyValue

type KeyValue struct {
	Key   string
	Value []byte
}

KeyValue key-value pair