blob: 95f25f01c6a48f0a0ee87fba989c828442b8e590 [file] [log] [blame]
khenaidoo59ce9dd2019-11-11 13:05:32 -05001/*
2package bbolt implements a low-level key/value store in pure Go. It supports
3fully serializable transactions, ACID semantics, and lock-free MVCC with
4multiple readers and a single writer. Bolt can be used for projects that
5want a simple data store without the need to add large dependencies such as
6Postgres or MySQL.
7
8Bolt is a single-level, zero-copy, B+tree data store. This means that Bolt is
9optimized for fast read access and does not require recovery in the event of a
10system crash. Transactions which have not finished committing will simply be
11rolled back in the event of a crash.
12
13The design of Bolt is based on Howard Chu's LMDB database project.
14
15Bolt currently works on Windows, Mac OS X, and Linux.
16
17
18Basics
19
20There are only a few types in Bolt: DB, Bucket, Tx, and Cursor. The DB is
21a collection of buckets and is represented by a single file on disk. A bucket is
22a collection of unique keys that are associated with values.
23
24Transactions provide either read-only or read-write access to the database.
25Read-only transactions can retrieve key/value pairs and can use Cursors to
26iterate over the dataset sequentially. Read-write transactions can create and
27delete buckets and can insert and remove keys. Only one read-write transaction
28is allowed at a time.
29
30
31Caveats
32
33The database uses a read-only, memory-mapped data file to ensure that
34applications cannot corrupt the database, however, this means that keys and
35values returned from Bolt cannot be changed. Writing to a read-only byte slice
36will cause Go to panic.
37
38Keys and values retrieved from the database are only valid for the life of
39the transaction. When used outside the transaction, these byte slices can
40point to different data or can point to invalid memory which will cause a panic.
41
42
43*/
44package bbolt