rocks 0.1.9

RocksDB bindings for Rust.
Documentation

RustRocks

crates.io badge DOCS.RS badge Linux Build Status macOS Build Status Windows Build Status

Another RocksDB binding for Rust. Documentation

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:

[dependencies]
rocks = "0.1"

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

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

With all static features(all compression types):

[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

$ 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):

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

For Linux:

(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.

> 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 via vcpkg.

FAQ

Feel free to Open a New Issue.

List current supported compression types

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

Development

Bindgen:

$ 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 requires 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