Boltdb 源码导读（一）：Boltdb 数据组织

boltdb 是市面上为数很少的纯 go 语言开发的、单机 KV 库。boltdb 基于 Howard Chu'sLMDB 项目，实现的比较清爽，去掉单元测试和适配代码，核心代码大概四千多行。简单的 API、简约的实现，也是做者的意图所在。因为做者精力所限，原 boltdb 已经封版，再也不更新。若想改进，提交新的 pr，建议去 etcd 维护的 fork 版本 bbolt。css

为了方便，本系列导读文章仍以再也不变更的原 repo 为基础。该项目麻雀虽小，五脏俱全，仅仅四千多行代码，就实现了一个基于 B+ 树索引、支持一写多读事务的单机 KV 引擎。代码自己简约朴实、注释得当，若是你是 go 语言爱好者、若是对 KV 库感兴趣，那 boltdb 绝对是不可错过的一个 repo。
node

本系列计划分红三篇文章，依次围绕数据组织、索引设计、事务实现等三个主要方面对 boltdb 源码进行剖析。因为三个方面不是彻底正交解耦的，所以叙述时会不可避免的产生交织，读不懂时，暂时略过便可，待有全貌，再回来梳理。本文是第一篇， boltdb 数据组织。
git

引子

一个存储引擎最底层的构成，就是处理数据在各类物理介质（好比在磁盘上、在内存里）上的组织。而这些数据组织也体现了该存储引擎在设计上的取舍哲学。github

在文件系统上，boltdb 采用页（page）的组织方式，将一切数据都对齐到页；在内存中，boltdb 按 B+ 树组织数据，其基本单元是节点（node），一个内存中的树节点对应文件系统上一个或者多个连续的页。boltdb 就在数据组织上就只有这两种核心抽象，可谓设计简洁。固然，这种简洁必然是有代价的，后面文章会进行详细分析。golang

本文首先对节点和页的关系进行整体说明，而后逐一分析四种页的格式及其载入内存后的表示，最后按照 db 的生命周期串一下 db 文件的增加过程以及载入内存的策略。数据库

概述

本文主要涉及到 page.go 和 freelist.go 两个源文件，主要分析了 boltdb 各类 page 在磁盘上的格式和其加载到内存中后的表示。swift

顶层组织

boltdb 的数据组织，自上而下来讲：数组

每一个 db 对应一个文件。缓存
在逻辑上：微信

一个 db 包含多个桶（bucket），至关于多个命名空间（namespace）
每一个桶对应一棵 B+ 树，每一个桶的树根在顶层也组织成一棵树，但不必定是 B+ 树

在物理上：

一个 db 文件是按页为单位进行顺序存储
一个页大小和操做系统的页大小保持一致（一般是 4KB）

页和节点

页分为四种类型：

元信息页：全局有且仅有两个 meta 页，保存在文件；它们是 boltdb 实现事务的关键
空闲列表页：有一种特殊的页，存放空闲页（freelist） id 列表；他们在文件中表现为一段一段的连续的页
两种数据页：剩下的页都是数据页，有两种类型，分别对应 B+ 树中的中间节点和叶子节点

页和节点的关系在于：

页是 db 文件存储的基本单位，节点是 B+ 树的基本构成节点
一个数据节点对应一到多个连续的数据页
连续的数据页序列化加载到内存中就成为一个数据节点

总结一下：在文件系统上线性组织的数据页，经过页内指针，在逻辑上组织成了一棵二维的 B+ 树，该树的树根保存在元信息页中，而文件中全部其余没有用到的页的 id 列表，保存在空闲列表页中。

页格式和内存表示

boltdb 中的页分四种类型：元信息页、空闲列表页、中间节点页和叶子节点页。boltdb 使用常量枚举标记：

const ( branchPageFlag = 0x01 leafPageFlag = 0x02 metaPageFlag = 0x04 freelistPageFlag = 0x10)

每一个页都由定长 header 和数据部分组成：

其中 ptr 指向的是页的数据部分，为了不载入内存和写入文件系统时的序列化和反序列化操做，boltdb 使用了大量的 go unsafe 包中的指针操做。

