boltdb

README

boltdb

Simple wrapper around BoltDB.

LICENSE

Like the original BoltDB code by Ben Johnson and active maintenance development by etcd.io, this wrapper also uses the MIT license.

Documentation

Index

• Variables
• func DecodeUint64(valueBytes []byte) uint64
• func EncodeUint64(value uint64) []byte
• type Bucket
  • func (bucket *Bucket) Bucket(path []byte) (*Bucket, error)
  • func (bucket *Bucket) DB() *DB
  • func (bucket *Bucket) Delete(key []byte) error
  • func (bucket *Bucket) DeleteBucket(path []byte) error
  • func (bucket *Bucket) Get(key []byte) []byte
  • func (bucket *Bucket) Iterate() *Iterator
  • func (bucket *Bucket) Name() []byte
  • func (bucket *Bucket) NextSequence() (uint64, error)
  • func (bucket *Bucket) Put(key []byte, value []byte) error
  • func (bucket *Bucket) Stats() BucketStats
  • func (bucket *Bucket) TX() *TX
  • func (bucket *Bucket) WithIterator(opts IteratorOptions, cb WithinIteratorCallback) error
• type BucketStats
• type DB
  • func New(filename string) (*DB, error)
  • func NewWithOptions(filename string, opts Options) (*DB, error)
  • func (db *DB) BeginTx(opts TxOptions) (*TX, error)
  • func (db *DB) Close()
  • func (db *DB) Delete(bucket []byte, key []byte) error
  • func (db *DB) Get(bucket []byte, key []byte) ([]byte, error)
  • func (db *DB) Put(bucket []byte, key []byte, value []byte) error
  • func (db *DB) WithinTx(opts TxOptions, cb WithinTxCallback) error
• type Iterator
  • func (iter *Iterator) Bucket() *Bucket
  • func (iter *Iterator) CopyValue() []byte
  • func (iter *Iterator) Delete() error
  • func (iter *Iterator) First() bool
  • func (iter *Iterator) HasKeyPrefix(prefix []byte) bool
  • func (iter *Iterator) IsNestedBucket() bool
  • func (iter *Iterator) IsValid() bool
  • func (iter *Iterator) Key() []byte
  • func (iter *Iterator) Last() bool
  • func (iter *Iterator) Next() bool
  • func (iter *Iterator) Prev() bool
  • func (iter *Iterator) Seek(prefix []byte, method SeekMethod) bool
  • func (iter *Iterator) Value() []byte
• type IteratorOptions
• type Options
• type SeekMethod
• type TX
  • func (tx *TX) Bucket(path []byte) (*Bucket, error)
  • func (tx *TX) Commit() error
  • func (tx *TX) DB() *DB
  • func (tx *TX) DeleteBucket(path []byte) error
  • func (tx *TX) ReadOnly() bool
  • func (tx *TX) Rollback()
• type TxOptions
• type WithinIteratorCallback
• type WithinTxCallback

Variables

var (
	ErrInvalidPath           = errors.New("invalid path")
	ErrBucketNotFound        = bbolt.ErrBucketNotFound
	ErrTxNotWritable         = bbolt.ErrTxNotWritable
	ErrDatabaseReadOnly      = bbolt.ErrDatabaseReadOnly
	ErrInvalidCursorPosition = errors.New("invalid cursor position")
)

Functions

func DecodeUint64

func DecodeUint64(valueBytes []byte) uint64

DecodeUint64 decodes a little endian uint64 value

func EncodeUint64

func EncodeUint64(value uint64) []byte

EncodeUint64 stores an uint64 into a byte array using little endian format

Types

type Bucket

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

Bucket represents a directory that contains keys and values inside the database.

func (*Bucket) Bucket

func (bucket *Bucket) Bucket(path []byte) (*Bucket, error)

Bucket returns a bucket on the database (and creates if it does not exist)

func (*Bucket) DB

func (bucket *Bucket) DB() *DB

DB gets the database associated with this bucket.

func (*Bucket) Delete

func (bucket *Bucket) Delete(key []byte) error

Delete deletes a specific key. No error is returned if key is not found.

func (*Bucket) DeleteBucket

func (bucket *Bucket) DeleteBucket(path []byte) error

DeleteBucket removes an existing child bucket on the database NOTE: Inner sub-keys and buckets will be also deleted

func (*Bucket) Get

func (bucket *Bucket) Get(key []byte) []byte

Get returns the value of a key in a bucket or nil if not found.

func (*Bucket) Iterate

func (bucket *Bucket) Iterate() *Iterator

Iterate creates an iterator object that allows to search for stored keys.

func (*Bucket) Name

func (bucket *Bucket) Name() []byte

Name returns the bucket name.

func (*Bucket) NextSequence

func (bucket *Bucket) NextSequence() (uint64, error)

NextSequence returns an autoincrement integer for the bucket.

func (*Bucket) Put

func (bucket *Bucket) Put(key []byte, value []byte) error

Put stores a key/value pair in the bucket.

func (*Bucket) Stats

func (bucket *Bucket) Stats() BucketStats

func (*Bucket) TX

func (bucket *Bucket) TX() *TX

TX gets the transaction associated with this bucket.

func (*Bucket) WithIterator

func (bucket *Bucket) WithIterator(opts IteratorOptions, cb WithinIteratorCallback) error

type BucketStats

type BucketStats = bbolt.BucketStats

BucketStats contains statistical data about a bucket.

