boltdb 介绍

介绍

BoltDB 是一个用 Go 语言编写的嵌入式键/值数据库。以下是关于 BoltDB 的一些基本介绍：

• 键/值存储: BoltDB 为应用程序提供了简单的键/值存储接口。
• 事务: BoltDB 支持完整的 ACID 事务。
• 嵌入式: 与像 MySQL 或 PostgreSQL 这样的数据库系统不同，BoltDB 不运行在单独的服务器进程中。它作为一个库被直接嵌入到你的应用程序中。
• 单文件存储: 所有的数据都存储在一个文件中，这使得备份和迁移变得简单。
• 高效的二进制存储: 数据在磁盘上使用 B+ 树结构存储，这为随机读取提供了高性能。
• 前缀扫描: 可以很容易地按键的前缀进行扫描，这使得它适用于范围查询。
• 没有外部依赖: BoltDB 不依赖于任何外部系统或库。
• 线程安全: BoltDB 是线程安全的，可以在多个 goroutines 中并发地使用。

BoltDB 特别适用于需要一个轻量级、高性能、易于部署和维护的数据库解决方案的场景。

虽然 BoltDB 非常有用，但它也有其局限性。例如，它不支持分布式存储，也不适用于需要多节点复制或分片的场景。但对于许多应用程序，它提供了一个简单且高性能的存储解决方案。

源码地址：

https://github.com/boltdb/bolt 这个项目已经不维护了, etcd 官方维护了一个 fork 库，api 是互通的: https://github.com/etcd-io/bbolt

谁在使用

etcd、tidb、influxdb、consul ......

架构图

引入

go get go.etcd.io/bbolt

使用

open a database

Bolt 中的顶级对象是 DB。它在你的硬盘上表示为一个单独的文件，并代表了你数据的一个一致性快照。

要打开你的数据库，只需使用 bolt.Open() 函数：

package main

import (
	"log"

	bolt "go.etcd.io/bbolt"
)

