# 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 in your project root:

## 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: PostgreSQL 的 drop-in？**
A: 大部分 PostgreSQL 功能兼容。不兼容的有：存储过程（支持有限）、某些类型、一些 PG 扩展。迁移前测试。

**Q: 性能开销？**
A: 分布式事务比单机慢（延迟≈网络 RTT 2-3 次）。但横向扩展能力远超单机。小应用单机 Postgres 更快更便宜。

**Q: BUSL 限制？**
A: 源码可读、可自用，但不能做商用托管服务与 Cockroach Cloud 竞争。4 年后自动转 Apache 2.0。

## 来源与致谢 Sources

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

---
Source: https://tokrepo.com/en/workflows/90136870-35f6-11f1-9bc6-00163e2b0d79
Author: AI Open Source