Go每日一库之23：buntdb
简介
buntdb是一个完全用 Go 语言编写的内存键值数据库。它支持 ACID、并发读、自定义索引和空间信息数据。buntdb只用一个源码文件就实现了这些功能，对于想要学习数据库底层知识的童鞋更是不容错过。
感谢@kiyonlin推荐！
快速使用
先安装：
$ go get github.com/tidwall/buntdb
后使用：
package main
import (
"fmt"
"log"
"github.com/tidwall/buntdb"
)
func main() {
db, err := buntdb.Open(":memory:")
if err != nil {
log.Fatal(err)
}
defer db.Close()
db.Update(func(tx *buntdb.Tx) error {
oldValue, replaced, err := tx.Set("testkey", "testvalue", nil)
if err != nil {
return err
}
fmt.Printf("old value:%q replaced:%t\n", oldValue, replaced)
return nil
})
db.View(func(tx *buntdb.Tx) error {
value, err := tx.Get("testkey")
if err != nil {
return err
}
fmt.Println("value is:", value)
return nil
})
}
buntdb在使用方式上与我们熟知的sqlite有些类似，只是前者支持的是键值对，后者支持的关系型数据。首先，我们要打开一个数据库，buntdb支持将数据存储到文件和内存，将数据保存在磁盘上的文件中，断电不会丢失。直接存放在内存中，程序退出后数据就丢失了。调用buntdb.Open()方法需要传入一个文件名的参数，指定数据保存的文件路径。如果传入特殊字符串:memory:，则buntdb不会将数据保存到磁盘。
在buntdb中，所有的读写操作都必须在一个事务中执行。同一时间只能存在一个写事务，但是可以同时存在多个并发的读事务。如果只需要读取数据，那么调用db.View()方法。方法接收一个类型为func (tx *buntdb.Tx) error的函数作为参数，db.View()方法内部会生成一个事务对象tx，然后将这个tx作为参数传给该函数。在此函数中使用事务对象tx的Get()方法执行读取的逻辑：
db.View(func(tx *buntdb.Tx) error {
value, err := tx.Get("testkey")
if err != nil {
return err
}
fmt.Println("value is:", value)
return nil
})
如果需要读写数据，那么使用db.Update()方法。同样地，也需要传入一个类型为func (tx *buntdb.Tx) error的函数，在此函数中使用事务对象tx的Set方法执行写入逻辑。tx.Set()方法返回 3 个值。如果Set()替换了当前值，则返回替换之前的值和true。如果此函数返回非空错误，db.Update()会回退此前所做的修改，反之会提交此次修改。
如果运行两次上面的程序，我们会看到下面的输出：
// 第一次运行
$ go run main.go
old value:"" replaced:false
value is: testvalue
// 第二次运行
$ go run main.go
old value:"testvalue" replaced:true
value is: testvalue
注意：
- 数据库操作很容易出错，所以基本上所有的方法都会返回错误，在实际中需要处理每个可能的错误。示例中为了代码简洁，有点地方忽略了；
- 在传入
db.View()和db.Update()的函数中不要直接使用db对象，否则可能会导致程序死锁； - 默认情况下，若键对应的值不存在，则返回
ErrNotFound错误。
遍历
buntdb中存储的数据是根据键排序的，我们可以按顺序依次遍历这些数据。由于遍历是读取操作，我们用db.View()方法。buntdb提供了很多遍历的方法，基本形式都差不多，这里只介绍一个基本的Ascend()方法：
func (tx *Tx) Ascend(index string, iterator func(key, value string) bool) error
Ascend()方法接收一个索引名，然后以该索引定义的顺序遍历所有键值对，将遍历到的键值对传给iterator函数处理，如果iterator返回false，终止遍历。另外，如果未指定索引名，则根据键升序遍历：
func main() {
db, err := buntdb.Open(":memory:")
if err != nil {
log.Fatal(err)
}
defer db.Close()
db.Update(func(tx *buntdb.Tx) error {
data := map[string]string{
"a": "apple",
"b": "banana",
"p": "pear",
"o": "orange",
}
for key, value := range data {
tx.Set(key, value, nil)
}
return nil
})
db.View(func(tx *buntdb.Tx) error {
var count int
tx.Ascend("", func(key, value string) bool {
fmt.Printf("key:%s value:%s\n", key, value)
count++
if count >= 3 {
return false
}
return true
})
return nil
})
}
上面代码中，我们按键升序遍历（因为传入索引名为""），在处理完第三个键值对后，iterator函数返回false，停止遍历。最终输出：
key:a value:apple
key:b value:banana
key:o value:orange
索引
buntdb将所有数据都存储在一个B-tree中，每组数据都有一个键和值。所有数据是根据键来排序的。我们也可以创建自定义索引，这样就可以对值进行排序了。创建索引需要调用db.CreateIndex()方法，该方法签名如下：
func (db *DB) CreateIndex(name, pattern string, less ...func(a, b string) bool) error
name为索引名，在上一节介绍遍历的时候，我们说过遍历时需要传入索引名，以便按照该索引所定义的顺序遍历。pattern为模式，指定索引对哪些键生效，可以只对某些特定模式的键创建索引。*表示所有键，user:*:name表示键名是user:和:name之间有任意字符的键。通过less函数，我们可以自定义排序规则。buntdb内置了一些排序规则，如IndexString对值进行大小写不敏感的排序，IndexInt/IndexUint/IndexFloat执行数值类型的排序。
func main() {
db, err := buntdb.Open(":memory:")
if err != nil {
log.Fatal(err)
}
defer db.Close()
db.CreateIndex("names", "user:*:name", buntdb.IndexString)
db.Update(func(tx *buntdb.Tx) error {
tx.Set("user:1:name", "tom", nil)
tx.Set("user:2:name", "Randi", nil)
tx.Set("user:3:name", "jane", nil)
tx.Set("user:4:name", "Janet", nil)
tx.Set("user:5:name", "Paula", nil)
tx.Set("user:6:name", "peter", nil)
tx.Set("user:7:name", "Terri", nil)
return nil
})
db.View(func(tx *buntdb.Tx) error {
tx.Ascend("names", func(key, value string) bool {
fmt.Printf("%s: %s\n", key, value)
return true
})
return nil
})
}
我们先为键名满足模式user:*:name的数据创建一个名为names的索引，执行大小写不敏感的排序（buntdb.IndexString）。然后向buntdb中写入几组数据。最后，我们使用Ascend()方法，传入索引名names按该索引指定次序遍历键值对（这里只是遍历满足模式user:*:name的键值对）。
如果我们的键只有user:*:name这种模式的，也可以直接使用模式*或user:*
对于整数等非字符串类型的排序，我们需要注意一点：因为buntdb存储的键值都是字符串，所以自定义的排序函数需要执行相应的类型转换。一般需求的数值排序，内置函数就可以满足要求了：
func main() {
db, err := buntdb.Open(":memory:")
if err != nil {
log.Fatal(err)
}
defer db.Close()
db.CreateIndex("ages", "user:*:age", buntdb.IndexInt)
db.Update(func(tx *buntdb.Tx) error {
tx.Set("user:1:age", "16", nil)
tx.Set("user:2:age", "35", nil)
tx.Set("user:3:age", "24", nil)
tx.Set("user:4:age", "32", nil)
tx.Set("user:5:age", "25", nil)
tx.Set("user:6:age", "28", nil)
tx.Set("user:7:age", "31", nil)
return nil
})
db.View(func(tx *buntdb.Tx) error {
tx.Ascend("ages", func(key, value string) bool {
fmt.Printf("%s: %s\n", key, value)
return true
})
return nil
})
}
首先，为键名满足user:*:age的键创建索引ages，因为在这些键对应的值中，我们存储的都是年龄（整数），故使用排序规则IndexInt。
JSON 索引
buntdb提供了强大的 JSON 索引功能。如果存储的值是一个 JSON 字符串，buntdb可以对 JSON 串内部的键创建索引。buntdb.IndexJSON()实现了 JSON 索引的排序规则，我们需要传入键在 JSON 内部的路径，如name.first，contact.email等：
func main() {
db, _ := buntdb.Open(":memory:")
defer db.Close()
db.CreateIndex("first_name", "user:*", buntdb.IndexJSON("name.first"))
db.CreateIndex("age", "user:*", buntdb.IndexJSON("age"))
db.Update(func(tx *buntdb.Tx) error {
tx.Set("user:1", `{"name":{"first":"zhang","last":"san"},"age":18}`, nil)
tx.Set("user:2", `{"name":{"first":"li","last":"si"},"age":27`, nil)
tx.Set("user:3", `{"name":{"first":"wang","last":"wu"},"age":32}`, nil)
tx.Set("user:4", `{"name":{"first":"sun","last":"qi"},"age":8}`, nil)
return nil
})
db.View(func(tx *buntdb.Tx) error {
fmt.Println("Order by first name")
tx.Ascend("first_name", func(key, value string) bool {
fmt.Printf("%s: %s\n", key, value)
return true
})
fmt.Println("Order by age")
tx.Ascend("age", func(key, value string) bool {
fmt.Printf("%s: %s\n", key, value)
return true
})
fmt.Println("Order by age range 18-30")
tx.AscendRange("age", `{"age":18}`, `{"age":30}`, func(key, value string) bool {
fmt.Printf("%s: %s\n", key, value)
return true
})
return nil
})
}
JSON 给我们提供了一种很好的存储用户数据的格式。以user:后加上用户 ID 作为键名，用户数据以 JSON 格式存储在值中，如上所示。
我们分别为 JSON 内部的键name.first和age创建索引。然后分别以name.first和age定义的顺序遍历输出。值得一提的是最后一个遍历使用了AscendRange，可以只遍历指定范围内的数据，例子中为年龄在 18~30 之间。范围遍历并非 JSON 索引独有的，与普通的Ascend相比，AscendRange需要传入区间上下限min和max，所有处于[min, max)之间的数据都会被遍历到（注意不包含max）。
多重索引
细节的盆友应该发现了，创建索引的方法CreateIndex()接受可变数量的排序规则函数，如果第一个函数无法判断两个值的大小，则继续使用后一个函数，直到可以判断或没有其他函数了。这个就是多重索引。在上面的示例中，我们可以将first_name和age两个索引放在一起，先对name.first比较，如果相等，再比较age：
func main() {
db, _ := buntdb.Open(":memory:")
defer db.Close()
db.CreateIndex("first_name_age", "user:*", buntdb.IndexJSON("name.first"), buntdb.IndexJSON("age"))
db.Update(func(tx *buntdb.Tx) error {
tx.Set("user:1", `{"name":{"first":"zhang","last":"san"},"age":18}`, nil)
tx.Set("user:2", `{"name":{"first":"li","last":"si"},"age":27`, nil)
tx.Set("user:3", `{"name":{"first":"wang","last":"wu"},"age":30}`, nil)
tx.Set("user:4", `{"name":{"first":"sun","last":"qi"},"age":8}`, nil)
tx.Set("user:5", `{"name":{"first":"li", "name":"dajun"},"age":20}`, nil)
return nil
})
db.View(func(tx *buntdb.Tx) error {
tx.Ascend("first_name_age", func(key, value string) bool {
fmt.Printf("%s: %s\n", key, value)
return true
})
return nil
})
}
由于user:2和user:5的name.first都是li，相等。故使用age的值排序，所以输出中user:5在user:2前面。
降序
我们使用的内置函数都是升序规则。可以使用buntdb.Desc()将升序规则变为降序，拿前面整数排序的例子来说，只需要将buntdb.IndexInt变为buntdb.Desc(buntdb.IndexInt)即可：
func main() {
db, _ := buntdb.Open(":memory:")
defer db.Close()
db.CreateIndex("ages", "user:*:age", buntdb.Desc(buntdb.IndexInt))
db.Update(func(tx *buntdb.Tx) error {
tx.Set("user:1:age", "16", nil)
tx.Set("user:2:age", "35", nil)
tx.Set("user:3:age", "24", nil)
tx.Set("user:4:age", "32", nil)
tx.Set("user:5:age", "25", nil)
tx.Set("user:6:age", "28", nil)
tx.Set("user:7:age", "31", nil)
return nil
})
db.View(func(tx *buntdb.Tx) error {
tx.Ascend("ages", func(key, value string) bool {
fmt.Printf("%s: %s\n", key, value)
return true
})
return nil
})
}
过期
在向buntdb中设置键值时，我们可以通过选项buntdb.SetOptions指定过期时间，超过这个时间数据会自动从buntdb中移除。如果想要移除过期时间，重新使用nil选项设置该键值即可：
func main() {
db, _ := buntdb.Open(":memory:")
defer db.Close()
db.Update(func(tx *buntdb.Tx) error {
tx.Set("testkey", "testvalue", &buntdb.SetOptions{Expires: true, TTL: time.Second})
return nil
})
db.View(func(tx *buntdb.Tx) error {
value, _ := tx.Get("testkey")
fmt.Println("value is:", value)
return nil
})
time.Sleep(time.Second)
db.View(func(tx *buntdb.Tx) error {
value, _ := tx.Get("testkey")
fmt.Println("value is:", value)
return nil
})
}
上面例子中，我们先写入数据，并设置过期时间为1s。然后立刻读取，这时可以读到刚刚设置的值。然后Sleep 1s 之后再次读取，读到空值，说明已被删除：
value is: testvalue
value is:
杂项
遍历时删除
buntdb不支持遍历时删除数据，一般迂回的做法是先记录需要删除的键，遍历结束后统一删除。下面将年龄 >= 30 的用户删掉（嗯，程序员年龄大了，干不动了）：
func main() {
db, _ := buntdb.Open(":memory:")
defer db.Close()
db.Update(func(tx *buntdb.Tx) error {
tx.Set("user:1:age", "16", nil)
tx.Set("user:2:age", "35", nil)
tx.Set("user:3:age", "24", nil)
tx.Set("user:4:age", "32", nil)
tx.Set("user:5:age", "25", nil)
tx.Set("user:6:age", "28", nil)
tx.Set("user:7:age", "31", nil)
return nil
})
db.Update(func(tx *buntdb.Tx) error {
// 先汇总
deleteKeys := make([]string, 0)
tx.Ascend("", func(key, value string) bool {
age, _ := strconv.ParseUint(value, 10, 64)
if age >= 30 {
deleteKeys = append(deleteKeys, key)
}
return true
})
// 再删除
for _, key := range deleteKeys {
tx.Delete(key)
}
return nil
})
db.View(func(tx *buntdb.Tx) error {
tx.Ascend("", func(key, value string) bool {
fmt.Printf("%s: %s\n", key, value)
return true
})
return nil
})
}
Web 服务
buntdb只能在本地程序中操作，我们简单为它编写一个 Web 服务，可以通过 HTTP 请求操作远程的buntdb。代码如下：
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"strconv"
"time"
"github.com/tidwall/buntdb"
)
var db *buntdb.DB
func init() {
var err error
db, err = buntdb.Open("data.db")
if err != nil {
log.Fatal(err)
}
}
func response(w http.ResponseWriter, err error, data interface{}) {
bytes, _ := json.Marshal(map[string]interface{}{
"error": err,
"data": data,
})
w.Write(bytes)
}
func set(w http.ResponseWriter, r *http.Request) {
key := r.FormValue("key")
value := r.FormValue("value")
expire, _ := strconv.ParseBool(r.FormValue("expire"))
ttl, _ := time.ParseDuration(r.FormValue("ttl"))
var setOption *buntdb.SetOptions
if expire && ttl > 0 {
setOption = &buntdb.SetOptions{Expires: true, TTL: ttl}
}
err := db.Update(func(tx *buntdb.Tx) error {
_, _, err := tx.Set(key, value, setOption)
return err
})
response(w, err, nil)
}
func get(w http.ResponseWriter, r *http.Request) {
key := r.FormValue("key")
var value string
err := db.View(func(tx *buntdb.Tx) error {
var err error
value, err = tx.Get(key)
return err
})
response(w, err, value)
}
type Pair struct {
Key string
Value string
}
func iterate(w http.ResponseWriter, r *http.Request) {
index := r.FormValue("index")
fmt.Println(index)
var items []Pair
err := db.View(func(tx *buntdb.Tx) error {
err := tx.Ascend(index, func(key, value string) bool {
fmt.Println(key, value)
items = append(items, Pair{key, value})
return true
})
return err
})
response(w, err, items)
}
func createIndex(w http.ResponseWriter, r *http.Request) {
name := r.FormValue("name")
pattern := r.FormValue("pattern")
less := buntdb.IndexString
err := db.CreateIndex(name, pattern, less)
response(w, err, nil)
}
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/get", get)
mux.HandleFunc("/set", set)
mux.HandleFunc("/iterate", iterate)
mux.HandleFunc("/create_index", createIndex)
server := &http.Server{
Addr: ":8000",
Handler: mux,
}
if err := server.ListenAndServe(); err != nil {
log.Fatal(err)
}
}
我只编写了基本读取、设置、创建索引和遍历的功能，代码并不难理解。下面我们先运行程序，然后用浏览器请求：
请求localhost:8000/set?key=name&value=dj，返回：
{"error":null, "data":null}
error为null表示无错误。
请求localhost:8000/set?key=dj&value=18，返回：
{"error":null, "data":null}
请求localhost:8000/iterate，返回：
{
"data": [
{
"Key": "age",
"Value": "18"
},
{
"Key": "name",
"Value": "dj"
}
],
"error": null
}
感兴趣可以试着添加更多的功能。如果对 Go Web 编程不太了解，可以去看看我的Go Web 编程系列文章。
总结
本文介绍buntdb的读取、写入、创建索引等基本操作，最后编写一个简单的 web 服务可以在远程运行，其他程序通过 HTTP 与之交互。buntdb还支持空间索引等高级特性，感兴趣可自行研究。
大家如果发现好玩、好用的 Go 语言库，欢迎到 Go 每日一库 GitHub 上提交 issue😄
参考
- buntdb GitHub：https://github.com/tidwall/buntdb
- Go 每日一库 GitHub：https://github.com/go-quiz/go-daily-lib
