bucketeer

package module
v0.0.0-...-2271523 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 24, 2017 License: MIT Imports: 7 Imported by: 0

README

go-boltdb-bucketeer

A Go package for streamlining use of buckets and encoded values in Bolt.

The Bucketeer type wraps an already-open *bolt.DB instance to provide its convenience methods. Thus, you can create Bucketeer instances for every bucket path you want to access, and their transactions will be thread-safe and share the single DB write lock.

This package also provides most of its functionality via stand-alone methods which take *bolt.DB arguments.

Status

Current master branch should be considered a "release candidate" with interfaces and type signatures subject to change.

I will tag a 1.0 release when I am satisfied with usability and test coverage.

Usage

Basic use case with a single nested bucket:

var db *bolt.DB
// ... open DB ...
// we'll specify a path with a "bucket1" bucket nested in a "Misc" root bucket
bucket1 := bucketeer.New(db, "Misc", "bucket1")
// create the path buckets in the DB if they don't exist
bucket1.EnsurePathBuckets()
// store some key-value pairs in the "bucket1" bucket
bucket1.ForStringKey("key1").PutStringValue("value1")
bucket1.ForStringKey("key2").PutStringValue("value2")
bucket1.ForStringKey("key3").PutStringValue("value3")
// retrieve a value
value2, _ := bucket1.ForStringKey("key2").GetStringValue()

TODO

Cursor functionality will be useful, but lacking generics it will be difficult to iterate arbitrary key-value type combinations.

Online GoDoc

https://godoc.org/github.com/momokatte/go-boltdb-bucketeer

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DeleteKey 

func DeleteKey(db *bolt.DB, path Path, key []byte) (err error)

func EnsureNestedBucket 

func EnsureNestedBucket(db *bolt.DB, path Path, bucket string) (err error)

EnsureNestedBucket creates a nested bucket if it does not exist. The bucket's full parent path must exist.

func EnsurePathBuckets 

func EnsurePathBuckets(db *bolt.DB, path Path) (err error)

EnsurePathBuckets creates any buckets along the provided path if they do not exist.

func GetBucket 

func GetBucket(tx *bolt.Tx, path Path) (b *bolt.Bucket)

GetBucket retrieves the last (innermost) bucket of the provided path for use within a transaction. The bucket's full parent path must exist.

func GetByteValue 

func GetByteValue(b *bolt.Bucket, key []byte) (valueCopy []byte)

GetByteValue gets the key's value as a byte slice.

func GetInt64Value 

func GetInt64Value(b *bolt.Bucket, key []byte) (value int64, err error)

GetInt64Value gets the key's value and converts its bytes into an int64 value. The value must be 8 bytes with the bits in big-endian ordering.

func GetUint64Value 

func GetUint64Value(b *bolt.Bucket, key []byte) (value uint64, err error)

GetUint64Value gets the key's value and converts its bytes into a uint64 value. The value must be 8 bytes with the bits in big-endian ordering.

func GetUvarintValue 

func GetUvarintValue(b *bolt.Bucket, key []byte) (value uint64, err error)

GetUvarintValue gets the key's value and decodes it into a uint64 value using variable-length decoding.

func GetValueInTx 

func GetValueInTx(tx *bolt.Tx, path Path, key []byte) (value []byte)

func GetVarintValue 

func GetVarintValue(b *bolt.Bucket, key []byte) (value int64, err error)

GetVarintValue gets the key's value and decodes it into an int64 value using variable-length decoding.

func IncrementInt64Value 

func IncrementInt64Value(b *bolt.Bucket, key []byte, value int64) (newValue int64, err error)

IncrementInt64Value increments the key's value by the provided value, and returns the updated value.

func IncrementUint64Value 

func IncrementUint64Value(b *bolt.Bucket, key []byte, value uint64) (newValue uint64, err error)

IncrementUint64Value increments the key's value by the provided value, and returns the updated value.

func PutBinaryValue 

func PutBinaryValue(b *bolt.Bucket, key []byte, valueObj encoding.BinaryMarshaler) (err error)

PutBinaryValue marshals the provided object into its binary form and sets it as the value for the key.

func PutInt64Value 

