Distributed transactional key-value database, originally created to complement TiDB

yiwu-arbug fa032cb1fb engine: remove delete range extend key hack (#4526) 1 day ago
.circleci 1f597c99e1 Fix CI by installing tarpaulin from git, so that Cargo.lock is not ignored (#3590) 7 months ago
.github 17a50340a1 .github: ask for the TiKV instead of rustc version in bug-report template (#4488) 2 weeks ago
benches 2837dd45b2 Use `KeyBuilder` to reduce memory allocation and copy for bound key (#4537) 2 days ago
ci-build 4a2700b87f Change Copyright holders to the TiKV Authors (#4438) 1 week ago
components fa032cb1fb engine: remove delete range extend key hack (#4526) 1 day ago
docker c3d31b3c00 *: Update the tikv repo link (#3576) 7 months ago
docs 91b2ed347e Update roadmap (#4487) 1 week ago
etc 7d9540c7f3 import: wait all scatter region finished before importing (#4423) 6 days ago
fuzz 8dae71abe2 *: move util as a component (#4504) 1 week ago
images 789007eb88 readme: add TiKV logo and CNCF announcement (#3812) 5 months ago
scripts a8accfee9e scripts: Don't cp -b (#4465) 2 weeks ago
src 2837dd45b2 Use `KeyBuilder` to reduce memory allocation and copy for bound key (#4537) 2 days ago
tests b3a5d7b54f config: make properties index distance configurable (#4517) 5 days ago
.dockerignore 7315140a1a produce an Alpine Linux image (#3697) 6 months ago
.gitignore 2b0296b7c7 Cargo profiles with faster compile times (#4415) 3 weeks ago
CHANGELOG.md c92984bd78 Bump to 3.0.0-beta.1 (#4432) 4 weeks ago
CODE_COMMENT_STYLE.md 734d572233 re-add comment style guide for merge (#4259) 1 month ago
CODE_OF_CONDUCT.md 42eb6a0719 Create CODE_OF_CONDUCT.md (#4216) 2 months ago
CONTRIBUTING.md 1907900174 *: update contributing guide (#4325) 1 month ago
Cargo.lock 2837dd45b2 Use `KeyBuilder` to reduce memory allocation and copy for bound key (#4537) 2 days ago
Cargo.toml 545e47950c use tokio threadpool and thread local metrics for readpool (#4486) 1 week ago
Dockerfile 7315140a1a produce an Alpine Linux image (#3697) 6 months ago
GOVERNANCE.md 3f10327e64 Add governance (#4261) 1 month ago
Jenkinsfile 1159ac6e78 Jenkinsfile: init adding Jenkinsfile (#1835) 1 year ago
LICENSE 661af2a4dd *: add license 3 years ago
MAINTAINERS.md 123282f748 Add @sunxiaoguang to MAINTAINERS.md (#4397) 4 weeks ago
Makefile 1be65221e8 Upgrade tcmalloc-rs to 0.3 (#4516) 1 week ago
README.md 4c59e584d0 remove repeated content (#4529) 1 week ago
rust-toolchain 89a470a881 Miscellaneous tidying up (#4300) 1 month ago

README.md

tikv_logo

Build Status Coverage Status GitHub release CII Best Practices

TiKV ("Ti" stands for Titanium) is an open source distributed transactional key-value database. Unlike other traditional NoSQL systems, TiKV not only provides classical Key-Value APIs, but also transactional APIs with ACID compliance. Built in Rust and powered by Raft, TiKV was originally created to complement TiDB, a distributed HTAP database compatible with the MySQL protocol.

The design of TiKV is inspired by some great distributed systems from Google, such as BigTable, Spanner, and Percolator, and some of the latest achievements in the academia in recent years, such as the Raft consensus algorithm.

cncf_logo

TiKV is hosted by the Cloud Native Computing Foundation (CNCF). If you are an organization that wants to help shape the evolution of technologies that are container-packaged, dynamically-scheduled and microservices-oriented, consider joining the CNCF. For details about who's involved and how TiKV plays a role, read the CNCF announcement.


With the implementation of the Raft consensus algorithm in Rust and consensus state stored in RocksDB, TiKV guarantees data consistency. Placement Driver (PD), which is introduced to implement auto-sharding, enables automatic data migration. The transaction model is similar to Google's Percolator with some performance improvements. TiKV also provides snapshot isolation (SI), snapshot isolation with lock (SQL: SELECT ... FOR UPDATE), and externally consistent reads and writes in distributed transactions.

TiKV has the following key features:

  • Geo-Replication

    TiKV uses Raft and the Placement Driver to support Geo-Replication.

  • Horizontal scalability

    With PD and carefully designed Raft groups, TiKV excels in horizontal scalability and can easily scale to 100+ TBs of data.

  • Consistent distributed transactions

    Similar to Google's Spanner, TiKV supports externally-consistent distributed transactions.

  • Coprocessor support

    Similar to Hbase, TiKV implements a coprocessor framework to support distributed computing.

  • Cooperates with TiDB

    Thanks to the internal optimization, TiKV and TiDB can work together to be a compelling database solution with high horizontal scalability, externally-consistent transactions, support for RDBMS, and NoSQL design patterns.

TiKV Adopters

You can view the list of TiKV Adopters.

TiKV Roadmap

You can see the TiKV Roadmap.

TiKV software stack

The TiKV software stack

  • Placement Driver: PD is the cluster manager of TiKV, which periodically checks replication constraints to balance load and data automatically.
  • Store: There is a RocksDB within each Store and it stores data into the local disk.
  • Region: Region is the basic unit of Key-Value data movement. Each Region is replicated to multiple Nodes. These multiple replicas form a Raft group.
  • Node: A physical node in the cluster. Within each node, there are one or more Stores. Within each Store, there are many Regions.

When a node starts, the metadata of the Node, Store and Region are recorded into PD. The status of each Region and Store is reported to PD regularly.

Try TiKV

TiKV was originally a component of TiDB. To run TiKV you must build and run it with PD, which is used to manage a TiKV cluster. You can use TiKV together with TiDB or separately on its own.

We provide multiple deployment methods, but it is recommended to use our Ansible deployment for production environment. The TiKV documentation is available on TiKV's wiki page.

Testing deployment

Production deployment

For the production environment, use Ansible to deploy the cluster.

Client drivers

Currently, the only interface to TiKV is the TiDB Go client and the TiSpark Java client.

If you want to try the Go client, see Try Two Types of APIs.

Setting up a development workspace

The TiKV codebase is primarily written in Rust, but has components written in C++ (RocksDB) and Go (gRPC). To provide consistency and avoid opinion-based arguments, we make extensive use of linters and automated formatting tools. Additionally, due to Rust's youth we are currently utilizing nightly builds which provide access to many useful features.

Checking your prerequisites

To build TiKV you'll need to at least have the following installed:

  • git - Version control
  • rustup - Rust toolchain manager
  • awk - Pattern scanning/processing language
  • cmake - Build tool (required for gRPC)
  • go - Programming language (required for gRPC)
  • make - Build tool (run common workflows)
  • clang or gcc - C compiler toolchain

Getting the repository

git clone https://github.com/tikv/tikv.git
cd tikv
# Future instructions assume you are in this repository

Configuring your Rust toolchain

rustup is an official toolchain manager for Rust, similar to rvm or rbenv from the Ruby world.

TiKV uses the version of the Rust toolchain specified in rust-toolchain. rustup and cargo will automatically utilize this file. We also make use of the rustfmt and clippy components.

rustup component add rustfmt-preview

Building & testing

While TiKV includes a Makefile with common workflows, you are also able to use cargo as you would in a normal Rust project.

At this point, you can build TiKV:

make build

During interactive development, you may prefer using cargo check, which will do parse, borrow check, and lint run on your code, but not actually compile it. It is particularly handy alongside cargo-watch which will run a command each time you change a file.

cargo install cargo-watch
cargo watch -s "cargo check"

When you're ready to test out your changes, use the dev task. It will format your codebase, build with clippy enabled, and run tests. This should run without failure before you create a PR.

make dev

You can run the full test suite locally, or just run a specific test:

# Run the full suite
make test
# Run a specific test
cargo test $TESTNAME

Our CI systems automatically test all the pull requests, so making sure the full suite passes the test before creating your PR is not strictly required. All merged PRs must have passed CI test.

Getting the rest of the system working

To get other components (TiDB and PD) working, we suggest you follow the development guide, because you need the pd-server at least to work alongside tikv-server for integration level testing.

Configuration

Read our configuration guide to learn about various configuration options.

Contributing

Contributions are welcome! See CONTRIBUTING for details on submitting patches and the contribution workflow.

For beginners, we have prepared many suitable tasks for you. Checkout our Help Wanted issues for a list, in which we have also marked the difficulty level.

If you are planning something big, for example, relates to multiple components or changes current behaviors, make sure to open an issue to discuss with us before going on.

The TiKV team actively develops and maintains a bunch of dependencies used in TiKV, which you may be also interested in:

  • rust-prometheus: The Prometheus client for Rust, our metrics collecting and reporting library
  • rust-rocksdb: Our RocksDB binding and wrapper for Rust
  • raft-rs: The Raft distributed consensus algorithm implemented in Rust
  • grpc-rs: The gRPC library for Rust built on the gRPC C Core library and Rust Futures
  • fail-rs: Fail points for Rust

Communication

Communication within the TiKV community abides by TiKV Code of Conduct. Here is an excerpt:

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

Socia Media

Slack

Join the TiKV community on Slack - Sign up and join channels on TiKV topics that interest you.

WeChat

The TiKV community is also available on WeChat, a very popular messaging and social media application in China. If you want to join our WeChat group, send a request mail to zhangyanqing@pingcap.com, with your personal information that includes the following:

  • WeChat ID (Required)
  • PR you submitted to TiKV Repos (Required)
  • Other basic information

We will invite you in right away.

License

TiKV is under the Apache 2.0 license. See the LICENSE file for details.

Acknowledgments

  • Thanks etcd for providing some great open source tools.
  • Thanks RocksDB for their powerful storage engines.
  • Thanks rust-clippy. We do love the great project.