type DB

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

DB represents a database connection to a BoltDB database.

func New

func New(filename string) (*DB, error)

New returns a new database wrapper. If the database does not exist, it will be created.

func NewWithOptions

func NewWithOptions(filename string, opts Options) (*DB, error)

NewWithOptions returns a new database wrapper using the provided options.

func (*DB) BeginTx

func (db *DB) BeginTx(opts TxOptions) (*TX, error)

BeginTx starts a new transaction within the database.

func (*DB) Close

func (db *DB) Close()

Close closes the database connection.

func (*DB) Delete

func (db *DB) Delete(bucket []byte, key []byte) error

Delete deletes a specific key in the specified bucket. No error is returned if key is not found.

func (*DB) Get

func (db *DB) Get(bucket []byte, key []byte) ([]byte, error)

Get returns the value of a key in the specified bucket or nil if not found.

func (*DB) Put

func (db *DB) Put(bucket []byte, key []byte, value []byte) error

Put stores a key/value pair in the specified bucket.

func (*DB) WithinTx

func (db *DB) WithinTx(opts TxOptions, cb WithinTxCallback) error

WithinTx initiates a transaction and calls a callback.

type Iterator

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

Iterator encapsulates a bucket key/value iterator

func (*Iterator) Bucket

func (iter *Iterator) Bucket() *Bucket

Bucket returns the bucket associated with this iterator.

func (*Iterator) CopyValue

func (iter *Iterator) CopyValue() []byte

CopyValue acts like Value but returns a copy of the value so it remains valid after moving the iterator position.

func (*Iterator) Delete

func (iter *Iterator) Delete() error

Delete deletes the current key the iterator is pointing to.

func (*Iterator) First

func (iter *Iterator) First() bool

First moves the iterator to the first entry inside the bucket.

func (*Iterator) HasKeyPrefix

func (iter *Iterator) HasKeyPrefix(prefix []byte) bool

HasKeyPrefix checks if the current key has the provided prefix.

func (*Iterator) IsNestedBucket

func (iter *Iterator) IsNestedBucket() bool

IsNestedBucket returns true if the iterator is pointing to a nested bucket.

func (*Iterator) IsValid

func (iter *Iterator) IsValid() bool

IsValid returns true if the iterator is pointing to some value or nested bucket.

func (*Iterator) Key

func (iter *Iterator) Key() []byte

Key gets the current iterator key. Nil if reached the end or a search failed. The key is valid until the iterator position is changed.

func (*Iterator) Last

func (iter *Iterator) Last() bool

Last moves the iterator to the last entry inside the bucket.

func (*Iterator) Next

func (iter *Iterator) Next() bool

Next moves the iterator to the next entry inside the bucket.

func (*Iterator) Prev

func (iter *Iterator) Prev() bool

Prev moves the iterator to the previous entry inside the bucket.

func (*Iterator) Seek

func (iter *Iterator) Seek(prefix []byte, method SeekMethod) bool

Seek searches for a key match with the provided prefix and method. Prefix can be nil.

func (*Iterator) Value

func (iter *Iterator) Value() []byte

Value gets the current iterator value. The value is valid until the iterator position is changed. IMPORTANT: If value is nil, then the key points to a nested bucket name.

type IteratorOptions

type IteratorOptions struct {
	// Reverse scan keys in reverse order.
	Reverse bool

	// Prefix filters the iterator to keys with the given prefix. It cannot be used in conjunction with FirstKey.
	Prefix []byte

	// FirstKey sets the start point of the iterator. It cannot be used with Prefix.
	FirstKey []byte
}

type Options

type Options struct {
	ReadOnly    bool
	DirFileMode os.FileMode
	DbFileMode  os.FileMode
}

Options specifies a set of options when creating/opening the database.

type SeekMethod

type SeekMethod int

const (
	SeekExact          SeekMethod = iota
	SeekPrefix         SeekMethod = iota
	SeekPrefixReverse  SeekMethod = iota
	SeekGreaterOrEqual SeekMethod = iota
	SeekLessOrEqual    SeekMethod = iota
)

type TX

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

TX represents a transaction within the database.

func (*TX) Bucket

func (tx *TX) Bucket(path []byte) (*Bucket, error)

Bucket returns a bucket on the database. If the transaction is writable and the bucket does not exist, this function will try to create it.

func (*TX) Commit

func (tx *TX) Commit() error

Commit stores the transaction changes into the database and, on success, ends the operation.

func (*TX) DB

func (tx *TX) DB() *DB

DB gets the database this transaction belongs to.

func (*TX) DeleteBucket

func (tx *TX) DeleteBucket(path []byte) error

DeleteBucket removes an existing child bucket from the database including nested buckets and stored keys.

func (*TX) ReadOnly

func (tx *TX) ReadOnly() bool

ReadOnly returns if the transaction is writable or not.

func (*TX) Rollback

func (tx *TX) Rollback()

Rollback discards the transaction changes and ends the operation.

type TxOptions

type TxOptions struct {
	ReadOnly bool
}

TxOptions specifies a set of options when starting a transaction.

type WithinIteratorCallback

type WithinIteratorCallback func(iter *Iterator) (stop bool, err error)

WithinIteratorCallback is a callback that is called for every key found in the given request NOTE: If value == nil, then they key points to a child bucket

type WithinTxCallback

type WithinTxCallback func(tx *TX) error

WithinTxCallback is a callback to be called after the transaction is initiated.