Architecture

CockroachDB is built as a layered system. A SQL request enters at the top, is rewritten and planned against a logical schema, executed against a distributed transactional KV map, replicated by Raft on a per-range basis, and ultimately persisted to a Pebble LSM-tree on every replica.

graph TD
  Client["PostgreSQL client / driver"] -->|wire protocol| PGWire["pgwire (pkg/sql/pgwire)"]
  PGWire --> Conn["connExecutor / planner (pkg/sql)"]
  Conn --> Opt["cost-based optimizer (pkg/sql/opt)"]
  Opt --> Exec["row engine + DistSQL flows (pkg/sql/distsql*)"]
  Exec --> KVClient["kv.DB / kv.Txn (pkg/kv)"]
  KVClient -->|BatchRequest| DistSender["DistSender (pkg/kv/kvclient/kvcoord)"]
  DistSender -->|RPC per range| Server["Node server (pkg/server)"]
  Server --> Store["Store (pkg/kv/kvserver)"]
  Store --> Replica["Replica state machine"]
  Replica -->|propose / apply| Raft["raft (pkg/raft)"]
  Raft -->|log entries| Pebble["Pebble engine (pkg/storage)"]
  Replica -->|MVCC| Pebble

Layers

SQL gateway

Every CockroachDB node can serve SQL. pkg/sql/pgwire/ implements the PostgreSQL v3 protocol — startup messages, prepared statements, COPY, bind/execute. Authenticated sessions are handled by a connExecutor (pkg/sql/conn_executor.go). The connExecutor drives a state machine (pkg/sql/txn_state.go) that owns the SQL transaction, retries on retryable errors, and dispatches statements to a planner.

Optimizer and planner

CockroachDB uses a Cascades-style cost-based optimizer in pkg/sql/opt/ and a fallback heuristic planner in pkg/sql/. The optimizer normalizes SQL into a relational expression (opt.Expr), applies normalization rules (pkg/sql/opt/norm/rules/*.opt) and exploration rules (pkg/sql/opt/xform/rules/*.opt), and produces a physical plan that an ExecBuilder (pkg/sql/opt/exec/execbuilder/) lowers into a tree of plan nodes.

Execution

Two execution engines run side-by-side. The row-at-a-time engine (pkg/sql/*.go plan nodes such as scanNode, joinNode, renderNode) is the default for OLTP. The vectorized engine (pkg/sql/colexec/, pkg/sql/colflow/) processes batches of columnar data for analytical queries. Both can be parallelized across nodes via DistSQL (pkg/sql/distsql*.go, pkg/sql/flowinfra/).

Transactional KV

pkg/kv/ exposes kv.DB and kv.Txn as the in-process API for SQL. A KV operation is a roachpb.BatchRequest that travels through TxnSender (pkg/kv/kvclient/kvcoord/) where the TxnCoordSender interceptors handle pipelining, refresh, savepoints, parallel commits, and heartbeating. The DistSender partitions a batch across the ranges that own its keys, dispatches RPCs, and merges responses.

KV server

Each node owns a set of ranges in pkg/kv/kvserver/. The central type is Replica (pkg/kv/kvserver/replica.go) — a single Raft-replicated key range. Replicas use a latch manager (pkg/kv/kvserver/spanlatch/), a lock table (pkg/kv/kvserver/concurrency/), an MVCC layer, and a "below-Raft" application path (replica_app_batch.go, replica_application_state_machine.go). The Store (pkg/kv/kvserver/store.go) hosts many replicas, runs queue-based maintenance (split, merge, replicate, GC, lease, raft snapshot, MVCC GC, time series), and gossip.

Raft

pkg/raft/ is a fork of etcd/raft with CockroachDB-specific extensions: store-liveness-driven lease epochs (pkg/raft/raftstoreliveness/), term cache, learner replicas, and metric integration. Each Replica owns a RawNode and feeds its log entries into Pebble through a per-store log writer (pkg/kv/kvserver/logstore/).

Storage

pkg/storage/ wraps Pebble with CockroachDB's MVCC encoding (pkg/storage/mvcc.go, ~340 KLOC of code and tests), the lock-table encoding (pkg/storage/lock_table_iterator.go), encryption-at-rest (pkg/storage/encryption.go, with the CCL implementation in pkg/ccl/storageccl/engineccl/), and SST ingestion. Format major versions are tied to cluster versions through min_version.go.

RPC and node lifecycle

pkg/rpc/ manages gRPC and DRPC connections, mutual TLS, heartbeat-based liveness, clock offset tracking, and connection pools. pkg/server/server.go starts every component on a node — listeners, stores, replicas, jobs, the SQL server, the HTTP/admin servers — and orchestrates draining at shutdown (pkg/server/drain.go). Multi-tenancy (server_controller*.go, pkg/server/tenant.go) lets a single host process run multiple SQL servers, each with its own catalog and gateway.

Cross-cutting machinery

• Cluster versions and rolling upgrades — every backwards-incompatible change is gated on a cluster version (pkg/clusterversion/); migrations to a new version run jobs (pkg/upgrade/).
• Cluster settings — runtime-tunable knobs registered in pkg/settings/ and watched in-cluster via pkg/server/settingswatcher/.
• Jobs — schema changes, backups, restores, changefeeds, imports, and TTL deletes all run as registry-backed jobs (pkg/jobs/).
• Span configurations — zone configs are translated into roachpb.SpanConfigs by pkg/spanconfig/ and reconciled to KV through kvsubscriber.
• Multi-tenancy — see pkg/multitenant/ and pkg/ccl/multitenantccl/. Tenant capabilities limit what host APIs a tenant can call (pkg/multitenant/tenantcapabilities/).

Single-binary, symmetric topology

A CockroachDB cluster is homogeneous: every node runs the same binary and can serve every role. There is no master. Cluster-wide state that is too small to require Raft is propagated by a gossip network (pkg/gossip/); state that requires consistency lives in the KV store under reserved system ranges (pkg/keys/). Membership is tracked through node liveness records (pkg/kv/kvserver/liveness/), and store-liveness (pkg/kv/kvserver/storeliveness/) provides per-store fencing for leader leases.

Languages and shape

• ~9,100 Go source files (about 3,100 of them tests) under pkg/.
• ~990 TypeScript/TSX files for the DB Console (pkg/ui/).
• ~180 .proto files defining wire types.
• A C/C++ layer in c-deps/ for embedded GEOS, libroach helpers, and a few platform-specific builds.
• Bazel is the source of truth for builds; go.mod is kept in sync via ./dev generate bazel.