CockroachDB Distributed SQL Database Cheat Sheet

Back to DatabasesUpdated 2026-05-15

CockroachDB is a cloud-native distributed SQL database built for horizontal scalability, strong consistency, and automatic fault tolerance. It combines PostgreSQL wire protocol compatibility with a distributed architecture based on Raft consensus and range-based sharding, enabling applications to survive availability zone and region failures while maintaining ACID transactions at global scale. One key insight: CockroachDB separates leaseholder (handles reads/writes) from Raft leader (drives consensus) roles per range, optimizing both read performance and write durability, though in practice they're co-located via the leader leases mechanism.

What This Cheat Sheet Covers

This topic spans 19 focused tables and 92 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.

Table 1: Distributed Architecture Core ConceptsTable 2: Multi-Region Table Locality PatternsTable 3: PostgreSQL Compatibility and DialectTable 4: Schema Changes and Online DDLTable 5: Transaction Isolation and Retry HandlingTable 6: Backup and Restore OperationsTable 7: Change Data Capture (Changefeeds)Table 8: Query Optimization and ExecutionTable 9: Data Types and Column FeaturesTable 10: Zone Configuration and Replication ControlTable 11: Cluster Management and MonitoringTable 12: CockroachDB Cloud Deployment OptionsTable 13: SQL Functions and OperatorsTable 14: Data Import and ExportTable 15: Common Table Expressions and Advanced QueriesTable 16: Sequences and Auto-incrementing IDsTable 17: Constraints and Data IntegrityTable 18: Connection ManagementTable 19: Troubleshooting and Performance

Table 1: Distributed Architecture Core Concepts

Concept	Example	Description
Range	512 MiB default max size	Contiguous keyspace chunk replicated across nodes; CockroachDB's fundamental unit of data distribution and rebalancing.
Raft consensus	3-replica default with quorum writes	Protocol ensuring strong consistency by requiring majority approval for writes; each range maintains its own Raft group.
Leaseholder	Handles all reads/writes for a range	Replica serving traffic for a specific range; always co-located with Raft leader via leader leases for write consistency.

Table 1: Distributed Architecture Core Concepts

Concept	Example	Description
Range	512 MiB default max size	Contiguous keyspace chunk replicated across nodes; CockroachDB's fundamental unit of data distribution and rebalancing.
Raft consensus	3-replica default with quorum writes	Protocol ensuring strong consistency by requiring majority approval for writes; each range maintains its own Raft group.
Leaseholder	Handles all reads/writes for a range	Replica serving traffic for a specific range; always co-located with Raft leader via leader leases for write consistency.