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:
- ACID-compliant, transactional storage of Collections
- Atomic Key-Value storage with configurable delayed persistence (similar to Redis)
- At-rest Encryption
- Backup/Restore
- Role-Based Access Control (RBAC)
- Local-only access, networked access via QUIC, or networked access via WebSockets
- And much more.
BonsaiDb is considered alpha software. It is under active development (). 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.
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 Shape
s by their number_of_sides
(ShapesByNumberOfSides
), and demonstrates multiple ways to query that view.
First, here's how the schema is defined:
#[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:
let db = Database::open::<Shape>(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:
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.
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.
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:
[dependencies]
bonsaidb = { version = "*", default-features = false, features = "full" }
full
: Enableslocal-full
,server-full
, andclient-full
.cli
: Enables thebonsaidb
executable.password-hashing
: Enables the ability to use password authentication using Argon2 viaAnyConnection
.
[dependencies]
bonsaidb = { version = "*", default-features = false, features = "local-full" }
local-full
: Enables all the flags belowlocal
: Enables thelocal
module, which re-exports the cratebonsaidb-local
.local-cli
: Enables theclap
structures for embedding database management commands into your own command-line interface.local-compression
: Enables support for compressed storage using lz4.local-encryption
: Enables at-rest encryption.local-instrument
: Enables instrumenting withtracing
.local-multiuser
: Enables multi-user support.local-password-hashing
: Enables the ability to use password authentication using Argon2.
[dependencies]
bonsaidb = { version = "*", default-features = false, features = "server-full" }
server-full
: Enables all the flags below,server
: Enables theserver
module, which re-exports the cratebonsaidb-server
.server-acme
: Enables automtic certificate acquisition through ACME/LetsEncrypt.server-cli
: Enables thecli
module.server-compression
: Enables support for compressed storage using lz4.server-encryption
: Enables at-rest encryption.server-hyper
: Enables convenience functions for upgrading websockets usinghyper
.server-instrument
: Enables instrumenting withtracing
.server-pem
: Enables the ability to install a certificate using the PEM format.server-websockets
: EnablesWebSocket
support.server-password-hashing
: Enables the ability to use password authentication using Argon2.
[dependencies]
bonsaidb = { version = "*", default-features = false, features = "client-full" }
client-full
: Enablesclient
,client-trusted-dns
,client-websockets
, andclient-password-hashing
.client
: Enables theclient
module, which re-exports the cratebonsaidb-client
.client-trusted-dns
: Enables using trust-dns for DNS resolution. If not enabled, all DNS resolution is done with the OS's default name resolver.client-websockets
: EnablesWebSocket
support forbonsaidb-client
.client-password-hashing
: Enables the ability to use password authentication using Argon2.
Our CI processes require that some commands succeed without warnings or errors. These checks can be performed manually by running:
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:
cargo xtask install-pre-commit-hook
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.