Crate tikv_client

source ·
Expand description

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

  • backoff
  • codec
  • raw_lowering
    This module provides constructor functions for requests which take arguments as high-level types (i.e., the types from the client crate) and converts these to the types used in the generated protobuf code, then calls the low-level ctor functions in the requests module.
  • request
  • transaction_lowering

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

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 Aliases

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