# CockroachDB — Distributed SQL for the Global Cloud

> CockroachDB is a cloud-native, distributed SQL database designed for high availability, effortless horizontal scale, and geographic data placement. PostgreSQL-compatible wire protocol with serializable transactions across regions.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Install binary
curl https://binaries.cockroachdb.com/cockroach-v24.3.0.darwin-10.9-amd64.tgz | tar -xz
sudo cp cockroach-v24.3.0.darwin-10.9-amd64/cockroach /usr/local/bin

# Single-node insecure (dev)
cockroach start-single-node --insecure --listen-addr=localhost:26257 \
  --http-addr=localhost:8080 --store=cockroach-data

# Connect via SQL shell
cockroach sql --insecure --host=localhost:26257
```

Usage (PostgreSQL-compatible):
```sql
CREATE DATABASE tokrepo;
USE tokrepo;

CREATE TABLE assets (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  repo VARCHAR(255),
  stars INT,
  created_at TIMESTAMPTZ DEFAULT now()
);

INSERT INTO assets (repo, stars) VALUES
  ("react", 230000),
  ("vue", 210000);

SELECT * FROM assets ORDER BY stars DESC;

-- Multi-region locality (geo-distributed apps)
ALTER TABLE assets CONFIGURE ZONE USING
  num_replicas = 5,
  constraints = "{+region=us-west: 2, +region=eu-west: 2, +region=ap-south: 1}";
```

## Intro

CockroachDB is a distributed SQL database designed for the cloud. Inspired by Google Spanner, it offers serializable transactions, horizontal scale, automatic sharding, and survivability (nodes can fail, zones can fail, regions can fail). PostgreSQL-compatible wire protocol and most PostgreSQL syntax.

- **Repo**: https://github.com/cockroachdb/cockroach
- **Stars**: 32K+
- **Language**: Go
- **License**: BUSL 1.1 / CCL (some features)

## What CockroachDB Does

- **Serializable transactions** — strongest ACID guarantee
- **PostgreSQL compatibility** — wire protocol + most SQL features
- **Auto-sharding** — data split into ranges, auto-rebalanced
- **Multi-region** — place data near users via zone configs
- **Raft replication** — configurable replica count per table
- **Online schema changes** — non-blocking DDL
- **Time travel queries** — AS OF SYSTEM TIME
- **Follower reads** — read from closest replica for low latency
- **CDC** — change data capture stream

## Architecture

Each node is identical (no primary/secondary). Data is split into 64MB ranges, each replicated via Raft to typically 3 nodes. SQL layer sits on top of the distributed KV layer. DistSQL executes queries across nodes in parallel.

## Self-Hosting

```bash
# Secure 3-node cluster
cockroach start --certs-dir=certs --listen-addr=node1:26257 \
  --advertise-addr=node1 \
  --join=node1,node2,node3

# Init cluster
cockroach init --certs-dir=certs --host=node1
```

## Key Features

- Distributed SQL with serializable transactions
- PostgreSQL wire compatibility
- Multi-region with geo-partitioning
- Automatic sharding and rebalancing
- Zero-downtime upgrades
- Online schema changes
- Backup and restore
- Row-level TTL
- Change data capture
- BACKUP to cloud storage

## Comparison

| Database | Inspired By | Compatibility | License |
|---|---|---|---|
| CockroachDB | Spanner | PostgreSQL | BUSL + CCL |
| YugabyteDB | Spanner | PostgreSQL | Apache 2.0 |
| TiDB | Spanner + HTAP | MySQL | Apache 2.0 |
| Spanner | Own | Managed only | Proprietary |
| Citus (Postgres ext) | Postgres | PostgreSQL | Apache 2.0 |

## FAQ

**Q: A PostgreSQL drop-in?**
A: Most PostgreSQL features are compatible. Incompatibilities include: stored procedures (limited support), certain types, and some PG extensions. Test before migrating.

**Q: Performance overhead?**
A: Distributed transactions are slower than single-machine (latency ≈ 2-3 network RTTs). But the horizontal scaling capability far surpasses a single machine. For small apps, single-node Postgres is faster and cheaper.

**Q: BUSL restrictions?**
A: Source is readable and self-usable, but you cannot run a commercial managed service that competes with Cockroach Cloud. Automatically converts to Apache 2.0 after 4 years.

## Sources

- Docs: https://www.cockroachlabs.com/docs
- GitHub: https://github.com/cockroachdb/cockroach
- License: BUSL 1.1

---
Source: https://tokrepo.com/en/workflows/cockroachdb-distributed-sql-global-cloud-90136870
Author: AI Open Source