gg_bolt

package
v0.3.40 Latest Latest
Warning

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

 Go to latest Published: Mar 9, 2025 License: BSD-3-Clause Imports: 7 Imported by: 0

README

DB Bolt

Introduction to BBolt

Bolt is a pure Go key/value store inspired by Howard Chu's LMDB project.

The goal of the project is to provide a simple, fast, and reliable database for projects that don't require a full database server such as Postgres or MySQL.

BBolt supports fully serializable transactions, ACID semantics, and lock-free MVCC with multiple readers and a single writer. Bolt can be used for projects that want a simple data store without the need to add large dependencies such as Postgres or MySQL.

Bolt is a single-level, zero-copy, B+tree data store. This means that Bolt is optimized for fast read access and does not require recovery in the event of a system crash. Transactions which have not finished committing will simply be rolled back in the event of a crash.

The design of Bolt is based on Howard Chu's LMDB database project. Bolt currently works on Windows, Mac OS X, and Linux.

Basics

There are only a few types in Bolt: DB, Bucket, Tx, and Cursor. The DB is a collection of buckets and is represented by a single file on disk. A bucket is a collection of unique keys that are associated with values.

Transactions provide either read-only or read-write access to the database. Read-only transactions can retrieve key/value pairs and can use Cursors to iterate over the dataset sequentially. Read-write transactions can create and delete buckets and can insert and remove keys. Only one read-write transaction is allowed at a time.

DB Bolt

GGBolt is a wrapper implementation that allow use BBolt with a simple implementation.

    // create and open DB
    db := gg_bolt.NewBoltDatabase(config)
    err = db.Open()
    
    // get/create collection
    coll, err := db.Collection("big-coll", true)
    
    // insert/update item
    item := &map[string]interface{}{
        "_key": "1",
        "name": "Mario",
        "age":  22,
    }
    err = coll.Upsert(item)

GGBolt implementation assume that document's key is named "_key".

Use GGBolt for Cache

filename := "./db/expiring.dat"
_ = gg_paths.Mkdir(filename)
config := gg_bolt.NewBoltConfig()
config.Name = filename

db := gg_bolt.NewBoltDatabase(config)
err := db.Open()
if nil!=err{
    panic(err)
}

defer db.Close()

coll, err := db.Collection("cache", true)
if nil!=err{
    panic(err)
}

// set collection as expirable
coll.EnableExpire(true)

// add an expirable item to collection
item := map[string]interface{}{
    "_key":    gg.Rnd.Uuid(),
    "name":    "NAME " + gg.Strings.Format("%s", i),
}
item[gg_bolt.FieldExpire] = time.Now().Add(5 * time.Second).Unix()
err = coll.Upsert(item)

if nil!=err{
    panic(err)
}

DB Bolt can be used as a temporary cache repository because has a feature that automatically deletes data whose expiration time has reached.

To enable a collection to check items for timed expiration you need:

  • Enable a collection to check for expired fields
  • Add "_expire" field to collection (use constant "gg_bolt.FieldExpire")
// set collection as expirable
coll.EnableExpire(true)

...

// add "_expire" field
item[gg_bolt.FieldExpire] = time.Now().Add(5 * time.Second).Unix()

_expire field must be a unix timestamp, an int64 value.

When to Use DB Bolt

GGBolt is great when you need a full embeddable cross-platform key-value pair database.

Mongo, Arango Redis and so on are a fair way greater than GGBolt, but are not embeddable and fully cross-platform like pure Go code is. GGBolt is just pure Go code.

Documentation

Index

Constants

View Source 
const (
	ComparatorEqual        = "=="
	ComparatorNotEqual     = "!="
	ComparatorGreater      = ">"
	ComparatorLower        = "<"
	ComparatorLowerEqual   = "<="
	ComparatorGreaterEqual = ">="

	OperatorAnd = "&&"
	OperatorOr  = "||"
)
View Source 
const (
	FieldExpire = "_expire"
)

Variables

View Source 
var (
	ErrDatabaseIsNotConnected  = errors.New("database_is_not_connected")
	ErrCollectionDoesNotExists = errors.New("collection_does_not_exists")
	ErrMissingDocumentKey      = errors.New("document_missing_key")
)

Functions

This section is empty.

Types

type BoltCollection 

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

func NewBoltCollection 

func NewBoltCollection(db *BoltDatabase, boltdb *bbolt.DB, name string) *BoltCollection

func (*BoltCollection) Count 

