projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
1 | --- |
| 2 | docid: getting-started | |
| 3 | title: Getting started | |
| 4 | layout: docs | |
| 5 | permalink: /docs/getting-started.html | |
| 6 | --- | |
| 7 | ||
| 8 | ## Overview | |
| 9 | ||
| 10 | 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. | |
| 11 | ||
| 12 | The 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 | ||
| 11fdf7f2 | 14 | This 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. |
| 7c673cae FG |
15 | |
| 16 | ## Opening A Database | |
| 17 | ||
| 18 | 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: | |
| 19 | ||
| 20 | ```c++ | |
| 21 | #include <assert> | |
| 22 | #include "rocksdb/db.h" | |
| 23 | ||
| 24 | rocksdb::DB* db; | |
| 25 | rocksdb::Options options; | |
| 26 | options.create_if_missing = true; | |
| 27 | rocksdb::Status status = | |
| 28 | rocksdb::DB::Open(options, "/tmp/testdb", &db); | |
| 29 | assert(status.ok()); | |
| 30 | ... | |
| 31 | ``` | |
| 32 | ||
| 33 | If you want to raise an error if the database already exists, add the following line before the rocksdb::DB::Open call: | |
| 34 | ||
| 35 | ```c++ | |
| 36 | options.error_if_exists = true; | |
| 37 | ``` | |
| 38 | ||
| 39 | ## Status | |
| 40 | ||
| 41 | You may have noticed the `rocksdb::Status` type above. Values of this type are returned by most functions in RocksDB that may encounter | |
| 42 | an error. You can check if such a result is ok, and also print an associated error message: | |
| 43 | ||
| 44 | ```c++ | |
| 45 | rocksdb::Status s = ...; | |
| 46 | if (!s.ok()) cerr << s.ToString() << endl; | |
| 47 | ``` | |
| 48 | ||
| 49 | ## Closing A Database | |
| 50 | ||
| 51 | When 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 */ | |
| 56 | delete db; | |
| 57 | ``` | |
| 58 | ||
| 59 | ## Reads And Writes | |
| 60 | ||
| 61 | 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`. | |
| 62 | ||
| 63 | ```c++ | |
| 64 | std::string value; | |
| 65 | rocksdb::Status s = db->Get(rocksdb::ReadOptions(), key1, &value); | |
| 66 | if (s.ok()) s = db->Put(rocksdb::WriteOptions(), key2, value); | |
| 67 | if (s.ok()) s = db->Delete(rocksdb::WriteOptions(), key1); | |
| 68 | ``` | |
| 69 | ||
| 70 | ## Further documentation | |
| 71 | ||
| 72 | These 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 | ||
| 74 | Here are some specific details about the RocksDB implementation: | |
| 75 | ||
| 1e59de90 TL |
76 | - [RocksDB Overview](https://github.com/facebook/rocksdb/wiki/RocksDB-Overview) |
| 77 | - [Immutable BlockBased Table file format](https://github.com/facebook/rocksdb/wiki/Rocksdb-BlockBasedTable-Format) | |
| 78 | - [Log file format](https://github.com/facebook/rocksdb/wiki/Write-Ahead-Log-File-Format) |