You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
rust-rocksdb/README.md

187 lines
5.9 KiB

10 years ago
rust-rocksdb
============
[![Build Status](https://travis-ci.org/spacejam/rust-rocksdb.svg?branch=master)](https://travis-ci.org/spacejam/rust-rocksdb)
9 years ago
[![crates.io](http://meritbadge.herokuapp.com/rocksdb)](https://crates.io/crates/rocksdb)
10 years ago
This library has been tested against RocksDB 3.13.1 on linux and OSX. The 0.3.1 crate should work with the Rust 1.5 stable and nightly releases as of 3/23/16.
### status
- [x] basic open/put/get/delete/close
- [x] rustic merge operator
9 years ago
- [x] write batch (thanks @dgrnbrg!)
- [x] compaction filter, style
- [x] LRU cache
- [x] destroy/repair
9 years ago
- [x] iterator
- [x] comparator
9 years ago
- [x] snapshot
- [x] column family operations
- [ ] prefix seek
- [ ] slicetransform
- [ ] windows support
Feedback and pull requests welcome! If a particular feature of RocksDB is important to you, please let me know by opening an issue, and I'll prioritize it.
###### Prerequisite: RocksDB
First, use your system's package manager to install snappy. This is optional, but lets rocksdb take advantage of better compression, and some code may require it.
```bash
wget https://github.com/facebook/rocksdb/archive/rocksdb-3.8.tar.gz
tar xvf rocksdb-3.8.tar.gz && cd rocksdb-rocksdb-3.8 && make shared_lib
10 years ago
sudo make install
```
### Running
10 years ago
###### Cargo.toml
10 years ago
```rust
[dependencies]
rocksdb = "0.3.1"
10 years ago
```
10 years ago
###### Code
10 years ago
```rust
extern crate rocksdb;
use rocksdb::{DB, Writable};
fn main() {
let mut db = DB::open_default("/path/for/rocksdb/storage").unwrap();
10 years ago
db.put(b"my key", b"my value");
match db.get(b"my key") {
Ok(Some(value)) => println!("retrieved value {}", value.to_utf8().unwrap()),
Ok(None) => println!("value not found"),
9 years ago
Err(e) => println!("operational problem encountered: {}", e),
}
10 years ago
db.delete(b"my key");
9 years ago
}
```
###### Doing an atomic commit of several writes
```rust
extern crate rocksdb;
use rocksdb::{DB, WriteBatch, Writable};
9 years ago
fn main() {
// NB: db is automatically freed at end of lifetime
let mut db = DB::open_default("/path/for/rocksdb/storage").unwrap();
9 years ago
{
let mut batch = WriteBatch::new(); // WriteBatch and db both have trait Writable
batch.put(b"my key", b"my value");
batch.put(b"key2", b"value2");
batch.put(b"key3", b"value3");
db.write(batch); // Atomically commits the batch
}
}
```
###### Getting an Iterator
```rust
extern crate rocksdb;
9 years ago
use rocksdb::{DB, Direction, IteratorMode};
9 years ago
fn main() {
// NB: db is automatically freed at end of lifetime
let mut db = DB::open_default("/path/for/rocksdb/storage").unwrap();
9 years ago
let mut iter = db.iterator(IteratorMode::Start); // Always iterates forward
for (key, value) in iter {
9 years ago
println!("Saw {} {}", key, value); //actually, need to convert [u8] keys into Strings
}
9 years ago
iter = db.iterator(IteratorMode::End); // Always iterates backward
for (key, value) in iter {
println!("Saw {} {}", key, value);
}
iter = db.iterator(IteratorMode::From(b"my key", Direction::forward)); // From a key in Direction::{forward,reverse}
for (key, value) in iter {
9 years ago
println!("Saw {} {}", key, value);
}
9 years ago
// You can seek with an existing Iterator instance, too
iter.set_mode(IteratorMode::From(b"another key", Direction::reverse));
for (key, value) in iter {
9 years ago
println!("Saw {} {}", key, value);
}
}
```
9 years ago
###### Getting an Iterator from a Snapshot
9 years ago
```rust
extern crate rocksdb;
use rocksdb::{DB, Direction};
9 years ago
fn main() {
// NB: db is automatically freed at end of lifetime
let mut db = DB::open_default("/path/for/rocksdb/storage").unwrap();
9 years ago
let snapshot = db.snapshot(); // Creates a longer-term snapshot of the DB, but freed when goes out of scope
9 years ago
let mut iter = snapshot.iterator(IteratorMode::Start); // Make as many iterators as you'd like from one snapshot
10 years ago
}
10 years ago
```
10 years ago
###### Rustic Merge Operator
```rust
extern crate rocksdb;
use rocksdb::{Options, DB, MergeOperands, Writable};
10 years ago
fn concat_merge(new_key: &[u8], existing_val: Option<&[u8]>,
operands: &mut MergeOperands) -> Vec<u8> {
let mut result: Vec<u8> = Vec::with_capacity(operands.size_hint().0);
existing_val.map(|v| {
for e in v {
9 years ago
result.push(*e)
}
});
for op in operands {
for e in op {
9 years ago
result.push(*e)
}
}
result
}
fn main() {
let path = "/path/to/rocksdb";
let mut opts = Options::new();
opts.create_if_missing(true);
opts.add_merge_operator("test operator", concat_merge);
let mut db = DB::open(&opts, path).unwrap();
let p = db.put(b"k1", b"a");
db.merge(b"k1", b"b");
db.merge(b"k1", b"c");
db.merge(b"k1", b"d");
db.merge(b"k1", b"efg");
let r = db.get(b"k1");
assert!(r.unwrap().unwrap().to_utf8().unwrap() == "abcdefg");
}
```
###### Apply Some Tunings
Please read [the official tuning guide](https://github.com/facebook/rocksdb/wiki/RocksDB-Tuning-Guide), and most importantly, measure performance under realistic workloads with realistic hardware.
```rust
use rocksdb::{Options, DB};
use rocksdb::DBCompactionStyle::DBUniversalCompaction;
fn badly_tuned_for_somebody_elses_disk() -> DB {
let path = "_rust_rocksdb_optimizetest";
let mut opts = Options::new();
opts.create_if_missing(true);
opts.set_max_open_files(10000);
opts.set_use_fsync(false);
opts.set_bytes_per_sync(8388608);
opts.set_disable_data_sync(false);
opts.set_block_cache_size_mb(1024);
opts.set_table_cache_num_shard_bits(6);
opts.set_max_write_buffer_number(32);
opts.set_write_buffer_size(536870912);
opts.set_target_file_size_base(1073741824);
opts.set_min_write_buffer_number_to_merge(4);
opts.set_level_zero_stop_writes_trigger(2000);
opts.set_level_zero_slowdown_writes_trigger(0);
opts.set_compaction_style(DBUniversalCompaction);
opts.set_max_background_compactions(4);
opts.set_max_background_flushes(4);
opts.set_filter_deletes(false);
opts.set_disable_auto_compactions(true);
DB::open(&opts, path).unwrap()
}
```