Background

This section captures design context and historical "why" rather than current "what". The pages here are useful when changing or extending CockroachDB at the architecture level.

Pages

• Design decisions — recurring architectural choices and the reasoning behind them.
• Pitfalls — recurring mistakes and dangerous code patterns to avoid.
• Migration context — long-running migrations and their constraints.

Source documents

• docs/design.md — Spencer Kimball's original 2014 design document, occasionally updated.
• docs/RFCS/ — accepted and rejected RFCs.
• docs/tech-notes/ — technical notes on subsystems (KV, SQL, storage, …).
• pkg/raft/design.md — CRDB-specific Raft design notes.
• pkg/storage/doc.go — MVCC encoding and cluster-version coupling.
• pkg/kv/doc.go — KV API rationale.