简介

buntdb是一个完全用 Go 语言编写的内存键值数据库。它支持 ACID、并发读、自定义索引和空间信息数据。buntdb只用一个源码文件就实现了这些功能,对于想要学习数据库底层知识的童鞋更是不容错过。

感谢@kiyonlin推荐!

快速使用

先安装:

1
$ go get github.com/tidwall/buntdb

后使用:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
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作为参数传给该函数。在此函数中使用事务对象txGet()方法执行读取的逻辑:

1
2
3
4
5
6
7
8
9
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的函数,在此函数中使用事务对象txSet方法执行写入逻辑。tx.Set()方法返回 3 个值。如果Set()替换了当前值,则返回替换之前的值和true。如果此函数返回非空错误,db.Update()会回退此前所做的修改,反之会提交此次修改。

如果运行两次上面的程序,我们会看到下面的输出:

1
2
3
4
5
6
7
8
9
// 第一次运行
$ 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()方法:

1
func (tx *Tx) Ascend(index string, iterator func(key, value string) bool) error

Ascend()方法接收一个索引名,然后以该索引定义的顺序遍历所有键值对,将遍历到的键值对传给iterator函数处理,如果iterator返回false,终止遍历。另外,如果未指定索引名,则根据键升序遍历:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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,停止遍历。最终输出:

1
2
3
key:a value:apple
key:b value:banana
key:o value:orange

索引

buntdb将所有数据都存储在一个B-tree中,每组数据都有一个键和值。所有数据是根据键来排序的。我们也可以创建自定义索引,这样就可以对值进行排序了。创建索引需要调用db.CreateIndex()方法,该方法签名如下:

1
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执行数值类型的排序。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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存储的键值都是字符串,所以自定义的排序函数需要执行相应的类型转换。一般需求的数值排序,内置函数就可以满足要求了:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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.firstcontact.email等:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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.firstage创建索引。然后分别以name.firstage定义的顺序遍历输出。值得一提的是最后一个遍历使用了AscendRange,可以只遍历指定范围内的数据,例子中为年龄在 18~30 之间。范围遍历并非 JSON 索引独有的,与普通的Ascend相比,AscendRange需要传入区间上下限minmax,所有处于[min, max)之间的数据都会被遍历到(注意不包含max)。

多重索引

细节的盆友应该发现了,创建索引的方法CreateIndex()接受可变数量的排序规则函数,如果第一个函数无法判断两个值的大小,则继续使用后一个函数,直到可以判断或没有其他函数了。这个就是多重索引。在上面的示例中,我们可以将first_nameage两个索引放在一起,先对name.first比较,如果相等,再比较age

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
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:2user:5name.first都是li,相等。故使用age的值排序,所以输出中user:5user:2前面。

降序

我们使用的内置函数都是升序规则。可以使用buntdb.Desc()将升序规则变为降序,拿前面整数排序的例子来说,只需要将buntdb.IndexInt变为buntdb.Desc(buntdb.IndexInt)即可:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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选项设置该键值即可:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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 之后再次读取,读到空值,说明已被删除:

1
2
value is: testvalue
value is: 

杂项

遍历时删除

buntdb不支持遍历时删除数据,一般迂回的做法是先记录需要删除的键,遍历结束后统一删除。下面将年龄 >= 30 的用户删掉(嗯,程序员年龄大了,干不动了):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
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。代码如下:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
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,返回:

1
{"error":null, "data":null}

errornull表示无错误。

请求localhost:8000/set?key=dj&value=18,返回:

1
{"error":null, "data":null}

请求localhost:8000/iterate,返回:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "data": [
    {
      "Key": "age",
      "Value": "18"
    },
    {
      "Key": "name",
      "Value": "dj"
    }
  ],
  "error": null
}

感兴趣可以试着添加更多的功能。如果对 Go Web 编程不太了解,可以去看看我的Go Web 编程系列文章。

总结

本文介绍buntdb的读取、写入、创建索引等基本操作,最后编写一个简单的 web 服务可以在远程运行,其他程序通过 HTTP 与之交互。buntdb还支持空间索引等高级特性,感兴趣可自行研究。

大家如果发现好玩、好用的 Go 语言库,欢迎到 Go 每日一库 GitHub 上提交 issue😄

参考

  1. buntdb GitHub:https://github.com/tidwall/buntdb
  2. Go 每日一库 GitHub:https://github.com/darjun/go-daily-lib

我的博客:https://darjun.github.io

欢迎关注我的微信公众号【GoUpUp】,共同学习,一起进步~