Joins

Not Supported

Data Model

Key/Value

Bolt is a key-value store that provides an ordered map, which allows easy access and lookup. All collections of key/value pairs are stored in buckets, and all keys in a bucket must be unique. The keys are stored in byte-sorted order within a bucket.

A bucket can be created with Tx.CreateBucket or Tx.CreateBucketIfNotEXists so that it can be created only if it doesn't exist.

System Architecture

Embedded

Storage Organization

Copy-on-Write / Shadow Paging

BoltDB saves data into a single memory-mapped file on disk. Write-ahead log is not necessary since BoltDB only deals with one file at a time. With copy-on-write, when writing to a page, BoltDB makes updates on the copy of the original page and updates the pointer to point at the new page upon commit.

Query Interface

Custom API

BoltDB supports basic key/value queries such as insert, delete and update with its own APIs. All bucket operations are organized and monitored by transactions Tx. For example, Tx.CreateBucket creates a bucket, and Tx.DeleteBucket removes a bucket. All basic key/value queries are performed on bucket using Bucket.Put, Bucket.Get, and Bucket.Delete.

Since BoltDB stores its key in byte-sorted order within a bucket, it supports sequential iteration over a bucket with Bucket.Cursor. The Cursor allows moving to the first key (First), the last key (Last), the previous key (Prev), the next key (Next), and a specific key (Seek) in a bucket.

Prefix scan is supported by combining Seek and bytes.HasPrefix. Range scan is supported by combing Seek and bytes.Compare.

Besides Bucket.Cursor, Bucket.ForEach also supports iterating over all key/value pairs in a bucket.

Checkpoints

Not Supported

Logging

Not Supported

Bolt saves data into a single memory-mapped file on disk. It doesn’t have a separate journal or write-ahead log.

Isolation Levels

Serializable

BoltDB supports fully serializable ACID transactions. It allows only one read-write transaction at a time but allows as many read-only transactions as requested.

When opening a database with bolt.Open, BoltDB obtains a file lock on the data file so multiple processes cannot open the same database at the same time. Opening an already open Bolt database will cause it to hang until the other process closes it. BoltDB supports the ability to prevent an indefinite wait by passing a timeout option to the Open function.

Views

Virtual Views

Bolt allows only one read-write transaction at a time but allows as many read-only transactions as requested. Each transaction has a consistent view of the data as it existed when the transaction started. BoltDB recommends three types of transactions: read-write transactions with DB.Update, read-only transactions with DB.View and batch read-write transactions with DB.Batch. Along with the three recommended transactions, BoltDB also allows manual transaction management with DB.Begin.

Storage Architecture

Hybrid

There are only a few types in BoltDB: DB, Bucket, Tx, and Cursor.

• The DB is a single file represented by pages on disk. Each page is commonly 4096 Bytes. The first two pages of the file store the metadata that keeps track of version, transaction id, and page size of the database, as well as the locations of the freelist and the first page id of data. The third page stores a freelistthat keeps track the page id's of the free pages. The rest of the pages are the collection of buckets that store the key/value paris.

• A Bucket is a collection of unique keys that are associated with values. Each bucket is represented using a B+ tree. When accessing a B+ tree, the nodes in the corresponding page are fetched into memory. The B+ tree used in BoltDB is different from common B+tree in the following aspects:

  • While B+ trees typically have n+1 values and n keys in each node, the number of values and the number of keys are equal in BoltDB B+ tree.
  • In BoltDB B+ tree, the value field in a non-leaf node stores the page id of its child node and the corresponding key stores the first key in the child node.
  • There are no pointers between sibling leaf nodes in BoltDB B+ tree.

Foreign Keys

Not Supported

Concurrency Control

Multi-version Concurrency Control (MVCC)

BoltDB supports lock-free MVCC using a single writer and multiple readers. It allows only one read-write transaction at a time but allows multiple read-only transactions at the same time. Read-only transactions and read-write transactions should not depend on one another and generally shouldn't be opened simultaneously in the same goroutine. This can cause a deadlock as the read-write transaction needs to periodically re-map the data file but it cannot do so while a read-only transaction is open.

Indexes

B+Tree

BoltDB stores key/value pairs in a B+ tree.

Storage Model

Custom

BoltDB uses key/value storage, which does not involve rows or columns.