# bbolt — Embedded Key-Value Database for Go Applications

> A pure Go embedded key-value store forked from BoltDB that provides ACID transactions, B+ tree indexing, and memory-mapped I/O for reliable local storage in Go applications.

## Install

Save as a script file and run:

# bbolt — Embedded Key-Value Database for Go Applications

## Quick Use
```go
package main

import (
    "fmt"
    "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()

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

    db.View(func(tx *bolt.Tx) error {
        v := tx.Bucket([]byte("users")).Get([]byte("alice"))
        fmt.Printf("alice = %s
", v)
        return nil
    })
}
```

## Introduction
bbolt is the actively maintained fork of BoltDB, the embedded key-value store that powers etcd, Consul, and many other Go infrastructure projects. It stores data in a single memory-mapped file with full ACID transaction support, making it ideal for applications that need reliable local storage without the complexity of a client-server database. The etcd team adopted and maintains bbolt to ensure long-term stability for the Kubernetes ecosystem.

## What bbolt Does
- Provides ACID-compliant read-write transactions with serializable isolation
- Stores data in nested buckets (namespaces) using a B+ tree on disk
- Uses memory-mapped I/O for fast reads without deserialization overhead
- Supports concurrent readers with a single writer using MVCC snapshots
- Ships as a pure Go library with zero CGo dependencies

## Architecture Overview
bbolt uses a single file as its data store, memory-mapped into the process address space. The B+ tree structure organizes keys within buckets, and a copy-on-write strategy ensures that readers see a consistent snapshot while a writer modifies pages. Completed transactions are fsynced to disk before returning, guaranteeing durability. The file format is platform-independent and can be copied between systems.

## Self-Hosting & Configuration
- Import `go.etcd.io/bbolt` as a Go module dependency
- Open a database file with configurable file permissions and timeout
- Set `Options.NoSync` to skip fsync for faster writes in non-critical scenarios
- Use `Options.ReadOnly` to open databases in read-only mode for analytics
- Run `bbolt` CLI tool for database inspection, compaction, and statistics

## Key Features
- Zero external dependencies; embeds directly into any Go binary
- Single-file database that is easy to back up with a simple file copy
- Read transactions never block each other, enabling high read concurrency
- Nested buckets provide namespace organization without separate databases
- Stable on-disk format maintained across versions for long-term compatibility

## Comparison with Similar Tools
- **BadgerDB** — LSM-tree based with separate value log; bbolt uses B+ tree with simpler guarantees
- **LevelDB/RocksDB** — C/C++ with CGo bindings; bbolt is pure Go with no CGo overhead
- **SQLite** — full SQL engine; bbolt is a lower-level key-value store with less overhead
- **Pebble** — CockroachDB's LSM store; bbolt is simpler and better suited for metadata workloads
- **LMDB** — C library with similar MVCC design; bbolt is native Go and easier to embed

## FAQ
**Q: What is the relationship between BoltDB and bbolt?**
A: BoltDB was archived by its original author. The etcd team forked it as bbolt and continues to maintain it with bug fixes and performance improvements.

**Q: Can multiple processes access the same database file?**
A: No. bbolt uses a file lock to ensure only one process opens the database at a time. Multiple goroutines within a single process can share a connection safely.

**Q: How large can a bbolt database grow?**
A: bbolt supports databases up to 256 TB. Practical limits depend on available disk space and the operating system's mmap capabilities.

**Q: Is bbolt suitable for write-heavy workloads?**
A: bbolt serializes writes through a single writer, so it is best for read-heavy or moderate-write workloads. For high write throughput, consider an LSM-based engine like BadgerDB.

## Sources
- https://github.com/etcd-io/bbolt
- https://pkg.go.dev/go.etcd.io/bbolt

---
Source: https://tokrepo.com/en/workflows/db26d251-3d5a-11f1-9bc6-00163e2b0d79
Author: Script Depot