simpledb

README

simpledb v0.0.5

good wrapper for bbolt database

see godoc

or go.dev

safe for concurrent use. (?)

recent api change

api was stable, recently changed Update method

to fix your code, change Update to Put, or use the older go get gitlab.com/aerth/simpledb@v0.0.4 in your repo.

the new method Update is now the same as bbolt.Update, same as View.

Documentation

Overview

simpledb package wraps a *bbolt.DB and provides methods for common operations

Index

• Variables
• type BBolt
• type BoltLike
• type Bucket
• type Cursor
• type DB
• type Options
• type SimpleDB
  • func Load(path string, options ...*Options) (*SimpleDB, error)
  • func WrapBoltDB(db BoltLike) *SimpleDB
  • func (s *SimpleDB) Close() error
  • func (s *SimpleDB) CreateBucket(bucketnames ...string) error
  • func (s *SimpleDB) CreateBucketNested(bucketname string, nestednames ...string) error
  • func (s *SimpleDB) CreatePaths(paths [][]string) error
  • func (s *SimpleDB) DB() *bbolt.DB
  • func (s *SimpleDB) Delete(fromBucket string, key ...string) error
  • func (s *SimpleDB) DeleteNested(fromBucket, fromNested string, key ...string) error
  • func (s *SimpleDB) ForEach(bucket string, fn func(k, v []byte) error) error
  • func (s *SimpleDB) ForEachBucket(fn func(b []byte, bucket *Bucket) error) error
  • func (s *SimpleDB) ForEachNested(bucket, nested string, fn func(k, v []byte) error) error
  • func (s *SimpleDB) Get(bucket, key string) []byte
  • func (s *SimpleDB) GetNested(bucket, nestedname, key string) []byte
  • func (s *SimpleDB) GetPath(path []string) []byte
  • func (s *SimpleDB) Keys(bucket string) []string
  • func (s *SimpleDB) KeysNested(bucket, nestedname string) []string
  • func (s *SimpleDB) Marshal(bucket, key string, thing interface{}) error
  • func (s *SimpleDB) MarshalNested(bucket, nestedname, key string, thing interface{}) error
  • func (s *SimpleDB) MarshalPath(path []string, thing interface{}) error
  • func (s *SimpleDB) Put(bucket, key string, data []byte) error
  • func (s *SimpleDB) PutNested(bucket, nestedname, key string, data []byte) error
  • func (s *SimpleDB) PutPath(path []string, data []byte) error
  • func (s *SimpleDB) Unmarshal(bucket, key string, thingPtr interface{}) error
  • func (s *SimpleDB) UnmarshalNested(bucket, nestedname, key string, thingPtr interface{}) error
  • func (s *SimpleDB) UnmarshalPath(path []string, thingPtr interface{}) error
  • func (s *SimpleDB) Update(txfn func(tx *Tx) error) error
  • func (s *SimpleDB) View(txfn func(tx *Tx) error) error
• type Tx

Variables

var ErrBucketNotFound = errors.New("bucket not found")

if a bucket or nested bucket can not be found during Read/View operations

var ErrDBType = errors.New("db not found, or type assertion failed, are you not using a *bbolt.DB ?")

ErrDBType will be given if a programmer is not using the library correctly ;)

var ErrEmptyPath = errors.New("empty path")

var ErrNotFound = fmt.Errorf("not found")

ErrNotFound will be returned by Unmarshal functions if the key did not exist or gave empty value. For example, if the requested user does not exist in the database.

var ErrTimeout = bbolt.ErrTimeout

ErrTimeout returned if we can't get the lock on the db

var New = Load

New is an alias for Load()

Types

type BBolt

type BBolt interface {
	View(func(t *Tx) error) error
	Update(func(t *Tx) error) error
}

BBolt interface is basically only a *bbolt.DB. Not implemented yet.

type BoltLike

type BoltLike interface {
	Sync() error
}

BoltLike is any bolt-like DB package. This currently only supports bbolt

type Bucket

type Bucket = bbolt.Bucket

Bucket from bbolt.Bucket

type Cursor

type Cursor = bbolt.Cursor

Cursor from bbolt.Cursor

type DB

type DB = bbolt.DB

DB from bbolt.DB

type Options

type Options = bbolt.Options

Options from bbolt.Options

type SimpleDB

type SimpleDB struct {
	//db *bbolt.DB
	D BoltLike
}

SimpleDB ...

func Load

func Load(path string, options ...*Options) (*SimpleDB, error)

