README
¶
rod : helper functions inside BoltDB transactions
Overview 
Rod is a simple way to put and get values to/from a BoltDB store. It can deal with deep-hierarchies easily and is therefore a rod straight to the value you want.
Installation
go get github.com/chilts/rod
Or (for gb):
gb vendor fetch github.com/chilts/rod
Example
user := User{
Name: "chilts",
Email: "andychilton@gmail.com",
Logins: 1,
Inserted: time.Now(),
}
db.Update(func(tx *bolt.TX) error {
return rod.PutJson(tx, "users.chilts", "chilts", user)
})
Author
By Andrew Chilton, @twitter.
For AppsAttic, @AppsAttic.
License
MIT.
(Ends)
Documentation
¶
Overview ¶
Package rod is a simple way to put/get values to/from a BoltDB (https://github.com/boltdb/bolt) store. It can deal with deep-bucket hierarchies easily and is therefore a lightning-rod straight to the value you want. Hence the name.
Whilst this package won't solve all of your problems or use-cases, it does make a few things simple and is used successfully https://publish.li/ and https://weekproject.com/ and various other applications.
Whilst rod just uses strings for it's location and key values (unlike Bolt using []byte), rod helps with the following value types:
• []byte
• string
• JSON
Again, everything is a convenience and you should be aware of any overhead rod introduces. However, since rod is designed to be minimal we try not to add much overhead at all (in terms of both code size and run-time overhead).
(Ends)
Index ¶
- Variables
- func All(tx *bolt.Tx, location string, to interface{}) error
- func AllKeys(tx *bolt.Tx, location string) ([]string, error)
- func Del(tx *bolt.Tx, location, key string) error
- func Get(tx *bolt.Tx, location, key string) ([]byte, error)
- func GetBucket(tx *bolt.Tx, location string) (*bolt.Bucket, error)
- func GetJson(tx *bolt.Tx, location, key string, v interface{}) error
- func GetString(tx *bolt.Tx, location, key string) (string, error)
- func Put(tx *bolt.Tx, location, key string, value []byte) error
- func PutJson(tx *bolt.Tx, location, key string, v interface{}) error
- func PutString(tx *bolt.Tx, location, key, value string) error
- func SelAll(tx *bolt.Tx, location string, newItem func() interface{}, ...) error
Constants ¶
This section is empty.
Variables ¶
var ( // ErrLocationMustHaveAtLeastOneBucket is returned if any location given hasn't got anything in it, ie. it is // empty. ErrLocationMustHaveAtLeastOneBucket = errors.New("location must specify at least one bucket") // ErrInvalidLocationBucket is returned if any location is blank, ie. you specified something like "user..field". ErrInvalidLocationBucket = errors.New("invalid location bucket") // ErrKeyNotProvided is returned if key was not specified, ie. it is empty. ErrKeyNotProvided = errors.New("key must be specified") // ErrSlicePtrNeeded is returned when an unexpected value is given, instead of a pointer to slice. ErrSlicePtrNeeded = errors.New("provided target must be a pointer to slice") )
Functions ¶
func All ¶
All will give you everything inside the bucket specified by location.
var users []User err := rod.All(tx, "user", &users) var animals []Animals err := rod.All(tx, "animal", &animals)
This function supercedes SelAll() so use this instead of that.
func Del ¶
Del will find your bucket location and delete the key specified. It doesn't matter what is in the key's value, since it is ignored during this operation. If the bucket doesn't exist, no error is returned since technically you've already got what you asked for. Similarly, if the key doesn't exist, no error is returned for the same reason.
func Get ¶
Get will fetch the raw bytes from the BoltDB. If any bucket doesn't exist it will return nil. If the key doesn't exist it will also return nil.
Error returned from this function are: * ErrLocationMustHaveAtLeastOneBucket if no location was specified * ErrKeyNotProvided if no key was specified
func GetBucket ¶
GetBucket returns this nested bucket from the store. If any bucket along the way does not exist, then no bucket is returned (nil) but not error is returned either.
func GetJson ¶
GetJson calls Get and then json.Unmarshal() with the result to deserialise the value into interface{}. If any bucket doesn't exist we just return nil with nothing placed into v. The same if the key doesn't exist.
func GetString ¶
GetString calls Get and converts the []byte to a string before returning it to you. Everything that applies there applies here too.
func Put ¶
Put will find your bucket location and put your value into the key specified. The location is specified as a hierarchy of bucket names such as "users", "users.chilts", or "users.chilts.posts" and will be split on the period for each bucket name.
At every bucket specified in the location, CreateBucketIfNotExists() is called to make sure it exists. If any of these fail, the error is returned.
Once the final bucket is found, the value is put using the key.
Examples:
rod.Put(tx, "social", "twitter-123456", []byte("chilts"))
rod.Put(tx, "users.chilts", "email", []byte("andychilton@gmail.com"))
rod.Put(tx, "users.chilts.posts", "hello-world", []byte("Hello, World!"))
The location must have at least one bucket ("" is not allowed), and the key must also be a non-empty string. The transaction must be a writeable one otherwise an error is returned.
func PutJson ¶
PutJson calls json.Marshal() to serialise the value into []byte and calls rod.Put with the result.
func PutString ¶
PutString converts the string to []byte and calls Put. Everything that applies there applies here too.
func SelAll ¶
func SelAll(tx *bolt.Tx, location string, newItem func() interface{}, append func(interface{})) error
SelAll (*** DEPRECATED *** - use All() instead) will give you everything inside the bucket specified by location. The newItem function you pass in will be called for every key in the bucket and should just return an empty instance of your type. Append will also be called for every item once unmarshalling has taken place.
animals := make([]*Animal, 0)
err := SelAll(tx, "animal", func() interface{} {
return Animal{}
}, func(v interface{}) {
a, _ := v.(Animal)
animals = append(animals, &a)
})
It's a bit of boilerplate but you could just pass in a newItem function declared earlier in the program. This API is subject to change since it could probably be improved upon.
Types ¶
This section is empty.
Source Files