Rust Bindings For Couchbase Lite

This is a Rust API of Couchbase Lite, an embedded NoSQL document database engine with sync.

The crate wraps the couchbase-lite-C releases with an idiomatic Rust API.

Disclaimer

This library is NOT SUPPORTED BY COUCHBASE, it was forked from Couchbase Labs' repo couchbase-lite-rust and finalized. It is currently used and maintained by Doctolib (GitHub).

The supported platforms are Windows, macOS, Linux, Android and iOS.

Building

1. Install LLVM/Clang

In addition to Rust, you'll need to install LLVM and Clang, which are required by the bindgen tool that generates Rust FFI APIs from C headers. Installation instructions are here.

2. Build!

There two different editions of Couchbase Lite C: community & enterprise. You can find the differences here.

When building or declaring this repository as a dependency, you need to specify the edition through a cargo feature:

$ cargo build --features=community

$ cargo build --features=enterprise

Maintaining

Couchbase Lite For C

The Couchbase Lite For C shared library and headers (Git repo) are already embedded in this repo. They are present in two directories, one for each edition: libcblite_community & libcblite_enterprise.

Upgrade Couchbase Lite C

The different releases can be found in this page.

When a new C release is available, a new Rust release must be created. Running the following script will download and setup the libraries locally:

$ ./update_cblite_c.sh -v 3.2.2

If the script fails (for example declare: -A: invalid option, you'll need bash >= version 4) on MacOS, you might need to install wget or a recent bash version:

$ brew install wget
$ brew install bash

If the script was successful:

• Change the link CBL_API_REFERENCE in this README
• Change the version in the test couchbase_lite_c_version_test
• Update the version in Cargo.toml
• Fix the compilation in both editions
• Fix the tests in both editions
• Create pull request

New C features should also be added to the Rust API at some point.

Test

Tests can be found in the tests subdirectory. Test are run in the GitHub wrokflow Test. You can find the commands used there.

There are three variations:

Nominal run

$ cargo test --features=enterprise

Run with Couchbase Lite C leak check

Couchbase Lite C allows checking if instances of their objects are still alive through the functions CBL_InstanceCount & CBL_DumpInstances. If the LEAK_CHECK environment variable is set, we check that the number of instances at the end of each test is 0.

If this step fails in one of your pull requests, you should look into the take_ownership/reference logic on CBL pointers in the constructor of the Rust structs:

• take_ownership takes ownership of the pointer, it will not increase the ref count of the ref CBL pointer so releasing it (in a drop for example) will free the pointer
• reference just references the pointer, it will increase the ref count of CBL pointers so releasing it will not free the pointer

$ LEAK_CHECK=y cargo test --features=enterprise -- --test-threads 1

Run with address sanitizer

$ LSAN_OPTIONS=suppressions=san.supp RUSTFLAGS="-Zsanitizer=address" cargo +nightly test  --features=enterprise

Learning

Official Couchbase Lite documentation

C API reference

Using Fleece