README
¶
boltdb
Go module github.com/devilcove/boltdb is a generic abstractions layer for basic crud operations on a go.etcd.io/bbolt key/value store
Installing
To start using, install Go and run go get:
go get github.com/devilcove/boltdb@latest
Functions
Initialization
call initialize with the path to store and list of tables. Store and tables will be created if they do not exist.
import "github.com/devilcove/bbolt"
if err := boltdb.Initialize(path, []string{"users", "networks"}); err != nil{
return err
}
defer boltd.Close()
Create/Update
pass the key/value pair along with table name
Save -- save key/value always (overwrite existing or create new)
Insert -- save only iff key does not exist
Update -- save only iff key exists
cont userTable = "users"
user := models.User {
Username: "admin",
Password: "encrypted password",
IsAdmin: true,
}
if err := boltdb.Save(user, user.Username, userTable); err != nil {
return err
}
Read
read table names
tables := boltdb.Tables()
return value of key in table
user, err := boltdb.Get[models.User]("admin", userTable)
if err != nil {
return err
}
retrieve all values from table
users, err := boltdb.GetAll[models.User](userTable)
if err != nil {
return err
}
Delete
delete value of key in table
if err := boltdb.Delete[models.User]("admin", userTable); err != nil {
return err
}
Advanced Usage
the db connection is made available if more advanced queries are needed
import (
"encoding/json"
"errors"
"github.com/devilcove/boltdb"
"go.etcd.io/bbolt"
)
func AdminExists() bool {
var user models.User
var found bool
db := boltdb.Connection()
if db == nil {
return found
}
if err := db.View(func(tx *bbolt.Tx) error {
b := tx.Bucket([]byte(UserTable))
if b == nil {
return boltdb.ErrNoResults
}
_ = b.ForEach(func(k, v []byte) error {
if err := json.Unmarshal(v, &user); err != nil {
return err
}
if user.IsAdmin {
found = true
}
return nil
})
return nil
}); err != nil {
return false
}
return found
}
Documentation
¶
Index ¶
- Variables
- type Path
- type Store
- func (s *Store) Close() error
- func (s *Store) Connection() *bbolt.DB
- func (s *Store) CopyBucket(src, dest Path) error
- func (s *Store) CopyKey(sKey, dKey Path) error
- func (s *Store) CreateBucket(path Path) error
- func (s *Store) Delete(key string, parent Path) error
- func (s *Store) DeleteBucket(path Path) error
- func (s *Store) EmptyBucket(path Path) error
- func (s *Store) Get[T any](key string, bucket Path) (T, error)
- func (s *Store) GetAll[T any](path Path) ([]T, error)
- func (s *Store) GetAllRaw(path Path) ([][]byte, error)
- func (s *Store) GetRaw(key []byte, bucket Path) ([]byte, error)
- func (s *Store) Insert(value any, key string, bucket Path) error
- func (s *Store) MoveBucket(src, dest Path) error
- func (s *Store) MoveKey(src, dest Path) error
- func (s *Store) RenameBucket(path Path, name string) error
- func (s *Store) RenameKey(path Path, name string) error
- func (s *Store) Save(value any, key string, parent Path) error
- func (s *Store) SaveRaw(value, key []byte, parent Path) error
- func (s *Store) Update(value any, key string, bucket Path) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoResults indicates query found no results. ErrNoResults = errors.New("no results found") // ErrInvalidPath indicates that specified bucket does not exist. ErrInvalidPath = errors.New("invalid path") // ErrNoConnection indicates that database is not open. ErrNoConnection = errors.New("no db connection") // ErrExists indicates that a key exists. ErrExists = errors.New("key exists") )
Generic error results.
Functions ¶
This section is empty.
Types ¶
type Path ¶ added in v0.2.0
type Path []string
Path represents a nested bucket path.
type Store ¶ added in v0.1.9
type Store struct {
// contains filtered or unexported fields
}
Store represents a bbolt db store.
func Initialize ¶
Initialize sets up bbolt db using file path and creates tables if required.
func (*Store) Connection ¶ added in v0.1.9
Connection returns the connection to the store for more advanced queries by caller.
Example ¶
package main
import (
"encoding/json"
"fmt"
"github.com/devilcove/boltdb"
"go.etcd.io/bbolt"
)
type User struct {
UserName string
Password string
IsAdmin bool
}
const UserTable = "users"
func main() {
if AdminExists() {
fmt.Println("admin exists")
} else {
fmt.Println("admin does not exist")
}
}
func AdminExists() bool {
var user User
var found bool
s := boltdb.Store{}
db := s.Connection()
if db == nil {
return found
}
if err := db.View(func(tx *bbolt.Tx) error {
b := tx.Bucket([]byte(UserTable))
if b == nil {
return boltdb.ErrNoResults
}
_ = b.ForEach(func(k, v []byte) error {
if err := json.Unmarshal(v, &user); err != nil {
return err
}
if user.IsAdmin {
found = true
}
return nil
})
return nil
}); err != nil {
return false
}
return found
}
Output: admin does not exist
func (*Store) CopyBucket ¶ added in v0.2.0
CopyBucket copies a bucket from src path to dest path.
func (*Store) CreateBucket ¶ added in v0.2.0
CreateBucket creates a new bucket at given path.
func (*Store) DeleteBucket ¶ added in v0.2.0
DeleteBucket deletes the bucket at path.
func (*Store) EmptyBucket ¶ added in v0.2.0
EmptyBucket deletes all of a buckets children.
func (*Store) MoveBucket ¶ added in v0.2.0
MoveBucket copies bucket to new location and deletes original.
func (*Store) MoveKey ¶ added in v0.2.0
MoveKey copies a key to new destination and deletes original.
func (*Store) RenameBucket ¶ added in v0.2.0
RenameBucket renames a bucket.
Source Files