# BoltDB — Embedded Key-Value Database for Go

> A pure Go embedded key/value store with ACID transactions, memory-mapped I/O, and B+ tree indexing for reliable single-process data storage.

## Install

Save in your project root:

# BoltDB — Embedded Key-Value Database for Go

## Quick Use
```go
import "go.etcd.io/bbolt"

db, _ := bbolt.Open("my.db", 0600, nil)
defer db.Close()

db.Update(func(tx *bbolt.Tx) error {
    b, _ := tx.CreateBucketIfNotExists([]byte("users"))
    return b.Put([]byte("alice"), []byte("admin"))
})
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-a36dda4b
Author: AI Open Source