type pgid uint64type page struct { id pgid flags uint16 // 页类型，值为四种类型之一 count uint16 // 对应的节点包含元素个数，好比说包含的 kv 对 overflow uint32 // 对应节点溢出页的个数，即便用 overflow+1 个页来保存对应节点 ptr uintptr // 指向数据对应的 byte 数组，当 overlay>0 时会跨越多个连续页；不过多个物理也在内存中也只会用一个 page 结构体来表示}

元信息页（metaPage）

boltdb 中有且仅有两个元信息页，保存在 db 文件的开头（pageid = 0 和 1）。可是在元信息页中，ptr 指向的内容并不是元素列表，而是整个 db 的元信息的各个字段。

元信息页加载到内存后数据结构以下：

type meta struct { magic uint32 version uint32 pageSize uint32 // 该 db 页大小，经过 syscall.Getpagesize() 获取，一般为 4k flags uint32 //  root bucket // 各个子 bucket 根所组成的树 freelist pgid // 空闲列表所存储的起始页 id pgid pgid // 当前用到的最大 page id，也即用到 page 的数量 txid txid // 事务版本号，用以实现事务相关 checksum uint64 // 校验和，用于校验 meta 页是否写完整}

空闲列表页（freelistPage）

空闲列表页是 db 文件中一组连续的页（一个或者多个），用于保存在 db 使用过程当中因为修改操做而释放的页的 id 列表。

在内存中表示时分为两部分，一部分是能够分配的空闲页列表 ids，另外一部分是按事务 id 分别记录了在对应事务期间新增的空闲页列表。

// 表示当前已经释放的 page 列表// 和写事务刚释放的 pagetype freelist struct { ids []pgid // all free and available free page ids. pending map[txid][]pgid // mapping of soon-to-be free page ids by tx. cache map[pgid]bool // fast lookup of all free and pending page ids.}

其中 pending 部分须要单独记录主要是为了作 MVCC 的事务：

写事务回滚时，对应事务待释放的空闲页列表要从 pending 项中删除。
某个写事务（好比 txid=7）已经提交，但可能仍有一些读事务（如 txid <=7）仍然在使用其刚释放的页，所以不能当即用做分配。

这部份内容会在 boltdb 事务中详细说明，这里只需有个印象便可。

空闲列表转化为 page

freelist 经过 write 函数，在事务提交时将本身写入给定的页，进行持久化。在写入时，会将 pending 和 ids 合并后写入，这是由于：

write 函数是在写事务提交时调用，写事务是串行的，所以 pending 中对应的写事务都已经提交。
写入文件是为了应对崩溃后重启，而重启时没有任何读操做，天然不用担忧有读事务还在用刚释放的页。

func (f *freelist) write(p *page) error { // 设置页类型 p.flags |= freelistPageFlag
 // page.count 是 uint16 类型，其能表示的范围为 [0, 64k-1] 。若是空闲页 id 列表长度超出了此范围，就须要另想办法。 // 这里用了个 trick，将 page.count 置为 64k 即 0xFFF，而后在数据部分的第一个元素存实际数量（以 pgid 为类型，即 uint64）。 lenids := f.count() if lenids == 0 { p.count = uint16(lenids) } else if lenids < 0xFFFF { p.count = uint16(lenids) // copyall 会将 pending 和 ids 合并并排序 f.copyall(((*[maxAllocSize]pgid)(unsafe.Pointer(&p.ptr)))[:])  } else { p.count = 0xFFFF ((*[maxAllocSize]pgid)(unsafe.Pointer(&p.ptr)))[0] = pgid(lenids) f.copyall(((*[maxAllocSize]pgid)(unsafe.Pointer(&p.ptr)))[1:]) }
 return nil}

注意本步骤只是将 freelist 转化为内存中的页结构，须要额外的操做，好比 tx.write() 才会将对应的页真正持久化到文件。

空闲列表从 page 中加载

在数据库重启时，会首先从前两个元信息页恢复出一个合法的元信息。而后根据元信息中的 freelist 字段，找到存储 freelist 页的起始地址，进而将其恢复到内存中。

func (f *freelist) read(p *page) { // count == 0xFFFF 代表实际 count 存储在 ptr 所指向的内容的第一个元素 idx, count := 0, int(p.count) if count == 0xFFFF { idx = 1 count = int(((*[maxAllocSize]pgid)(unsafe.Pointer(&p.ptr)))[0]) }
 // 将空闲列表从 page 拷贝内存中 freelist 结构体中 if count == 0 { f.ids = nil } else { ids := ((*[maxAllocSize]pgid)(unsafe.Pointer(&p.ptr)))[idx:count] f.ids = make([]pgid, len(ids)) copy(f.ids, ids)
 // 保证 ids 是有序的 sort.Sort(pgids(f.ids)) }
 // 从新构建 freelist.cache 这个 map. f.reindex()}

空闲列表分配

做者原版的空闲列表分配异常简单，分配单位是页，分配策略是首次适应：即从排好序的空闲页列表 ids 中，找到第一段等于指定长度的连续空闲页，而后返回起始页 id。

// 若是能够找到连续 n 个空闲页，则返回起始页 id// 不然返回 0func (f *freelist) allocate(n int) pgid { if len(f.ids) == 0 { return 0 }
 // 遍历寻找连续空闲页，并判断是否等于 n var initial, previd pgid for i, id := range f.ids { if id <= 1 { panic(fmt.Sprintf("invalid page allocation: %d", id)) }
 // 若是不连续，则重置 initial if previd == 0 || id-previd != 1 { initial = id }
 if (id-initial)+1 == pgid(n) { // 当正好分配到 ids 中前 n 个 page 时，仅简单往前调整 f.ids 切片便可。 // 尽管一时会形成空间浪费，可是在对 f.ids append/free 操做时，会按需 // 从新空间分配，从新分配会致使这些浪费空间被回收掉 if (i + 1) == n { f.ids = f.ids[i+1:] } else { copy(f.ids[i-n+1:], f.ids[i+1:]) f.ids = f.ids[:len(f.ids)-n] }
 // 从 cache 中删除对应 page id for i := pgid(0); i < pgid(n); i++ { delete(f.cache, initial+i) }
 return initial }
 previd = id } return 0}

这个 GC 策略至关简单直接，是线性的时间复杂度。阿里彷佛作过一个 patch，将全部空闲 page 按其连续长度 group by 了一下。

叶子节点页（leafPage）

这种页对应某个 Bucket 的 B+ 树中叶子节点，或者顶层 Bucket 树中的叶子节点。

对于前者来讲，页中存储的基本元素为某个 bucket 中一条用户数据。对于后者来讲，页中的一个元素为该 db 中的某个 subbucket 。

// page ptr 指向的字节数组中的单个元素type leafPageElement struct {  flags uint32 // 普通 kv （flags=0）仍是 subbucket（flags=bucketLeafFlag） pos uint16 // kv header 与对应 kv 的距离 ksize uint32 // key 的字节数 vsize uint32 // val 字节数}

其详细结构以下：

能够看出，leaf page 在组织数据时，将元素头（leafPageElement）和元素自己（key value）分开存储。这样的好处在于 leafPageElement 是定长的，能够按下标访问对应元素。在二分查找指定 key 时，只需按需加载相应页到内存（访问 page 时是经过 mmap 进行的，所以只有访问时才会真正将数据从文件系统中加载到内存）便可。

inodes := p.leafPageElements()index := sort.Search(int(p.count), func(i int) bool { return bytes.Compare(inodes[i].key(), key) != -1})

若是元素头和对应元素紧邻存储，则需将 leafPageElement 数组对应的全部页顺序读取，所有加载到内存，才能进行二分。

另一个小优化是 pos 存储的是元素头的起始地址到元素的起始地址的相对偏移量，而非以 ptr 指针为起始地址的绝对偏移量。这样能够用尽可能少的位数（pos 是 uint16）表示尽可能长的距离。

func (n *branchPageElement) key() []byte { buf := (*[maxAllocSize]byte)(unsafe.Pointer(n)) // buf 是元素头起始地址 return (*[maxAllocSize]byte)(unsafe.Pointer(&buf[n.pos]))[:n.ksize]}

中间节点页（branchPage）

中间节点页和叶子节点页的结构大致相同。不一样之处在于，页中保存的数据的 value 是 page id，即该中间节点在哪些 key 上的分支分别指向的 page 。

branchPageElement 中的 key 存的是其指向的页中的起始 key。

转换流程

boltdb 使用 mmap 将 db 文件映射到内存空间。在构建树而且访问过程当中，按需将对应的页加载到内存里，而且利用操做系统的页缓存策略进行替换。

文件增加

当咱们打开一个 db 时，若是发现该 db 文件为空，会在内存中初始化四个页（4*4k=16K），分别是两个元信息页、一个空的空闲列表页和一个空的叶子节点页，而后将其写入 db 文件，而后走正常打开流程。

func (db *DB) init() error { // 设置页大小与操做系统一致 db.pageSize = os.Getpagesize()
 buf := make([]byte, db.pageSize*4) // 在 buffer 中建立两个元信息页. for i := 0; i < 2; i++ { p := db.pageInBuffer(buf[:], pgid(i)) p.id = pgid(i) p.flags = metaPageFlag
 // 初始化元信息页. m := p.meta() m.magic = magic m.version = version m.pageSize = uint32(db.pageSize) m.freelist = 2 m.root = bucket{root: 3} m.pgid = 4 m.txid = txid(i) m.checksum = m.sum64() }
 // 在 pgid=2 的页写入一个空的空闲列表. p := db.pageInBuffer(buf[:], pgid(2)) p.id = pgid(2) p.flags = freelistPageFlag p.count = 0
 // 在 pgid=3 的页写入一个空的叶子元素. p = db.pageInBuffer(buf[:], pgid(3)) p.id = pgid(3) p.flags = leafPageFlag p.count = 0
 // 将 buffer 中的这四个页写入数据文件并刷盘 if _, err := db.ops.writeAt(buf, 0); err != nil { return err } if err := fdatasync(db); err != nil { return err }
 return nil}

随着数据的不断写入，须要申请新的页。boltdb 首先会去 freelist 中找有无可重复利用的页，若是没有，就只能进行 re-mmap（先 mumap 在 mmap），扩大 db 文件。每次扩大会进行倍增（所以从 16K * 2 = 32K 开始），到达 1G 后，再次扩大会每次新增 1G。

func (db *DB) mmapSize(size int) (int, error) { // 从 32KB 开始，直到 1GB. for i := uint(15); i <= 30; i++ { if size <= 1<<i { return 1 << i, nil } }
 // Verify the requested size is not above the maximum allowed. if size > maxMapSize { return 0, fmt.Errorf("mmap too large") }
 // 对齐到 maxMmapStep = 1G sz := int64(size) if remainder := sz % int64(maxMmapStep); remainder > 0 { sz += int64(maxMmapStep) - remainder }
 // 对齐到 db.pageSize pageSize := int64(db.pageSize) if (sz % pageSize) != 0 { sz = ((sz / pageSize) + 1) * pageSize }
 // 不能超过 maxMapSize if sz > maxMapSize { sz = maxMapSize }
 return int(sz), nil}

在 32 位机器上文件最大不能超过 maxMapSize = 2G；在 64 位机器上，文件上限为 256T。

读写流程

在打开一个已经存在的 db 时，会首先将 db 文件映射到内存空间，而后解析元信息页，最后加载空闲列表。

在 db 进行读取时，会按需将访问路径上的 page 加载到内存，并转换为 node，进行缓存。

在 db 进行修改时，使用 COW 原则，全部修改不在原地，而是在改动前先复制一份。若是叶子节点 node 须要修改，则 root bucket 到该 node 路径上所涉及的全部节点都须要修改。这些节点都须要新申请空间，而后持久化，这些和事务的实现息息相关，以后会在本系列事务文章中作详细说明。

小结

boltdb 在数据组织方面只使用了两个概念：页（page）和节点（node）。每一个数据库对应一个文件，每一个文件中包含一系列线性组织的页。页的大小固定，依其性质不一样，分为四种类型：元信息页、空闲列表页、叶子节点页、中间节点页。打开数据库时，会渐次进行如下操做：

利用 mmap 将数据库文件映射到内存空间。
解析元信息页，获取空闲列表页 id 和 bucket 树页 id。
依据空闲列表页 id ，将全部空闲页列表载入内存。
依据 bucket 树起始地址，解析 bucket 树根节点。
根据读写需求，从树根开始遍历，按需将访问路径上的数据页（中间节点页和叶子节点页）载入内存成为节点（node）。

能够看出，节点分两种类型：中间节点（branch node）和叶子节点（leaf node）。

另外须要注意的是，多个子 Bucket 树和 Bucket 对应的 B+ 树复用了 bucket 这个数据结构，致使这一块稍微有点很差理解。在下一篇 boltdb 的索引设计中，将详细剖析 boltdb 是如何组织多个 bucket 以及单个 bucket 内的 B+ 树索引的。

参考

github，boltdb repo
我叫尤加利，boltdb 源码分析

不妨一读

漫谈 LevelDB 数据结构（二）：布隆过滤利器

golang Context 源码剖析

扫描二维码

获取更多文章

分布式点滴

本文分享自微信公众号 - 分布式点滴（distributed-system）。
若有侵权，请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”，欢迎正在阅读的你也加入，一块儿分享。