Overview 概述

Relevant source files 相关源文件

The following files were used as context for generating this wiki page:

bbolt is a pure Go key/value store that provides a simple, fast, and reliable embedded database solution.
bbolt 是一个纯 Go 键/值存储，提供简单、快速且可靠的嵌入式数据库解决方案。
Originally forked from Ben Johnson's Bolt, bbolt is maintained by the etcd-io organization to deliver improved reliability, stability, and additional features while preserving backward compatibility with the original Bolt API.
最初从 Ben Johnson 的 Bolt 分支而来，bbolt 由 etcd-io 组织维护，以提供改进的可靠性、稳定性和额外功能，同时保持与原始 Bolt API 的向后兼容性。

This page introduces the fundamental concepts of bbolt, its architecture, and key design principles. For more detailed information about specific components, refer to their dedicated wiki pages in the Core Components section.
本页介绍 bbolt 的基本概念、架构和关键设计原则。有关特定组件的更详细信息，请参阅核心组件部分的专用 wiki 页面。

What is bbolt? 什么是 bbolt？

bbolt is an embedded key-value store inspired by Howard Chu's LMDB project. It's designed for projects that need a reliable database but don't require a full database server like PostgreSQL or MySQL.
bbolt 是一个受 Howard Chu 的 LMDB 项目启发的嵌入式键值存储。它专为需要可靠数据库但不需要像 PostgreSQL 或 MySQL 这样完整的数据库服务器的项目而设计。
As a pure Go implementation, it offers seamless integration with Go applications without external dependencies.
作为一个纯 Go 实现，它能无缝集成到 Go 应用程序中，无需外部依赖。

Key characteristics of bbolt include:
bbolt 的主要特点包括：

Single file storage with a memory-mapped approach
使用内存映射方法的单文件存储
ACID-compliant transactions
支持 ACID 事务
B+tree data structure for efficient storage and retrieval
用于高效存储和检索的 B+树数据结构
Concurrent read access with serialized writes
并发读取，串行写入
Nested data organization using buckets
使用存储桶进行嵌套数据组织

Sources: README.md15-23 README.md9-13
源码：README.md15-23README.md9-13

Core Components 核心组件

bbolt has four primary components that work together to provide database functionality:
bbolt 有四个主要组件协同工作以提供数据库功能：

DB: The database handler that represents a bbolt database file on disk. It manages access to the database file and coordinates transactions.
数据库：表示磁盘上的 bbolt 数据库文件的数据库处理程序。它管理对数据库文件的访问并协调事务。
Tx: A transaction that provides a consistent view of the database at a point in time. Transactions can be read-only or read-write.
事务：在某一时间点提供数据库一致性视图的事务。事务可以是只读或读写。
Bucket: A collection of key/value pairs within the database, similar to a table in a relational database. Buckets can be nested to create a hierarchical data structure.
Bucket（桶）：数据库中键/值对的集合，类似于关系型数据库中的表。桶可以嵌套以创建分层数据结构。
Cursor: An iterator for traversing and querying data within a bucket.
游标：用于在桶中遍历和查询数据的迭代器。

Sources: db.go35-157 tx.go19-27 README.md116-117
源文件：db.go35-157tx.go19-27README.md116-117

Transaction Model 事务模型

bbolt employs a transaction model that ensures data consistency and ACID compliance:
bbolt 采用了确保数据一致性和 ACID 合规性的事务模型：

The transaction model has several important characteristics:
事务模型具有以下几个重要特征：

Serialized writes: Only one read-write transaction can be active at a time, ensuring data consistency
序列化写入：同一时间只能有一个读写事务处于活动状态，确保数据一致性
Concurrent reads: Multiple read-only transactions can run concurrently
并发读取：多个只读事务可以并发运行
Snapshot isolation: Each transaction sees a consistent view of the database as it existed when the transaction started
快照隔离：每个事务都看到数据库在事务开始时存在的一致性视图
Resource management: Transactions must be committed or rolled back to release resources
资源管理：事务必须提交或回滚以释放资源

