tikv_client/lib.rs
1// Copyright 2018 TiKV Project Authors. Licensed under Apache-2.0.
2
3//! This crate provides an easy-to-use client for [TiKV](https://github.com/tikv/tikv), a
4//! distributed, transactional key-value database written in Rust.
5//!
6//! This crate lets you connect to a TiKV cluster and use either a transactional or raw (simple
7//! get/put style without transactional consistency guarantees) API to access and update your data.
8//!
9//! The TiKV Rust client supports several levels of abstraction. The most convenient way to use the
10//! client is via [`RawClient`] and [`TransactionClient`]. This gives a very high-level API which
11//! mostly abstracts over the distributed nature of the store and has sensible defaults for all
12//! protocols. This interface can be configured, primarily when creating the client or transaction
13//! objects via the [`Config`] and [`TransactionOptions`] structs. Using some options, you can take
14//! over parts of the protocols (such as retrying failed messages) yourself.
15//!
16//! The lowest level of abstraction is to create and send gRPC messages directly to TiKV (and PD)
17//! nodes. The `tikv-client-store` and `tikv-client-pd` crates make this easier than using the
18//! protobuf definitions and a gRPC library directly, but give you the same level of control.
19//!
20//! In between these levels of abstraction, you can send and receive individual messages to the TiKV
21//! cluster, but take advantage of library code for common operations such as resolving data to
22//! regions and thus nodes in the cluster, or retrying failed messages. This can be useful for
23//! testing a TiKV cluster or for some advanced use cases. See the [`request`] module for
24//! this API, and [`raw::lowering`] and [`transaction::lowering`] for
25//! convenience methods for creating request objects.
26//!
27//! ## Choosing an API
28//!
29//! This crate offers both [raw](RawClient) and
30//! [transactional](Transaction) APIs. You should choose just one for your system.
31//!
32//! The consequence of supporting transactions is increased overhead of coordination with the
33//! placement driver and TiKV, and additional code complexity.
34//!
35//! *While it is possible to use both APIs at the same time, doing so is unsafe and unsupported.*
36//!
37//! ### Transactional
38//!
39//! The [transactional](Transaction) API supports **transactions** via multi-version
40//! concurrency control (MVCC).
41//!
42//! Best when you mostly do complex sets of actions, actions which may require a rollback,
43//! operations affecting multiple keys or values, or operations that depend on strong consistency.
44//!
45//!
46//! ### Raw
47//!
48//! The [raw](RawClient) API has reduced coordination overhead, but lacks any
49//! transactional abilities.
50//!
51//! Best when you mostly do single value changes, and have very limited cross-value
52//! requirements. You will not be able to use transactions with this API.
53//!
54//! ## Usage
55//!
56//! The general flow of using the client crate is to create either a raw or transaction client
57//! object (which can be configured) then send commands using the client object, or use it to create
58//! transactions objects. In the latter case, the transaction is built up using various commands and
59//! then committed (or rolled back).
60//!
61//! ### Examples
62//!
63//! Raw mode:
64//!
65//! ```rust,no_run
66//! # use tikv_client::{RawClient, Result};
67//! # use futures::prelude::*;
68//! # fn main() -> Result<()> {
69//! # futures::executor::block_on(async {
70//! let client = RawClient::new(vec!["127.0.0.1:2379"]).await?;
71//! client.put("key".to_owned(), "value".to_owned()).await?;
72//! let value = client.get("key".to_owned()).await?;
73//! # Ok(())
74//! # })}
75//! ```
76//!
77//! Transactional mode:
78//!
79//! ```rust,no_run
80//! # use tikv_client::{TransactionClient, Result};
81//! # use futures::prelude::*;
82//! # fn main() -> Result<()> {
83//! # futures::executor::block_on(async {
84//! let txn_client = TransactionClient::new(vec!["127.0.0.1:2379"]).await?;
85//! let mut txn = txn_client.begin_optimistic().await?;
86//! txn.put("key".to_owned(), "value".to_owned()).await?;
87//! let value = txn.get("key".to_owned()).await?;
88//! txn.commit().await?;
89//! # Ok(())
90//! # })}
91//! ```
92
93#![allow(clippy::field_reassign_with_default)]
94
95pub mod backoff;
96#[doc(hidden)]
97pub mod raw;
98pub mod request;
99#[doc(hidden)]
100pub mod transaction;
101
102mod common;
103mod compat;
104mod config;
105mod kv;
106mod pd;
107mod proto;
108mod region;
109mod region_cache;
110mod stats;
111mod store;
112mod timestamp;
113mod util;
114
115#[cfg(test)]
116mod mock;
117#[cfg(test)]
118mod proptests;
119
120#[doc(inline)]
121pub use common::security::SecurityManager;
122#[doc(inline)]
123pub use common::Error;
124#[doc(inline)]
125pub use common::ProtoKeyError;
126#[doc(inline)]
127pub use common::ProtoRegionError;
128#[doc(inline)]
129pub use common::Result;
130#[doc(inline)]
131pub use config::Config;
132
133#[doc(inline)]
134pub use crate::backoff::Backoff;
135#[doc(inline)]
136pub use crate::kv::BoundRange;
137#[doc(inline)]
138pub use crate::kv::IntoOwnedRange;
139#[doc(inline)]
140pub use crate::kv::Key;
141#[doc(inline)]
142pub use crate::kv::KvPair;
143#[doc(inline)]
144pub use crate::kv::Value;
145#[doc(inline)]
146pub use crate::raw::lowering as raw_lowering;
147#[doc(inline)]
148pub use crate::raw::Client as RawClient;
149#[doc(inline)]
150pub use crate::raw::ColumnFamily;
151#[doc(inline)]
152pub use crate::request::RetryOptions;
153#[doc(inline)]
154pub use crate::timestamp::Timestamp;
155#[doc(inline)]
156pub use crate::timestamp::TimestampExt;
157#[doc(inline)]
158pub use crate::transaction::lowering as transaction_lowering;
159#[doc(inline)]
160pub use crate::transaction::CheckLevel;
161#[doc(inline)]
162pub use crate::transaction::Client as TransactionClient;
163#[doc(inline)]
164pub use crate::transaction::ProtoLockInfo;
165#[doc(inline)]
166pub use crate::transaction::Snapshot;
167#[doc(inline)]
168pub use crate::transaction::Transaction;
169#[doc(inline)]
170pub use crate::transaction::TransactionOptions;