CockroachDB — Overview#

Identity#

• Module path: github.com/cockroachdb/cockroach
• Go version: 1.25.5
• License: CockroachDB Software License (CSL) — proprietary since v24.3 (Nov 2024); earlier versions were BSL or Apache 2.0
• Repository: https://github.com/cockroachdb/cockroach

Purpose#

CockroachDB is a cloud-native distributed SQL database designed for horizontal scalability, strong consistency (serializable isolation), and automatic survivability across disk, machine, rack, and datacenter failures. It provides a familiar PostgreSQL-compatible SQL interface over a transactional, strongly-consistent key-value store backed by the Raft consensus algorithm. Its target users are organizations building data-intensive applications that outgrow a single-node relational database and need geo-distributed, multi-region deployments without manual sharding.

Significance#

CockroachDB is one of the most architecturally ambitious Go projects in existence — a full-featured, production-grade distributed relational database written almost entirely in Go. Alongside TiDB and YugabyteDB, it pioneered the “NewSQL” category: the insight that you can build a globally distributed, ACID-compliant SQL database by layering a SQL engine atop a distributed KV store with Raft-based replication. As of 2024 the project transitioned from BSL to a proprietary CockroachDB Software License, signaling its maturity and commercial focus. With thousands of GitHub stars and a managed cloud offering (Cockroach Cloud), it is widely used by enterprises as a drop-in PostgreSQL replacement that survives cloud outages. The codebase is a masterclass in layered distributed systems architecture in Go.

Key metrics#

• Go files: 9,185 (XL tier — one of the largest Go codebases in open source)
• Top-level directories: build/, c-deps/, cloud/, docs/, licenses/, monitoring/, pkg/, scripts/, tools/
• Package distribution (by file count within pkg/):
  • sql/ — 3,344 files (SQL parser, planner, executor, optimizer)
  • kv/ — 1,079 files (distributed key-value layer, Raft, transactions)
  • cmd/ — 847 files (CLI binaries: cockroach, roachtest, roachprod, workload, etc.)
  • util/ — 788 files (shared utilities: tracing, logging, encoding, sync primitives)
  • ccl/ — 401 files (commercial/enterprise features loaded via init hooks)
  • server/ — 332 files (node server, admin/status APIs, gRPC endpoints)
  • storage/ — 142 files (Pebble MVCC storage engine wrapper)
  • cli/ — 218 files (cobra-based command-line interface)
• Direct dependencies: 216
• Indirect dependencies: 265 (go.mod); ~1,698 entries in go.sum
• First commit / age: Repository history shows continuous development since 2014 (copyright headers date to 2014); ~11 years old

Notable characteristics#

• Single-binary “cockroach” design: Every node runs the same binary and can act as SQL gateway, KV node, and Raft participant simultaneously. There are no separate coordinator or worker processes. The entry point (pkg/cmd/cockroach/main.go) is 5 lines — it delegates to pkg/cli after importing CCL init hooks.

• Layered distributed architecture: The system is built as distinct layers: PostgreSQL wire protocol → SQL planner/executor → distributed KV client (pkg/kv/kvclient) → Raft consensus + KV server (pkg/kv/kvserver) → MVCC storage on Pebble (pkg/storage). Each layer has well-defined interfaces, making the stack navigable despite the enormous codebase.

• Custom Raft implementation (pkg/raft): Rather than using etcd/raft, CockroachDB maintains its own fork/implementation of the Raft consensus algorithm. This gives the team full control over Raft internals, including integration with their HLC (hybrid logical clock) for causality tracking and their own MultiRaft optimizations.

• CCL (commercial feature) separation via init hooks: Enterprise features (backup/restore, change feeds, geo-partitioning, encryption-at-rest) live in pkg/ccl/ and are injected into the open-source binary via blank imports in pkg/cmd/cockroach/main.go. The OSS binary (cockroach-short) omits the CCL import. This is an elegant plugin-by-init-hook pattern for separating commercial and open-source code in a monorepo.

• Massive SQL engine: The pkg/sql directory alone has 3,344 Go files, containing a full SQL parser (custom, not generated via yacc), a cost-based optimizer (Cascade-style), a vectorized execution engine (pkg/col), and all DDL/DML execution logic. This rivals the scale of dedicated standalone database SQL engines.

• Bazel as primary build system: Despite being a Go project, CockroachDB uses Bazel (with WORKSPACE, BUILD.bazel files everywhere) for hermetic, reproducible builds. Every package has a BUILD.bazel file. The dev wrapper script orchestrates Bazel invocations. This is atypical for Go projects and signals the scale of the build graph.

• C dependency integration: The c-deps/ directory contains bundled C/C++ libraries (jemalloc, RocksDB/Pebble dependencies, GEOS for geospatial, KRB5 for Kerberos, PROJ for projections). CockroachDB uses CGo to link these, making it one of the more CGo-heavy Go projects at scale.

• PostgreSQL-wire-protocol compatibility: CockroachDB speaks the PostgreSQL wire protocol natively, allowing any PostgreSQL client driver to connect without modification. The pkg/sql/pgwire/ package handles wire protocol framing, authentication, and session management, making the SQL compatibility layer a first-class architectural concern.