CockroachDB Tutorial: Learn Distributed SQL from Scratch (2026)
I have deployed CockroachDB in multi-region production environments where PostgreSQL compatibility and survivability were critical. CockroachDB is a distributed SQL database that looks like PostgreSQL but automatically replicates and rebalances data.
We will cover cluster setup, SQL compatibility, automatic sharding, survivability patterns, backup, and multi-region configurations.
Installing and Starting a CockroachDB Cluster
CockroachDB is a single binary with no dependencies. Start a single-node cluster for dev. For production, three nodes for survivability.
Nodes discover each other via --join. The cluster uses Raft consensus. Data splits into ranges (512 MB), each replicated to three nodes. Rebalancing is automatic.
cockroach start --insecure --store=node1 --listen-addr=localhost:26257 --http-addr=localhost:8080 --join=localhost:26257,localhost:26258,localhost:26259
cockroach init --insecure --host=localhost:26257PostgreSQL-Compatible SQL with Distributed Extensions
CockroachDB aims for PostgreSQL wire-protocol compatibility. Most tools, drivers, and ORMs work without modification.
Limitations: no triggers, no PL/pgSQL stored procedures, SERIALIZABLE isolation only. These reflect distributed trade-offs.
CREATE TABLE users (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email STRING UNIQUE NOT NULL, name STRING NOT NULL, created_at TIMESTAMP DEFAULT now());
ALTER TABLE users CONFIGURE ZONE USING constraints = '{+region=us-east: 1}';
INSERT INTO users (email, name) VALUES ('alice@example.com', 'Alice');Automatic Sharding and Rebalancing
Every table automatically splits into ranges on the primary key. Each range is a Raft-replicated group. When a range exceeds 512 MB, it splits.
Adding a node triggers automatic rebalancing to equalize load. Rebalancing respects zone constraints and is non-disruptive.
SHOW RANGES FROM TABLE users;
ALTER TABLE users SPLIT AT VALUES ('m');
ALTER TABLE USERS EXPERIMENTAL_RELOCATE LEASE VALUES (3, 'alice@example.com');Survivability Goals: Zone and Region
ZONE survivability survives one AZ loss. REGION survivability survives one region loss. Set at the database level.
Multi-region table localities: GLOBAL (read anywhere), REGIONAL BY TABLE (home region), REGIONAL BY ROW (distributed by crdb_region column).
ALTER DATABASE mydb SURVIVE ZONE FAILURE;
ALTER DATABASE mydb SURVIVE REGION FAILURE;
CREATE DATABASE mydb PRIMARY REGION "us-east1" REGIONS "us-west1", "europe-west1";
ALTER TABLE users SET LOCALITY REGIONAL BY TABLE IN "us-east1";Backup, Restore, and Disaster Recovery
Supports full, incremental, and scheduled backups to S3, GCS, Azure Blob, or NFS. Backups are consistent at cluster, database, or table level.
Point-in-time recovery restores to any timestamp between oldest backup and most recent replicated log entry.
BACKUP INTO 's3://mybackups/cockroach?AWS_ACCESS_KEY_ID=...&AWS_SECRET_ACCESS_KEY=...';
BACKUP INTO LATEST IN 's3://mybackups/cockroach?...';
CREATE SCHEDULE FOR BACKUP INTO 's3://mybackups/cockroach?...' RECURRING '@daily' FULL BACKUP '@weekly';Monitoring, Alerting, and Performance Tuning
CockroachDB exposes Prometheus metrics and a built-in admin UI. Key metrics: range count, replication lag, lease transfers, query latency percentiles.
Use EXPLAIN ANALYZE for distributed execution plans. For write-heavy workloads, use hash-sharded indexes to distribute write load.
SELECT * FROM crdb_internal.cluster_sessions WHERE active;
CANCEL QUERY '1689d0d5b6b7d1e80000000000000001';
CREATE INDEX users_email_hash ON users(email) USING HASH WITH BUCKET_COUNT = 16;Frequently Asked Questions
Is CockroachDB free?
CockroachDB Core is free under BSL. Enterprise adds backup scheduling, multi-region SQL, and row-level TTL with a paid license.
How does CockroachDB compare to YugabyteDB?
CockroachDB uses Raft and has deeper PostgreSQL compatibility. YugabyteDB uses a custom Raft implementation and also supports Cassandra-compatible YCQL.
What is the maximum transaction throughput?
Throughput scales with nodes. Hundreds of thousands of TPS in a tuned cluster. Write-heavy workloads benefit from hash-sharded indexes.
Does CockroachDB support foreign keys?
Yes, fully supported including cascading deletes. Cross-range foreign key checks add latency from distributed coordination.
Originally published on Ayodhyyya. Last updated June 1, 2026.