1---
2docid: getting-started
3title: Getting started
4layout: docs
5permalink: /docs/getting-started.html
6---
7
8## Overview
9
10The 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.
11
12The library is maintained by the Facebook Database Engineering Team, and is based on [LevelDB](https://github.com/google/leveldb), by Sanjay Ghemawat and Jeff Dean at Google.
13
14This overview gives some simple examples of how RocksDB is used. For the story of why RocksDB was created in the first place, see [Dhruba Borthakur’s introductory talk](https://github.com/facebook/rocksdb/blob/gh-pages-old/intro.pdf?raw=true) from the Data @ Scale 2013 conference.
15
16## Opening A Database
17
18A 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:
19
20```c++
21#include <assert>
22#include "rocksdb/db.h"
23
24rocksdb::DB* db;
25rocksdb::Options options;
26options.create_if_missing = true;
27rocksdb::Status status =
28  rocksdb::DB::Open(options, "/tmp/testdb", &db);
29assert(status.ok());
30...
31```
32
33If you want to raise an error if the database already exists, add the following line before the rocksdb::DB::Open call:
34
35```c++
36options.error_if_exists = true;
37```
38
39## Status
40
41You may have noticed the `rocksdb::Status` type above. Values of this type are returned by most functions in RocksDB that may encounter
42an error. You can check if such a result is ok, and also print an associated error message:
43
44```c++
45rocksdb::Status s = ...;
46if (!s.ok()) cerr << s.ToString() << endl;
47```
48
49## Closing A Database
50
51When you are done with a database, just delete the database object. For example:
52
53```c++
54/* open the db as described above */
55/* do something with db */
56delete db;
57```
58
59## Reads And Writes
60
61The 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`.
62
63```c++
64std::string value;
65rocksdb::Status s = db->Get(rocksdb::ReadOptions(), key1, &value);
66if (s.ok()) s = db->Put(rocksdb::WriteOptions(), key2, value);
67if (s.ok()) s = db->Delete(rocksdb::WriteOptions(), key1);
68```
69
70## Further documentation
71
72These are just simple examples of how RocksDB is used. The full documentation is currently on the [GitHub wiki](https://github.com/facebook/rocksdb/wiki).
73
74Here are some specific details about the RocksDB implementation:
75
76- [Architecture Guide](https://github.com/facebook/rocksdb/wiki/Rocksdb-Architecture-Guide)
77- [Format of an immutable Table file](https://github.com/facebook/rocksdb/wiki/Rocksdb-Table-Format)
78- [Format of a log file](https://github.com/facebook/rocksdb/wiki/Write-Ahead-Log-File-Format)
79