func main() {
	db, err := bolt.Open("my.db", 0600, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()
}

请注意，Bolt 在数据文件上获得一个文件锁，因此多个进程不能同时打开同一个数据库。打开一个已经打开的 Bolt 数据库会导致它挂起，直到另一个进程关闭它。为了防止无限期的等待，你可以向 Open() 函数传递一个超时选项：

db, err := bolt.Open("my.db", 0600, &bolt.Options{Timeout: 1 * time.Second})

Transactions

Bolt一次只允许一个读写 transactions ，但允许您一次进行多个只读 transactions 。每一个 transactions 在开始时都能看到数据的一致视图。

单独的 transactions 和从它们创建的所有对象（例如桶、键）都不是线程安全的。要在多个goroutines中处理数据，您必须为每一个goroutine启动一个 transactions ，或使用锁来确保一次只有一个goroutine访问一个 transactions 。从数据库创建 transactions 是线程安全的。

transactions 不应相互依赖，并且通常不应在同一goroutine中同时打开。这可能会导致死锁，因为读写 transactions 需要定期重新映射数据文件，但在任何只读 transactions 打开时都不能这样做。即使是嵌套的只读 transactions 也可能导致死锁，因为子 transactions 可能阻止父 transactions 释放其资源。

Read-write transactions

要开始一个读写 transactions ，可以使用DB.Update()函数：

err := db.Update(func(tx *bolt.Tx) error {
	...
	return nil
})

在闭包中，您可以看到数据库的一致视图。通过在最后返回nil来提交 transactions 。您还可以通过返回错误在任何时候回滚 transactions 。所有的数据库操作都允许在一个读写 transactions 中进行。

始终检查返回错误，因为它会报告任何可能导致您的 transactions 未完成的磁盘故障。如果您在闭包内返回错误，它将被传递。

Read-only transactions

要开始一个只读 transactions ，您可以使用DB.View()函数：

err := db.View(func(tx *bolt.Tx) error {
	...
	return nil
})

在这个闭包内，您也可以看到数据库的一致视图，但在只读 transactions 中不允许进行变动操作。在一个只读 transactions 中，您只能检索桶、检索值和复制数据库。

Batch read-write transactions

每个DB.Update()都会等待磁盘提交写入。这种开销可以通过使用DB.Batch()函数结合多个更新来最小化：

err := db.Batch(func(tx *bolt.Tx) error {
	...
	return nil
})

并发的Batch调用会被机会性地组合成更大的 transactions 。只有当有多个goroutines调用它时，Batch才是有用的。

权衡之处在于，Batch在 transactions 的部分失败时可以多次调用给定的函数。该函数必须是幂等的，且只有在成功从DB.Batch()返回后，副作用才会生效。

例如：不要从函数内部显示消息，而是在封闭范围内设置变量：

var id uint64
err := db.Batch(func(tx *bolt.Tx) error {
	// 在桶中查找最后一个键，解码为bigendian uint64，增加
	// 一个，编码回[]byte，并添加新键。
	...
	id = newValue
	return nil
})
if err != nil {
	return ...
}
fmt.Println("Allocated ID %d", id)

Managing transactions manually

DB.View()和DB.Update()函数是DB.Begin()函数的包装。这些助手函数将启动 transactions 、执行函数，然后在返回错误时安全地关闭您的 transactions 。这是使用Bolt transactions 的推荐方法。

然而，有时您可能希望手动开始和结束您的 transactions 。您可以直接使用DB.Begin()函数，但请确保关闭 transactions 。

// 开始一个可写的 transactions 。
tx, err := db.Begin(true)
if err != nil {
    return err
}
defer tx.Rollback()

// 使用 transactions ...
_, err := tx.CreateBucket([]byte("MyBucket"))
if err != nil {
    return err
}

// 提交 transactions 并检查错误。
if err := tx.Commit(); err != nil {
    return err
}

DB.Begin()的第一个参数是一个布尔值，表示 transactions 是否应该是可写的。

Using buckets

桶是数据库中的键/值对集合。一个桶中的所有键都必须是唯一的。您可以使用Tx.CreateBucket()函数创建一个桶：

db.Update(func(tx *bolt.Tx) error {
	b, err := tx.CreateBucket([]byte("MyBucket"))
	if err != nil {
		return fmt.Errorf("create bucket: %s", err)
	}
	return nil
})

您可以使用Tx.Bucket()函数检索现有的桶：

db.Update(func(tx *bolt.Tx) error {
	b := tx.Bucket([]byte("MyBucket"))
	if b == nil {
		return fmt.Errorf("bucket does not exist")
	}
	return nil
})

您还可以使用Tx.CreateBucketIfNotExists()函数只在桶不存在时创建一个桶。打开数据库后，为所有的顶级桶调用此函数是一种常见的模式，这样您可以保证它们存在于未来的 transactions 中。

要删除一个桶，只需调用Tx.DeleteBucket()函数。

Using key/value pairs

要将键/值对保存到存储桶，使用Bucket.Put()函数：

db.Update(func(tx *bolt.Tx) error {
	b := tx.Bucket([]byte("MyBucket"))
	err := b.Put([]byte("answer"), []byte("42"))
	return err
})

这会在MyBucket存储桶中将"answer"键的值设置为"42"。要检索此值，我们可以使用Bucket.Get()函数：

db.View(func(tx *bolt.Tx) error {
	b := tx.Bucket([]byte("MyBucket"))
	v := b.Get([]byte("answer"))
	fmt.Printf("The answer is: %s\n", v)
	return nil
})

Get()函数不返回错误，因为其操作保证可以工作（除非有某种系统故障）。如果键存在，它将返回其字节切片值。如果不存在，则返回nil。重要的是要注意，您可以将零长度的值设置为一个键，这与键不存在是不同的。

使用Bucket.Delete()函数从存储桶中删除键：

db.Update(func (tx *bolt.Tx) error {
    b := tx.Bucket([]byte("MyBucket"))
    err := b.Delete([]byte("answer"))
    return err
})

这将从MyBucket存储桶中删除答案键。

请注意，从Get()返回的值只在事务打开时有效。如果您需要在事务外部使用值，则必须使用copy()将其复制到另一个字节切片。

Autoincrementing integer for the bucket

通过使用NextSequence()函数，您可以让Bolt确定一个序列，该序列可以用作键/值对的唯一标识符。请参阅下面的示例。

// CreateUser saves u to the store. The new user ID is set on u once the data is persisted.
func (s *Store) CreateUser(u *User) error {
    return s.db.Update(func(tx *bolt.Tx) error {
        // Retrieve the users bucket.
        // This should be created when the DB is first opened.
        b := tx.Bucket([]byte("users"))

        // Generate ID for the user.
        // This returns an error only if the Tx is closed or not writeable.
        // That can't happen in an Update() call so I ignore the error check.
        id, _ := b.NextSequence()
        u.ID = int(id)

        // Marshal user data into bytes.
        buf, err := json.Marshal(u)
        if err != nil {
            return err
        }

        // Persist bytes to users bucket.
        return b.Put(itob(u.ID), buf)
    })
}

// itob returns an 8-byte big endian representation of v.
func itob(v int) []byte {
    b := make([]byte, 8)
    binary.BigEndian.PutUint64(b, uint64(v))
    return b
}

type User struct {
    ID int
    ...
}

Iterating over keys

Bolt在存储桶内按字节排序存储其键。这使得对这些键进行顺序迭代非常快。要迭代键，我们将使用一个Cursor：

db.View(func(tx *bolt.Tx) error {
	// Assume bucket exists and has keys
	b := tx.Bucket([]byte("MyBucket"))

	c := b.Cursor()

	for k, v := c.First(); k != nil; k, v = c.Next() {
		fmt.Printf("key=%s, value=%s\n", k, v)
	}

	return nil
})

游标允许您移动到键列表中的特定点，并一次向前或向后移动一个键。

以下函数在游标上可用：

• First() 移动到第一个键。
• Last() 移动到最后一个键。
• Seek() 移动到特定键。
• Next() 移动到下一个键。
• Prev() 移动到上一个键。 每个函数都有一个返回签名（key []byte, value []byte）。当您迭代到游标的末尾时，Next()将返回一个nil键。您必须使用First()、Last()或Seek()移动到某个位置，然后再调用Next()或Prev()。如果您没有移动到某个位置，那么这些函数将返回一个nil键。

在迭代过程中，如果键不是nil，但值是nil，那么意味着键引用的是一个存储桶而不是一个值。使用Bucket.Bucket()来访问子存储桶。

Prefix scans

要迭代键前缀，您可以结合使用Seek()和bytes.HasPrefix()：

db.View(func(tx *bolt.Tx) error {
	// Assume bucket exists and has keys
	c := tx.Bucket([]byte("MyBucket")).Cursor()

	prefix := []byte("1234")
	for k, v := c.Seek(prefix); k != nil && bytes.HasPrefix(k, prefix); k, v = c.Next() {
		fmt.Printf("key=%s, value=%s\n", k, v)
	}

	return nil
})

Range scans

另一个常见的用例是扫描范围，例如时间范围。如果您使用可排序的时间编码，例如RFC3339，那么您可以像这样查询特定的日期范围：

db.View(func(tx *bolt.Tx) error {
	// Assume our events bucket exists and has RFC3339 encoded time keys.
	c := tx.Bucket([]byte("Events")).Cursor()

	// Our time range spans the 90's decade.
	min := []byte("1990-01-01T00:00:00Z")
	max := []byte("2000-01-01T00:00:00Z")

	// Iterate over the 90's.
	for k, v := c.Seek(min); k != nil && bytes.Compare(k, max) <= 0; k, v = c.Next() {
		fmt.Printf("%s: %s\n", k, v)
	}

	return nil
})

请注意，虽然RFC3339是可排序的，但Golang的RFC3339Nano实现不使用小数点后固定数量的数字，因此不可排序。

ForEach()

如果您知道要在存储桶中迭代所有键，也可以使用ForEach()函数：

db.View(func(tx *bolt.Tx) error {
	// Assume bucket exists and has keys
	b := tx.Bucket([]byte("MyBucket"))

	b.ForEach(func(k, v []byte) error {
		fmt.Printf("key=%s, value=%s\n", k, v)
		return nil
	})
	return nil
})

请注意，ForEach()中的键和值仅在事务打开时有效。如果您需要在事务之外使用键或值，您必须使用copy()将其复制到另一个字节切片。

Nested buckets

以下是给定文档的中文翻译：

请注意，ForEach()中的键和值仅在事务打开时有效。如果您需要在事务之外使用键或值，您必须使用copy()将其复制到另一个字节切片。

嵌套的桶 您还可以在键中存储一个桶，以创建嵌套的桶。该API与DB对象上的桶管理API相同：

func (*Bucket) CreateBucket(key []byte) (*Bucket, error)
func (*Bucket) CreateBucketIfNotExists(key []byte) (*Bucket, error)
func (*Bucket) DeleteBucket(key []byte) error

假设您有一个多租户应用程序，其中根级别的桶是帐户桶。在此桶内是一系列自身为桶的帐户。在这个序列桶里，你可以拥有许多与账户自身相关的桶（如用户、笔记等），将信息隔离到逻辑分组中。

// createUser 在给定账户中创建一个新用户。
func createUser(accountID int, u *User) error {
    // 开始事务。
    tx, err := db.Begin(true)
    if err != nil {
        return err
    }
    defer tx.Rollback()

    // 检索帐户的根桶。
    // 假设在设置帐户时已经创建了此桶。
    root := tx.Bucket([]byte(strconv.FormatUint(accountID, 10)))

    // 设置用户桶。
    bkt, err := root.CreateBucketIfNotExists([]byte("USERS"))
    if err != nil {
        return err
    }

    // 为新用户生成ID。
    userID, err := bkt.NextSequence()
    if err != nil {
        return err
    }
    u.ID = userID

    // 序列化并保存编码的用户。
    if buf, err := json.Marshal(u); err != nil {
        return err
    } else if err := bkt.Put([]byte(strconv.FormatUint(u.ID, 10)), buf); err != nil {
        return err
    }

    // 提交事务。
    if err := tx.Commit(); err != nil {
        return err
    }

    return nil
}

数据库备份

Bolt是一个单一的文件，所以备份很容易。您可以使用Tx.WriteTo()函数将数据库的一致视图写入一个写入器。如果您从只读事务中调用此函数，它将执行一个热备份，并且不会阻止您的其他数据库读取和写入。

默认情况下，它将使用一个常规的文件句柄，该句柄将利用操作系统的页面缓存。请查看Tx文档，了解有关优化大于RAM数据集的信息。

一个常见的用例是通过HTTP进行备份，这样您就可以使用像cURL这样的工具进行数据库备份：

func BackupHandleFunc(w http.ResponseWriter, req *http.Request) {
    err := db.View(func(tx *bolt.Tx) error {
        w.Header().Set("Content-Type", "application/octet-stream")
        w.Header().Set("Content-Disposition", `attachment; filename="my.db"`)
        w.Header().Set("Content-Length", strconv.Itoa(int(tx.Size())))
        _, err := tx.WriteTo(w)
        return err
    })
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

然后你可以使用这个命令备份：

$ curl http://localhost/backup > my.db

或者您可以打开您的浏览器访问http://localhost/backup，它将自动下载。

如果您想备份到另一个文件，您可以使用Tx.CopyFile()辅助函数。

统计信息 数据库保持对其执行的许多内部操作的持续计数，这样您可以更好地了解正在发生的事情。通过在两个时间点获取这些统计的快照，我们可以看到在这个时间范围内执行了哪些操作。

例如，我们可以启动一个goroutine，每10秒记录一次统计信息：

go func() {
    // 获取初始统计。
    prev := db.Stats()

    for {
        // 等待10秒。
        time.Sleep(10 * time.Second)

        // 获取当前统计并对其进行差异处理。
        stats := db.Stats()
        diff := stats.Sub(&prev)

        // 将统计信息编码为JSON并打印到STDERR。
        json.NewEncoder(os.Stderr).Encode(diff)

        // 为下一个循环保存统计。
        prev = stats
    }
}()

将这些统计信息管道到像statsd这样的服务进行监控，或者提供一个HTTP端点来执行固定长度的样本，也很有用。

只读模式

有时创建一个共享的、只读的Bolt数据库是很有用的。要做到这一点，打开数据库时设置Options.ReadOnly标志。只读模式使用共享锁，允许多个进程从数据库中读取，但它会阻止任何进程以读写模式打开数据库。

db, err := bolt.Open("my.db", 0600, &bolt.Options{ReadOnly: true})
if err != nil {
    log.Fatal(err)
}

希望这可以帮助您理解给定的文档！如果您有任何问题或需要进一步的澄清，请告诉我。

referance

• https://github.com/etcd-io/bbolt
• https://zhuanlan.zhihu.com/p/377572049