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> 的别名。

cargo install cargo-nextest --locked

tiup playground nightly --mode tikv-slim

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