rocks 0.1.8

RocksDB bindings for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

# RustRocks

[![crates.io badge](https://img.shields.io/crates/v/rocks.svg)](https://crates.io/crates/rocks)
[![DOCS.RS badge](https://docs.rs/rocks/badge.svg)](https://docs.rs/rocks)
[![Linux Build Status](https://travis-ci.org/bh1xuw/rust-rocks.svg?branch=master)](https://travis-ci.org/bh1xuw/rust-rocks)
[![macOS Build Status](https://github.com/bh1xuw/rust-rocks/workflows/Rust/badge.svg)](https://github.com/bh1xuw/rust-rocks/actions)
[![Windows Build Status](https://ci.appveyor.com/api/projects/status/atawb7u8ekseodhm/branch/master?svg=true)](https://ci.appveyor.com/project/bh1xuw/rust-rocks)

Another RocksDB binding for Rust. [Documentation](https://docs.rs/rocks/)

Make RocksDB really rocks!

- Static link against RocksDB 6.7.3 (git submodules)
- Dynamic link tested:
  - macOS homebrew
  - Windows 10, VS 2019 with `vcpkg`
  - ArchLinux pacman, both x86_64 and aarch64(ODroid-C2)
  - Ubuntu 18.04 (`rocksdb5.8` branch), both x86_64 and aarch64(RPi 3)
  - Ubuntu 20.04 (`rocksdb5.17` branch)

## Installation

Dynamicly link RocksDB:

```toml
[dependencies]
rocks = "0.1"
```

Static link against RocksDB(with snappy enabled by default):

```toml
[dependencies.rocks]
version = "0.1"
default-features = false
features = ["static-link"]
```

With all static features(all compression types):

```toml
[dependencies.rocks]
version = "0.1"
default-features = false
features = ["full"]
```

## How to compile

Feel free to refer Travic-CI, AppVeyor and Github Actions configuration files.

### Static Link

```console
$ git submodule update --init --recursive
$ cargo test --features static-link -- --test-threads 1
(This will build with snappy as the only compression supported)

$ cargo test --features full -- --test-threads 1
(This will build with all compression supported)
```

### Dynamic Link

For macOS(with RocksDB installed via brew):

```console
$ brew install rocksdb
$ cargo test -- --nocapture --test-threads 1
```

For Linux:

```console
(install rocksdb via package manager or make & install)
$ sudo apt install lld
(NOTE: gcc-ld can't handle circular references while linking.)
(for more, refer the last section of README)
$ RUSTFLAGS="-C link-arg=-fuse-ld=lld" cargo test -- --test-threads 1
```

Use environment variables if rocksdb is installed to non-default directory:

`LD_LIBRARY_PATH=/usr/local/lib LIBRARY_PATH=/usr/local/lib CXXFLAGS=-I/usr/local/include`

### Ubuntu LTS

RocksDB changes its API often, so `rust-rocks` use different branch to support Ubuntu LTS.

```console
> sudo apt install librocksdb-dev libsnappy-dev
```

You also need `lld` form official source or `http://apt.llvm.org/`.

Branches:

- rocksdb5.8 (18.04 LTS)
- rocksdb5.17 (20.04 LTS)

### Windows

You need VS 2017 or VS 2019, and [install RocksDB](https://github.com/facebook/rocksdb/wiki/Building-on-Windows)
via [vcpkg](https://github.com/Microsoft/vcpkg).

## FAQ

- [Which features are supported/missing comparing to C++ RocksDB?](https://github.com/bh1xuw/rust-rocks/issues/1)
- [Why another RocksDB binding for Rust?](https://github.com/bh1xuw/rust-rocks/issues/2)

Feel free to Open a [New Issue](https://github.com/bh1xuw/rust-rocks/issues/new).

### List current supported compression types

```console
$ cargo run --example it-works
RocksDB: 6.7.3
Compression Supported:
  - NoCompression
  - SnappyCompression
  - ZlibCompression
  - BZip2Compression
  - LZ4Compression
  - LZ4HCCompression
  - ZSTD
  - ZSTDNotFinalCompression
```

## Development

Bindgen:

```console
$ cd rocks-sys
$ PATH="/usr/local/opt/llvm/bin:$PATH" make
(this will regenerate the bindgen c.rs)
```

## Known bugs

### Linking error under Linux

- rust-rocks exports rust functions to c++, so there are circular references while linking
- GCC reuqire that you put the object files and libraries in the order that they depend on each other
- Rust will not wrap user crates in `--start-group` and `--end-group`
- So circular references will be errors.
- Can be fixed by using `lld` as linker, `RUSTFLAGS="-C link-arg=-fuse-ld=lld"`
- Can be fixed by manually organising link arguments
  - librocks, then librocks_sys, *then librocks again*

### Minor memory leaks

- The raw pointers are created on the fly, should be impled via `lazy_static` and wrapped in trait objects
  - `ColumnFamilyOptions::comparator`: `const Comparator*`
  - `ColumnFamilyOptions::compaction_filter`: `const CompactionFilter*`

### Iterator leaks lifetime

Ref: <https://github.com/bh1xuw/rust-rocks/issues/15>

- While doing a `for`-traverse: That's OK
- While collecting for later use: Clone the keys and values