A Layered System
CockroachDB presents a single SQL database but is built from several layers stacked on top of a distributed key value store. Understanding the layers explains how it scales without sharding by hand.
The Layers
- SQL layer parses queries and turns rows into key value pairs.
- Distribution layer splits the key space into ranges of about 512 MB.
- Replication layer keeps each range on multiple nodes using Raft.
- Storage layer persists each replica on a local key value engine.
How A Query Flows
A query hits any node, which acts as a gateway. The gateway plans the query, locates which ranges hold the needed keys, and routes requests to the leaseholder replica of each range. The leaseholder serves reads and coordinates writes through Raft. Because any node can be a gateway, there is no single coordinator bottleneck.
Key idea
CockroachDB stacks a SQL engine over auto split ranges replicated by Raft, so any node can serve any query and the cluster scales without manual sharding.