func PutInt64Value(b *bolt.Bucket, key []byte, value int64) error

PutInt64Value encodes the provided int64 into big-endian bytes and sets that as the value for the key.

func PutJsonValue 

func PutJsonValue(b *bolt.Bucket, key []byte, valueObj interface{}) (err error)

PutJsonValue marshals the provided object into its JSON form and sets it as the value for the key.

func PutTextValue 

func PutTextValue(b *bolt.Bucket, key []byte, valueObj encoding.TextMarshaler) (err error)

PutTextValue marshals the provided object into its textual form and sets it as the value for the key.

func PutUint64Value 

func PutUint64Value(b *bolt.Bucket, key []byte, value uint64) (err error)

PutUint64Value encodes the provided uint64 into big-endian bytes and sets that as the value for the key.

func PutUvarintValue 

func PutUvarintValue(b *bolt.Bucket, key []byte, value uint64) (err error)

PutUvarintValue encodes the provided uint64 into bytes using variable-length encoding and sets that as the value for the key. Values set via this method must be read using variable-length decoding.

func PutVarintValue 

func PutVarintValue(b *bolt.Bucket, key []byte, value int64) (err error)

PutVarintValue encodes the provided int64 into bytes using variable-length encoding and sets that as the value for the key. Values set via this method must be read using variable-length decoding.

func UnmarshalBinaryValue 

func UnmarshalBinaryValue(b *bolt.Bucket, key []byte, valueObj encoding.BinaryUnmarshaler) (err error)

UnmarshalBinaryValue gets the key's value and unmarshals it into the provided object.

func UnmarshalJsonValue 

func UnmarshalJsonValue(b *bolt.Bucket, key []byte, valueObj interface{}) (err error)

UnmarshalJsonValue gets the key's value and unmarshals it into the provided object.

func UnmarshalTextValue 

func UnmarshalTextValue(b *bolt.Bucket, key []byte, valueObj encoding.TextUnmarshaler) (err error)

UnmarshalTextValue gets the key's value and unmarshals it into the provided object.

func UpdateInBucket 

func UpdateInBucket(db *bolt.DB, path Path, updateFunc func(b *bolt.Bucket) error) (err error)

UpdateInBucket executes the provided function in an Update transaction.

func ViewInBucket 

func ViewInBucket(db *bolt.DB, path Path, viewFunc func(b *bolt.Bucket) error) (err error)

ViewInBucket executes the provided function in a View transaction.

func ViewValue 

func ViewValue(db *bolt.DB, path Path, key []byte, viewFunc func(value []byte) error) (err error)

ViewValue gets the key's value and passes it to the provided function for arbitrary use. The byte slice is only valid within the scope of the function.

Types

type BinaryKey 

type BinaryKey struct {
	encoding.BinaryMarshaler
}

func NewBinaryKey 

func NewBinaryKey(keyObj encoding.BinaryMarshaler) *BinaryKey

func (BinaryKey) KeyBytes 

func (k BinaryKey) KeyBytes() (b []byte)

type Bucketeer 

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

Bucketeer encapsulates the components needed to resolve a bucket in BoltDB and provides convenience methods for initializing Keyfarers for various key types.

func ForPath 

func ForPath(db *bolt.DB, path Path) (bb *Bucketeer)

ForPath creates a new Bucketeer for the provided database and bucket path.

func New 

func New(db *bolt.DB, bucketNames ...string) (bb *Bucketeer)

New creates a Bucketeer for the provided database and bucket names.

func (*Bucketeer) DeleteNestedBucket 

func (bb *Bucketeer) DeleteNestedBucket(bucket string) error

DeleteNestedBucket deletes a nested bucket with the provided name.

func (*Bucketeer) EnsureNestedBucket 

func (bb *Bucketeer) EnsureNestedBucket(bucket string) error

EnsureNestedBucket creates a nested bucket if it does not exist. The bucket's full parent path must exist.

func (*Bucketeer) EnsurePathBuckets 

func (bb *Bucketeer) EnsurePathBuckets() error

EnsurePathBuckets creates any buckets along the provided path if they do not exist.

func (*Bucketeer) ForBinaryKey 

