Distributed SQLadvanced

CockroachDB Architecture

Ranges, replicas, leaseholders and the layered design that turns SQL into distributed key-value operations.

2 min readAdvancedUpdated 31 Jul 2026Edit this page

CockroachDB

CockroachDB presents a PostgreSQL-compatible SQL interface over a distributed, transactional key-value store.

Raft replication of a single range

Layers

SQL — parses, plans and executes, translating rows into key-value operations.
Transactional KV — provides serializable transactions across arbitrary keys.
Distribution — maps keys to ranges and routes requests.
Replication — Raft consensus per range.
Storage — Pebble, an embedded LSM engine derived from RocksDB.

Ranges and replicas

The keyspace is divided into ranges — contiguous key spans, split when they exceed a size threshold. Each range is replicated to (by default) three nodes, forming a Raft group.

One replica per range holds the leaseholder role. It serves reads without consensus, because it knows it holds a valid lease, and coordinates writes through Raft. Separating the leaseholder from the Raft leader is an optimisation — placing the leaseholder near the traffic reduces read latency without moving the whole group.

SHOW RANGES FROM TABLE orders;
SELECT range_id, lease_holder, replicas FROM crdb_internal.ranges LIMIT 10;

What this means for queries

A read served by a leaseholder near the client is fast — no consensus needed.
A write always requires a Raft majority.
A query touching one range is a single-node operation; one touching many fans out.
Ranges split automatically as data grows, and rebalance across nodes.

The hotspot problem

A sequential primary key creates a single hot range

SERIAL or a timestamp-ordered key sends every new insert to the range holding the highest keys, and therefore to one leaseholder — one node doing all the write work regardless of cluster size.

Use UUID with gen_random_uuid(), or hash-shard the index:

CREATE TABLE events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    INDEX (created_at) USING HASH WITH (bucket_count = 16)
);

USING HASH distributes a sequential index across buckets so no single range absorbs all inserts.

Node roles

All nodes are equal — every one runs all layers and can serve any query. There is no coordinator node to lose. Cluster metadata is itself stored in ranges, replicated the same way.

Clock dependency

CockroachDB uses hybrid logical clocks and requires bounded clock skew between nodes (--max-offset, 500 ms by default).