xref: /6.0.3/forestdb/README.md (revision 4708a267)
17741bce9SChiyoung Seo# ForestDB
27741bce9SChiyoung Seo
336f7345aSChiyoung SeoForestDB is a key-value storage engine that is developed by Couchbase Caching and Storage Team, and its main index structure is built from [Hierarchical B+-Tree based Trie](http://db.csail.mit.edu/sigmod11contest/sigmod_2011_contest_poster_jungsang_ahn.pdf), called HB+-Trie. [HB+-Trie](http://db.csail.mit.edu/sigmod11contest/sigmod_2011_contest_poster_jungsang_ahn.pdf) was originally presented at [ACM SIGMOD 2011 Programming Contest](http://db.csail.mit.edu/sigmod11contest/), by [Jung-Sang Ahn](http://cagsky.kaist.ac.kr/jsahn/) who works at Couchbase Caching and Storage Team.
47741bce9SChiyoung Seo
5d602442cSChiyoung SeoCompared with traditional B+-Tree based storage engines, ForestDB shows significantly better read and write performance with less storage overhead. ForestDB has been tested on various server OS environments (Centos, Ubuntu, Mac OS x, Windows) and mobile OSs (iOS, Android).
6c46c340cSChiyoung Seo
74708a267SChiyoung SeoForestDB is currently in [1.0 Beta](https://github.com/couchbaselabs/forestdb/wiki/ForestDB-1.0-Beta) and its GA will be released separately soon. The test coverage stats for ForestDB are available in [ForestDB Code Coverage Report](http://labs.couchbase.com/fdbcoverage/index.html).
8ab05e6dfSChiyoung Seo
9ab05e6dfSChiyoung Seo[ForestDB benchmark program](https://github.com/couchbaselabs/ForestDB-Benchmark) is also available for performance comparisons with other key-value storage engines.
107741bce9SChiyoung Seo
11848144efSChiyoung SeoPlease visit the [ForestDB wiki](https://github.com/couchbaselabs/forestdb/wiki) for more details.
12848144efSChiyoung Seo
137741bce9SChiyoung Seo## Main Features
147741bce9SChiyoung Seo
157741bce9SChiyoung Seo- Keys and values are treated as an arbitrary binary.
167741bce9SChiyoung Seo- Applications can supply a custom compare function to support a customized key order.
177741bce9SChiyoung Seo- A value can be retrieved by its sequence number or disk offset in addition to a key.
187741bce9SChiyoung Seo- Write-Ahead Logging (WAL) and its in-memory index are used to reduce the main index lookup / update overhead.
19d602442cSChiyoung Seo- Multi-Version Concurrency Control (MVCC) support and append-only storage layer.
207741bce9SChiyoung Seo- Multiple snapshot instances can be created from a given ForestDB instance to provide different views of database.
217741bce9SChiyoung Seo- Rollback is supported to revert the database to a specific point.
227741bce9SChiyoung Seo- Ranged iteration by keys or sequence numbers is supported for a partial or full range lookup operation.
237741bce9SChiyoung Seo- Manual or auto compaction can be configured per ForestDB database file.
247741bce9SChiyoung Seo- Transactional support with read\_committed or read\_uncommitted isolation level.
257741bce9SChiyoung Seo
26ab05e6dfSChiyoung Seo## How to build
27ab05e6dfSChiyoung Seo
28ab05e6dfSChiyoung SeoSee INSTALL.MD
29ab05e6dfSChiyoung Seo
307741bce9SChiyoung Seo## How to Use
312534ac38SJung-Sang Ahn
32ab05e6dfSChiyoung SeoPlease refer to [Public APIs](https://github.com/couchbaselabs/forestdb/wiki/Public-APIs) and tests/fdb\_functional\_test.cc in ForestDB source directory.
33