kvalbolt

package module
Version: v0.0.0-...-f379777 Latest Latest
Warning

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

Go to latest
Published: Mar 30, 2017 License: GPL-3.0 Imports: 9 Imported by: 3

README

KVAL-BoltDB

Build Status GoDoc Go Report Card

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

View Source
const Base64 = "base64"

Base64, const to help users validate Kvalblob struct

View Source
const Data = "data"

Datam const to help users validate Kvalblob struct

View Source
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

func GetBlobData(kvb Kvalblob) ([]byte, error)

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

func Version

func Version() string

Version will return an indication of which version of the KVAL language we are working from and the version of the library that you are implementing from

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL