boltx

README

boltx

This package contains a collection of tools for BoltDB. It tries to simplify the handling of models in a BoltDB bucket without being too opinionated.

It's basically assumes that models implement encoding.BinaryMarshaler and encoding.BinaryUnmarshaler from Go's standard library.

type model struct { ... }

func (m *model) MarshalBinary() ([]byte, error) { ... }

func (m *model) UnmarshalBinary([]byte) (error) { ... }

Those methods should handle the (de)serialization of the model. The interfaces are than used by the functions of this package to store and load models.

model := &model{}

boltx.PutModel(bucket, []byte("key"), model)

boltx.GetModel(bucket, []byte("key"), model)

Queue

The Queue helper implements a queue (single-ended) on a bucket. It's persistent and safe to used with multiple goroutines.

queue := boltx.NewQueue(db, []byte("queue-test"))
queue.EnqueueModel(&model{"item"})

model := &model{}
queue.DequeueModel(model)

log.Println(model)

Deque

The Deque helper implements a deque (double-ended queue) on a bucket. It's persistent and safe to use with multiple goroutines.

deque := boltx.NewDeque(db, []byte("deque-test"))

go func () {
  deque.EnqueueModelBack(&model{"item"})
}()

model := &model{}
deque.DequeueModelFront(model)

log.Println(model)

Documentation

Overview

