Struct TransactionClient 

pub struct TransactionClient { /* private fields */ }

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: Into<String>>(pd_endpoints: Vec<S>) -> Result<Client>

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: Into<String>>( pd_endpoints: Vec<S>, config: Config, ) -> Result<Client>

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 new_with_config_api_v2_no_prefix<S: Into<String>>( pd_endpoints: Vec<S>, config: Config, ) -> Result<Client>

Create a transactional Client that uses API V2 without adding or removing any API V2 keyspace/key-mode prefix, with a custom configuration.

This is intended for server-side embedding use cases. config.keyspace must be unset.

pub async fn begin_optimistic(&self) -> Result<Transaction>

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>

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>

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>

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>

Request garbage collection (GC) of the TiKV cluster.

GC deletes MVCC records whose timestamp is lower than the given safepoint. We must guarantee that all transactions started before this timestamp had committed. We can keep an active transaction list in application to decide which is the minimal start timestamp of them.

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.

pub async fn cleanup_locks( &self, range: impl Into<BoundRange>, safepoint: &Timestamp, options: ResolveLocksOptions, ) -> Result<CleanupLocksResult>

pub async fn scan_locks( &self, safepoint: &Timestamp, range: impl Into<BoundRange>, batch_size: u32, ) -> Result<Vec<ProtoLockInfo>>

pub async fn resolve_locks( &self, locks: Vec<ProtoLockInfo>, timestamp: Timestamp, backoff: Backoff, ) -> Result<Vec<ProtoLockInfo>>

Resolves the given locks and returns any that remain live.

This method retries until either all locks are resolved or the provided backoff is exhausted. The timestamp is used as the caller start timestamp when checking transaction status.

pub async fn unsafe_destroy_range( &self, range: impl Into<BoundRange>, ) -> Result<()>

Cleans up all keys in a range and quickly reclaim disk space.

The range can span over multiple regions.

Note that the request will directly delete data from RocksDB, and all MVCC will be erased.

This interface is intended for special scenarios that resemble operations like “drop table” or “drop database” in TiDB.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.