Load a database, creating it, and making directories to it, if does not exist. Write operations (Update, Marshal, and their nested counterparts) create buckets if they don't exist. Read operations (Get, Unmarshal) will return nil if the bucket doesn't exist yet.

func WrapBoltDB

func WrapBoltDB(db BoltLike) *SimpleDB

WrapBoltDB ... do not use with non-bbolt db yet

func (*SimpleDB) Close

func (s *SimpleDB) Close() error

Close the database safely, allowing other processes to use it

func (*SimpleDB) CreateBucket

func (s *SimpleDB) CreateBucket(bucketnames ...string) error

CreateBucket makes sure your database is initialized. Do at beginning for each bucket your program will use. Or if creating many buckets dynamically, just make sure CreateBucket is called before any Read operations happen. Example: s.CreateBucket("contacts"); s.Unmarshal("contacts", "bob", &user);

func (*SimpleDB) CreateBucketNested

func (s *SimpleDB) CreateBucketNested(bucketname string, nestednames ...string) error

CreateBucketNested makes sure your database is initialized. Do at beginning for each bucket your program will use. Or if creating many buckets dynamically, just make sure CreateBucket is called before any Read operations happen.

func (*SimpleDB) CreatePaths

func (s *SimpleDB) CreatePaths(paths [][]string) error

func (*SimpleDB) DB

func (s *SimpleDB) DB() *bbolt.DB

DB returns the underlying *bbolt.DB if in fact a bbolt DB.

func (*SimpleDB) Delete

func (s *SimpleDB) Delete(fromBucket string, key ...string) error

Delete keys from bucket

func (*SimpleDB) DeleteNested

func (s *SimpleDB) DeleteNested(fromBucket, fromNested string, key ...string) error

DeleteNested keys from nested bucket

func (*SimpleDB) ForEach

func (s *SimpleDB) ForEach(bucket string, fn func(k, v []byte) error) error

ForEach key in a named bucket...

func (*SimpleDB) ForEachBucket

func (s *SimpleDB) ForEachBucket(fn func(b []byte, bucket *Bucket) error) error

ForEach bucket...

func (*SimpleDB) ForEachNested

func (s *SimpleDB) ForEachNested(bucket, nested string, fn func(k, v []byte) error) error

ForEachNested key in a named nested bucket...

func (*SimpleDB) Get

func (s *SimpleDB) Get(bucket, key string) []byte

Get returns the value of bucket[key]

func (*SimpleDB) GetNested

func (s *SimpleDB) GetNested(bucket, nestedname, key string) []byte

GetNested returns the value of the nested bucket at key

func (*SimpleDB) GetPath

func (s *SimpleDB) GetPath(path []string) []byte

GetNested returns the value of the nested bucket at key

func (*SimpleDB) Keys

func (s *SimpleDB) Keys(bucket string) []string

Keys lists key names within named bucket

func (*SimpleDB) KeysNested

func (s *SimpleDB) KeysNested(bucket, nestedname string) []string

KeysNested lists key names within nested bucket

func (*SimpleDB) Marshal

func (s *SimpleDB) Marshal(bucket, key string, thing interface{}) error

Marshal writes to database

func (*SimpleDB) MarshalNested

func (s *SimpleDB) MarshalNested(bucket, nestedname, key string, thing interface{}) error

MarshalNested writes to database

func (*SimpleDB) MarshalPath

func (s *SimpleDB) MarshalPath(path []string, thing interface{}) error

func (*SimpleDB) Put

func (s *SimpleDB) Put(bucket, key string, data []byte) error

Update writes to database

func (*SimpleDB) PutNested

func (s *SimpleDB) PutNested(bucket, nestedname, key string, data []byte) error

UpdateNested writes to database

func (*SimpleDB) PutPath

func (s *SimpleDB) PutPath(path []string, data []byte) error

PutPath writes to database

func (*SimpleDB) Unmarshal

func (s *SimpleDB) Unmarshal(bucket, key string, thingPtr interface{}) error

Unmarshal a value directly into thingPtr

func (*SimpleDB) UnmarshalNested

func (s *SimpleDB) UnmarshalNested(bucket, nestedname, key string, thingPtr interface{}) error

Unmarshal a nested value

func (*SimpleDB) UnmarshalPath

func (s *SimpleDB) UnmarshalPath(path []string, thingPtr interface{}) error

func (*SimpleDB) Update

func (s *SimpleDB) Update(txfn func(tx *Tx) error) error

Update wraps db.Update

func (*SimpleDB) View

func (s *SimpleDB) View(txfn func(tx *Tx) error) error

View wraps db.View

type Tx

type Tx = bbolt.Tx

Tx from bbolt.Tx