Skip to content
Navigation

Type at least two characters. Search covers page titles, headings, tags and database names.

↑ ↓ to navigateEnter to openEsc to close0 pages
Distributed SQLadvanced

CockroachDB

Distributed SQL database with Raft-replicated ranges, serializable transactions and locality-aware data placement.

2 min readAdvancedUpdated Edit this page
CockroachDB

What it is

A distributed SQL database presenting a PostgreSQL-compatible interface over a transactional key-value store. Licensed under BSL 1.1 with a CCL for enterprise features.

Architecture

The keyspace is divided into ranges, each replicated to three nodes by Raft. One replica holds the leaseholder role and serves reads without consensus; writes go through Raft. All nodes are equal and run every layer, so there is no coordinator to lose. Storage is Pebble, a RocksDB-derived LSM engine.

Raft replication of a single rangeA client writes to the Raft leader, which appends the entry to its log and replicates it to two followers. Once a majority has persisted the entry it is committed and applied to the state machine, then acknowledged to the client.writeAppendEntriesAppendEntriescommit ackClientLeaderterm 7, log index 42Follower 1log index 42Follower 2log index 41
Raft replication of a single range

Best use cases

  • Transactional workloads that genuinely exceed one node's write capacity.
  • Multi-region applications where a regional outage must not cause downtime.
  • Data residency requirements, addressed with per-row locality.
  • Deployments where the failover gap of a primary-replica system is unacceptable.

When not to use it

  • When a single-node engine with a replica would do, which is the common case.
  • When write latency budgets are tight and the deployment spans regions — consensus latency has a hard floor.
  • When you need PostgreSQL feature parity rather than wire compatibility; extensions and some behaviours differ.

Data model

PostgreSQL-compatible SQL. Primary key design determines range locality, so it plays the role that a shard key plays elsewhere: sequential keys create a hot range, and hash-sharded indexes exist specifically to avoid it.

Consistency and transactions

SERIALIZABLE by default across the whole dataset, including across ranges and regions. Applications must retry SQLSTATE 40001. READ COMMITTED is available in recent versions for workloads where retries are impractical. Follower reads serve slightly stale data from the nearest replica.

Scaling model

Add nodes; ranges split and rebalance automatically. Throughput scales with node count provided the workload's key distribution spreads across ranges.

Replication

Raft per range, with a configurable replication factor. Survival goals are declarative: SURVIVE ZONE FAILURE keeps quorum within a region; SURVIVE REGION FAILURE spans regions and puts an inter-region round trip on every write.

Backup and recovery

BACKUP/RESTORE to object storage, with scheduled and incremental variants, producing cluster-consistent backups — a genuine advantage over per-shard snapshot systems.

Monitoring

Prometheus metrics at /_status/vars, plus the DB Console with hotspot views. Key series: under-replicated ranges, live node count, transaction restarts, clock offset and Raft commit latency.

Common mistakes

Production checklist

See CockroachDB Production Checklist.