README
¶
ubolt
ubolt is a convenience wrapper around various github.com/etcd-io/bbolt calls.
Differences
All calls such as Get or Put are automatically run within a transaction, to ensure consistent reads/writes for that call.
In addition the OpenBucket function allows the opening of a database and creation of a bucket in one call, with subsequent calls to Put, Get etc being made against the named bucket automatically.
If lower level access is required the underlying bbolt.DB is available as BoltDB(), however in this case it is up to the user to ensure transactions are used and reads/writes are against the expected bucket.
Additional calls such as PutV, which inserts a value using a generated key, along with GetE and PutE variants of Get and Put which return an error in all cases, such as ErrKeyNotFound rather than a nil value.
Usage
The following example shows opening a bucket and reading and writing a single key.
package main
import "github.com/andrewheberle/ubolt"
func main() {
bucket := []byte("mybucket")
key := []byte("mykey")
value := []byte("myvalue")
db, err := ubolt.OpenBucket("database.db", bucket)
if err != nil {
panic(err)
}
defer db.Close()
if err := db.Put(key, value); err != nil {
panic(err)
}
v, err := db.GetE(key)
if err != nil {
panic(err)
}
fmt.Printf("%s\n", v)
// Output: myvalue
}
Documentation
¶
Overview ¶
Package ubolt wraps various calls from "go.etcd.io/bbolt" to make basic use simpler and quicker.
Various calls such as Get, Put etc are automatically wrapped in transactions to ensure consistency.
Index ¶
- Constants
- type Bucket
- func (b *Bucket) BoltDB() *bolt.DB
- func (b *Bucket) Close() error
- func (b *Bucket) Decode(key []byte, value any) error
- func (b *Bucket) Delete(key []byte) error
- func (b *Bucket) Encode(key []byte, value any) error
- func (b *Bucket) ForEach(fn func(k, v []byte) error) error
- func (b *Bucket) Get(key []byte) (value []byte)
- func (b *Bucket) GetE(key []byte) (value []byte, err error)
- func (b *Bucket) GetKeys() (keys [][]byte)
- func (b *Bucket) GetKeysE() (keys [][]byte, err error)
- func (b *Bucket) Ping() error
- func (b *Bucket) Put(key, value []byte) error
- func (b *Bucket) PutV(value []byte) (key []byte, err error)
- func (b *Bucket) Scan(prefix []byte, fn func(k, v []byte) error) error
- type Database
- func (db *Database) BoltDB() *bolt.DB
- func (db *Database) Close() error
- func (db *Database) CreateBucket(bucket []byte) error
- func (db *Database) Decode(bucket, key []byte, value any) error
- func (db *Database) Delete(bucket, key []byte) error
- func (db *Database) DeleteBucket(bucket []byte) error
- func (db *Database) Encode(bucket, key []byte, value any) error
- func (db *Database) ForEach(bucket []byte, fn func(k, v []byte) error) error
- func (db *Database) Get(bucket, key []byte) (value []byte)
- func (db *Database) GetBuckets() (buckets [][]byte)
- func (db *Database) GetBucketsE() (buckets [][]byte, err error)
- func (db *Database) GetE(bucket, key []byte) (value []byte, err error)
- func (db *Database) GetKeys(bucket []byte) (keys [][]byte)
- func (db *Database) GetKeysE(bucket []byte) (keys [][]byte, err error)
- func (db *Database) Ping() error
- func (db *Database) Put(bucket, key, value []byte) error
- func (db *Database) PutV(bucket, value []byte) (key []byte, err error)
- func (db *Database) Scan(bucket, prefix []byte, fn func(k, v []byte) error) error
- func (db *Database) WriteTo(w io.Writer) (n int64, err error)
- type ErrBucketNotFound
- type ErrKeyNotFound
- type Option
Examples ¶
Constants ¶
const ( DefaultTimeout = 5 * time.Second DefaultMode = 0600 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bucket ¶
type Bucket struct {
// contains filtered or unexported fields
}
func OpenBucket ¶
OpenBucket performs the same process as Open however all subsequent operations, such as Get and Put are performed on the specified bucket
func (*Bucket) BoltDB ¶ added in v1.7.2
BoltDB provides access to the underlying bbolt.DB if lower level access is required
func (*Bucket) Close ¶
Close releases all database resources and closes the file. This call will block while any open transactions complete.
func (*Bucket) Decode ¶
Decode retrieves and decodes a value set by Encode into the provided pointer value.
func (*Bucket) Delete ¶
Delete removes the specified key. This process is wrapped in a read/write transaction.
func (*Bucket) Encode ¶
Encode encodes the provided value using "encoding/gob" then writes the resulting byte slice to the provided key
func (*Bucket) Get ¶
Get retrieves the specified key and returns the value. The value returned may be nil which indicates the key was not found.
Example ¶
package main
import (
"fmt"
"github.com/andrewheberle/ubolt"
)
func main() {
bucket := []byte("mybucket")
key := []byte("mykey")
value := []byte("myvalue")
db, err := ubolt.OpenBucket("database.db", bucket)
if err != nil {
panic(err)
}
defer db.Close()
if err := db.Put(key, value); err != nil {
panic(err)
}
v := db.Get(key)
if v == nil {
panic("no value returned")
}
fmt.Printf("%s\n", v)
}
Output: myvalue
func (*Bucket) GetE ¶
GetE retrieves the specified key and returns the value and an error. The returned error is non-nil if a failure occurred, which includes if the key was not found.
Example ¶
package main
import (
"fmt"
"github.com/andrewheberle/ubolt"
)
func main() {
bucket := []byte("mybucket")
key := []byte("mykey")
value := []byte("myvalue")
db, err := ubolt.OpenBucket("database.db", bucket)
if err != nil {
panic(err)
}
defer db.Close()
if err := db.Put(key, value); err != nil {
panic(err)
}
v, err := db.GetE(key)
if err != nil {
panic(err)
}
fmt.Printf("%s\n", v)
}
Output: myvalue
func (*Bucket) Put ¶
Put sets the specified key in the bucket opened to the provided value. This process is wrapped in a read/write transaction.
type Database ¶
type Database struct {
// contains filtered or unexported fields
}
func Open ¶
Open creates and opens a database at the given path. If the file does not exist it will be created automatically with a file-mode of DefaultMode, or the provided WithMode Option.
The default timeout to obtain a lock on the database is based on DefaultTimeout, howevber this can be overridden by passing the WithTimeout Option to Open.
func (*Database) BoltDB ¶ added in v1.7.2
BoltDB provides access to the underlying bbolt.DB if lower level access is required
func (*Database) Close ¶
Close releases all database resources and closes the file. This call will block while any open transactions complete.
func (*Database) CreateBucket ¶
DeleteBucket removes the specified bucket. This also deletes all keys contained in the bucket and any nested buckets.
func (*Database) Decode ¶
Decode retrieves and decodes a value set by Encode into the provided pointer value.
func (*Database) Delete ¶
Delete removes the specified key in the chosen bucket. This process is wrapped in a read/write transaction.
func (*Database) DeleteBucket ¶
DeleteBucket removes the specified bucket. This also deletes all keys contained in the bucket and any nested buckets.
func (*Database) Encode ¶
Encode encodes the provided value using "encoding/gob" then writes the resulting byte slice to the provided key
func (*Database) Get ¶
Get retrieves the specified key from the chosen bucket and returns the value. The value returned may be nil which indicates the bucket or key was not found.
func (*Database) GetBuckets ¶
func (*Database) GetBucketsE ¶
func (*Database) GetE ¶
GetE retrieves the specified key from the chosen bucket and returns the value and an error. The returned error is non-nil if a failure occurred, which includes if the bucket or key was not found.
func (*Database) Put ¶
Put sets the specified key in the chosen bucket to the provided value. This process is wrapped in a read/write transaction.
type ErrBucketNotFound ¶
type ErrBucketNotFound struct {
// contains filtered or unexported fields
}
ErrBucketNotFound is returned when the bucket requested was not found.
func (ErrBucketNotFound) Error ¶
func (e ErrBucketNotFound) Error() string
Error returns the formatted configuration error.
func (ErrBucketNotFound) Is ¶
func (e ErrBucketNotFound) Is(target error) bool
Is allows testing using errors.Is
type ErrKeyNotFound ¶
type ErrKeyNotFound struct {
// contains filtered or unexported fields
}
ErrKeyNotFound is returned when the key requested was not found
func (ErrKeyNotFound) Error ¶
func (e ErrKeyNotFound) Error() string
Error returns the formatted configuration error.
func (ErrKeyNotFound) Is ¶
func (e ErrKeyNotFound) Is(target error) bool
Is allows testing using errors.Is
type Option ¶ added in v1.7.1
type Option func(*Database)
func WithOpenFile ¶ added in v1.7.1
WithOpenFile allows the providing a custom OpenFile function. This is primarily useful for filesystem mocking during tests.
func WithTimeout ¶ added in v1.7.1
WithTimeout sets the timeout to wait to obtain a lock on a database during Open. A value of 0 will wait forever.
Source Files