bbolt provides two patterns for working with transactions:
bbolt 提供了两种事务处理模式：

Managed transactions: Using DB.Update() for read-write operations and DB.View() for read-only operations
托管事务：使用 DB.Update() 进行读写操作和 DB.View() 进行只读操作
Manual transactions: Using DB.Begin() with explicit commit or rollback
手动事务：使用 DB.Begin() 并显式提交或回滚

Sources: README.md154-162 db.go726-947 tx.go167-183 tx.go300-309
源代码：README.md154-162db.go726-947tx.go167-183tx.go300-309

Internal Storage Architecture 内部存储架构

bbolt uses a B+tree data structure to store and organize data efficiently:
bbolt 使用 B+树数据结构高效地存储和组织数据：

Meta Pages: The database contains two meta pages (for redundancy) that store metadata about the database, including the root bucket and freelist location.
元数据页：数据库包含两个元数据页（用于冗余），存储关于数据库的元数据，包括根桶和空闲列表的位置。
Freelist: Tracks pages that have been freed and can be reused for new data.
空闲列表：跟踪已被释放并可重用于新数据的页面。
B+tree Structure: Data is organized in a B+tree with branch pages containing pointers to other pages and leaf pages containing the actual key/value data.
B+树结构：数据在 B+树中组织，分支页面包含指向其他页面的指针，叶子页面包含实际的键/值数据。
Page Types: 页面类型：
- Meta pages: Store database metadata
  元数据页面：存储数据库元数据
- Branch pages: Internal B+tree nodes with pointers to child pages
  分支页面：包含指向子页面指针的内部 B+树节点
- Leaf pages: Store key/value pairs
  叶子页面：存储键/值对
- Freelist pages: Track unused pages
  空闲列表页面：跟踪未使用的页面

bbolt memory-maps the database file, allowing the operating system to handle caching and paging, which provides efficient performance for both small and large databases.
bbolt 对数据库文件进行内存映射，允许操作系统处理缓存和分页，这为小型和大型数据库提供了高效的性能。

Sources: db.go514-517 db.go446-452 db.init621-665
源代码：db.go514-517 db.go446-452 db.init621-665

Key Design Features 关键设计特征

bbolt's design is guided by several core principles:
bbolt 的设计遵循几个核心原则：

1. Simplicity 1. 简单性

bbolt intentionally provides a minimal API that focuses on the essential operations of a key/value store. This simplicity makes it easy to learn and use while reducing the potential for bugs and complexity.
bbolt 故意提供了一个最小的 API，专注于键/值存储的基本操作。这种简单性使其易于学习和使用，同时降低了出现错误和复杂性的可能性。

2. ACID Transactions 2. ACID 事务

All operations in bbolt are performed within transactions, ensuring Atomicity, Consistency, Isolation, and Durability. This makes bbolt suitable for applications that require data reliability.
bbolt 中的所有操作都在事务中执行，确保原子性、一致性、隔离性和持久性。这使得 bbolt 适用于需要数据可靠性的应用程序。

3. Single File Storage 3. 单文件存储

The entire database is stored in a single file on disk, making it easy to deploy, back up, and manage.
整个数据库存储在磁盘上的单个文件中，使部署、备份和管理变得简单。

4. Memory-Mapped Access 4. 内存映射访问

bbolt uses memory mapping (mmap) to access the database file, providing efficient performance by leveraging the operating system's virtual memory and caching capabilities.
bbolt 使用内存映射（mmap）访问数据库文件，通过利用操作系统的虚拟内存和缓存功能提供高效的性能。

5. No External Dependencies 5. 无外部依赖

As a pure Go implementation, bbolt has no external dependencies, making it lightweight and portable.
作为一个纯 Go 语言实现，bbolt 没有外部依赖，使其轻量且可移植。

Sources: README.md20-22 README.md837-887
来源：README.md20-22README.md837-887

Getting Started with bbolt bbolt 入门

The most common operations in bbolt involve:
bbolt 中最常见的操作包括：

Opening a database: 打开数据库：

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

