README
¶
KVAL-BoltDB
BoltDB bindings for KVAL
Package kvalbolt implements a BoltDB binding for KVAL (Key Value Access Language) The binding provides more than just 'boilerplate' for working with BoltDB. It implements a language thus enabling access from a higher point of abstraction. Users of the binding can provide simple instructions and the binding will take care of Bucket creation (and deletion), and the generation of keys and values, plus their maintenance, no matter how deep into the database structure they are needed, or indeed exist.
"Everything should be made as simple as possible, but no simpler." - Albert Einstein
The most up-to-date specification for KVAL can be found here: https://github.com/kval-access-language/kval
My first blog post describing my thoughts a little better can be found here: http://exponentialdecay.co.uk/blog/key-value-access-language-kval-for-boltdb-and-golang/
Key Value Access Language
I have created a modest specification for a key value access langauge. It allows for input and access of values to a key value store such as Golang's BoltDB.
The language specification: https://github.com/kval-access-language/KVAL
Features
- Single function entry-point:
- res, err := Query(kb, "INS B1 >> B2 >> B3 >>>> KEY :: VAL") //(will create three buckets, plus k/v in one-go)
- res, err := Query(kb, "GET B1 >> B2 >> B3 >>>> KEY") //(will retrieve that entry in one-go)
- Start using BoltDB immediately without writing boiler plate before you can code
- KVAL-Parse enables handling of Base64 binary BLOBS
- Regular Expression based searching for key names and values
- KVAL Language specifies easy bulk or singleton DEL and RENAME capabilities
- Language specification at highest abstraction, so other bindings for other DBs are hoped for (hint: NOMS!)
- Start working with BoltDB immediately!
Usage
Use is simple. There is one function which accepts a string formatted to KVAL's specification:
res, err = Query(kb, "GET Bucket One >> Bucket Two >>>> Requested Key")
if err != nil {
fmt.Fprintf(os.Stderr, "Error querying db: %v", err)
} else {
//Access our (result structure)[https://github.com/kval-access-language/kval-boltdb/blob/master/kval-bolt-structs.go#L16]: res.Result (a map[string]string)
}
For write operations we simply check for the existence of an error, else the operation passed as expected:
res, err = Query(kb, "INS Bucket One >> Bucket Two >>>> Insert Key :: Insert Value")
if err != nil {
fmt.Fprintf(os.Stderr, "Error querying db: %v", err)
}
How easy is it?
Once you've a connection to a database, call Query as many times as you like to work with your data. The most basic implementation, creating a DB, and inserting data looks as follows:
package main
import (
"fmt"
"os"
kval "github.com/kval-access-language/kval-boltdb"
)
func main() {
kb, err := kval.Connect("newdb.bolt")
if err != nil {
fmt.Fprintf(os.Stderr, "Error opening bolt database: %#v", err)
os.Exit(1)
}
defer kval.Disconnect(kb)
//Lets do a test insert...
res, err := kval.Query(kb, "INS test bucket one >> test bucket two >>>> key one :: value one")
if err != nil {
//work with your error
}
// else: start working with you res struct
}
Demo
Have a look at some of the bits and pieces implemented as part of this binding in the demo Go app here: https://github.com/kval-access-language/kval-boltdb-demo
How to contribute
I will be starting to use the code in my own work once the dust has settled from thie first tranche of work. As I do that, and before then, I need the following:
- Comments on the KVAL specification, working towards a version 1.
- Code review
- Code testers - Get using it and report your issues!
- Spread the word
- Let me know how it goes here via Issue, or on Twitter via @beet_keeper
License
GPL Version 3: https://github.com/kval-access-language/KVAL-BoltDB/blob/master/LICENSE
Documentation
¶
Overview ¶
Package kvalbolt implements a BoltDB binding for KVAL (Key Value Access Language)
The binding provides more than just 'boilerplate' for working with BoltDB. It implements a language thus enabling access from a higher point of abstraction. Users of the binding can provide simple instructions and the binding will take care of Bucket creation (and deletion), and the generation of keys and values, plus their maintenance, no matter how deep into the database structure they are needed, or indeed exist.
"Everything should be made as simple as possible, but no simpler." - Albert Einstein
The most up-to-date information on the project can be found on the GitHub.com README: https://github.com/kval-access-language/kval-boltdb/blob/master/README.md
The most up-to-date specification for KVAL can be found here: https://github.com/kval-access-language/kval
Index ¶
Constants ¶
const Base64 = "base64"
Base64, const to help users validate Kvalblob struct
const Data = "data"
Datam const to help users validate Kvalblob struct
const Nestedbucket = "NestedBucket"
Nestedbucket, const to help users validate Kvalblob struct
Variables ¶
This section is empty.
Functions ¶
func Disconnect ¶
func Disconnect(kb Kvalboltdb)
Disconnect lets us disconnect from a BoltDB. It is recommended that this function is deffered where possible.
func GetBlobData ¶
GetBlobData decodes the Base64 data stored in a Kvalblob object
func GetBolt ¶
func GetBolt(kb Kvalboltdb) *bolt.DB
GetBolt retrieves a pointer to BoltDB at any time for working with it manually.
func StoreBlob ¶
func StoreBlob(kb Kvalboltdb, loc string, mime string, data []byte) error
StoreBlob is used to wrap a blob of data. KVAL-Bolt/KVAL proposes a standard encoding for this data inside Key-Value databases, that goes like this: data:mimetype;base64;{base64 data}. Use Unwrap to get the datastream back and further GetBlobdata as a shortcut to decode it from Base64. Location for StoreBlob should be specified in the form of a query: e.g. INS bucket >>>> key
Types ¶
type Kvalblob ¶
type Kvalblob struct {
Query string // Where valid, the query used is stored here
Datatype string // Datatype is stored here, expected: 'data'
Mimetype string // Mimetype is recorded here and is up to users to insert correctly
Encoding string // Encoding is stored here, expected:'base64'
Data string // Our data is stored here as a base64 string
}
Kvalblob struct to allow users to work with Base64 encoded blobs
func UnwrapBlob ¶
func UnwrapBlob(kv Kvalresult) (Kvalblob, error)
UnwrapBlob can be used to unwrap a blob you are retrieving via GET
type Kvalboltdb ¶
type Kvalboltdb struct {
DB *bolt.DB // Pointer to BoltDB, users can access directly or via function call
Fname string // Filename used to create our DB with
// contains filtered or unexported fields
}
Kvalboltdb represents a parsed query structure that we can pass aound in code
func Attach ¶
func Attach(db *bolt.DB, fname string) Kvalboltdb
Attach enables you to open the datbaase on your own terms and then connect it to the KVAL binding to work on it separately. WARNING: if you do open the database in ReadOnly mode, then expect undefined behaviour when you try to write something to the database.
func Connect ¶
func Connect(dbname string) (Kvalboltdb, error)
Connect should first be used to open a connection to a BoltDB with a given name. Returns a KVAL Bolt structure with the details required for future KVAL BoltDB operations.
type Kvalresult ¶
type Kvalresult struct {
Result map[string]string // Result map to access various types of result post-query
Exists bool // When using a LIS query this is set to true if we can find our data
Stats bolt.BucketStats // BoltDB bucket stats relevant to the operation performed by the user
// contains filtered or unexported fields
}
Kvalresult provides a mechanism for users to interact with results. It also allows for a wide-variety of results from single GET results, to retrieving all from a Bucket through various different mechanisms. Maplen will be one if a single result. Users should understand their data, but also be curious to the results they're getting from their various queries, therefore checking this length is a good approach.
func Query ¶
func Query(kb Kvalboltdb, query string) (Kvalresult, error)
Query is our primary function once we've opened a BoltDB connection. Given a KVALBolt Structure, and a KVAL query string this function will do all of the work for you when interacting with BoltDB. Everything should become less programmatic making for cleaner code. The KVAL spec can be found here: https://github.com/kval-access-language/kval.
Source Files