CockroachDB
23.xSummary
Distributed SQL database wire-compatible with PostgreSQL that replicates each key range (512 MiB by default) across multiple nodes via Raft consensus. Serializable isolation is the default. Geographic data partitioning allows row-level data residency control. Designed for global deployments requiring strong consistency without a single-region primary.
Primary Use Case
Global SaaS applications and financial systems requiring ACID transactions with no single region as a single point of failure. Workloads that need data residency compliance (GDPR row-level geo-partitioning) while preserving SQL semantics.
Workload Fit
Strengths
Best for
- ·Global applications requiring ACID transactions without a single-region primary: no manual failover or region promotion needed
- ·Financial systems requiring serializable isolation across geographically distributed writes with no tolerance for split-brain
- ·Applications subject to data residency regulations: GDPR row-level geo-partitioning pins specific tenants' data to specific regions via PARTITION BY LIST
- ·Horizontal write scaling for relational workloads where PostgreSQL single-primary throughput is the bottleneck
- ·Multi-cloud or hybrid deployments requiring a single SQL interface across regions with automatic range rebalancing
Excels when
- ·Workload is naturally partitioned by a well-distributed key (UUID, hash) that minimizes cross-range transactions
- ·Read traffic can tolerate bounded staleness and use follower reads to avoid Raft round-trips
- ·The application already uses PostgreSQL-compatible SQL and can adopt CockroachDB's dialect differences with minimal query changes
- ·Multi-region operation is a hard requirement and the team has capacity to operate a distributed cluster
Architectural advantages
- ·Serializable isolation by default eliminates entire classes of anomalies (phantom reads, write skew) that require explicit locking in PostgreSQL
- ·Automatic range rebalancing removes manual sharding management: no Vitess-style middleware or application-layer routing
- ·Raft-based replication provides automatic failover without manual primary promotion: surviving nodes elect a new leader within seconds
- ·Geographic partitioning (PARTITION BY LIST on region column) provides data residency at the SQL schema level
- ·Hybrid Logical Clocks (HLC) enable causally consistent reads across nodes without requiring perfectly synchronized clocks
When to Avoid
Avoid when
- ·Single-region deployment where PostgreSQL provides lower latency, lower cost, and simpler operations without the distributed overhead
- ·Workload is primarily analytical: CockroachDB is an OLTP engine; large aggregation queries cause full-cluster fan-out and should use a dedicated analytics store
- ·Write patterns produce hot ranges (monotonic keys, sequential IDs) and the team cannot change the key generation scheme
- ·Latency SLA is sub-5ms for all write transactions: cross-region Raft commits are incompatible with this requirement
Common misuses
- ·Treating CockroachDB as a drop-in PostgreSQL replacement without auditing for hot range patterns: sequential primary keys that work fine in PostgreSQL cause severe hot spot problems in CockroachDB
- ·Running multi-region active-active without understanding that two-phase commit across regions adds 100–300ms to cross-region transactions: application SLAs must account for this
- ·Using CockroachDB for development or staging when the application will run single-region in production: the distributed latency profile differs substantially from the production behavior the team needs to validate
Consistency & Transactions
Scaling
Read scalability
Reads can be served from any node in a region via follower reads (historical reads at a configured staleness bound). Stale follower reads incur no Raft round-trip and are suitable for eventually-consistent use cases. Strongly consistent reads go to the Raft leader for the key range.
Write scalability
Writes are horizontally scalable by adding nodes; new key ranges are automatically split and rebalanced across the cluster. Throughput scales roughly linearly with node count for independent key ranges. Cross-range transactions (two-phase commit) reduce throughput and increase latency.
Failure Behavior
Known failure modes
- ·Cross-range distributed transactions are subject to two-phase commit coordinator failure: if the coordinator dies mid-transaction, the transaction enters a deadlock resolution path that can hold locks for seconds
- ·Clock skew exceeding 500ms causes nodes to self-terminate: CockroachDB requires NTP synchronization across all nodes; cloud environments must be monitored for clock drift
- ·Hot range contention: if all writes target the same key range (e.g., monotonically increasing primary keys), that range's Raft leader becomes a bottleneck
- ·Multi-region transactions spanning three regions require two Raft round trips each: at 80ms inter-region RTT, a simple two-row cross-region transaction takes 200ms+
- ·Scatter queries (queries without a shard key predicate) must be executed on all ranges: can cause fan-out latency spikes proportional to cluster size
- ·Node decommissioning during range rebalancing can cause transient latency increases as Raft leadership elections occur for affected ranges
Bottlenecks
- ·Two-phase commit coordinator for cross-range transactions adds latency proportional to the number of ranges touched and the network RTT between coordinator and range leaders
- ·Hot range contention: a single Raft leader handles all writes to its range; hash-prefix or UUID key design is required to distribute write load
- ·Network round-trip time is the primary latency floor for multi-region transactions: no amount of hardware scaling overcomes WAN latency
- ·Full-table scans in a distributed cluster fan out to all ranges: analytical queries are expensive without range pruning
- ·Raft election during node failure causes a brief write unavailability for affected ranges while a new leader is elected
Degradation patterns
- ·Clock skew approaching 500ms threshold causes proactive node shutdown to preserve consistency: all ranges on the node become unavailable until clock sync is restored
- ·Hot range overload causes queue depth to grow on the range leader; other nodes in the cluster appear healthy while the hot range shows increasing write latency
- ·Cross-region transaction storms during multi-region failover testing cause lock contention as transactions are retried: applications must implement exponential backoff on serialization errors
Recovery considerations
- ·A region losing majority quorum for any range causes writes to that range to block until quorum is restored: survivability analysis requires knowing which ranges span which regions
- ·CockroachDB's survivability goal configuration (zone vs. region survivability) determines Raft voter placement: must be set before a failure, not after
- ·Logical backups via EXPORT or changefeeds to S3; RESTORE is region-aware and can restore into a different topology
Operational Pitfalls
- ·Using monotonically increasing primary keys (SERIAL, SEQUENCE) in high-write tables: all inserts target the same 'hot end' range. Use UUID v4 or hash-prefixed keys to distribute write load
- ·Not designing for multi-region latency: CockroachDB's distributed transactions are correct but slow across regions; teams that expect PostgreSQL-like latency in a multi-region deployment are surprised by the WAN penalty
- ·Not using follower reads for read-heavy analytics: strongly consistent reads add Raft round-trip overhead; follower reads with AS OF SYSTEM TIME interval '10s' reduce latency significantly for acceptable-staleness workloads
- ·Ignoring range hot spots in the DB Console: hot ranges are the primary cause of unexpected latency spikes and must be addressed through key design changes
- ·Running CockroachDB for single-region OLTP where PostgreSQL is simpler, faster, and less expensive: CockroachDB's distributed overhead is not justified without a multi-region or horizontal write scaling requirement
Architecture Guidance
Common topology roles
Migration notes
- ·From PostgreSQL: most SQL is compatible but sequences and SERIAL generate hot ranges: switch to gen_random_uuid() or hash-prefixed keys before migrating write-heavy tables
- ·Schema migrations require careful attention to online schema change behavior: CockroachDB supports online ADD COLUMN but some ALTER TABLE operations have performance implications at scale
- ·To CockroachDB Serverless: consumption-based pricing model suits bursty workloads; dedicated clusters provide predictable latency for sustained throughput requirements
Advisor Guidance
When: scenario has multi_region requirement or data residency compliance requirement
Use PARTITION BY LIST with region-based partitioning to pin row data to specific regions; define zone configs to place Raft voters in the target region
When: scenario uses sequential primary keys or auto-increment IDs on high-write tables
Replace sequential keys with UUID v4 or hash-prefixed keys to distribute writes across ranges and avoid hot end contention
When: scenario requires sub-5ms write latency in multi-region deployment
CockroachDB cross-region Raft commits are bounded below by network RTT; follower reads can meet low-latency SLAs for reads but writes cannot avoid the WAN latency floor
Comparison Factors
multi region consistency
Strongest available: serializable isolation by default, automatic range rebalancing, no manual failover for regional outages
single region latency
Higher than PostgreSQL due to Raft overhead on every write; not competitive for latency-sensitive single-region OLTP
operational complexity
High: distributed cluster operations, range rebalancing, clock synchronization, and hot spot diagnosis require distributed systems expertise
total cost of ownership
High: requires multi-node deployment for HA; BSL license restricts competing use; Dedicated clusters carry significant infrastructure cost
Managed Cloud Options
Enables Patterns
Basis
CockroachDB's distributed architecture is publicly documented with detailed design docs; latency characteristics verified against published benchmarks and practitioner reports