BoltDB — Embedded Key-Value Database for Go

Introduction

BoltDB is an embedded key/value database written in pure Go, inspired by LMDB. It provides a simple, fast, and reliable data store for projects that need a lightweight persistence layer without running a separate database server.

What BoltDB Does

• Stores key/value pairs in named buckets within a single file
• Provides fully serializable ACID transactions
• Uses memory-mapped files for fast read performance
• Supports nested buckets for hierarchical data organization
• Offers byte-slice keys with range scans via B+ tree cursors

Architecture Overview

BoltDB uses a single-file, copy-on-write B+ tree design backed by memory-mapped I/O. Write transactions acquire an exclusive lock, serialize changes to new pages, and atomically update the file metadata pointer. Read transactions operate on a stable snapshot with zero-copy access through the mmap, making concurrent reads extremely efficient.

Self-Hosting & Configuration

• Import the actively maintained fork at go.etcd.io/bbolt
• Open a database file with configurable file permissions and timeout options
• No external dependencies or server processes required
• Tune page size and mmap settings for workload-specific performance
• Back up a live database using the Tx.WriteTo method for consistent snapshots

Key Features

• Pure Go with zero CGo dependencies for easy cross-compilation
• Single-file storage simplifies deployment and backup
• Read transactions never block each other via MVCC snapshots
• Cursor API supports prefix scans, range queries, and iteration
• Battle-tested as the storage engine behind etcd, Consul, and InfluxDB

Comparison with Similar Tools

• BadgerDB — LSM-tree design optimized for write-heavy workloads; BoltDB uses B+ trees favoring read-heavy patterns
• SQLite — full relational SQL engine; BoltDB is a simpler key/value store with no query language
• LMDB — C library with similar mmap design; BoltDB is pure Go with a more idiomatic API
• Pebble — LSM engine by CockroachDB for high-throughput writes; BoltDB targets simpler embedded use cases

FAQ

Q: Is BoltDB still maintained? A: The original boltdb/bolt repository is archived. The etcd team maintains an active fork at go.etcd.io/bbolt with ongoing improvements.

Q: Can multiple processes access the same database file? A: No, BoltDB uses file locking for single-process access. Multiple goroutines within one process can read concurrently.

Q: How large can a BoltDB database grow? A: The database is limited by available disk space and address space for mmap. Multi-gigabyte databases work well on 64-bit systems.

Q: Is it suitable for write-heavy workloads? A: BoltDB excels at read-heavy patterns. For write-intensive use cases, consider an LSM-based store like BadgerDB or Pebble.

Sources

• https://github.com/boltdb/bolt
• https://github.com/etcd-io/bbolt