|
|
The Erlang Rocksdb binding provides access to most of the key/value API of the rocksdb library.
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
Download the sources from our [Gitlab repository](https://gitlab.com/barrel-db/erlang-rocksdb)
|
|
|
|
|
|
To build the application simply run 'rebar3 compile'.
|
|
|
|
|
|
To run tests run 'rebar3 eunit'. To generate doc, run 'rebar3 edoc'.
|
|
|
|
|
|
Or add it to your rebar config
|
|
|
|
|
|
|
|
|
```
|
|
|
{deps, [
|
|
|
....
|
|
|
{rocksdb, {rocksdb, "0.10.0"}}
|
|
|
]}.
|
|
|
```
|
|
|
|
|
|
Or your mix config file:
|
|
|
|
|
|
```
|
|
|
{:rocksdb, "~> 0.10"}
|
|
|
```
|
|
|
|
|
|
## Basic operations
|
|
|
|
|
|
|
|
|
### Open a database
|
|
|
|
|
|
```erlang
|
|
|
|
|
|
Path = "/tmp/erocksdb.fold.test",
|
|
|
Options = [{create_if_missing, true],
|
|
|
{ok, DB} = rocksdb:open(Path, Options).
|
|
|
|
|
|
```
|
|
|
|
|
|
This will create a nif resource.
|
|
|
|
|
|
> Makes sure that the process that opened it will stay open across or the session (or that at least one process own it) to prevent any garbage collection of it which will close the database and kill all the resources related (iterators, column families) ...
|
|
|
|
|
|
|
|
|
### Closing a database
|
|
|
|
|
|
When you are done with a database run the following function
|
|
|
|
|
|
```erlang
|
|
|
ok = rocksdb:close(DB).
|
|
|
```
|
|
|
|
|
|
> the database will be automatically closed if no process own it.
|
|
|
|
|
|
### Read and Writes
|
|
|
|
|
|
The library provides put, delete, and get methods to modify/query the database. For example, the following code moves the value stored under key1 to key2.
|
|
|
|
|
|
```
|
|
|
rocksdb:put(Db, <<"my key">>, <<"my value">>),
|
|
|
case rocksdb:get(Db, <<"my key">>, []) of
|
|
|
{ok, Value} => io:format("retrieved value %p~n", [Value]);
|
|
|
not_found => io:format("value not found~n", []);
|
|
|
Error -> io:format("operational problem encountered: %p~n", [Error])
|
|
|
end,
|
|
|
rocksdb:delete(Db, <<"my key">>).
|
|
|
```
|
|
|
|
|
|
### Atomic Updates
|
|
|
|
|
|
Note that if the process dies after the Put of key2 but before the delete of key1, the same value may be left stored under multiple keys. Such problems can be avoided by using the function `rocksdb:write/3` class to atomically apply a set of updates:
|
|
|
|
|
|
```
|
|
|
Batch = [
|
|
|
{put, <<"key1">>, <<"value1">>},
|
|
|
{delete, <<"keytodelete">>},
|
|
|
...
|
|
|
],
|
|
|
rocksdb:write(DB, Batch, [])
|
|
|
```
|
|
|
|
|
|
### Synchronous writes
|
|
|
|
|
|
Using the setting `{sync, true}` in any write operations will makes sure to store synchronously on the filesystem your data.
|
|
|
|
|
|
|
|
|
### Iterate your data
|
|
|
|
|
|
You can start an iterator using the function `rocksdb:iterator/2` :
|
|
|
|
|
|
```erlang
|
|
|
ItrOptions = [],
|
|
|
{ok, Itr} = iterator(DB, ItrOptions)
|
|
|
```
|
|
|
|
|
|
You close the iterator using the function `rocksdb:iterator_close/1`:
|
|
|
```erlang
|
|
|
rocksdb:iterator_close(Itr)
|
|
|
```
|
|
|
|
|
|
then you can move to the previous or next data using the function `iterator:move/2` :
|
|
|
|
|
|
* move to the next key: `rocksdb:iterator_move(Itr, next)`
|
|
|
* move to the previous key: `rocksdb:iterator_move(Itr, prev)`
|
|
|
* start at the first key: `rocksdb:iterator_move(Itr, first)`
|
|
|
* start at the last key: `rocksdb:iterator_move(Itr, last)`
|
|
|
* move to a key: `rocksdb:iterator_move(Itr, Key)` or `rocksdb:iterator_move(Itr,{seek, Key})`
|
|
|
* move to the previous key of: `rocksdb:iterator_move(Itr,{seek_for_prev, Key})`
|
|
|
|
|
|
> make sure to run
|
|
|
|
|
|
|