CockroachDB — Dependencies#

Module info#

• Module: github.com/cockroachdb/cockroach
• Go version: 1.25.5
• Direct dependencies: 216
• Indirect dependencies: 265 (481 total in go.mod)
• go.sum entries: 3,396 lines (~1,698 module versions)

Dependency categories#

Core infrastructure#

Key insight: CockroachDB maintains a substantial ecosystem of satellite packages under the cockroachdb/ GitHub org — these are not internal packages but separately versioned modules that have been extracted for reuse across CRDB tooling and the Pebble storage engine. The errors package alone is used in more than a third of all source files, functioning as a first-class citizen in the codebase.

Networking / RPC#

Key insight: CockroachDB uses gogo/protobuf (their own fork: cockroachdb/gogoproto) rather than the official Google protobuf library. This predates the modern google.golang.org/protobuf API and gives them custom code generation extensions. The recent addition of storj.io/drpc (also forked as cockroachdb/drpc) represents an architectural shift — DRPC is a simpler, higher-performance RPC protocol used for CLI-to-server connections and select internal paths where gRPC overhead is undesirable.

Data / Storage#

Key insight: CockroachDB is its own storage engine user — it wraps Pebble (which it also develops). The separate pebble module versioning means Pebble can be released and tested independently. The Apache Arrow dependency powers the vectorized SQL execution engine (pkg/col), which operates on Arrow’s columnar batch format for OLAP-style query processing.

Cloud / Object Storage#

Key insight: CockroachDB carries both the old aws-sdk-go (v1) and the new aws-sdk-go-v2 simultaneously, indicating an ongoing migration. The cloud SDK dependencies are almost entirely confined to pkg/cloud/ and pkg/ccl/ (commercial features), particularly backup/restore and changefeed sinks.

Streaming / Message Queues (Changefeed)#

Key insight: The changefeed (CDC) system has two Kafka client libraries simultaneously — the older Sarama (IBM fork) and the newer franz-go. This dual-client situation mirrors the AWS SDK migration pattern and reflects the evolution of the streaming ecosystem. The franz-go library is widely adopted across the Go community and appears in multiple projects in this analysis set.

Observability#

Key insight: The observability stack is unusually broad — CRDB supports Prometheus, OpenTelemetry, Jaeger, Sentry, DataDog, Grafana Alloy, and InfluxDB simultaneously. This reflects their enterprise customer base: different organizations use different monitoring stacks, and CockroachDB must integrate with all of them. The Prometheus fork (cockroachdb/client_golang) was created specifically to improve histogram update performance at CRDB’s scale.

Authentication / Security / Enterprise#

CLI / Terminal UI#

Geospatial#

Testing#

Key insight: datadriven is CockroachDB’s most important testing innovation — a text-file-based testing DSL where test inputs and expected outputs are stored in human-readable files. This makes SQL query tests readable, reviewable, and rerunnable without recompilation. With 274 import sites, it’s the backbone of the SQL testing infrastructure.

Development Tools (go.mod tool directive)#

github.com/bufbuild/buf/cmd/buf           # Protocol Buffer management
github.com/cockroachdb/crlfmt             # CockroachDB-style Go formatter  
github.com/cockroachdb/gostdlib/...       # Pinned gofmt/goimports versions
github.com/cockroachdb/stress             # Stress test runner
github.com/golang/mock/mockgen            # Mock generation
github.com/grpc-ecosystem/grpc-gateway/.. # gRPC-gateway code gen
github.com/kevinburke/go-bindata/...      # Binary asset embedding
github.com/kisielk/errcheck               # Error return linting
github.com/mmatczuk/go_generics/...       # Go generics emulation (pre-1.18)
github.com/pseudomuto/protoc-gen-doc/...  # Proto documentation gen
github.com/swaggo/swag/cmd/swag           # OpenAPI/Swagger doc gen
golang.org/x/perf/cmd/benchstat           # Benchmark comparison
golang.org/x/tools/cmd/goyacc             # yacc-based parser generator
honnef.co/go/tools/cmd/staticcheck        # Static analysis
github.com/buchgr/bazel-remote            # Remote Bazel cache

CockroachDB uses the Go 1.24+ tool directive (22 tool deps) to pin all development tool versions in go.mod, ensuring all contributors use identical versions of formatters, linters, and code generators — a practice not yet common in the Go ecosystem.

Other Notable Dependencies#

Stdlib reliance#

The standard library is deeply and heavily used across the codebase. Top stdlib packages by import count across pkg/:

The ratio of stdlib to third-party usage is high: context, fmt, testing, and time alone account for more imports than any external package. CockroachDB’s philosophy is to use stdlib heavily and reach for external dependencies only when the need is clear and well-justified. Notably, golang.org/x/* packages are explicitly documented in go.mod as being treated as extended stdlib by the team.

Shared dependencies#

Dependencies shared with other projects in this 50-project analysis set (creating cross-project connections for the book):

Vendoring#

No vendor directory. CockroachDB does not vendor its Go dependencies. With 216 direct dependencies and the total module graph, vendoring would be impractical (hundreds of MB of source). The project uses the standard Go module proxy (proxy.golang.org) and pins specific versions in go.mod. The Bazel build system uses its own dependency resolution separate from the module system, with gazelle and rules_go generating BUILD.bazel files from go.mod.

Notable dependency decisions#

1. The CockroachDB satellite ecosystem#

Rather than growing a monolithic codebase, CRDB has extracted key infrastructure into separately versioned modules under github.com/cockroachdb/: errors, pebble, redact, logtags, apd, tokenbucket, datadriven, crlib, cmux, swiss. These are real open-source packages usable by others, not just internal packages — a form of architectural discipline that forces clear API boundaries. This is unusual at this scale.

2. Forking upstream dependencies (replace directives)#

CockroachDB maintains 10 replace directives pointing to CRDB-maintained forks:

• gogo/protobuf → cockroachdb/gogoproto: Extended protobuf with CRDB-specific code generation
• prometheus/client_golang → cockroachdb/client_golang: Histogram perf improvements
• charmbracelet/bubbletea → cockroachdb/bubbletea: Bracketed paste mode (PR pending upstream)
• olekukonko/tablewriter → cockroachdb/tablewriter: Custom cell rendering
• storj.io/drpc → cockroachdb/drpc: Custom DRPC extensions
• gopkg.in/yaml.v2 → cockroachdb/yaml: YAML parsing fixes
• snowflakedb/gosnowflake → cockroachdb/gosnowflake: Private API access
• knz/strtime → cockroachdb/strtime: Time parsing fixes

This fork-and-maintain pattern is a significant operational burden but gives the team precise control over critical infrastructure. It also means upstream users may benefit when CRDB eventually upstreams their changes.

3. gogo/protobuf over google.golang.org/protobuf#

The 182-to-19 ratio of gogo/protobuf to google.golang.org/protobuf imports reflects CRDB’s deep historical investment in the older gogo/protobuf ecosystem. The gogo/protobuf library offers more code generation customization (custom marshal/unmarshal, nullable fields, etc.) that CRDB exploited heavily for KV encoding performance. Migration to the modern google.golang.org/protobuf API is clearly in progress but expected to take years given the codebase scale.

4. Two Kafka clients#

Both IBM/sarama (legacy) and twmb/franz-go (modern) are imported simultaneously for the Kafka changefeed sink. The franz-go library (twmb/franz-go) is a pure Go, high-performance Kafka client that the Go community broadly considers superior to Sarama. CRDB’s dual-client state indicates an active migration — new Kafka features are being built on franz-go while old ones remain on Sarama.

5. DRPC as gRPC alternative#

The 2025 addition of storj.io/drpc (via CRDB’s fork cockroachdb/drpc) is architecturally notable. DRPC is a lightweight binary RPC protocol: no HTTP/2, no header compression overhead, simpler connection management. CRDB uses it for CLI-to-cluster connections (pkg/rpc/drpc.go) and select internal fast paths where gRPC’s overhead is measurable. This reflects CRDB’s willingness to invest in custom infrastructure when performance demands it.

6. golang.org/x/* as extended stdlib#

The go.mod includes a rare explicit comment treating all golang.org/x/* packages as extended standard library, subject to the same upgrade review process as Go itself. This means golang.org/x/crypto, golang.org/x/net, golang.org/x/sync, etc. are treated with extreme conservatism — changes require broad reviewer involvement. This is a notable team process decision codified in the module file itself.

7. Go tool directive for reproducible dev tooling#

The tool (...) section pins 22 development tools (linters, code generators, formatters) to exact versions in go.mod, using the Go 1.24+ tool directive. This ensures every developer, CI machine, and Bazel build uses identical tool versions — eliminating “works on my machine” linter discrepancies. This is forward-looking practice not yet adopted by most Go projects.

8. gcassert for performance regression prevention#

github.com/jordanlewis/gcassert is used to add compile-time assertions that specific values do NOT escape to the heap. This is rare in the Go ecosystem — CRDB’s hot paths are so performance-sensitive that they assert memory allocation behavior in test code, catching accidental heap allocations before they reach production.