An embedded key/value database for Go.

Go to file

Ben Johnson 3cc959fb1a Remove ease-of-use functions from the DB type. Functions such as DB.Put(), DB.Get(), and DB.Delete() were originally added to be easy to use, however, after implementing Bolt in multiple projects I have found these ease-of-use functions useless. Nearly every use case requires multiple calls in a single transaction. Using the DB ease of use functions turned out to be an antipattern.		2014-03-21 09:52:01 -06:00
.gitignore	Add benchmarks.	2014-03-04 13:23:46 -07:00
LICENSE	Initial commit	2013-12-20 10:26:14 -08:00
Makefile	Add benchmarks.	2014-03-04 13:23:46 -07:00
NOTES	Add RWTransaction.Put().	2014-02-01 12:30:37 -05:00
README.md	README	2014-03-10 15:03:26 -07:00
bolt.go	Minor refactor.	2014-02-28 15:13:07 -07:00
bucket.go	Merge pull request #65 from benbjohnson/fix-tx-buckets-sort-order	2014-03-21 08:45:34 -06:00
bucket_test.go	Remove ease-of-use functions from the DB type.	2014-03-21 09:52:01 -06:00
buckets.go	Add parallel usage test and race detector.	2014-02-15 21:50:34 -07:00
buckets_test.go	Rename sys ☞ buckets.	2014-02-05 22:15:47 -07:00
const.go	Check for sequence overflow.	2014-02-20 09:24:02 -07:00
cursor.go	Fix Cursor.Last() on empty buckets.	2014-03-13 14:39:28 -06:00
db.go	Remove ease-of-use functions from the DB type.	2014-03-21 09:52:01 -06:00
db_test.go	Remove ease-of-use functions from the DB type.	2014-03-21 09:52:01 -06:00
doc.go	Consolidate Tx and RWTx.	2014-03-08 20:40:48 -07:00
error.go	Consolidate Tx and RWTx.	2014-03-08 20:40:48 -07:00
error_test.go	Add freelist.	2014-02-10 14:04:01 -07:00
example_test.go	Remove ease-of-use functions from the DB type.	2014-03-21 09:52:01 -06:00
freelist.go	Rename Transaction to Tx.	2014-03-08 17:04:02 -07:00
freelist_test.go	Rename Transaction to Tx.	2014-03-08 17:04:02 -07:00
functional_test.go	Remove ease-of-use functions from the DB type.	2014-03-21 09:52:01 -06:00
meta.go	Consolidate Tx and RWTx.	2014-03-08 20:40:48 -07:00
meta_test.go	Rename errors.	2014-02-16 12:18:44 -07:00
node.go	Consolidate Tx and RWTx.	2014-03-08 20:40:48 -07:00
node_test.go	API Documentation.	2014-02-13 10:58:27 -07:00
os.go	Add freelist.	2014-02-10 14:04:01 -07:00
os_test.go	Intermediate.	2014-01-27 10:11:54 -05:00
page.go	Allow reads of unflushed nodes.	2014-03-01 09:13:59 -07:00
page_test.go	API Documentation.	2014-02-13 10:58:27 -07:00
quick_test.go	Minor refactor.	2014-02-28 15:13:07 -07:00
syscall_darwin.go	Mmap remap.	2014-02-12 11:49:57 -07:00
syscall_darwin_test.go	Mmap remap.	2014-02-12 11:49:57 -07:00
syscall_linux.go	Mmap remap.	2014-02-12 11:49:57 -07:00
syscall_linux_test.go	Mmap remap.	2014-02-12 11:49:57 -07:00
tx.go	Fix Tx.Buckets() sort order.	2014-03-13 15:08:59 -06:00
tx_test.go	Remove ease-of-use functions from the DB type.	2014-03-21 09:52:01 -06:00

README.md

Bolt

Overview

Bolt is a pure Go key/value store inspired by Howard Chu and the LMDB project. The goal of the project is to provide a simple, fast, and reliable database for projects that don't require a full database server such as Postgres or MySQL. It is also meant to be educational. Most of us use tools without understanding how the underlying data really works.

Since Bolt is meant to be used as such a low-level piece of functionality, simplicity is key. The API will be small and only center around getting values and setting values. That's it. If you want to see additional functionality added then we encourage you submit a Github issue and we can discuss developing it as a separate fork.

Simple is the new beautiful.

— Tobias Lütke

Project Status

Bolt is functionally complete and has nearly full unit test coverage. The library test suite also includes randomized black box testing to ensure database consistency and thread safety. Bolt is currently in use in a few project, however, it is still at a beta stage so please use with caution and report any bugs found.

Comparing Bolt vs LMDB

Bolt is inspired by LMDB so there are many similarities between the two:

Both use a B+Tree data structure.
ACID semantics with fully serializable transactions.
Lock-free MVCC support using a single writer and multiple readers.

There are also several differences between Bolt and LMDB:

LMDB supports more additional features such as multi-value keys, fixed length keys, multi-key insert, and direct writes. Bolt only supports basic Get(), Put(), and Delete() operations and bidirectional cursors.
LMDB databases can be shared between processes. Bolt only allows a single process access.
LMDB is written in C and extremely fast. Bolt is fast but not as fast as LMDB.
LMDB is a more mature library and is used heavily in projects such as OpenLDAP.

So why use Bolt? The goal of Bolt is provide a simple, fast data store that is easily integrated into Go projects. The library does not require CGO so it is compatible with go get and you can easily build static binaries with it. We are not accepting additional functionality into the library so the API and file format are stable. Bolt also has near 100% unit test coverage and also includes heavy black box testing using the testing/quick package.

Internals

The Bolt database is meant to be a clean, readable implementation of a fast single-level key/value data store. This section gives an overview of the basic concepts and structure of the file format.

B+ Tree

Bolt uses a data structure called an append-only B+ tree to store its data. This structure allows for efficient traversal of data.

TODO: Explain better. :)