Performing transactions: 执行事务：

// Read-write transaction
err = db.Update(func(tx *bolt.Tx) error {
    b, err := tx.CreateBucketIfNotExists([]byte("MyBucket"))
    if err != nil {
        return err
    }
    return b.Put([]byte("key"), []byte("value"))
})

// Read-only transaction
err = db.View(func(tx *bolt.Tx) error {
    b := tx.Bucket([]byte("MyBucket"))
    v := b.Get([]byte("key"))
    fmt.Printf("Value: %s\n", v)
    return nil
})

Working with buckets: 处理存储桶：

err = db.Update(func(tx *bolt.Tx) error {
    // Create a bucket
    b, err := tx.CreateBucketIfNotExists([]byte("MyBucket"))
    if err != nil {
        return err
    }
    
    // Create a nested bucket
    nested, err := b.CreateBucketIfNotExists([]byte("NestedBucket"))
    if err != nil {
        return err
    }
    
    return nil
})

Using cursors for iteration:
使用游标进行迭代：

err = db.View(func(tx *bolt.Tx) error {
    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
})

Sources: README.md118-140 README.md172-189 README.md284-317 README.md421-439
来源：README.md118-140README.md172-189README.md284-317README.md421-439

Performance Considerations 性能考虑

When using bbolt, consider these performance aspects:
使用 bbolt 时，请考虑以下性能方面：

Read vs. Write Performance: bbolt is optimized for read performance. Sequential write performance is good, but random writes can be slower.
读取与写入性能：bbolt 针对读取性能进行了优化。连续写入性能较好，但随机写入可能较慢。
Transaction Management: Long-running read transactions prevent old pages from being reclaimed, potentially increasing database size. Close transactions promptly.
事务管理：长时间运行的读取事务会阻止旧页面被回收，可能会增加数据库大小。请及时关闭事务。
Batch Operations: For better write performance with many small updates, use DB.Batch() to batch multiple write operations.
批量操作：为了在进行多个小更新时获得更好的写入性能，请使用 DB.Batch() 来批量执行多个写入操作。
Memory Usage: bbolt uses memory-mapped files, so the OS handles caching. This can show high memory usage for large databases, but the OS will manage this efficiently.
内存使用：bbolt 使用内存映射文件，因此操作系统处理缓存。对于大型数据库，可能会显示高内存使用，但操作系统将有效地管理这一情况。
SSD vs. HDD: bbolt performs significantly better on SSDs due to its B+tree structure, which involves random page access.
SSD 与 HDD 比较：由于其 B+树结构涉及随机页面访问，bbolt 在 SSD 上的性能显著更好。

Sources: README.md842-887
来源：README.md842-887

Usage Notes and Limitations 使用说明和限制

Some important considerations when using bbolt:
使用 bbolt 时的一些重要注意事项：

Exclusive Access: bbolt uses file locking to ensure only one process can open the database in write mode at a time.
独占访问：bbolt 使用文件锁定来确保同一时间只有一个进程可以以写入模式打开数据库。
Byte Slices: Keys and values returned from bbolt are only valid during the transaction. Copy them if you need to use them after the transaction closes.
字节切片：从 bbolt 返回的键和值仅在事务期间有效。如果需要在事务关闭后使用它们，请复制它们。
Database Size: bbolt can handle databases much larger than available RAM, but operations might slow down when the working set exceeds available memory.
数据库大小：bbolt 可以处理比可用 RAM 大得多的数据库，但是当工作集超过可用内存时，操作可能会变慢。
Endianness: Database files are not portable between architectures with different endianness (though most modern CPUs are little-endian).
字节序：数据库文件不能在具有不同字节序的体系架构之间移植（尽管大多数现代 CPU 都是小端序）。
Bucket Organization: Carefully design your bucket structure; improper organization can lead to poor performance.
桶组织：仔细设计你的桶结构；不当的组织可能导致性能低下。

Sources: README.md142-146 README.md852-865 README.md873-879
源码：README.md142-146README.md852-865README.md873-879