BonsaiDb

BonsaiDb is considered alpha crate version Live Build Status HTML Coverage Report for <code>v0.2.0</code> Documentation for <code>v0.2.0</code>

BonsaiDb is a developer-friendly document database for Rust that grows with you. It offers many features out of the box that many developers need:

⚠️ Status of this project

BonsaiDb is considered alpha software. It is under active development (GitHub commit activity). There may still be bugs that result in data loss. All users should regularly back up their data and test that restoring from backup works correctly.

Example

To get an idea of how it works, let's review the view-examples example. See the examples README for a list of all available examples.

The view-examples example shows how to define a simple schema containing a single collection (Shape), a view to query the Shapes by their number_of_sides (ShapesByNumberOfSides), and demonstrates multiple ways to query that view.

First, here's how the schema is defined:

```rust,ignore

[derive(Debug, Serialize, Deserialize, Collection)]

[collection(name = "shapes", views = [ShapesByNumberOfSides])]

struct Shape { pub sides: u32, }

[derive(Debug, Clone, View)]

[view(collection = Shape, key = u32, value = usize, name = "by-number-of-sides")]

struct ShapesByNumberOfSides;

impl CollectionViewSchema for ShapesByNumberOfSides { type View = Self;

fn map(&self, document: CollectionDocument<Shape>) -> ViewMapResult<Self::View> {
    document
        .header
        .emit_key_and_value(document.contents.sides, 1)
}

fn reduce(
    &self,
    mappings: &[ViewMappedValue<Self>],
    _rereduce: bool,
) -> ReduceResult<Self::View> {
    Ok(mappings.iter().map(|m| m.value).sum())
}

} ```

After you have your collection(s) and view(s) defined, you can open up a database and insert documents:

```rust,ignore let db = Database::open::(StorageConfiguration::new("view-examples.bonsaidb")).await?;

// Insert a new document into the Shape collection. Shape { sides: 3 }.push_into(&db).await?; ```

And query data using the Map-Reduce-powered view:

rust,ignore let triangles = db .view::<ShapesByNumberOfSides>() .with_key(3) .query() .await?; println!("Number of triangles: {}", triangles.len());

You can review the full example in the repository, or see all available examples in the examples README.

Minimum Supported Rust Version (MSRV)

While this project is alpha, we are actively adopting the current version of Rust. The current minimum version is 1.58, and we plan on updating the MSRV to implement namespaced Features as soon as the feature is released.

Feature Flags

No feature flags are enabled by default in the bonsaidb crate. This is because in most Rust executables, you will only need a subset of the functionality. If you'd prefer to enable everything, you can use the full feature:

toml [dependencies] bonsaidb = { version = "*", default-features = false, features = "full" }

Local databases only

toml [dependencies] bonsaidb = { version = "*", default-features = false, features = "local-full" }

BonsaiDb server

toml [dependencies] bonsaidb = { version = "*", default-features = false, features = "server-full" }

Client for accessing a BonsaiDb server

toml [dependencies] bonsaidb = { version = "*", default-features = false, features = "client-full" }

Developing BonsaiDb

Pre-commit hook

Our CI processes require that some commands succeed without warnings or errors. These checks can be performed manually by running:

bash cargo xtask test --fail-on-warnings

Or, if you would like to run all these checks before each commit, you can install the check as a pre-commit hook:

bash cargo xtask install-pre-commit-hook

Open-source Licenses

This project, like all projects from Khonsu Labs, are open-source. This repository is available under the MIT License or the Apache License 2.0.

To learn more about contributing, please see CONTRIBUTING.md.