Struct bb8_tivk::TransactionClient

pub struct TransactionClient { /* fields omitted */ }

The TiKV transactional Client is used to interact with TiKV using transactional requests.

Transactions support optimistic and pessimistic modes. For more details see the SIG-transaction docs.

Begin a Transaction by calling begin_optimistic or begin_pessimistic. A transaction must be rolled back or committed.

Besides transactions, the client provides some further functionality:

• gc: trigger a GC process which clears stale data in the cluster.
• current_timestamp: get the current Timestamp from PD.
• snapshot: get a Snapshot of the database at a specified timestamp. A Snapshot is a read-only transaction.

The returned results of transactional requests are Futures that must be awaited to execute.

Implementations

impl Client

pub async fn new<S>(pd_endpoints: Vec<S, Global>) -> Result<Client, Error> where
    S: Into<String>, 

Create a transactional Client and connect to the TiKV cluster.

Because TiKV is managed by a PD cluster, the endpoints for PD must be provided, not the TiKV nodes. It’s important to include more than one PD endpoint (include all endpoints, if possible), this helps avoid having a single point of failure.

Examples

let client = TransactionClient::new(vec!["192.168.0.100"]).await.unwrap();

pub async fn new_with_config<S>(
    pd_endpoints: Vec<S, Global>,
    config: Config
) -> Result<Client, Error> where
    S: Into<String>, 

Create a transactional Client with a custom configuration, and connect to the TiKV cluster.

Because TiKV is managed by a PD cluster, the endpoints for PD must be provided, not the TiKV nodes. It’s important to include more than one PD endpoint (include all endpoints, if possible), this helps avoid having a single point of failure.

Examples

let client = TransactionClient::new_with_config(
    vec!["192.168.0.100"],
    Config::default().with_timeout(Duration::from_secs(60)),
).await.unwrap();

pub async fn begin_optimistic(
    &'_ self
) -> Result<Transaction<PdRpcClient<TikvConnect, Cluster>>, Error>

Creates a new optimistic Transaction.

Use the transaction to issue requests like get or put.

Write operations do not lock data in TiKV, thus the commit request may fail due to a write conflict.

Examples

let client = TransactionClient::new(vec!["192.168.0.100"]).await.unwrap();
let mut transaction = client.begin_optimistic().await.unwrap();
// ... Issue some commands.
transaction.commit().await.unwrap();

pub async fn begin_pessimistic(
    &'_ self
) -> Result<Transaction<PdRpcClient<TikvConnect, Cluster>>, Error>

Creates a new pessimistic Transaction.

Write operations will lock the data until committed, thus commit requests should not suffer from write conflicts.

Examples

let client = TransactionClient::new(vec!["192.168.0.100"]).await.unwrap();
let mut transaction = client.begin_pessimistic().await.unwrap();
// ... Issue some commands.
transaction.commit().await.unwrap();

pub async fn begin_with_options(
    &'_ self,
    options: TransactionOptions
) -> Result<Transaction<PdRpcClient<TikvConnect, Cluster>>, Error>

Create a new customized Transaction.

Examples

let client = TransactionClient::new(vec!["192.168.0.100"]).await.unwrap();
let mut transaction = client
    .begin_with_options(TransactionOptions::default().use_async_commit())
    .await
    .unwrap();
// ... Issue some commands.
transaction.commit().await.unwrap();

pub fn snapshot(
    &self,
    timestamp: Timestamp,
    options: TransactionOptions
) -> Snapshot

Create a new Snapshot at the given Timestamp.

pub async fn current_timestamp(&'_ self) -> Result<Timestamp, Error>

Retrieve the current [Timestamp].

Examples

let client = TransactionClient::new(vec!["192.168.0.100"]).await.unwrap();
let timestamp = client.current_timestamp().await.unwrap();

pub async fn gc(&'_ self, safepoint: Timestamp) -> Result<bool, Error>

Request garbage collection (GC) of the TiKV cluster.

GC deletes MVCC records whose timestamp is lower than the given safepoint.

For each key, the last mutation record (unless it’s a deletion) before safepoint is retained.

GC is performed by:

1. resolving all locks with timestamp <= safepoint
2. updating PD’s known safepoint

This is a simplified version of GC in TiDB. We skip the second step “delete ranges” which is an optimization for TiDB.