diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 158 |
1 files changed, 0 insertions, 158 deletions
@@ -42,147 +42,6 @@ There are also several differences between Bolt and LMDB: 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](http://golang.org/pkg/testing/quick/) package. -## API - -### Database - -The database is the object that represents your data as a whole -It is split up into buckets which is analogous to tables in a relational database. - -#### Opening and closing a database - -```go -db := DB() -err := db.Open("/path/to/db", 0666) -... -err := db.Close() -``` - - -### Transactions - -Versioning of data in the bucket data happens through a Transaction. -These transactions can be either be read-only or read/write transactions. -Transactions are what keeps Bolt consistent and allows data to be rolled back if needed. - -It may seem strange that read-only access needs to be wrapped in a transaction but this is so Bolt can keep track of what version of the data is currently in use. -The space used to hold data is kept until the transaction closes. - -One important note is that long running transactions can cause the database to grow in size quickly. -Please double check that you are appropriately closing all transactions after you're done with them. - -#### Creating and closing a read-only transaction - -```go -t, err := db.Transaction() -t.Close() -``` - -#### Creating and committing a read/write transaction - -``` -t, err := db.RWTransaction() -err := t.Commit() -``` - -#### Creating and aborting a read/write transaction - -``` -t, err := db.RWTransaction() -err := t.Abort() -``` - - -### Buckets - -Buckets are where your actual key/value data gets stored. -You can create new buckets from the database and look them up by name. - -#### Creating a bucket - -```go -t, err := db.RWTransaction() -err := t.CreateBucket("widgets") -``` - -#### Renaming a bucket - -```go -t, err := db.RWTransaction() -err := t.RenameBucket("widgets", "woojits") -``` - -#### Deleting a bucket - -```go -t, err := db.RWTransaction() -err := t.DeleteBucket("widgets") -``` - -#### Retrieve an existing bucket - -```go -t, err := db.Transaction() -b, err := t.Bucket("widgets") -``` - -#### Retrieve a list of all buckets - -```go -t, err := db.Transaction() -buckets, err := db.Buckets() -``` - - -### Key/Value Access - -#### Retrieve a value for a specific key - -```go -t, err := db.Transaction() -value, err := t.Get("widgets", []byte("foo")) -value, err := t.GetString("widgets", "foo") -``` - -#### Set the value for a key - -```go -t, err := db.RWTransaction() -err := t.Put("widgets", []byte("foo"), []byte("bar")) -err := t.PutString("widgets", "foo", "bar") -``` - -#### Delete a given key - -```go -t, err := db.RWTransaction() -err := t.Delete("widgets", []byte("foo")) -err := t.DeleteString("widgets", "foo") -``` - - -### Cursors - -Cursors provide fast read-only access to a specific bucket within a transaction. - - -#### Creating a read-only cursor - -```go -t, err := db.Transaction() -c, err := b.Cursor("widgets") -``` - -#### Iterating over a cursor - -```go -for k, v, err := c.First(); k != nil; k, v, err = c.Next() { - if err != nil { - return err - } - ... DO SOMETHING ... -} -``` ## Internals @@ -213,20 +72,3 @@ There are several different types of pages: * Overflow pages - These are special pages used when a key's data is too large for a leaf page and needs to spill onto additional pages. - -### Nodes - -Within each page there are one or more elements called nodes. -In branch pages, these nodes store references to other child pages in the tree. -In leaf pages, these nodes store the actual key/value data. - - -## TODO - -The following is a list of items to do on the Bolt project: - -1. Calculate freelist on db.Open(). (Traverse branches, set bitmap index, load free pages into a list -- lazy load in the future). -2. Resize map. (Make sure there are no reader txns before resizing) -3. DB.Copy() -4. Merge pages. -5. Rebalance (after deletion). |