TiKV: A Distributed Transactional Key-Value Store Built on Raft and RocksDB

What TiKV solves, and who ends up running it

A single-machine key-value store stops being an option once the dataset outgrows one disk or the service cannot tolerate losing one host. TiKV addresses that by replicating key-value ranges across nodes with Raft and keeping the data on local RocksDB instances. The README describes it as an open-source, distributed, transactional key-value database, and notes it provides both classical key-value APIs and transactional APIs with ACID compliance. That second part is the differentiator against plain NoSQL stores, which typically give you replication without cross-key transactions.

The intended audience is narrow. TiKV was originally created by PingCAP to complement TiDB, the MySQL-compatible HTAP database, so the default reason to run TiKV is that you are running TiDB. Running TiKV standalone is supported, and the README calls PD plus TiKV the minimal deployment, but standalone means you are writing against a key-value API rather than SQL. Teams that want SQL should look at the TiDB layer instead of treating TiKV as a database they query directly.

Regions, Raft groups and the Placement Driver

The architecture has four named levels in the README's software stack: Placement Driver, Store, Region and Node. A Node is a physical machine. Each node holds one or more Stores, and each Store holds a RocksDB instance writing to the local disk. Data is split into Regions, and each Region is replicated to multiple nodes, with those replicas forming a Raft group.

PD is the cluster manager. It periodically checks replication constraints and balances load and data automatically. When a node starts, the metadata of the Node, Store and Region is recorded into PD, and the status of each Region and Store is reported back to PD regularly. That makes PD a dependency of the data path's control plane: without it, placement decisions stop. The README states that PD is introduced to implement auto-sharding and enables automatic data migration, and that TiKV uses Raft and PD to support geo-replication.

Consensus state itself lives in RocksDB, which is how the README explains the consistency guarantee. The transaction model is described as similar to Google's Percolator with performance improvements, and TiKV provides snapshot isolation, snapshot isolation with lock for SQL SELECT ... FOR UPDATE, and externally consistent reads and writes in distributed transactions. The README also cites BigTable, Spanner and Percolator as design influences, and HBase as the comparison point for the coprocessor framework used for distributed computing.

Installing TiKV and running a first read and write

The README gives two quick-start paths: TiUP, described as the quickest way to try TiKV with TiDB, and a manual binary deployment. The manual path is the one that shows what a minimal cluster actually looks like, so it is worth reading even if you later use TiUP.

First you download and extract the TiKV and PD binaries. The README's example pins TIKV_VERSION to v7.5.0, and only darwin and linux are listed for GOOS, with amd64 and arm64 for GOARCH.

export TIKV_VERSION=v7.5.0
export GOOS=darwin  # only {darwin, linux} are supported
export GOARCH=amd64 # only {amd64, arm64} are supported
curl -O  https://tiup-mirrors.pingcap.com/tikv-$TIKV_VERSION-$GOOS-$GOARCH.tar.gz
curl -O  https://tiup-mirrors.pingcap.com/pd-$TIKV_VERSION-$GOOS-$GOARCH.tar.gz
tar -xzf tikv-$TIKV_VERSION-$GOOS-$GOARCH.tar.gz
tar -xzf pd-$TIKV_VERSION-$GOOS-$GOARCH.tar.gz

Next, start PD. This is the single-node form the README uses, with the client API on port 2379 and peer communication on 2380.

./pd-server --name=pd --data-dir=/tmp/pd/data --client-urls="http://127.0.0.1:2379" --peer-urls="http://127.0.0.1:2380" --initial-cluster="pd=http://127.0.0.1:2380" --log-file=/tmp/pd/log/pd.log

Then start TiKV against that PD endpoint, listening on port 20160.

export TIKV_VERSION=v7.5.0
./tikv-server --pd-endpoints="127.0.0.1:2379" --addr="127.0.0.1:20160" --data-dir=/tmp/tikv/data --log-file=/tmp/tikv/log/tikv.log

To verify the deployment, the README uses the Python client, which requires Python 3.5 or later and is installed from a test index.

pip3 install -i https://test.pypi.org/simple/ tikv-client

The client example connects to PD, writes a key and reads it back, then overwrites the same key. The comments in the README show b'bar' after the first get and b'baz' after the second.

from tikv_client import RawClient

client = RawClient.connect(["127.0.0.1:2379"])

client.put(b'foo', b'bar')
print(client.get(b'foo')) # b'bar'

client.put(b'foo', b'baz')
print(client.get(b'foo')) # b'baz'