Package boltx contains a collection of tools for [BoltDB](https://github.com/boltdb/bolt). It tries to simplify the handling of models in a BoltDB bucket without being too opinionated.

It's basically assumes that models implement `encoding.BinaryMarshaler` and `encoding.BinaryUnmarshaler` from Go's standard library.

type model struct { ... }

func (m *model) MarshalBinary() ([]byte, error) { ... }

func (m *model) UnmarshalBinary([]byte) (error) { ... }

Those methods should handle the (de)serialization of the model. The interfaces are than used by the functions of this package to store and load models.

model := &model{}

boltx.PutModel(bucket, []byte("key"), model)

boltx.GetModel(bucket, []byte("key"), model)

Index

• Constants
• Variables
• func BucketSize(db *bolt.DB, name []byte) int
• func DeleteFromBucket(db *bolt.DB, name, key []byte) error
• func ForEach(bucket *bolt.Bucket, prototype encoding.BinaryUnmarshaler, ...) ([]byte, interface{}, error)
• func GetFromBucket(db *bolt.DB, name, key []byte) []byte
• func GetModel(bucket *bolt.Bucket, key []byte, model encoding.BinaryUnmarshaler) (bool, error)
• func GetModelFromBucket(db *bolt.DB, name, key []byte, model encoding.BinaryUnmarshaler) (bool, error)
• func Pop(tx *bolt.Tx, name []byte, position *Position) []byte
• func PopModelOrWait(tx *bolt.Tx, name []byte, position *Position, model encoding.BinaryUnmarshaler, ...) error
• func PopOrWait(tx *bolt.Tx, name []byte, position *Position, session *Session) []byte
• func Push(tx *bolt.Tx, name []byte, position *Position, value, defaultKey []byte) error
• func PushAndSignal(tx *bolt.Tx, name []byte, position *Position, value, defaultKey []byte, ...) error
• func PushModelAndSignal(tx *bolt.Tx, name []byte, position *Position, model encoding.BinaryMarshaler, ...) error
• func PutInBucket(db *bolt.DB, name, key, value []byte) error
• func PutModel(bucket *bolt.Bucket, key []byte, model encoding.BinaryMarshaler) error
• func PutModelInBucket(db *bolt.DB, name, key []byte, model encoding.BinaryMarshaler) error
• type Action
• type Deque
  • func NewDeque(db *bolt.DB, name []byte) *Deque
  • func (d *Deque) DequeueModelBack(model encoding.BinaryUnmarshaler) error
  • func (d *Deque) DequeueModelFront(model encoding.BinaryUnmarshaler) error
  • func (d *Deque) EnqueueModelBack(model encoding.BinaryMarshaler) error
  • func (d *Deque) EnqueueModelFront(model encoding.BinaryMarshaler) error
  • func (d *Deque) Size() int
• type Position
• type Queue
  • func NewQueue(db *bolt.DB, name []byte) *Queue
  • func (q *Queue) DequeueModel(model encoding.BinaryUnmarshaler) error
  • func (q *Queue) EnqueueModel(model encoding.BinaryMarshaler) error
  • func (q *Queue) Size() int
• type Session
  • func NewSession(db *bolt.DB) *Session
  • func (s *Session) Update(fn func(tx *bolt.Tx) error) error

Constants

const (
	// ActionContinue tells the iterator to jump to the next element.
	ActionContinue = 1 << iota

	// ActionReturn indicates that the iteration should be stopped and the current element should be returned.
	ActionReturn = 1 << iota

	// ActionUpdate tells the iterator that the current element has been changed and should be updated.
	ActionUpdate = 1 << iota

	// ActionDelete tells the iterator to delete the current element.
	ActionDelete = 1 << iota
)

Variables

var (
	// DefaultUint64QueueKey defines the default key for a queue with uint64 keys.
	DefaultUint64QueueKey = []byte{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}

	// DefaultUint64DequeKey defines the default key for a deque (double-ended queue) with uint64 keys.
	DefaultUint64DequeKey = big.NewInt(0).SetUint64(math.MaxUint64 / 2).Bytes()

	// PositionFront specifies the front of a queue or deque.
	PositionFront = &Position{delta: -1, fn: func(cursor *bolt.Cursor) ([]byte, []byte) {
		return cursor.First()
	}}

	// PositionBack specifies the back of a queue or deque.
	PositionBack = &Position{delta: 1, fn: func(cursor *bolt.Cursor) ([]byte, []byte) {
		return cursor.Last()
	}}
)

Functions

func BucketSize

func BucketSize(db *bolt.DB, name []byte) int

BucketSize returns the number of key/value pairs in the provided bucket. If the bucket doesn't exists, 0 is returned.

func DeleteFromBucket

func DeleteFromBucket(db *bolt.DB, name, key []byte) error

DeleteFromBucket removes the provided key from the provided bucket.

func ForEach

func ForEach(
	bucket *bolt.Bucket,
	prototype encoding.BinaryUnmarshaler,
	fn func([]byte, interface{}) (Action, error),
) ([]byte, interface{}, error)

ForEach iterates over all elements in the bucket.

func GetFromBucket

func GetFromBucket(db *bolt.DB, name, key []byte) []byte

GetFromBucket loads the value from the provided bucket at the provided key. If the bucket and the value was found, the content is returned. Nil otherwise.

func GetModel

func GetModel(bucket *bolt.Bucket, key []byte, model encoding.BinaryUnmarshaler) (bool, error)

GetModel loads the value from the provided bucket at the provided key and unmarshals it into the provided model. If the value was found, true is returned. False otherwise.

func GetModelFromBucket

func GetModelFromBucket(db *bolt.DB, name, key []byte, model encoding.BinaryUnmarshaler) (bool, error)

GetModelFromBucket loads the value from the provided bucket at the provided key and unmarshals it into the provided model. If the bucket and the value was found, true is returned. False otherwise.

func Pop

func Pop(tx *bolt.Tx, name []byte, position *Position) []byte

Pop removes and returns the value at the provided position in the provided bucket. If the bucket is empty, nil is returned.

func PopModelOrWait

func PopModelOrWait(
	tx *bolt.Tx,
	name []byte,
	position *Position,
	model encoding.BinaryUnmarshaler,
	session *Session,
) error

PopModelOrWait behaves like PopOrWair, but handels the model unmarshaling.

func PopOrWait

func PopOrWait(tx *bolt.Tx, name []byte, position *Position, session *Session) []byte

PopOrWait tries to pop a value from the provided bucket at the provided position. If the bucket is empty, the provided transaction is stored in the provided session and the function blocks until a value is inserted into the bucket. Insert-transactions should be started with session.Update.

func Push

func Push(tx *bolt.Tx, name []byte, position *Position, value, defaultKey []byte) error

Push inserts the provided value at the provided position in the provided bucket. If the bucket is empty, the provided defaultKey is used.

func PushAndSignal

func PushAndSignal(tx *bolt.Tx, name []byte, position *Position, value, defaultKey []byte, session *Session) error

PushAndSignal pushes the the provided value at the provided position in the provided bucket. Afterwards an update is siganled through the provided session.

func PushModelAndSignal

func PushModelAndSignal(
	tx *bolt.Tx,
	name []byte,
	position *Position,
	model encoding.BinaryMarshaler,
	defaultKey []byte,
	session *Session,
) error

PushModelAndSignal behaves like PushAndSignal, but handels the model marshaling.

func PutInBucket

func PutInBucket(db *bolt.DB, name, key, value []byte) error

PutInBucket creates the bucket with the provided name if it's not existing and stores the provided value under the provided key.

func PutModel

func PutModel(bucket *bolt.Bucket, key []byte, model encoding.BinaryMarshaler) error

PutModel marshals the provided model and stores it in the provided bucket under the provided key.

func PutModelInBucket

func PutModelInBucket(db *bolt.DB, name, key []byte, model encoding.BinaryMarshaler) error

PutModelInBucket marshals the provided model, creates the bucket with the provided name if it's not existing and stores the marshalled model under the provided key.

Types

type Action

type Action int

Action indicates how an element should be handled after the iterator went over it.

type Deque

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

Deque defines a double-ended queue on a bucket. It's persistent and safe to use with multiple goroutines.

deque := boltx.NewDeque(db, []byte("deque-test"))

go func () {
  deque.EnqueueModelBack(&model{"item"})
}()

model := &model{}
deque.DequeueModelFront(model)

log.Println(model)

func NewDeque

func NewDeque(db *bolt.DB, name []byte) *Deque

NewDeque initializes a deque in the bucket with the provided name.

func (*Deque) DequeueModelBack

func (d *Deque) DequeueModelBack(model encoding.BinaryUnmarshaler) error

DequeueModelBack gets the value from the back of the deque, unmarshals it into the provided model and removes it. If the deque is empty the call blocks until an element is enqueued.

func (*Deque) DequeueModelFront

func (d *Deque) DequeueModelFront(model encoding.BinaryUnmarshaler) error

DequeueModelFront gets the value from the front of the deque, unmarshals it into the provided model and removes it. If the deque is empty the call blocks until an element is enqueued.

func (*Deque) EnqueueModelBack

func (d *Deque) EnqueueModelBack(model encoding.BinaryMarshaler) error

EnqueueModelBack puts the provided model to the back of the deque.

func (*Deque) EnqueueModelFront

func (d *Deque) EnqueueModelFront(model encoding.BinaryMarshaler) error

EnqueueModelFront puts the provided model to the front of the deque.

func (*Deque) Size

func (d *Deque) Size() int

Size returns the number of elements in the deque.

type Position

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

Position defines a position in a queue or deque.

type Queue

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

Queue defines a single-ended queue on a bucket. It's persistent and safe to use with multiple goroutines.

queue := boltx.NewQueue(db, []byte("queue-test"))

queue.EnqueueModel(&model{"item"})

model := &model{}
queue.DequeueModel(model)

log.Println(model)

func NewQueue

func NewQueue(db *bolt.DB, name []byte) *Queue

NewQueue initializes a queue in the bucket with the provided name.

func (*Queue) DequeueModel

func (q *Queue) DequeueModel(model encoding.BinaryUnmarshaler) error

DequeueModel gets the value from the front of the deque, unmarshals it into the provided model and removes it. If the deque is empty the call blocks until an element is enqueued.

func (*Queue) EnqueueModel

func (q *Queue) EnqueueModel(model encoding.BinaryMarshaler) error

EnqueueModel puts the provided model to the back of the queue.

func (*Queue) Size

func (q *Queue) Size() int

Size returns the number of elements in the deque.

type Session

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

Session defines a update session. It can be used to re-used transactions that are waiting on an update.

func NewSession

func NewSession(db *bolt.DB) *Session

NewSession returns a new initialized session.

func (*Session) Update

func (s *Session) Update(fn func(tx *bolt.Tx) error) error

Update starts an update transaction on the db. If a transaction is set, it's re-used.