Systems

CockroachDB is organized as a stack of cooperating Go subsystems. Each page in this section documents one of them: the code under a top-level pkg/ directory (or a tightly related group), the responsibilities of the major types, and the points where one subsystem hands control to another.

The big picture

graph TD
  SQL["sql — pgwire, planner, distSQL, schema changer"]
  KV["kv — kv.DB, kv.Txn, DistSender, TxnCoordSender"]
  KVServer["kvserver — Replica, Store, queues, leases"]
  Raft["raft — log replication, leader election"]
  Storage["storage — MVCC over Pebble"]
  Server["server — node, gateway, admin/status APIs"]
  RPC["rpc — gRPC/DRPC, TLS, heartbeat"]
  Gossip["gossip"]
  Settings["settings + clusterversion + upgrade"]
  Jobs["jobs — registry-backed long-running tasks"]
  Security["security — TLS, JWT, OIDC, LDAP, password"]
  SpanCfg["spanconfig — zone-config reconciliation"]

  SQL --> KV
  KV --> KVServer
  KVServer --> Raft
  KVServer --> Storage
  Server --> SQL
  Server --> KVServer
  Server --> RPC
  Server --> Gossip
  Settings --> Server
  Jobs --> SQL
  Jobs --> KV
  SpanCfg --> KVServer
  Security --> RPC
  Security --> SQL

Pages in this section

• SQL — pkg/sql/: parser, planner, optimizer, execution engines, schema changer, pgwire.
• KV client — pkg/kv/: the transactional KV API used by SQL.
• KV server — pkg/kv/kvserver/: replicas, ranges, leases, queues, concurrency, latches.
• Raft — pkg/raft/: CockroachDB's fork of etcd/raft.
• Storage / MVCC — pkg/storage/: Pebble-backed engine, MVCC encoding, SSTs, encryption.
• Server — pkg/server/: node lifecycle, HTTP/gRPC servers, multi-tenant orchestration.
• RPC — pkg/rpc/: connection management, TLS, heartbeat, DRPC.
• Security — pkg/security/: certs, auth providers (JWT/OIDC/LDAP/SCRAM), key management.
• Gossip — pkg/gossip/: cluster-wide ephemeral state.
• Cluster version & upgrade — pkg/clusterversion/, pkg/upgrade/: rolling upgrades and gating.
• Cluster settings — pkg/settings/: runtime knobs.
• Jobs — pkg/jobs/: registry, scheduling, persistence.
• Span config — pkg/spanconfig/: zone-config reconciliation.
• Util — pkg/util/: ~115 small foundation packages (HLC, log, syncutil, tracing, metric, …).

For features that span multiple subsystems (changefeeds, backup/restore, multi-region, multi-tenant, cross-cluster replication), see features.