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.

Getting Started with Local-only Databases

Add BonsaiDb to your Cargo.toml:

[dependencies]
bonsaidb = { version = "0.4", features = ["local"] }

Local-only Examples

Each of these examples can be run within the BonsaiDb repository by executing cargo run --example EXAMPLE-NAME.

• basic-local: Shows using one database with one collection.
• basic-local-multidb: Shows using one collection with multiple databases.
• view-examples: Shows basic Map/Reduce views usage for collections. Also available as an async example:
• keyword-search: Shows how to use a View to build a keyword search index across data contained in a collection.
• primary-keys: Shows how to customize the primary key type for a collection.
• view-histogram: Demonstrates using a histogram as a value type within a Map/Reduce view, enabling automatic aggregation of histograms through queries.
• pubsub: Demonstrates publishing and subscribing to events published to topics. While PubSub is arguably more useful in the client/server model, it works offline as well. Also available as an async example:
• key-value-store: Shows basic usage of the atomic key-value store. Also available as an async example:

Getting Started with Client/Server Databases

Add BonsaiDb to your server's Cargo.toml:

[dependencies]
bonsaidb = { version = "0.4", features = ["server"] }

And to your client's Cargo.toml:

[dependencies]
bonsaidb = { version = "0.4", features = ["client"] }

Client/Server Examples

Each of these examples can be run within the BonsaiDb repository by executing cargo run --example EXAMPLE-NAME.

The examples for local-only databases are focused on teaching the basics on BonsaiDb and apply to all forms of accessing BonsaiDb, including Client/Server. If you're new to BonsaiDb, it might be best to start with the local-only examples while learning the fundamentals.

• basic-server: Shows basic server setup and access. Example includes both QUIC and WebSocket based connections.
• users: Shows basic user and permission group management.
• custom-api: Shows how to extend the BonsaiDb network protocol with a custom API. See also the user's guide section covering this example.
• cli: Shows how to use and extend the BonsaiDb command line interface.
• axum: Shows how to expose an Axum webserver that supports upgrading BonsaiDb websockets on a specified route.
• acme: Shows how to configure BonsaiDb to use LetsEncrypt to automatically issue TLS certificates.