func (instance *BoltCollection) Count() (int64, error)

func (*BoltCollection) CountByFieldValue 

func (instance *BoltCollection) CountByFieldValue(fieldName string, fieldValue interface{}) (int64, error)

func (*BoltCollection) Drop 

func (instance *BoltCollection) Drop() error

func (*BoltCollection) EnableExpire 

func (instance *BoltCollection) EnableExpire(value bool)

func (*BoltCollection) Find 

func (instance *BoltCollection) Find(query *BoltQuery) ([]interface{}, error)

func (*BoltCollection) ForEach 

func (instance *BoltCollection) ForEach(callback ForEachCallback) error

func (*BoltCollection) Get 

func (instance *BoltCollection) Get(key string) (interface{}, error)

func (*BoltCollection) GetByFieldValue 

func (instance *BoltCollection) GetByFieldValue(fieldName string, fieldValue interface{}) ([]interface{}, error)

func (*BoltCollection) Remove 

func (instance *BoltCollection) Remove(key string) error

func (*BoltCollection) RemoveBatch 

func (instance *BoltCollection) RemoveBatch(key string) error

func (*BoltCollection) Upsert 

func (instance *BoltCollection) Upsert(entity interface{}) error

func (*BoltCollection) UpsertBatch 

func (instance *BoltCollection) UpsertBatch(entity interface{}) error

type BoltConfig 

type BoltConfig struct {
	Name      string        `json:"name"`
	TimeoutMs time.Duration `json:"timeout_ms"`
}

func NewBoltConfig 

func NewBoltConfig() *BoltConfig

func (*BoltConfig) Parse 

func (instance *BoltConfig) Parse(text string) error

func (*BoltConfig) ToString 

func (instance *BoltConfig) ToString() string

type BoltDatabase 

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

func NewBoltDatabase 

func NewBoltDatabase(config *BoltConfig) *BoltDatabase

func (*BoltDatabase) Close 

func (instance *BoltDatabase) Close() error

func (*BoltDatabase) Collection 

func (instance *BoltDatabase) Collection(name string, createIfNotExists bool) (*BoltCollection, error)

func (*BoltDatabase) CollectionAutoCreate 

func (instance *BoltDatabase) CollectionAutoCreate(name string) (*BoltCollection, error)

func (*BoltDatabase) Drop 

func (instance *BoltDatabase) Drop() error

func (*BoltDatabase) Error 

func (instance *BoltDatabase) Error() error

func (*BoltDatabase) HasError 

func (instance *BoltDatabase) HasError() bool

func (*BoltDatabase) Name 

func (instance *BoltDatabase) Name() string

func (*BoltDatabase) Open 

func (instance *BoltDatabase) Open() error

func (*BoltDatabase) Size 

func (instance *BoltDatabase) Size() (int64, error)

type BoltQuery 

type BoltQuery struct {
	Conditions []*BoltQueryConditionGroup `json:"conditions"`
}

func NewQueryFromFile 

func NewQueryFromFile(path string) (*BoltQuery, error)

func (*BoltQuery) MatchFilter 

func (instance *BoltQuery) MatchFilter(entity interface{}) bool

func (*BoltQuery) Parse 

func (instance *BoltQuery) Parse(text string) error

func (*BoltQuery) ToString 

func (instance *BoltQuery) ToString() string

type BoltQueryCondition 

type BoltQueryCondition struct {
	Field      interface{} `json:"field"`      // absolute value or field "doc.name"
	Comparator string      `json:"comparator"` // ==, !=, > ...
	Value      interface{} `json:"value"`      // absolute value or field "doc.surname", "Rossi"
}

type BoltQueryConditionGroup 

type BoltQueryConditionGroup struct {
	Operator string                `json:"operator"`
	Filters  []*BoltQueryCondition `json:"filters"`
}

type ExpireItem 

type ExpireItem struct {
	Exp int64 `json:"_expire"`
}

type ExpireWorker 

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

func NewExpireWorker 

func NewExpireWorker(db *BoltDatabase) *ExpireWorker

func (*ExpireWorker) Disable 

func (instance *ExpireWorker) Disable(collectionName string)

func (*ExpireWorker) Enable 

func (instance *ExpireWorker) Enable(collectionName string)

type ExpireWorkerJob 

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

func (*ExpireWorkerJob) Stop 

func (instance *ExpireWorkerJob) Stop()

type ForEachCallback 

type ForEachCallback func(k, v []byte) bool

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.