CockroachDB

CockroachDB is a distributed SQL database that scales horizontally, survives datacenter failures, and provides strongly-consistent ACID transactions over a PostgreSQL-compatible wire protocol. It runs as a single Go binary (cockroach) and stores all user and system data in a single, monolithic, sorted key-value map that is partitioned into ranges, replicated by Raft, and persisted by a Pebble LSM-tree.

This wiki is a developer-oriented map of the source tree at commit 7ede7041c6. It explains what each subsystem does, where the code lives, and how the pieces fit together.

What this repo contains

The repository is dominated by Go code under pkg/. Major top-level subsystems:

• pkg/sql/ — the SQL layer: parser, optimizer, planner, distSQL, schema changer, vector index, pgwire.
• pkg/kv/ — the transactional KV API exposed to SQL (pkg/kv/kvclient/) and the per-store replication state machine (pkg/kv/kvserver/).
• pkg/storage/ — the on-disk MVCC engine built on Pebble.
• pkg/raft/ — a fork of etcd/raft adapted for CockroachDB.
• pkg/server/ — node lifecycle, HTTP/gRPC/DRPC servers, admin and status APIs, multi-tenant orchestration.
• pkg/rpc/ — gRPC and DRPC connection management, dialing, heartbeat, TLS.
• pkg/cli/ — every subcommand of the cockroach binary (start, sql, demo, debug, init, cert, …).
• pkg/ccl/ — features under the CockroachDB Software License: changefeeds, multi-region, cross-cluster replication, SQL proxy.
• pkg/cmd/ — secondary binaries: roachprod, roachtest, dev, workload, release, code generators.
• pkg/ui/ — the DB Console, a TypeScript/React app served by every node.

Additional foundation packages: pkg/security/ (TLS, JWT, OIDC, LDAP, password), pkg/jobs/ (long-running tasks), pkg/settings/ (cluster settings), pkg/clusterversion/ and pkg/upgrade/ (rolling-upgrade machinery), pkg/gossip/ (cluster-wide ephemeral state), pkg/spanconfig/ (zone-config plumbing), pkg/util/ (~115 utility subpackages: HLC, log, tracing, syncutil, metric, …).

Where to start reading

Goal	Start here
Understand the high-level system	Architecture, docs/design.md
Build and run from source	Getting started, docs/building.md
Pick up an issue	How to contribute, CONTRIBUTING.md
Find a domain term	Glossary
Find code owners	Maintainers, .github/CODEOWNERS

Sibling resources

• Public architecture guide: https://www.cockroachlabs.com/docs/stable/architecture/overview.html
• Original (and partially out-of-date) design doc: docs/design.md
• Tech notes covering specific subsystems: docs/tech-notes/
• Style and contribution guides: docs/style.md, docs/commits-and-prs.md, docs/backporting.md
• Active RFCs and design discussion: docs/RFCS/

License

Code released on or after 18 Nov 2024 (v24.3+ and recent patch releases) is published under the CockroachDB Software License (CSL); see the root LICENSE file. Earlier source files keep their original BSL or Apache headers. CCL-licensed code lives under pkg/ccl/.