RocksDB | A persistent key-value store for fast storage environments

The rocksdb library provides a persistent key value store. Keys and values are arbitrary byte arrays. The keys are ordered within the key value store according to a user-specified comparator function.

The library is maintained by the Facebook Database Engineering Team, and is based on leveldb, by Sanjay Ghemawat and Jeff Dean at Google.

Opening A Database

A rocksdb database has a name which corresponds to a file system directory. All of the contents of database are stored in this directory. The following example shows how to open a database, creating it if necessary:

#include <assert>
#include "rocksdb/db.h"

rocksdb::DB* db;
rocksdb::Options options;
options.create_if_missing = true;
rocksdb::Status status =
  rocksdb::DB::Open(options, "/tmp/testdb", &db);
assert(status.ok());
...

If you want to raise an error if the database already exists, add the following line before the rocksdb::DB::Open call:

options.error_if_exists = true;

Status

You may have noticed the rocksdb::Status type above. Values of this type are returned by most functions in rocksdb that may encounter an error. You can check if such a result is ok, and also print an associated error message:

rocksdb::Status s = ...;
if (!s.ok()) cerr << s.ToString() << endl;

Closing A Database

When you are done with a database, just delete the database object. For example:

/* open the db as described above */
/* do something with db */
delete db;

Reads And Writes

The database provides Put, Delete, and Get methods to modify/query the database. For example, the following code moves the value stored under key1 to key2.

std::string value;
rocksdb::Status s = db->Get(rocksdb::ReadOptions(), key1, &value);
if (s.ok()) s = db->Put(rocksdb::WriteOptions(), key2, value);
if (s.ok()) s = db->Delete(rocksdb::WriteOptions(), key1);

Further documentation

These are just simple examples of how RocksDB is used. The full documentation is available within the /doc folder of the project.

In addition, further details about the RocksDB implementation may be found in the following documents: