From 8ad59edd02a8ea6001f15cd6d92944ae83c88f6d Mon Sep 17 00:00:00 2001 From: Ben Johnson Date: Wed, 12 Feb 2014 14:57:27 -0700 Subject: API Documentation. --- doc.go | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) (limited to 'doc.go') diff --git a/doc.go b/doc.go index ea75951..d7f3ec1 100644 --- a/doc.go +++ b/doc.go @@ -1,3 +1,39 @@ -package bolt +/* +Package bolt implements a low-level key/value store in pure Go. It supports +fully serializable transactions, ACID semantics, and lock-free MVCC with +multiple readers and a single writer. Bolt can be used for projects that +want a simple data store without the need to add large dependencies such as +Postgres or MySQL. + +Bolt is a single-level, zero-copy, B+tree data store. This means that Bolt is +optimized for fast read access and does not require recovery in the event of a +system crash. Transactions which have not finished committing will simply be +rolled back in the event of a crash. + +The design of Bolt is based on Howard Chu's LMDB database project. + +Basics + +There are only a few types in Bolt: DB, Bucket, Transaction, RWTransaction, and +Cursor. The DB is a collection of buckets and is represented by a single file +on disk. A bucket is a collection of unique keys that are associated with values. + +Transactions provide read-only access to data inside the database. They can +retrieve key/value pairs and can use Cursors to iterate over the entire dataset. +RWTransactions provide read-write access to the database. They can create and +delete buckets and they can insert and remove keys. Only one RWTransaction is +allowed at a time. -// TODO(benbjohnson) + +Caveats + +The database uses a read-only, memory-mapped data file to ensure that +applications cannot corrupt the database, however, this means that keys and +values returned from Bolt cannot be changed. Writing to a read-only byte slice +will cause Go to panic. If you need to work with data returned from a Get() you +need to first copy it to a new byte slice. + +Bolt currently works on Mac OS and Linux. Windows support is coming soon. + +*/ +package bolt -- cgit v1.2.3