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 proto; // export `proto` to enable user customized codec
98#[doc(hidden)]
99pub mod raw;
100pub mod request;
101#[doc(hidden)]
102pub mod transaction;
103
104mod common;
105mod compat;
106mod config;
107mod kv;
108mod pd;
109mod region;
110mod region_cache;
111mod stats;
112mod store;
113mod timestamp;
114mod util;
115
116#[cfg(test)]
117mod mock;
118#[cfg(test)]
119mod proptests;
120
121#[doc(inline)]
122pub use common::security::SecurityManager;
123#[doc(inline)]
124pub use common::Error;
125#[doc(inline)]
126pub use common::Result;
127#[doc(inline)]
128pub use config::Config;
129
130#[doc(inline)]
131pub use crate::backoff::Backoff;
132#[doc(inline)]
133pub use crate::kv::BoundRange;
134#[doc(inline)]
135pub use crate::kv::IntoOwnedRange;
136#[doc(inline)]
137pub use crate::kv::Key;
138#[doc(inline)]
139pub use crate::kv::KvPair;
140#[doc(inline)]
141pub use crate::kv::Value;
142#[doc(inline)]
143pub use crate::raw::lowering as raw_lowering;
144#[doc(inline)]
145pub use crate::raw::Client as RawClient;
146#[doc(inline)]
147pub use crate::raw::ColumnFamily;
148#[doc(inline)]
149pub use crate::request::codec;
150#[doc(inline)]
151pub use crate::request::RetryOptions;
152#[doc(inline)]
153pub use crate::timestamp::Timestamp;
154#[doc(inline)]
155pub use crate::timestamp::TimestampExt;
156#[doc(inline)]
157pub use crate::transaction::lowering as transaction_lowering;
158#[doc(inline)]
159pub use crate::transaction::CheckLevel;
160#[doc(inline)]
161pub use crate::transaction::Client as TransactionClient;
162#[doc(inline)]
163pub use crate::transaction::Snapshot;
164#[doc(inline)]
165pub use crate::transaction::Transaction;
166#[doc(inline)]
167pub use crate::transaction::TransactionOptions;