Crate tikv_client

This crate provides an easy-to-use client for TiKV, a distributed, transactional key-value database written in Rust.

This crate lets you connect to a TiKV cluster and use either a transactional or raw (simple get/put style without transactional consistency guarantees) API to access and update your data.

The TiKV Rust client supports several levels of abstraction. The most convenient way to use the client is via RawClient and TransactionClient. This gives a very high-level API which mostly abstracts over the distributed nature of the store and has sensible defaults for all protocols. This interface can be configured, primarily when creating the client or transaction objects via the Config and TransactionOptions structs. Using some options, you can take over parts of the protocols (such as retrying failed messages) yourself.

The lowest level of abstraction is to create and send gRPC messages directly to TiKV (and PD) nodes. The tikv-client-store and tikv-client-pd crates make this easier than using the protobuf definitions and a gRPC library directly, but give you the same level of control.

In between these levels of abstraction, you can send and receive individual messages to the TiKV cluster, but take advantage of library code for common operations such as resolving data to regions and thus nodes in the cluster, or retrying failed messages. This can be useful for testing a TiKV cluster or for some advanced use cases. See the request module for this API, and raw::lowering and transaction::lowering for convenience methods for creating request objects.

Choosing an API

This crate offers both raw and transactional APIs. You should choose just one for your system.

The consequence of supporting transactions is increased overhead of coordination with the placement driver and TiKV, and additional code complexity.

While it is possible to use both APIs at the same time, doing so is unsafe and unsupported.

Transactional

The transactional API supports transactions via multi-version concurrency control (MVCC).

Best when you mostly do complex sets of actions, actions which may require a rollback, operations affecting multiple keys or values, or operations that depend on strong consistency.

Raw

The raw API has reduced coordination overhead, but lacks any transactional abilities.

Best when you mostly do single value changes, and have very limited cross-value requirements. You will not be able to use transactions with this API.

Usage

The general flow of using the client crate is to create either a raw or transaction client object (which can be configured) then send commands using the client object, or use it to create transactions objects. In the latter case, the transaction is built up using various commands and then committed (or rolled back).

Examples

Raw mode:

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

Transactional mode:

let txn_client = TransactionClient::new(vec!["127.0.0.1:2379"]).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?;

Modules

raw_lowering
request
transaction_lowering

Macros

shardable_keys
shardable_range

Structs

Backoff	When a request is retried, we can backoff for some time to avoid saturating the network.
BoundRange	A struct for expressing ranges. This type is semi-opaque and is not really meant for users to deal with directly. Most functions which operate on ranges will accept any types which implement Into<BoundRange>.
Config	The configuration for either a RawClient or a TransactionClient.
Key	The key part of a key/value pair.
KvPair	A key/value pair.
RawClient	The TiKV raw Client is used to interact with TiKV using raw requests.
RetryOptions
SecurityManager	Manages the TLS protocol
Snapshot	A read-only transaction which reads at the given timestamp.
Timestamp
Transaction	An undo-able set of actions on the dataset.
TransactionClient	The TiKV transactional Client is used to interact with TiKV using transactional requests.
TransactionOptions	Options for configuring a transaction.

Enums

CheckLevel	Determines what happens when a transaction is dropped without being rolled back or committed.
ColumnFamily	A ColumnFamily is an optional parameter for raw::Client requests.
Error	An error originating from the TiKV client or dependencies.

Traits

IntoOwnedRange	A convenience trait for converting ranges of borrowed types into a BoundRange.
TimestampExt	A helper trait to convert a Timestamp to and from an u64.

Type Definitions

Result	A result holding an Error.
Value	The value part of a key/value pair. An alias for Vec<u8>.