BonsaiDb

BonsaiDb 是一个针对 Rust 的开发者友好的文档数据库，它随着你的成长而成长。它提供了许多开箱即用的功能，许多开发者都需要这些功能

• ACID 兼容的 集合 事务存储
• 原子性键值存储，具有可配置的延迟持久性（类似于 Redis）
• 静止加密
• 备份/恢复
• 基于角色的访问控制 (RBAC)
• 仅本地访问，通过 QUIC 网络访问或通过 WebSocket 网络访问
• 还有更多。

⚠️ 项目状态

BonsaiDb 被视为 alpha 软件。它处于积极开发中（）。仍然可能存在导致数据丢失的漏洞。所有用户应定期备份其数据并测试从备份中恢复是否正确。

大约在 2022 年 5 月，发现了基准测试中的错误和错误。错误被迅速修复，但最终结果是 BonsaiDb 的交易写入性能明显低于其他数据库。除非你正在构建一个非常注重写入的应用程序，否则性能可能仍然可以接受。性能更新的进度可在 GitHub 上的 问题 #251 上跟踪。从开发者的角度来看，迁移预计将非常顺利，只需要复制旧数据库到新格式所需的 IO。

示例

为了了解它的工作原理，让我们回顾一下 view-examples 示例。有关所有可用示例的列表，请参阅 示例 README。

示例 view-examples 展示了如何定义一个包含单个集合（Shape）、一个通过 number_of_sides（ShapesByNumberOfSides）查询 Shape 的视图，并演示了多种查询该视图的方法的简单模式。

首先，这是如何定义模式的

#[derive(Debug, Serialize, Deserialize, Collection)]
#[collection(name = "shapes", views = [ShapesByNumberOfSides])]
struct Shape {
    pub sides: u32,
}

#[derive(Debug, Clone, View, ViewSchema)]
#[view(collection = Shape, key = u32, value = usize, name = "by-number-of-sides")]
struct ShapesByNumberOfSides;

impl CollectionMapReduce for ShapesByNumberOfSides {
    fn map<'doc>(&self, document: CollectionDocument<Shape>) -> ViewMapResult<'doc, 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())
    }
}

在定义了您的集合和视图之后，您可以打开数据库并插入文档

let db = Database::open::<Shape>(StorageConfiguration::new("view-examples.bonsaidb"))?;

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

然后使用 Map-Reduce 驱动的视图查询数据

let triangles = ShapesByNumberOfSides::entries(&db).with_key(&3).query()?;
println!("Number of triangles: {}", triangles.len());

您可以在仓库中查看完整的示例 https://github.com/khonsulabs/bonsaidb/blob/v0.5.0/examples/basic-local/examples/view-examples.rs，或者查看所有可用的示例 https://github.com/khonsulabs/bonsaidb/blob/v0.5.0/examples/README.md。

用户指南

我们的用户指南正处于开发初期，但可在以下位置找到：https://dev.bonsaidb.io/v0.5.0/guide/

支持的最低Rust版本（MSRV）

虽然此项目处于alpha阶段，但我们正在积极采用当前版本的Rust。当前最低版本是 1.70。

功能标志

bonsaidb 模块默认未启用任何功能标志。这是因为在大多数Rust可执行文件中，您只需要功能子集。如果您希望启用所有功能，可以使用 full 功能

[dependencies]
bonsaidb = { version = "*", features = "full" }

• full：启用以下功能和 local-full、server-full 和 client-full。
• cli：启用 bonsaidb 可执行文件。
• files：启用通过 bonsaidb-files 的文件存储支持
• password-hashing：启用使用 Argon2 通过 AnyConnection 使用密码认证的能力
• token-authentication：启用使用认证令牌进行认证的能力，这些令牌类似于API密钥

以下所有其他功能标志会影响各个crate，但可以安全地组合。

本地数据库

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

影响本地数据库的所有Cargo功能

• local-full：启用以下所有标志
• local：启用 local 模块，该模块重新导出 bonsaidb-local crate。
• async：启用与 Tokio 的异步支持
• cli：启用将数据库管理命令嵌入到您自己的命令行界面的 clap 结构
• compression：启用使用 lz4 的压缩存储支持
• encryption：启用静态加密
• instrument：启用使用 tracing 进行仪表化
• password-hashing：启用使用 Argon2 进行密码认证的能力
• token-authentication：启用使用认证令牌进行认证的能力，这些令牌类似于API密钥

BonsaiDb 服务器

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

影响网络服务器的所有Cargo功能

• server-full：启用以下所有标志
• server：启用 server 模块，该模块重新导出 bonsaidb-server crate。
• acme：启用通过 ACME/LetsEncrypt 自动获取证书
• cli：启用 cli 模块
• compression：启用使用 lz4 的压缩存储支持
• encryption：启用静态加密
• hyper：启用使用 hyper 升级 websockets 的便利函数
• instrument：启用使用 tracing 进行仪表化
• pem：启用使用 PEM 格式安装证书的能力
• websockets：启用 WebSocket 支持。
• password-hashing：启用使用 Argon2 进行密码认证的能力
• token-authentication：启用使用认证令牌进行认证的能力，这些令牌类似于API密钥

BonsaiDb 服务器的客户端

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

影响网络客户端的所有 Cargo 功能

• client-full：启用以下所有标志。
• client：启用 client 模块，该模块重新导出 bonsaidb-client 包。
• trusted-dns：启用使用 trust-dns 进行 DNS 解析。如果未启用，所有 DNS 解析都使用操作系统的默认名称解析器。
• websockets：为 bonsaidb-client 启用 WebSocket 支持。
• password-hashing：启用使用 Argon2 进行密码认证的能力
• token-authentication：启用使用认证令牌进行认证的能力，这些令牌类似于API密钥

BonsaiDb 的开发

编写单元测试

除非有充分的理由不这样做，BonsaiDb 中的每个功能都应该有彻底的单元测试。许多测试是通过在 bonsaidb_core::test_util 中使用宏实现的，该宏允许使用各种方法访问 BonsaiDb 来运行测试套件。

某些功能无法仅使用 Connection、StorageConnection、KeyValue 和 PubSub 特性进行测试。如果情况如此，您应该在最适合测试代码的任何包中添加测试。例如，如果这是一个只能在 bonsaidb-server 中使用的功能，则测试应位于 bonsaidb-server 包中。

需要客户端和服务器都的测试可以添加到 core-suite 测试文件中，位于 bonsaidb 包。

检查语法

我们使用 clippy 为我们的代码提供额外的指导。Clippy 应始终在启用或禁用功能标志时返回无错误。

cargo clippy --all-features

运行所有测试

我们的 CI 流程要求某些命令成功执行，无警告或错误。可以通过以下命令手动执行这些检查：

cargo xtask test --fail-on-warnings

或者，如果您希望在每次提交之前运行所有这些检查，您可以将检查作为预提交钩子安装

cargo xtask install-pre-commit-hook

代码格式化

我们有一个自定义的 rustfmt 配置，该配置启用仅在 nightly 构建中可用的选项。

cargo +nightly fmt

开源许可证

该项目，如同 Khonsu Labs 的所有项目一样，是开源的。此存储库在 MIT 许可证 或 Apache License 2.0 下提供。

要了解更多关于贡献的信息，请参阅 CONTRIBUTING.md。