func (bb *Bucketeer) ForBinaryKey(keyObj encoding.BinaryMarshaler) *Keyfarer

ForBinaryKey creates a new Keyfarer for the binary form of the provided object. If there is an error marshaling the object to binary, this function will panic.

func (*Bucketeer) ForByteKey 

func (bb *Bucketeer) ForByteKey(key []byte) *Keyfarer

ForByteKey creates a new Keyfarer for the provided key name.

func (*Bucketeer) ForInt64Key 

func (bb *Bucketeer) ForInt64Key(key int64) *Keyfarer

ForInt64Key creates a new Keyfarer for the provided key name. The key value is shifted to always be a positive number, and is stored in big-endian, fixed-length format so it is byte-sortable with other int64 keys.

func (*Bucketeer) ForJsonKey 

func (bb *Bucketeer) ForJsonKey(keyObj interface{}) *Keyfarer

ForJsonKey creates a new Keyfarer for the JSON form of the provided object. If there is an error marshaling the object to JSON, this function will panic.

func (*Bucketeer) ForKey 

func (bb *Bucketeer) ForKey(key Key) *Keyfarer

ForByteKey creates a new Keyfarer for the provided key.

func (*Bucketeer) ForStringKey 

func (bb *Bucketeer) ForStringKey(key string) *Keyfarer

ForStringKey creates a new Keyfarer for the provided key name.

func (*Bucketeer) ForTextKey 

func (bb *Bucketeer) ForTextKey(keyObj encoding.TextMarshaler) *Keyfarer

ForTextKey creates a new Keyfarer for the textual form of the provided object. If there is an error marshaling the object to text, this function will panic.

func (*Bucketeer) ForUint64Key 

func (bb *Bucketeer) ForUint64Key(key uint64) *Keyfarer

ForUint64Key creates a new Keyfarer for the provided key name. The key value is stored in big-endian, fixed-length format so it is byte-sortable with other uint64 keys.

func (*Bucketeer) GetBucketStats 

func (bb *Bucketeer) GetBucketStats() (stats bolt.BucketStats, err error)

GetBucketStats retrieves the BucketStats for the current bucket.

func (*Bucketeer) InNestedBucket 

func (bb *Bucketeer) InNestedBucket(bucket string) *Bucketeer

InNestedBucket creates a new Bucketeer for a nested bucket with the provided name.

func (*Bucketeer) Update 

func (bb *Bucketeer) Update(updateFunc func(b *bolt.Bucket) error) error

Update executes the provided function in an Update transaction.

func (*Bucketeer) UpdateWithSequence 

func (bb *Bucketeer) UpdateWithSequence(updateFunc func(b *bolt.Bucket, sequence uint64) error) (sequence uint64, err error)

UpdateWithSequence executes the provided function in an Update transaction, and supplies the next sequence value for the bucket.

func (*Bucketeer) View 

func (bb *Bucketeer) View(viewFunc func(b *bolt.Bucket) error) error

View executes the provided function in a View transaction.

type ByteKey 

type ByteKey []byte

func NewByteKey 

func NewByteKey(key []byte) ByteKey

func (ByteKey) KeyBytes 

func (k ByteKey) KeyBytes() []byte

type Int64Key 

type Int64Key int64

func NewInt64Key 

func NewInt64Key(key int64) Int64Key

func (Int64Key) KeyBytes 

func (k Int64Key) KeyBytes() (b []byte)

type JsonKey 

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

func NewJsonKey 

func NewJsonKey(keyObj interface{}) *JsonKey

func (JsonKey) KeyBytes 

func (k JsonKey) KeyBytes() (b []byte)

type Key 

type Key interface {
	KeyBytes() []byte
}

type Keyfarer 

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

Keyfarer encapsulates the components needed to resolve a key in BoltDB and provides convenience methods for setting and retrieving the value

func NewKeyfarer 

func NewKeyfarer(bb *Bucketeer, key []byte) (kf *Keyfarer)

func (*Keyfarer) GetByteValue 

func (kf *Keyfarer) GetByteValue() (value []byte, err error)

GetByteValue gets the key's value as a byte slice.

