# CockroachDB / NewSQL ## Зачем Single-region Postgres упирается в стену по трём осям одновременно: write-throughput на single primary (десятки тысяч txn/s — и всё), failover между регионами (10-30 минут с риском split-brain), и data residency (GDPR/CCPA требуют чтобы EU users физически жили в EU). Стандартные ответы — read-replicas (не помогают writes), Postgres+Citus (sharding есть, но ACID только per-shard и multi-region writes требуют app-level routing), full migration на NoSQL (теряем SQL, теряем ACID, переписываем приложение). NewSQL — это попытка получить **distributed scale как у NoSQL + ACID и SQL как у RDBMS + strong consistency**, не выбирая между ними. CockroachDB конкретно делает это так: **distributed KV (multi-Raft per range) + SQL parser/optimizer на верхнем уровне + 2PC поверх для cross-range транзакций + HLC вместо atomic clocks**. Postgres wire-compatible — драйверы и ORM работают без изменений (psycopg, pg, JDBC). Multi-region first-class — `REGIONAL BY ROW` пинит каждую строку к home региону через служебную колонку `crdb_region`. Survival modes — `REGION` survival выдерживает потерю целого региона без manual failover. Open-source (BSL), self-hosted или managed (Cockroach Cloud). Цена этого: каждая cross-range транзакция = consensus round-trip. Intra-region ~5ms, cross-region 50-150ms. Optimizer слабее Postgres на сложных аналитических запросах. Хранение 3× (replication factor 3 по умолчанию). Для single-DC small workload это overkill и медленнее обычного Postgres. NewSQL — это решение конкретной проблемы (multi-region ACID at scale), а не drop-in замена Postgres "потому что современнее". ## Mental model > NewSQL = распределённый KV (Raft per range) + SQL parser/optimizer + 2PC поверх; ACID и SQL гарантированы, но каждая cross-range транзакция = consensus round-trip (десятки ms), поэтому это не drop-in замена Postgres для latency-sensitive OLTP. Ключевые объекты, которые надо держать в голове: - **Range** ~ shard. Каждая range — свой Raft-группа (multi-Raft на ноду = тысячи Raft-групп). Default ~512MB или 100K writes/s — потом auto-split. - **Leaseholder** — одна из replicas каждой range, держит lease на чтение. Reads на leaseholder без consensus (1 RTT). Writes proposed leaseholder'ом через Raft (majority ack). - **HLC (Hybrid Logical Clock)** — `(physical_part_ms, logical_counter)`. Update rule: `pt = max(local_phys, recv.pt)`; если pt не изменился — `l++`, иначе `l = 0`. Заменяет TrueTime: вместо `commit-wait` на uncertainty interval, CockroachDB делает **uncertainty restart** — если read попадает в `[read_ts, read_ts + max_offset]` существующего intent, транзакция перезапускается с обновлённым ts. - **Pebble** — Go-rewrite RocksDB. LSM storage на каждой ноде. - **Gossip** — cluster metadata (membership, range descriptors, node capacity, lease info). Distributed transaction = **write intents** на ranges (provisional values + tx_id), Raft replication intra-range, **2PC** для commit (с 19.2 — Parallel Commits: staged tx record + intents async, на чтении intent проверяется tx status), async cleanup intents → committed values. ## Что на диаграмме Три региона по 3 ноды (типичный 3-region REGION-survival setup): - **us-east-1**: E1 (leaseholder R1), E2 (leaseholder R3), E3 — Postgres-compatible nodes. - **us-west-2**: W1 (leaseholder R2), W2, W3. - **eu-west-1**: EU1, EU2, EU3 — home region для EU rows (GDPR). - **Clients**: `app-us` (Django+psycopg), `app-eu` (Rails+pg) — обычные Postgres-клиенты. Edges делятся на три класса: **pgwire** (клиент → gateway-нода), **Raft** intra-region (тяжёлый поток репликации), **gossip + cross-region Raft** (для ranges с replicas в нескольких регионах — это и есть survival). Range R3 нарисован специально cross-region (E2 leaseholder, replicas W3 и EU2) чтобы показать что survival = consensus quorum через WAN. Range R-eu — наоборот, полностью в eu-west (REGIONAL BY ROW для EU users). ADR-001 (на ноде E1) — выбор CockroachDB против Citus и Spanner. ADR-002 — почему HLC + uncertainty restart, а не TrueTime commit-wait (commodity hardware vs Google's atomic clocks). ## Сценарии **1. Cross-range distributed txn.** `BEGIN; UPDATE acct_A; UPDATE acct_B; COMMIT` где acct_A на R1 (us-east) и acct_B на R2 (us-west). Coordinator E1 присваивает HLC tx_ts, пишет intent на R1 (Raft replicate intra-east), форвардит на W1 для R2, W1 forward'ит свой HLC до tx_ts, пишет intent на R2 (Raft replicate intra-west), на COMMIT — Parallel Commits с PREPARE vote от обоих ranges, async cleanup. Latency ~70ms (доминирует WAN consensus). Intra-region аналогичная транзакция — ~5ms. **2. Range rebalance после добавления ноды.** R1 растёт под нагрузкой sequential writes до 480MB, при 512MB или 100K writes/s — auto-split на R1a (keys < K) и R1b (keys >= K). Операторы добавляют W2 в кластер — gossip пропагирует capacity. Allocator на каждой ноде сравнивает scores (загрузка E1=85%, W2=10%) и принимает decision: replica R1b с E3 → W2. Raft snapshot transfer (~30s для 256MB), catch-up log entries, joint consensus для membership change (add W2, remove E3), GC данных на E3. **3. Multi-region locality (REGIONAL BY ROW).** EU user (id=42, `crdb_region='eu-west'`) делает SELECT через `app-eu` → gateway EU1 → local lookup (range R-eu, leaseholder EU1) → local read без consensus → ~3ms ответ внутри EU. Тот же запрос от `app-us` через east-1 — east-1 видит crdb_region=eu-west и форвардит на EU1 — корректно, но медленно (~80ms WAN). Урок: routing должен быть на app-уровне тоже. WRITE на EU user — intent на R-eu, Raft replicate EU2/EU3 — local quorum, ~5ms, данные не покидают EU (GDPR happy). **4. REGION failure (survival mode).** us-east полностью отваливается (DC outage / network partition). Range R3 имел leaseholder E2, replicas W3 + EU2 — кворум 2/3 выживает. Heartbeat timeout → Raft election на R3 → W3 кандидат, EU2 голосует за → W3 новый leader → W3 acquires lease → writes resume. In-flight транзакция на E1 abort, клиент retries через us-west gateway — следующий write идёт на W3 → Raft replicate на EU2 → majority 2/2 survivors → ack. Никакого manual failover, никакой потери данных. При возвращении us-east — re-replication и catch-up Raft log. ## Trade-offs (ADR) **ADR-001 — CockroachDB vs Postgres+Citus vs Spanner.** SaaS платформа с tenants в US/EU/APAC. Citus rejected: ACID только per-shard, multi-region writes требуют app coordination, manual rebalance. Spanner rejected: GCP-only (vendor lock-in), нет on-prem option, enterprise pricing 2-3× для small workloads, требует atomic clocks. CockroachDB выбран потому что: Postgres wire compatibility (миграция ORM без переписывания), multi-Raft даёт авто-sharding без app-level routing, REGIONAL BY ROW = GDPR без app changes, REGION survival выдерживает потерю DC, open-source (self-hosted option), HLC не требует special hardware. Trade-offs accepted: cross-range txns дороже (consensus RTT), optimizer слабее Postgres для аналитики (DWH = ClickHouse отдельно), ops cost 3× single Postgres. **ADR-002 — HLC + uncertainty restart, а не TrueTime commit-wait.** Spanner использует TrueTime (GPS+atomic clocks в каждом DC), `TT.now() → [earliest, latest]` interval с uncertainty bound ε ~7ms, commit-wait блокирует write на ε для external consistency. Работает потому что Google имеет atomic clocks. CockroachDB на commodity hardware: NTP даёт 100-250ms точность в лучшем случае → commit-wait убивает latency (250ms на каждую транзакцию). Решение: HLC `(physical_ms, logical_uint16)`, uncertainty interval `[read_ts, read_ts + max_offset]` (default 500ms). Если read попадает в uncertainty zone существующего intent — transaction restarts с обновлённым ts. Single-key linearizability без atomic clocks. Cost: extra restart latency для overlapping reads (~5-10ms). NOT external consistency между независимыми transactions across regions — для большинства OLTP acceptable. max_offset configurable; нода suicide при clock drift > max_offset (защита от lost-write). **ADR-003 (implicit) — REGION survival vs ZONE survival.** REGION survival = 3 replicas, по одной в каждом регионе → выдерживает потерю целого региона, но cross-region quorum на каждый write (~70ms WAN). ZONE survival = replicas в одной region, разные AZ → выдерживает AZ failure, local quorum (~5ms), но потеря региона = downtime. Выбор по SLA и cost. ## Реальные системы - **CockroachDB**: DoorDash (миграция после Postgres scaling pain), Netflix (internal services), Comcast (billing), Bose (IoT speakers), Hard Rock Digital (regulated gambling), Form3 (UK fintech payments), Shipt/Target, Lush e-commerce, eBay parts. - **TiDB** (PingCAP, China): Square, Pinterest analytics, Tencent. Архитектура TiKV+TiDB+PD, MySQL wire dialect, TSO (single PD) вместо HLC. - **YugabyteDB**: GE Healthcare, T-Mobile. DocDB+YQL, Postgres-compatible, HLC. - **Spanner** (GCP only): Google internal (Gmail, AdWords, Photos), now external GCP product. Paxos + TrueTime. - **FaunaDB**: Calvin algorithm, deterministic ordering, document+SQL. - **YDB** (Yandex Open Source): RU jurisdiction primarily, tablets model. - **Aurora DSQL** (AWS, 2024+): proprietary, TrueTime-like, AWS-only. ## Anti-patterns - **Использование CockroachDB для single-region small workload** — overkill, дорого (3× storage, 3× compute, 3× network), медленнее single Postgres (consensus overhead). Используйте Postgres до момента, когда упрётесь в реальную проблему scale/multi-region/survival. - **Sequential auto-increment PK (SERIAL)** → hot range → постоянные splits + rebalance overhead. Используйте UUID v7 / ULID / hash partitioning. - **Cross-region transactions для каждого write** — ~100ms latency убивает UX. Дизайнить схему так чтобы транзакции были intra-region (REGIONAL BY ROW + app-level routing). - **Heavy analytical queries напрямую** — optimizer слабее Postgres, MPP не такой мощный как Snowflake/ClickHouse. ETL в OLAP store. - **Игнорировать REGIONAL BY ROW для multi-region** — каждый user без crdb_region travels через WAN на каждый read/write. - **Долгие транзакции (минуты)** — держат intents, блокируют конкурентов, высокий риск abort/retry. Разбивайте на короткие. - **CockroachDB как cache / counter** — high contention на single key = Raft contention = деградация. Это OLTP database, не Redis. - **`SELECT FOR UPDATE` в multi-region** дорог (cross-region lock). Используйте `FOR SHARE` где можно или дизайните без блокировок (CRDT-like подходы). ## Когда НЕ использовать - **Single-DC, single-server достаточно** — большинство приложений. Postgres + read-replicas + pgbouncer покрывает 95% случаев и стоит в разы меньше. - **Latency-sensitive OLTP (<5ms p99 на простой txn)** — consensus RTT нельзя обмануть. Single Postgres даёт <1ms на single-row update в hot cache. - **Сложные analytical / OLAP** — берите ClickHouse, DuckDB, Snowflake, BigQuery. CockroachDB optimizer не справится. - **Heavy full-text search или PostGIS-зависимые приложения** — Postgres extensions богаче и зрелее. - **Маленькие команды без ops capacity** — distributed database = больше moving parts, мониторинг кластера, capacity planning, range splits monitoring, hotspot detection. - **Cost-sensitive проекты** — replication factor 3 + cross-region network traffic + leaseholder overhead = существенно дороже single Postgres. ## Дальше читать - **Papers**: Spanner (Corbett et al., 2012) — ; F1 (Shute et al., 2013); Calvin (Thomson et al., 2012); TiDB VLDB 2020 (Huang et al.). - **CockroachDB**: docs , blog , особенно "Living Without Atomic Clocks" (Spencer Kimball) и "Parallel Commits" серия. - **Case studies**: "DoorDash + CockroachDB" . - **Spanner docs**: . - **TiDB docs**: . - **YugabyteDB docs**: . - **Books**: *DDIA* (Kleppmann) Ch. 7 (Transactions), 8 (Trouble with distributed systems), 9 (Consistency and Consensus); *Database Internals* (Petrov) Ch. 11-13. - **System Design Space**: , . - **Concept dependencies in this course**: ::concept{slug="consensus-overview"}, ::concept{slug="raft"}, ::concept{slug="mvcc"}, ::concept{slug="pacelc-theorem"}.