For a full cluster, the repository ships a docker-compose.yml with three PD nodes and three TiKV nodes, described in the README as the easiest way to run a complete TiKV cluster for development. The compose file maps PD client ports 23791, 23792 and 23793 to 2379 inside each container, and peer ports 23801, 23802 and 23803 to 2380, with healthchecks hitting /pd/api/v1/health.

Where TiKV is the wrong tool

The first limitation is operational weight. Even the minimal deployment is two processes, PD and TiKV, with PD owning placement and sharding. A single-node cache or an embedded store has no equivalent of this, and adding PD to a small service buys you a control plane you now have to keep alive. The README's own framing supports this: it calls PD plus TiKV the minimal deployment, not a trivial one.

The second limitation is that TiKV is not a SQL database. It exposes key-value and transactional APIs. If your team's mental model is tables and joins, the README points you at TiDB, which is MySQL-protocol compatible and uses TiKV underneath. Choosing TiKV directly means writing range scans and transactions by hand.

The third is version skew between PD and TiKV. The README's binary example pins a single TIKV_VERSION variable used for both the TiKV and PD tarballs, which is a hint that the two are expected to move together. The repository's Cargo.toml declares version 9.0.0-beta.2 while the most recent listed releases are v7.5.8 and v8.5.8, so the version you build from master and the version you deploy from a release tarball are not the same thing. Nothing in the README documents rollback or downgrade, so treat upgrade planning as an open question you must answer from the website documentation rather than from the repository front page.

Finally, the Python client in the quick start is installed from https://test.pypi.org/simple/, a test index. That is fine for a first smoke test and a poor basis for a production dependency decision.

TiKV compared with FoundationDB and Redis

FoundationDB is the closest structural comparison, and the difference is in how much is handed to you. TiKV ships a transaction model the README describes as similar to Google's Percolator with performance improvements, and it ships a coprocessor framework similar to HBase's for pushing computation to the storage layer. A bare ordered key-value store leaves transaction semantics and pushdown to the layer above it. TiKV also bundles the placement and rebalancing logic into PD, which the README describes as periodically checking replication constraints to balance load and data automatically. That is a component you operate, not a library you link.

The Redis comparison is a category error that people make anyway. Redis is primarily an in-memory data structure server; TiKV stores data in RocksDB on local disk and replicates Regions through Raft. The README's feature list is about geo-replication, horizontal scalability to 100+ TBs with PD and Raft groups, externally consistent distributed transactions, and coprocessor support. Those are durability and scale properties, not latency properties. If your access pattern is sub-millisecond reads of ephemeral values, none of TiKV's design goals apply to you.

Licence, maintenance and the cost of staying current

TiKV is licensed under Apache-2.0, declared both in the repository metadata and in Cargo.toml. That is a permissive licence, and it is the same licence family as much of the surrounding Rust and CNCF ecosystem. It is not legal advice: if you redistribute TiKV inside a product or modify it, read the LICENSE file and your own counsel's guidance rather than relying on this paragraph.

The project is a graduated CNCF project, and the repository is not archived. The last push to the default branch was on 2026-09-21, and the most recent listed release is v7.5.8 from 2026-09-17, with v8.5.8 from 2026-08-27 before it. Two release lines are being maintained in parallel, which is a real upgrade cost: you have to decide which line you are on and whether you intend to move. The README does not document a downgrade path, and the repository front page does not describe a supported migration procedure, so that work belongs to the website documentation and to your own testing.

Building from source is a third cost. Cargo.toml sets publish = false, so this is not a crate you pull from crates.io. The Dockerfile shows the build environment: Rocky Linux 8.10, protoc v3.15.8, and a rustup install with --default-toolchain none, followed by ROCKSDB_SYS_STATIC=1 make dist_release. The Makefile notes that frame pointers are enabled by default and that enabling them means the Rust standard library will be recompiled, which makes the first build slower than a typical Rust project. The Makefile also documents a dev rule as the one that must pass before submitting a pull request, running tests and static analysis including clippy and rustfmt.

Editorial conclusion

Adopt TiKV when you need ACID transactions over a key-value store that must survive node loss and grow past a single machine, and when you accept running PD alongside it. Do not adopt it for single-node caching, embedded storage, or a workload that only needs a simple key-value API. Before committing, verify the PD and TiKV version pair you intend to run, since the README's binary example pins TIKV_VERSION to v7.5.0, and confirm which client library you will use, because the Python client shown is installed from a test PyPI index.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. tikv/tikv on GitHub