func (*Keyfarer) GetStringValue 

func (kf *Keyfarer) GetStringValue() (value string, err error)

GetStringValue gets the key's value as a string.

func (*Keyfarer) GetUvarintValue 

func (kf *Keyfarer) GetUvarintValue() (value uint64, err error)

func (*Keyfarer) GetVarintValue 

func (kf *Keyfarer) GetVarintValue() (value int64, err error)

func (*Keyfarer) IncrementInt64Value 

func (kf *Keyfarer) IncrementInt64Value(value int64) (newValue int64, err error)

func (*Keyfarer) IncrementUint64Value 

func (kf *Keyfarer) IncrementUint64Value(value uint64) (newValue uint64, err error)

func (*Keyfarer) PutBinaryValue 

func (kf *Keyfarer) PutBinaryValue(valueObj encoding.BinaryMarshaler) error

PutBinaryValue marshals the provided object into its binary form and sets it as the value for the key.

func (*Keyfarer) PutByteValue 

func (kf *Keyfarer) PutByteValue(value []byte) error

PutByteValue sets the value for the key.

func (*Keyfarer) PutJsonValue 

func (kf *Keyfarer) PutJsonValue(valueObj interface{}) error

PutJsonValue marshals the provided object into its JSON form and sets it as the value for the key.

func (*Keyfarer) PutStringValue 

func (kf *Keyfarer) PutStringValue(value string) (err error)

PutByteValue sets the value for the key.

func (*Keyfarer) PutTextValue 

func (kf *Keyfarer) PutTextValue(valueObj encoding.TextMarshaler) (err error)

PutTextValue marshals the provided object into its textual form and sets it as the value for the key.

func (*Keyfarer) PutUvarintValue 

func (kf *Keyfarer) PutUvarintValue(value uint64) error

func (*Keyfarer) PutVarintValue 

func (kf *Keyfarer) PutVarintValue(value int64) error

func (*Keyfarer) UnmarshalBinaryValue 

func (kf *Keyfarer) UnmarshalBinaryValue(valueObj encoding.BinaryUnmarshaler) error

UnmarshalBinaryValue gets the key's value and unmarshals it into the provided object.

func (*Keyfarer) UnmarshalJsonValue 

func (kf *Keyfarer) UnmarshalJsonValue(valueObj interface{}) error

UnmarshalJsonValue gets the key's value and unmarshals it into the provided object.

func (*Keyfarer) UnmarshalTextValue 

func (kf *Keyfarer) UnmarshalTextValue(valueObj encoding.TextUnmarshaler) error

UnmarshalTextValue gets the key's value and unmarshals it into the provided object.

func (*Keyfarer) ViewValue 

func (kf *Keyfarer) ViewValue(viewFunc func(value []byte) error) error

ViewValue gets the key's value and passes it to the provided function for arbitrary use. The byte slice is only valid within the scope of the function.

type Path 

type Path [][]byte

Path attaches methods to [][]byte to make it more convenient to use as a sequence of BoltDB bucket names.

func NewPath 

func NewPath(buckets ...string) (p Path)

NewPath creates a new Path from one or more bucket names.

func (Path) Nest 

func (p Path) Nest(bucket string) (newPath Path)

Nest allocates a new Path with the provided bucket name appended to the current path.

func (Path) String 

func (p Path) String() string

String formats the contents of this Path so it can be read by a human.

func (Path) Swap 

func (p Path) Swap(i, j int)

Swap should not be called on a sequence of bucket names.

type StringKey 

type StringKey string

func NewStringKey 

func NewStringKey(key string) StringKey

func (StringKey) KeyBytes 

func (k StringKey) KeyBytes() []byte

type TextKey 

type TextKey struct {
	encoding.TextMarshaler
}

func NewTextKey 

func NewTextKey(keyObj encoding.TextMarshaler) *TextKey

func (TextKey) KeyBytes 

func (k TextKey) KeyBytes() (b []byte)

type Uint64Key 

type Uint64Key uint64

func NewUint64Key 

func NewUint64Key(key uint64) Uint64Key

func (Uint64Key) KeyBytes 

func (k Uint64Key) KeyBytes() (b []byte)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.