TiKV客户端（Rust）

本crate提供了一个易于使用的TiKV客户端，TiKV是一个用Rust编写的分布式、事务性键值数据库。

本crate允许您连接到TiKV(>= v5.0.0)集群，并使用事务性或原始（简单get/put风格，不保证事务一致性）API访问和更新数据。

TiKV Rust客户端是一个由TiKV作者维护的开源（Apache 2）项目。我们欢迎贡献，更多信息请见下文。

请注意，当前版本不适合生产使用 - API尚不稳定，crate尚未在实际应用中进行彻底测试。

入门

TiKV客户端是一个Rust库（crate）。要在项目中使用此crate，请在您的Cargo.toml中添加以下依赖项

[dependencies]
tikv-client = "0.3"

先决条件

• rust >= 1.56.1，这是hashbrown-v0.12.1所需的

使用客户端crate的一般流程是创建一个原始或事务客户端对象（可以进行配置），然后使用客户端对象发送命令，或者使用它创建事务对象。在后一种情况下，事务是通过各种命令构建的，然后提交（或回滚）。

示例

原始模式

use tikv_client::RawClient;

let client = RawClient::new(vec!["127.0.0.1:2379"], None).await?;
client.put("key".to_owned(), "value".to_owned()).await?;
let value = client.get("key".to_owned()).await?;

事务模式

use tikv_client::TransactionClient;

let txn_client = TransactionClient::new(vec!["127.0.0.1:2379"], None).await?;
let mut txn = txn_client.begin_optimistic().await?;
txn.put("key".to_owned(), "value".to_owned()).await?;
let value = txn.get("key".to_owned()).await?;
txn.commit().await?;

由于TiKV客户端提供了异步API，您需要使用异步运行时（我们目前只支持Tokio）。有关完整示例，请参阅getting-started.md。

API摘要

TiKV Rust客户端支持多个抽象级别。使用客户端最方便的方式是通过RawClient和TransactionClient。这提供了一个非常高级的API，主要抽象了存储的分布式特性，并为所有协议提供了合理的默认值。该接口可以配置，主要是在创建客户端或事务对象时通过Config和TransactionOptions结构体进行。使用一些选项，您可以自己接管协议的部分（例如重试失败的消息）。

最低级别的抽象是直接创建并发送gRPC消息到TiKV（和PD）节点。`tikv-client-store`和`tikv-client-pd`crate使得比直接使用protobuf定义和gRPC库更简单，但提供了相同级别的控制。

在这两个抽象级别之间，您可以向TiKV集群发送和接收单个消息，但可以利用库代码执行常见操作，例如将数据解析到区域和集群中的节点，或重试失败的消息。这可以用于测试TiKV集群或某些高级用例。请参阅此API的client_rust::request模块，以及client_rust::raw::lowering和client_rust::transaction::lowering模块以获取创建请求对象的便利方法。

本文件的其余部分仅描述RawClient/TransactionClient API。

重要提示：不建议或支持在同一个数据库上同时使用原始和事务API。

类型

Key：存储中的键。String和Vec<u8>实现了Into<Key>，因此您可以直接将它们传递给客户端函数。

Value：存储中的值；是Vec<u8>的别名。

KvPair：一个键和值的对。它提供了转换到和从其他类型的便利方法。

BoundRange：用于范围相关请求，如scan。它实现了Rust范围中的From，因此您可以传递Rust键范围到请求中，例如，client.delete_range(vec![]..)。

原始请求

事务性请求

开发和贡献

我们欢迎您的贡献！贡献代码是很好的，我们也感谢提交问题以识别错误和提供反馈，添加测试或示例，以及改进文档。

构建和测试

我们使用标准的Cargo工作流程，例如，使用cargo build进行构建和使用cargo test/nextest运行单元测试。您需要使用夜间Rust工具链来构建和运行测试。可以使用nextest来加快ut，首先安装nextest。

cargo install cargo-nextest --locked

运行集成测试或手动使用TiKV集群测试客户端稍微复杂一些。最简单的方法是使用TiUp (>= 1.5) 在您的本地机器上初始化集群

tiup playground nightly --mode tikv-slim

然后如果您想运行集成测试

PD_ADDRS="127.0.0.1:2379" cargo test --package tikv-client --test integration_tests --features integration-tests

创建PR

我们使用标准的GitHub PR工作流程。我们在每个PR上运行CI，并要求所有PR构建时没有警告（包括clippy和Rustfmt警告），通过测试，有DCO签名（在提交时使用-s，DCO机器人将指导您完成第一个PR的DCO协议），并且至少有一个审阅。如果您在这方面的任何方面有困难，请不要担心，在PR上询问。

要在本地运行类似CI的测试，我们建议您在提交PR之前运行cargo clippy、cargo test/nextest run和cargo fmt。有关运行集成测试的说明，但您可能不需要在您的前几个PR上担心这一点。

请遵循PingCAP的Rust风格指南。所有代码PR都应包括新测试或测试用例。

获取帮助

如果您需要帮助，无论是寻找要工作的内容，还是遇到任何技术问题，最简单的方法是通过internals.tidb.io，这是TiDB开发者的论坛。

您也可以在Slack上提问。我们监视tikv-wg slack上的#client-rust频道。

您可以直接在GitHub issues或PR中提问；如果您没有收到回复，您应该ping @ekexium或@andylokandy。