A simple, humane, typed key-value storage solution.
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.
Niko 19fc8e0b68 in get_key_value pass value by ref 2 months ago
.github/workflows Bump MSRV to Rust 1.58.0 (#225) 4 months ago
examples Follow the default behavior of rustfmt (#224) 4 months ago
src in get_key_value pass value by ref 2 months ago
tests in get_key_value pass value by ref 2 months ago
.gitattributes Migrate from Travis CI to GitHub Actions (#220) 6 months ago
.gitignore adding version function to environment 3 months ago
CODE_OF_CONDUCT.md Add Mozilla Code of Conduct file 4 years ago
Cargo.toml switching to p2pcollab/lmdb-rs 3 months ago
LICENSE Initial commit. 5 years ago
README.md use lmdb-crypto-rs 3 months ago
run-all-examples.sh run examples in travis 5 years ago

README.md

rkv-crypto

This repo is a fork of mozilla/rkv that enables encryption of data at rest in LMDB.

CI Build Status Documentation Crate

The rkv Rust crate is a simple, humane, typed key-value storage solution. It supports multiple backend engines with varying guarantees, such as LMDB for performance, or "SafeMode" for reliability.

Warning

To use rkv in production/release environments at Mozilla, you may do so with the "SafeMode" backend, for example:

use rkv::{Manager, Rkv};
use rkv::backend::{SafeMode, SafeModeEnvironment};

let mut manager = Manager::<SafeModeEnvironment>::singleton().write().unwrap();
let shared_rkv = manager.get_or_create(path, Rkv::new::<SafeMode>).unwrap();

...

The "SafeMode" backend performs well, with two caveats: the entire database is stored in memory, and write transactions are synchronously written to disk (only on commit).

In the future, it will be advisable to switch to a different backend with better performance guarantees. We're working on either fixing some LMDB crashes, or offering more choices of backend engines (e.g. SQLite).

Use

Comprehensive information about using rkv is available in its online documentation, which can also be generated for local consumption:

cargo doc --open

Build

Build this project as you would build other Rust crates:

cargo build

Features

There are several features that you can opt-in and out of when using rkv:

By default, db-dup-sort and db-int-key features offer high level database APIs which allow multiple values per key, and optimizations around integer-based keys respectively. Opt out of these default features when specifying the rkv dependency in your Cargo.toml file to disable them; doing so avoids a certain amount of overhead required to support them.

To aid fuzzing efforts, with-asan, with-fuzzer, and with-fuzzer-no-link configure the build scripts responsible with compiling the underlying backing engines (e.g. LMDB) to build with these LLMV features enabled. Please refer to the official LLVM/Clang documentation on them for more informatiuon. These features are also disabled by default.

Test

Test this project as you would test other Rust crates:

cargo test

The project includes unit and doc tests embedded in the src/ files, integration tests in the tests/ subdirectory, and usage examples in the examples/ subdirectory. To ensure your changes don't break examples, also run them via the run-all-examples.sh shell script:

./run-all-examples.sh

Note: the test fixtures in the tests/envs/ subdirectory aren't included in the package published to crates.io, so you must clone this repository in order to run the tests that depend on those fixtures or use the rand and dump executables to recreate them.

Contribute

Of the various open source archetypes described in A Framework for Purposeful Open Source, the rkv project most closely resembles the Specialty Library, and we welcome contributions. Please report problems or ask questions using this repo's GitHub issue tracker and submit pull requests for code and documentation changes.

rkv relies on the latest rustfmt for code formatting, so please make sure your pull request passes the rustfmt before submitting it for review. See rustfmt's quick start for installation details.

We follow Mozilla's Community Participation Guidelines while contributing to this project.

License

The rkv source code is licensed under the Apache License, Version 2.0, as described in the LICENSE file.