1**LevelDB is a fast key-value storage library written at Google that provides an ordered mapping from string keys to string values.** 2 3[](https://travis-ci.org/google/leveldb) 4 5Authors: Sanjay Ghemawat ([email protected]) and Jeff Dean ([email protected]) 6 7# Features 8 * Keys and values are arbitrary byte arrays. 9 * Data is stored sorted by key. 10 * Callers can provide a custom comparison function to override the sort order. 11 * The basic operations are `Put(key,value)`, `Get(key)`, `Delete(key)`. 12 * Multiple changes can be made in one atomic batch. 13 * Users can create a transient snapshot to get a consistent view of data. 14 * Forward and backward iteration is supported over the data. 15 * Data is automatically compressed using the [Snappy compression library](http://google.github.io/snappy/). 16 * External activity (file system operations etc.) is relayed through a virtual interface so users can customize the operating system interactions. 17 18# Documentation 19 [LevelDB library documentation](https://github.com/google/leveldb/blob/master/doc/index.md) is online and bundled with the source code. 20 21 22# Limitations 23 * This is not a SQL database. It does not have a relational data model, it does not support SQL queries, and it has no support for indexes. 24 * Only a single process (possibly multi-threaded) can access a particular database at a time. 25 * There is no client-server support builtin to the library. An application that needs such support will have to wrap their own server around the library. 26 27# Contributing to the leveldb Project 28The leveldb project welcomes contributions. leveldb's primary goal is to be 29a reliable and fast key/value store. Changes that are in line with the 30features/limitations outlined above, and meet the requirements below, 31will be considered. 32 33Contribution requirements: 34 351. **POSIX only**. We _generally_ will only accept changes that are both 36 compiled, and tested on a POSIX platform - usually Linux. Very small 37 changes will sometimes be accepted, but consider that more of an 38 exception than the rule. 39 402. **Stable API**. We strive very hard to maintain a stable API. Changes that 41 require changes for projects using leveldb _might_ be rejected without 42 sufficient benefit to the project. 43 443. **Tests**: All changes must be accompanied by a new (or changed) test, or 45 a sufficient explanation as to why a new (or changed) test is not required. 46 47## Submitting a Pull Request 48Before any pull request will be accepted the author must first sign a 49Contributor License Agreement (CLA) at https://cla.developers.google.com/. 50 51In order to keep the commit timeline linear 52[squash](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Squashing-Commits) 53your changes down to a single commit and [rebase](https://git-scm.com/docs/git-rebase) 54on google/leveldb/master. This keeps the commit timeline linear and more easily sync'ed 55with the internal repository at Google. More information at GitHub's 56[About Git rebase](https://help.github.com/articles/about-git-rebase/) page. 57 58# Performance 59 60Here is a performance report (with explanations) from the run of the 61included db_bench program. The results are somewhat noisy, but should 62be enough to get a ballpark performance estimate. 63 64## Setup 65 66We use a database with a million entries. Each entry has a 16 byte 67key, and a 100 byte value. Values used by the benchmark compress to 68about half their original size. 69 70 LevelDB: version 1.1 71 Date: Sun May 1 12:11:26 2011 72 CPU: 4 x Intel(R) Core(TM)2 Quad CPU Q6600 @ 2.40GHz 73 CPUCache: 4096 KB 74 Keys: 16 bytes each 75 Values: 100 bytes each (50 bytes after compression) 76 Entries: 1000000 77 Raw Size: 110.6 MB (estimated) 78 File Size: 62.9 MB (estimated) 79 80## Write performance 81 82The "fill" benchmarks create a brand new database, in either 83sequential, or random order. The "fillsync" benchmark flushes data 84from the operating system to the disk after every operation; the other 85write operations leave the data sitting in the operating system buffer 86cache for a while. The "overwrite" benchmark does random writes that 87update existing keys in the database. 88 89 fillseq : 1.765 micros/op; 62.7 MB/s 90 fillsync : 268.409 micros/op; 0.4 MB/s (10000 ops) 91 fillrandom : 2.460 micros/op; 45.0 MB/s 92 overwrite : 2.380 micros/op; 46.5 MB/s 93 94Each "op" above corresponds to a write of a single key/value pair. 95I.e., a random write benchmark goes at approximately 400,000 writes per second. 96 97Each "fillsync" operation costs much less (0.3 millisecond) 98than a disk seek (typically 10 milliseconds). We suspect that this is 99because the hard disk itself is buffering the update in its memory and 100responding before the data has been written to the platter. This may 101or may not be safe based on whether or not the hard disk has enough 102power to save its memory in the event of a power failure. 103 104## Read performance 105 106We list the performance of reading sequentially in both the forward 107and reverse direction, and also the performance of a random lookup. 108Note that the database created by the benchmark is quite small. 109Therefore the report characterizes the performance of leveldb when the 110working set fits in memory. The cost of reading a piece of data that 111is not present in the operating system buffer cache will be dominated 112by the one or two disk seeks needed to fetch the data from disk. 113Write performance will be mostly unaffected by whether or not the 114working set fits in memory. 115 116 readrandom : 16.677 micros/op; (approximately 60,000 reads per second) 117 readseq : 0.476 micros/op; 232.3 MB/s 118 readreverse : 0.724 micros/op; 152.9 MB/s 119 120LevelDB compacts its underlying storage data in the background to 121improve read performance. The results listed above were done 122immediately after a lot of random writes. The results after 123compactions (which are usually triggered automatically) are better. 124 125 readrandom : 11.602 micros/op; (approximately 85,000 reads per second) 126 readseq : 0.423 micros/op; 261.8 MB/s 127 readreverse : 0.663 micros/op; 166.9 MB/s 128 129Some of the high cost of reads comes from repeated decompression of blocks 130read from disk. If we supply enough cache to the leveldb so it can hold the 131uncompressed blocks in memory, the read performance improves again: 132 133 readrandom : 9.775 micros/op; (approximately 100,000 reads per second before compaction) 134 readrandom : 5.215 micros/op; (approximately 190,000 reads per second after compaction) 135 136## Repository contents 137 138See [doc/index.md](doc/index.md) for more explanation. See 139[doc/impl.md](doc/impl.md) for a brief overview of the implementation. 140 141The public interface is in include/*.h. Callers should not include or 142rely on the details of any other header files in this package. Those 143internal APIs may be changed without warning. 144 145Guide to header files: 146 147* **include/db.h**: Main interface to the DB: Start here 148 149* **include/options.h**: Control over the behavior of an entire database, 150and also control over the behavior of individual reads and writes. 151 152* **include/comparator.h**: Abstraction for user-specified comparison function. 153If you want just bytewise comparison of keys, you can use the default 154comparator, but clients can write their own comparator implementations if they 155want custom ordering (e.g. to handle different character encodings, etc.) 156 157* **include/iterator.h**: Interface for iterating over data. You can get 158an iterator from a DB object. 159 160* **include/write_batch.h**: Interface for atomically applying multiple 161updates to a database. 162 163* **include/slice.h**: A simple module for maintaining a pointer and a 164length into some other byte array. 165 166* **include/status.h**: Status is returned from many of the public interfaces 167and is used to report success and various kinds of errors. 168 169* **include/env.h**: 170Abstraction of the OS environment. A posix implementation of this interface is 171in util/env_posix.cc 172 173* **include/table.h, include/table_builder.h**: Lower-level modules that most 174clients probably won't use directly 175
){kind=link}