TiKV is a distributed, transactional key-value database. It stores an ordered map of keys to values, splits that keyspace into small ranges called Regions, replicates each Region with the Raft consensus protocol, and spreads the Regions across many machines, so capacity and throughput grow by adding nodes. It addresses the point at which a single database server runs out of room: it offers strong consistency, automatic rebalancing and ACID transactions across keys without manual sharding. TiKV was created by PingCAP as the storage engine of the TiDB SQL database, was accepted into the CNCF in August 2018 and graduated on September 2, 2020. It is used as the storage layer under TiDB and, through its own client APIs, as a database in its own right.
CNCF daily · Sprint 3, post 3 of 21 · Database
At a glance
| Category | App Definition and Development › Database |
| CNCF status | Graduated. Accepted August 28, 2018; graduated September 2, 2020 |
| Written in | Rust |
| License | Apache 2.0 |
| Data model | Ordered key-value pairs, divided into Regions that are replicated with Raft |
| APIs | RawKV for single-key operations, and a transactional API (TxnKV) with distributed transactions |
| Storage engine | RocksDB on each node |
| Cluster metadata | Placement Driver (PD), which also issues cluster-wide timestamps |
| Clients | Go, Java, Rust, Python and C++ clients; TiDB for SQL |
Architecture
flowchart TB
CLI[Client application<br/>Go, Java or Rust client] ==>|ask where is key X<br/>and get a timestamp| PD[Placement Driver<br/>metadata and timestamps]
CLI ==>|read write prewrite commit<br/>gRPC| TK1[TiKV node 1]
CLI ==> TK2[TiKV node 2]
CLI ==> TK3[TiKV node 3]
TK1 -.->|Raft replication<br/>per Region| TK2
TK2 -.->|Raft replication| TK3
TK3 -.->|Raft replication| TK1
TK1 ==>|local storage| ROC[RocksDB<br/>on local disk]
TK1 -.->|heartbeats and Region stats| PD
PD -.->|split merge move leaders<br/>scheduling commands| TK2
TIDB[TiDB SQL layer<br/>optional] ==>|key value requests| CLI
classDef core fill:#0f766e,stroke:#064e4a,stroke-width:2px,color:#ffffff
classDef data fill:#e3f2fd,stroke:#1565c0,stroke-width:1.5px,color:#1d1c1a
classDef ctrl fill:#ede7f6,stroke:#5e35b1,stroke-width:1.5px,color:#1d1c1a
class TK1,TK2,TK3,PD core
class CLI,ROC data
class TIDB ctrl
Key: teal blocks are TiKV cluster components, blue are the client and local storage, purple is the optional SQL layer. Thick arrows carry client requests, dashed arrows carry replication and control signals.
| Component | Responsibility |
|---|---|
| TiKV node | Stores Regions on local disk, serves reads and writes, takes part in Raft groups, and runs the transaction logic. |
| Region | A contiguous range of keys, tens to a hundred megabytes, replicated on three or more nodes with one leader. Regions split and merge as data changes. |
| Placement Driver (PD) | Keeps the Region map, schedules replica and leader placement to balance load, and issues the timestamps that order transactions. It embeds etcd for its own state. |
| RocksDB | The log-structured storage engine on each node. |
| Client library | Finds the right Region leader through PD, caches the mapping, and runs transactions. |
Design principle. Make the unit of distribution small and self-contained. Because every Region is its own Raft group, TiKV can move, split and repair data piece by piece, and scale out without re-sharding the whole database.
Production reference design
On Kubernetes, the usual path is the TiDB Operator, which can deploy TiKV and PD on their own without the SQL layer.
- Install the operator. Add the chart repository, install the CRDs, then the operator, pinning versions from the documentation:
helm repo add pingcap https://charts.pingcap.org kubectl create -f https://raw.githubusercontent.com/pingcap/tidb-operator/<version>/manifests/crd.yaml helm install tidb-operator pingcap/tidb-operator \ --namespace tidb-admin --create-namespace --version <version> - Declare the cluster. A three-node PD and three-node TiKV cluster on fast local storage:
apiVersion: pingcap.com/v1alpha1 kind: TidbCluster metadata: { name: kv, namespace: tikv } spec: version: <supported-version> pvReclaimPolicy: Retain configUpdateStrategy: RollingUpdate pd: baseImage: pingcap/pd replicas: 3 requests: { storage: 10Gi } tikv: baseImage: pingcap/tikv replicas: 3 requests: { storage: 200Gi } storageClassName: local-nvme - Spread across failure domains. Label nodes with zone or rack information and configure PD location labels so the three replicas of a Region land in different zones.
- Connect an application. Use a client library with the PD endpoints, for example the Go client with the PD address
kv-pd.tikv:2379, using the transactional API when several keys must change together. - Monitor and back up. Scrape the built-in Prometheus metrics, and take backups with the BR tool to object storage.
Typical uses include the storage layer for TiDB, metadata and index stores, large transactional key-value workloads, and systems that need ordered scans with strong consistency.
Operational considerations
- Storage speed matters. TiKV is write-intensive and sensitive to disk latency. Use local NVMe or high-performance network volumes, and keep Raft logs on fast media.
- Three replicas is the floor. The default of three tolerates one failure. Spread across at least three failure domains, and plan capacity so surviving nodes can absorb a lost node.
- Hotspots. Sequential keys or one popular key concentrate load on a single Region leader. Design keys to spread writes, and watch PD’s hot Region view.
- PD is the control point. Run three PD members with stable storage, and monitor timestamp latency, since every transaction asks PD for a timestamp.
- Upgrades and scale-out. Use rolling upgrades through the operator, and let PD rebalance after adding nodes. Rebalancing consumes disk and network bandwidth, so limit its speed during busy hours.
Adoption
- PingCAP created TiKV and builds TiDB, its distributed SQL database, on top of it.
- The CNCF graduation material and the project’s adopters list on GitHub name production users across e-commerce, finance, gaming and internet companies, mostly through TiDB; consult them for current organisations.
- Direct use of TiKV without TiDB is less common than TiDB deployments, so teams evaluating the raw API should check for recent reference implementations.
Alternatives
| Solution | Model | Best suited to |
|---|---|---|
| Vitess (CNCF Graduated) | Sharding layer over MySQL | Scaling an existing MySQL estate; see the Vitess brief |
| etcd (CNCF Graduated) | Small, strongly consistent key-value store | Configuration and coordination data of modest size; see the etcd brief |
| FoundationDB | Distributed transactional key-value store | Layered databases on an ordered transactional store |
| CockroachDB, YugabyteDB | Distributed SQL | Teams that want a SQL database from the start |
| Cassandra, ScyllaDB | Wide-column stores with tunable consistency | Very high write volume where eventual consistency is acceptable |
Strengths and limitations
| Strengths | Limitations |
|---|---|
| Horizontal scale with automatic Region splitting and balancing | Operationally heavy: PD, TiKV and storage tuning |
| Strong consistency with distributed ACID transactions | Transactions across Regions cost extra round trips |
| Raft replication tolerates node and zone failures | Client ecosystem is smaller than for mainstream databases |
| Proven as the storage layer of TiDB at large scale | Most users reach it through TiDB rather than the raw API |
| Graduated CNCF project with Apache 2.0 licence | Needs fast storage and careful key design |
Recommendation
Assess. TiKV is a strong foundation when a workload needs an ordered, transactional key-value store that scales beyond one machine, and it is the right component to understand if you run TiDB. Test it with a realistic key distribution, measure latency under node failure, and size storage before committing. Teams that mainly need SQL should evaluate TiDB, and teams with modest data and a MySQL or PostgreSQL stack are usually better served by a conventional database with replicas.
References: CNCF project page · TiKV website · TiKV repository · CNCF Landscape