{"id":13504380,"url":"https://github.com/khonsulabs/bonsaidb","last_synced_at":"2025-05-14T21:07:36.905Z","repository":{"id":37341671,"uuid":"349627612","full_name":"khonsulabs/bonsaidb","owner":"khonsulabs","description":"A developer-friendly document database that grows with you, written in Rust","archived":false,"fork":false,"pushed_at":"2024-07-25T15:52:08.000Z","size":5642,"stargazers_count":1041,"open_issues_count":101,"forks_count":38,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-05-09T16:11:52.305Z","etag":null,"topics":["database","rust"],"latest_commit_sha":null,"homepage":"https://bonsaidb.io/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/khonsulabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["ecton"]}},"created_at":"2021-03-20T04:35:24.000Z","updated_at":"2025-04-13T17:55:49.000Z","dependencies_parsed_at":"2023-12-05T15:58:58.278Z","dependency_job_id":"98c45a3a-2824-4714-9506-15ea945fba3e","html_url":"https://github.com/khonsulabs/bonsaidb","commit_stats":{"total_commits":978,"total_committers":7,"mean_commits":"139.71428571428572","dds":0.05214723926380371,"last_synced_commit":"35c14b5853727e6aea9fadedfc42b6bde736a30d"},"previous_names":["khonsulabs/pliantdb"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khonsulabs%2Fbonsaidb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khonsulabs%2Fbonsaidb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khonsulabs%2Fbonsaidb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khonsulabs%2Fbonsaidb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khonsulabs","download_url":"https://codeload.github.com/khonsulabs/bonsaidb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010793,"owners_count":21998993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","rust"],"created_at":"2024-08-01T00:00:35.803Z","updated_at":"2025-05-14T21:07:31.891Z","avatar_url":"https://github.com/khonsulabs.png","language":"Rust","funding_links":["https://github.com/sponsors/ecton"],"categories":["Databases","Rust","rust"],"sub_categories":["NoSQL, Document Databases"],"readme":"# BonsaiDb\n\n![BonsaiDb forbids unsafe code](https://img.shields.io/badge/unsafe-forbid-success)\n![BonsaiDb is considered alpha](https://img.shields.io/badge/status-alpha-orange)\n[![crate version](https://img.shields.io/crates/v/bonsaidb.svg)](https://crates.io/crates/bonsaidb)\n[![Live Build Status](https://img.shields.io/github/actions/workflow/status/khonsulabs/bonsaidb/tests.yml?branch=main)](https://github.com/khonsulabs/bonsaidb/actions?query=workflow:Tests)\n[![HTML Coverage Report for `main`](https://dev.bonsaidb.io/main/coverage/badge.svg)](https://dev.bonsaidb.io/main/coverage/)\n[![Documentation for `main`](https://img.shields.io/badge/docs-main-informational)](https://dev.bonsaidb.io/main/docs/bonsaidb)\n\nBonsaiDb is a developer-friendly document database for\n[Rust](https://rust-lang.org) that grows with you. It offers many features out\nof the box that many developers need:\n\n- ACID-compliant, transactional storage of [Collections][collection]\n- [Atomic Key-Value storage][key-value] with configurable delayed persistence (similar to Redis)\n- At-rest Encryption\n- Backup/Restore\n- Role-Based Access Control (RBAC)\n- Local-only access, networked access via QUIC, or networked access via WebSockets\n- And [much more](https://bonsaidb.io/about).\n\n[collection]: https://dev.bonsaidb.io/main/guide/about/concepts/collection.html\n[key-value]: https://dev.bonsaidb.io/main/guide/traits/key-value.html\n\n## ⚠️ Status of this project\n\nBonsaiDb is considered alpha software. It is under active development (![GitHub\ncommit\nactivity](https://img.shields.io/github/commit-activity/m/khonsulabs/bonsaidb)).\nThere may still be bugs that result in data loss. All users should regularly\nback up their data and test that restoring from backup works correctly.\n\nAround May 2022, a bug and a mistake in benchmarking were discovered. The bug\nwas promptly fixed, but the net result is that BonsaiDb's transactional write\nperformance is significantly slower than other databases. Unless you're building\na very write-heavy application, the performance will likely still be acceptable.\n[Issue #251 on GitHub](https://github.com/khonsulabs/bonsaidb/issues/251) is\nwhere progress of the performance updates are being tracked. From a developer's\nperspective, migration is expected to be painless beyond the IO needed to copy\nthe old database into the new format.\n\n## Example\n\nTo get an idea of how it works, let's review the [`view-examples` example][view-examples].\nSee the [examples README][examples-readme] for a list of all available examples.\n\nThe [`view-examples` example][view-examples] 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.\n\nFirst, here's how the schema is defined:\n\n```rust,ignore\n#[derive(Debug, Serialize, Deserialize, Collection)]\n#[collection(name = \"shapes\", views = [ShapesByNumberOfSides])]\nstruct Shape {\n    pub sides: u32,\n}\n\n#[derive(Debug, Clone, View, ViewSchema)]\n#[view(collection = Shape, key = u32, value = usize, name = \"by-number-of-sides\")]\nstruct ShapesByNumberOfSides;\n\nimpl CollectionMapReduce for ShapesByNumberOfSides {\n    fn map\u003c'doc\u003e(\u0026self, document: CollectionDocument\u003cShape\u003e) -\u003e ViewMapResult\u003c'doc, Self::View\u003e {\n        document\n            .header\n            .emit_key_and_value(document.contents.sides, 1)\n    }\n\n    fn reduce(\n        \u0026self,\n        mappings: \u0026[ViewMappedValue\u003c'_, Self\u003e],\n        _rereduce: bool,\n    ) -\u003e ReduceResult\u003cSelf::View\u003e {\n        Ok(mappings.iter().map(|m| m.value).sum())\n    }\n}\n```\n\nAfter you have your collection(s) and view(s) defined, you can open up a database and insert documents:\n\n```rust,ignore\nlet db = Database::open::\u003cShape\u003e(StorageConfiguration::new(\"view-examples.bonsaidb\"))?;\n\n// Insert a new document into the Shape collection.\nShape { sides: 3 }.push_into(\u0026db)?;\n```\n\nAnd query data using the Map-Reduce-powered view:\n\n```rust,ignore\nlet triangles = ShapesByNumberOfSides::entries(\u0026db).with_key(\u00263).query()?;\nprintln!(\"Number of triangles: {}\", triangles.len());\n```\n\nYou can review the [full example in the repository][view-examples], or see all available examples [in the examples README][examples-readme].\n\n[view-examples]: https://github.com/khonsulabs/bonsaidb/blob/main/examples/basic-local/examples/view-examples.rs\n[examples-readme]: https://github.com/khonsulabs/bonsaidb/blob/main/examples/README.md\n\n## User's Guide\n\nOur user's guide is early in development, but is available at: \u003chttps://dev.bonsaidb.io/main/guide/\u003e\n\n## Minimum Supported Rust Version (MSRV)\n\nWhile this project is alpha, we are actively adopting the current version of\nRust. The current minimum version is `1.70`.\n\n## Feature Flags\n\nNo feature flags are enabled by default in the `bonsaidb` crate. This is\nbecause in most Rust executables, you will only need a subset of the\nfunctionality. If you'd prefer to enable everything, you can use the `full`\nfeature:\n\n```toml\n[dependencies]\nbonsaidb = { version = \"*\", features = \"full\" }\n```\n\n- `full`: Enables the features below and `local-full`, `server-full`, and `client-full`.\n- `cli`: Enables the `bonsaidb` executable.\n- `files`: Enables file storage support with `bonsaidb-files`\n- `password-hashing`: Enables the ability to use password authentication using\n  Argon2 via `AnyConnection`.\n- `token-authentication`: Enables the ability to authenticate using\n  authentication tokens, which are similar to API keys.\n\nAll other feature flags, listed below, affect each crate individually, but can\nbe safely combined.\n\n### Local databases only\n\n```toml\n[dependencies]\nbonsaidb = { version = \"*\", features = \"local-full\" }\n```\n\nAll Cargo features that affect local databases:\n\n- `local-full`: Enables all the flags below\n- `local`: Enables the [`local`](https://dev.bonsaidb.io/main/docs/bonsaidb/local/) module, which re-exports the crate\n  `bonsaidb-local`.\n- `async`: Enables async support with Tokio.\n- `cli`: Enables the `clap` structures for embedding database\n  management commands into your own command-line interface.\n- `compression`: Enables support for compressed storage using lz4.\n- `encryption`: Enables at-rest encryption.\n- `instrument`: Enables instrumenting with `tracing`.\n- `password-hashing`: Enables the ability to use password authentication\n  using Argon2.\n- `token-authentication`: Enables the ability to authenticate using\n  authentication tokens, which are similar to API keys.\n\n### BonsaiDb server\n\n```toml\n[dependencies]\nbonsaidb = { version = \"*\", features = \"server-full\" }\n```\n\nAll Cargo features that affect networked servers:\n\n- `server-full`: Enables all the flags below,\n- `server`: Enables the [`server`](https://dev.bonsaidb.io/main/docs/bonsaidb/server/) module, which re-exports the crate\n  `bonsaidb-server`.\n- `acme`: Enables automtic certificate acquisition through ACME/LetsEncrypt.\n- `cli`: Enables the `cli` module.\n- `compression`: Enables support for compressed storage using lz4.\n- `encryption`: Enables at-rest encryption.\n- `hyper`: Enables convenience functions for upgrading websockets using `hyper`.\n- `instrument`: Enables instrumenting with `tracing`.\n- `pem`: Enables the ability to install a certificate using the PEM format.\n- `websockets`: Enables `WebSocket` support.\n- `password-hashing`: Enables the ability to use password authentication\n  using Argon2.\n- `token-authentication`: Enables the ability to authenticate using\n  authentication tokens, which are similar to API keys.\n\n### Client for accessing a BonsaiDb server\n\n```toml\n[dependencies]\nbonsaidb = { version = \"*\", features = \"client-full\" }\n```\n\nAll Cargo features that affect networked clients:\n\n- `client-full`: Enables all flags below.\n- `client`: Enables the [`client`](https://dev.bonsaidb.io/main/docs/bonsaidb/client/) module, which re-exports the crate\n  `bonsaidb-client`.\n- `trusted-dns`: Enables using trust-dns for DNS resolution. If not\n  enabled, all DNS resolution is done with the OS's default name resolver.\n- `websockets`: Enables `WebSocket` support for `bonsaidb-client`.\n- `password-hashing`: Enables the ability to use password authentication\n  using Argon2.\n- `token-authentication`: Enables the ability to authenticate using\n  authentication tokens, which are similar to API keys.\n\n## Developing BonsaiDb\n\n### Writing Unit Tests\n\nUnless there is a good reason not to, every feature in BonsaiDb should have\nthorough unit tests. Many tests are implemented in `bonsaidb_core::test_util`\nvia a macro that allows the suite to run using various methods of accessing\nBonsaiDb.\n\nSome features aren't able to be tested using the `Connection`,\n`StorageConnection`, `KeyValue`, and `PubSub` traits only. If that's the case,\nyou should add tests to whichever crates makes the most sense to test the code.\nFor example, if it's a feature that only can be used in `bonsaidb-server`, the\ntest should be somewhere in the `bonsaidb-server` crate.\n\nTests that require both a client and server can be added to the `core-suite`\ntest file in the `bonsaidb` crate.\n\n### Checking Syntax\n\nWe use `clippy` to give additional guidance on our code. Clippy should always return with no errors, regardless of feature flags being enabled:\n\n```bash\ncargo clippy --all-features\n```\n\n### Running all tests\n\nOur CI processes require that some commands succeed without warnings or errors. These checks can be performed manually by running:\n\n```bash\ncargo xtask test --fail-on-warnings\n```\n\nOr, if you would like to run all these checks before each commit, you can install the check as a pre-commit hook:\n\n```bash\ncargo xtask install-pre-commit-hook\n```\n\n### Formatting Code\n\nWe have a custom rustfmt configuration that enables several options only available in nightly builds:\n\n```bash\ncargo +nightly fmt\n```\n\n## Open-source Licenses\n\nThis project, like all projects from [Khonsu Labs](https://khonsulabs.com/), is open-source.\nThis repository is available under the [MIT License](./LICENSE-MIT) or the\n[Apache License 2.0](./LICENSE-APACHE).\n\nTo learn more about contributing, please see [CONTRIBUTING.md](./CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhonsulabs%2Fbonsaidb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhonsulabs%2Fbonsaidb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhonsulabs%2Fbonsaidb/lists"}