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
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
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)
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
convenience methods for creating request objects.
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.
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.
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.
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).
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?;
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?;
When a request is retried, we can backoff for some time to avoid saturating the network.
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
The key part of a key/value pair.
A key/value pair.
The TiKV raw
Manages the TLS protocol
A read-only transaction which reads at the given timestamp.
An undo-able set of actions on the dataset.
The TiKV transactional
Options for configuring a transaction.
Determines what happens when a transaction is dropped without being rolled back or committed.
An error originating from the TiKV client or dependencies.
A convenience trait for converting ranges of borrowed types into a
A helper trait to convert a Timestamp to and from an u64.
A result holding an
The value part of a key/value pair. An alias for