|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## CockroachDB Development Environment |
| 6 | + |
| 7 | +CockroachDB is a distributed SQL database written in Go, built with Bazel and managed through a unified `./dev` tool. |
| 8 | + |
| 9 | +### Essential Commands |
| 10 | + |
| 11 | +**Setup and Environment Check:** |
| 12 | +```bash |
| 13 | +./dev doctor # Verify development environment setup |
| 14 | +``` |
| 15 | + |
| 16 | +**Building:** |
| 17 | +```bash |
| 18 | +./dev build cockroach # Build full cockroach binary |
| 19 | +./dev build short # Build cockroach without UI (faster) |
| 20 | +./dev build roachtest # Build integration test runner |
| 21 | +./dev build workload # Build load testing tool |
| 22 | +``` |
| 23 | + |
| 24 | +**Testing:** |
| 25 | +```bash |
| 26 | +./dev test pkg/sql # Run unit tests for SQL package |
| 27 | +./dev test pkg/sql -f=TestParse # Run specific test pattern |
| 28 | +./dev test pkg/sql --race # Run with race detection |
| 29 | +./dev test pkg/sql --stress # Run repeatedly until failure |
| 30 | +./dev testlogic # Run all SQL logic tests |
| 31 | +./dev testlogic ccl # Run enterprise logic tests |
| 32 | +./dev testlogic --files='prepare|fk' # Run specific test files |
| 33 | +``` |
| 34 | + |
| 35 | +**Code Generation and Linting:** |
| 36 | +```bash |
| 37 | +./dev generate # Generate all code (protobuf, parsers, etc.) |
| 38 | +./dev generate go # Generate Go code only |
| 39 | +./dev lint # Run all linters |
| 40 | +./dev lint --short # Run fast subset of linters |
| 41 | +``` |
| 42 | + |
| 43 | +### Architecture Overview |
| 44 | + |
| 45 | +CockroachDB follows a layered architecture: |
| 46 | +``` |
| 47 | +SQL Layer (pkg/sql/) → Distributed KV (pkg/kv/) → Storage (pkg/storage/) |
| 48 | +``` |
| 49 | + |
| 50 | +**Key Components:** |
| 51 | +- **SQL Engine**: `/pkg/sql/` - Complete PostgreSQL-compatible SQL processing |
| 52 | +- **Transaction Layer**: `/pkg/kv/` - Distributed transactions with Serializable Snapshot Isolation |
| 53 | +- **Storage Engine**: `/pkg/storage/` - RocksDB/Pebble integration with MVCC |
| 54 | +- **Consensus**: `/pkg/raft/` - Raft protocol for data replication |
| 55 | +- **Networking**: `/pkg/rpc/`, `/pkg/gossip/` - RPC and cluster coordination |
| 56 | +- **Enterprise Features**: `/pkg/ccl/` - Commercial features (backup, restore, multi-tenancy) |
| 57 | + |
| 58 | +**Key Design Patterns:** |
| 59 | +- Range-based data partitioning (512MB default ranges) |
| 60 | +- Raft consensus per range for strong consistency |
| 61 | +- Lock-free transactions with automatic retry handling |
| 62 | +- Multi-tenancy with virtual clusters |
| 63 | + |
| 64 | +### Development Workflow |
| 65 | + |
| 66 | +1. **Environment Setup**: Run `./dev doctor` to ensure all dependencies are installed |
| 67 | +2. **Building**: Use `./dev build short` for iterative development, `./dev build cockroach` for full builds |
| 68 | +3. **Testing**: Run package-specific tests with `./dev test pkg/[package]` |
| 69 | +4. **Code Generation**: After schema/proto changes, run `./dev generate go` |
| 70 | +5. **Quality Checks**: Run `./dev lint` before committing |
| 71 | + |
| 72 | +### Testing Strategy |
| 73 | + |
| 74 | +CockroachDB has comprehensive testing infrastructure: |
| 75 | +- **Unit Tests**: Standard Go tests throughout `/pkg/` packages |
| 76 | +- **Logic Tests**: SQL correctness tests using `./dev testlogic` |
| 77 | +- **Roachtests**: Distributed system integration tests |
| 78 | +- **Acceptance Tests**: End-to-end testing in `/pkg/acceptance/` |
| 79 | +- **Stress Testing**: Continuous testing with `--stress` flag |
| 80 | + |
| 81 | +### Build System |
| 82 | + |
| 83 | +- **Primary Tool**: Bazel (wrapped by `./dev` script) |
| 84 | +- **Cross-compilation**: Support for Linux, macOS, Windows via `--cross` flag |
| 85 | +- **Caching**: Distributed build caching for faster builds |
| 86 | +- **Multiple Binaries**: Produces `cockroach`, `roachprod`, `workload`, `roachtest`, etc. |
| 87 | + |
| 88 | +### Code Organization |
| 89 | + |
| 90 | +**Package Structure:** |
| 91 | +- `/pkg/sql/` - SQL layer (parser, optimizer, executor) |
| 92 | +- `/pkg/kv/` - Key-value layer and transaction management |
| 93 | +- `/pkg/storage/` - Storage engine interface |
| 94 | +- `/pkg/server/` - Node and cluster management |
| 95 | +- `/pkg/ccl/` - Enterprise/commercial features |
| 96 | +- `/pkg/util/` - Shared utilities across the codebase |
| 97 | +- `/docs/` - Technical documentation and RFCs |
| 98 | + |
| 99 | +**Generated Code:** |
| 100 | +Large portions of the codebase are generated, particularly: |
| 101 | +- SQL parser from Yacc grammar |
| 102 | +- Protocol buffer definitions |
| 103 | +- Query optimizer rules |
| 104 | +- Various code generators in `/pkg/gen/` |
| 105 | + |
| 106 | +Always run `./dev generate` after modifying `.proto` files, SQL grammar, or optimizer rules. |
| 107 | + |
| 108 | +### Special Considerations |
| 109 | + |
| 110 | +- **Bazel Integration**: All builds must go through Bazel - do not use `go build` or `go test` directly |
| 111 | +- **SQL Compatibility**: Maintains PostgreSQL wire protocol compatibility |
| 112 | +- **Multi-Version Support**: Handles mixed-version clusters during upgrades |
| 113 | +- **Performance Critical**: Many components are highly optimized with careful attention to allocations and CPU usage |
| 114 | + |
| 115 | +### Resources |
| 116 | + |
| 117 | +- **Main Documentation**: https://cockroachlabs.com/docs/stable/ |
| 118 | +- **Architecture Guide**: https://www.cockroachlabs.com/docs/stable/architecture/overview.html |
| 119 | +- **Contributing**: See `/CONTRIBUTING.md` and https://wiki.crdb.io/ |
| 120 | +- **Design Documents**: `/docs/design.md` and `/docs/tech-notes/` |
| 121 | + |
| 122 | +### When generating PRs and commit records |
| 123 | + |
| 124 | +- Follow the format: |
| 125 | + - Separate the subject from the body with a blank line. |
| 126 | + - Use the body of the commit record to explain what existed before your change, what you changed, and why. |
| 127 | + - Require the user to specify whether or not there should be release notes. Release notes should be specified after the body, following "Release Notes:". |
| 128 | + - When writing release notes, please follow the guidance here: https://cockroachlabs.atlassian.net/wiki/spaces/CRDB/pages/186548364/Release+notes |
| 129 | + - Require the user to specify an epic number (or None) which should be included at the bottom of the commit record following "Epic:". |
| 130 | + - Prefix the subject line with the package in which the bulk of the changes occur. |
| 131 | + - For multi-commit PRs, summarize each commit in the PR record. |
| 132 | + - Do not include a test plan unless explicitly asked by the user. |
0 commit comments