CockroachDB is a distributed SQL database: you talk to it with the PostgreSQL wire protocol and SQL, but data is automatically split, replicated and rebalanced across several nodes. Lose a node — or, with enough nodes, a whole region — and the database keeps serving with no manual failover and no data loss.

How it works (briefly)

  • Data is divided into ranges (chunks of the key space).
  • Each range is replicated (3 copies by default) across nodes using the Raft consensus protocol. A write commits once a majority of replicas agree.
  • Any node can accept queries; it routes work to the nodes holding the relevant ranges.
  • Transactions are serializable by default.

The cost: writes involve network round trips between replicas, so latency is higher than a single-node PostgreSQL, especially across regions.

Licensing note

CockroachDB’s licensing has changed over time; recent versions are offered under the CockroachDB Software License with free tiers that have conditions (for example around company size and telemetry). Read the current terms before committing to it for production.

A three-node cluster

Three servers on a private network (10.0.0.61–63), with clocks synchronised (NTP/chrony is required — clock skew beyond the configured maximum causes nodes to stop). See time sync with chrony.

Download the binary on each node (from the official site), then generate TLS certificates once and distribute them:

cockroach cert create-ca --certs-dir=certs --ca-key=my-safe-directory/ca.key
cockroach cert create-node 10.0.0.61 localhost --certs-dir=certs --ca-key=my-safe-directory/ca.key
cockroach cert create-client root --certs-dir=certs --ca-key=my-safe-directory/ca.key

(Create a node certificate per node with its own addresses.)

Start each node:

cockroach start --certs-dir=certs \
  --advertise-addr=10.0.0.61 \
  --join=10.0.0.61,10.0.0.62,10.0.0.63 \
  --cache=.25 --max-sql-memory=.25 \
  --store=/var/lib/cockroach --background

Initialise the cluster once, from any node:

cockroach init --certs-dir=certs --host=10.0.0.61

Run it under systemd in production rather than --background.

Firewall: port 26257 (SQL and inter-node) between nodes and from app servers; 8080 (DB Console) restricted to admins.

Connect

cockroach sql --certs-dir=certs --host=10.0.0.61
CREATE DATABASE shop;
CREATE USER app WITH PASSWORD 'a-long-random-password';
GRANT ALL ON DATABASE shop TO app;

Applications use PostgreSQL drivers:

postgresql://app:[email protected]:26257/shop?sslmode=verify-full&sslrootcert=certs/ca.crt

Put a load balancer (HAProxy) in front, or list several hosts in drivers that support it.

PostgreSQL compatibility

Most standard SQL and many PostgreSQL features work, and ORMs (Django, Prisma, SQLAlchemy, Hibernate, ActiveRecord with the adapter) are supported. Differences to watch:

  • Primary keys: sequential integer IDs create hot spots on one range; prefer UUIDs (gen_random_uuid()) or hash-sharded indexes.
  • Some PostgreSQL extensions, functions and procedural features aren’t available.
  • Transaction retries: under contention, serializable transactions may fail with a retryable error (40001); application code must retry.
  • Schema changes run online but asynchronously.

Survival goals and multi-region

With nodes in several regions, you can declare that a database must survive a zone or region failure, and pin rows to regions (“regional by row”) so users read and write nearby. This is CockroachDB’s strongest feature — and requires careful latency planning.

Operating it

  • DB Console (port 8080) shows nodes, ranges, replication status, slow statements.
  • Backups: BACKUP DATABASE shop INTO 's3://…' with scheduled backups to S3-compatible storage.
  • Upgrades: rolling, one node at a time.

Is it worth it?

Yes when you need SQL with automatic high availability across servers or regions and can’t afford manual failover.

Probably not for a single-region app where a primary/standby PostgreSQL (streaming replication) or even a single well-backed-up server meets your availability needs — simpler, faster per query, and cheaper to run.

Related: database replication explained and database sharding.

  • CockroachDB
  • Distributed SQL
  • Databases