# Repository: cockroachdb/cockroach # Stars: 32059 ## CLAUDE.md # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## CockroachDB Development Environment CockroachDB is a distributed SQL database written in Go. We use Bazel as a build system but most operations are wrapped through the `./dev` tool, which should be preferred to direct `go (build|test)` or `bazel` invocations. ### Essential Commands #### Building a package / package tests This is useful as a compilation check. ```bash # Build package ./pkg/util/log ./dev build pkg/util/log # Build the tests in package ./pkg/util/log ./dev build pkg/util/log:log_test ``` #### Testing ```bash ./dev test pkg/sql # run unit tests for SQL package (slow!) ./dev test pkg/sql -f=TestParse -v # run specific test pattern ./dev test pkg/sql --count=5 # run test multiple times ``` Note that when filtering tests via `-f` to include the `-v` flag which will warn you in the output if your filter didn't match anything. Look for `testing: warning: no tests to run` in the output. See `./dev test --help` for all options. #### Building ```bash ./dev build cockroach # build full cockroach binary ./dev build short # build cockroach without UI (faster) ``` Building a CockroachDB binary (even in short mode) should be considered slow. Avoid doing this unless necessary. Use `./dev build --help` for the entire list of artifacts that can be built. #### Code Generation and Linting Protocol buffers, SQL parser, SQL Optimizer rules and others rely on Go code generated by `./dev generate `. This should be considered a slow command. Rebuild only what is actually needed. `./dev (test|build)` commands automatically generate their dependencies, but do not lift them into the worktree, i.e. if they need to be visible to you, you need to invoke the appropriate `./dev generate` command yourself. ```bash ./dev generate # generate all code (protobuf, parsers, etc.) - SLOW ./dev generate go # generate Go code only ./dev generate bazel # update BUILD.bazel files when dependencies change ./dev generate protobuf # generate protobuf files - relatively fast ``` See `./dev generate --help`. ### Architecture Overview CockroachDB consists of many components and subsystems. The file .github/CODEOWNERS is a good starting point if the overall architecture is relevant to the task. ## Coding Guidelines ### Code Formatting After editing Go files, run `crlfmt -w -tab 2 .go` to format them. `crlfmt` is CockroachDB's custom formatter (not `gofmt`); it enforces 100-column code lines, 80-column comments, and CockroachDB-specific signature wrapping. It also handles import grouping. `crlfmt` accepts one path argument at a time (either a file or directory). The formatter is not used on checked-in, generated files. ### Engineering Standards CockroachDB is a complex system and you should write code under the assumption that it will have to be understood and modified in the future by readers who have basic familiarity with CockroachDB, but are not experts on the respective subsystem. Key concepts and abstractions should be explained clearly, and lifecycles and ownership clearly stated. Whenever possible, you should use examples to make the code accessible to the reader. Comments should always add depth to the code (rather than repeating the code). When reviewing, other than technical correctness, you should also focus on the above aspects. Do not over-emphasize on grammar and comment typos, prefix with "nit:" in reviews. CockroachDB is a distributed system that allows for rolling upgrades. This means that any shared state or inter-process communication needs to be mindful of compatibility issues. See `pkg/clusterversion` for more on this. When adding or reviewing a newly added file with a license header the year on the header should be the current year. Favor modern Go idioms in new or updated code and use the standard library (e.g. the `slices`, `maps`, and `cmp` packages) where appropriate. ### Resources - **Main Documentation**: https://cockroachlabs.com/docs/stable/ - **Architecture Guide**: https://www.cockroachlabs.com/docs/stable/architecture/overview.html - **Contributing**: See `/CONTRIBUTING.md` and https://wiki.crdb.io/ - **Design Documents**: `/docs/design.md` and `/docs/tech-notes/` ### When generating PRs and commit records Use the `/commit-helper` skill when creating commits and PRs. - For multi-commit PRs, describe the overall goal and the approach taken. Reference individual commits only when needed for orientation (e.g. "early commits are mechanical refactors; the last two hook everything up"). Don't repeat commit messages — they're visible in the commit list and go stale as the PR evolves. - Do not include a test plan unless explicitly asked by the user. - Always include an `Epic:` footer in PR descriptions. Use the epic from prior context or attached issues if available, otherwise `Epic: none`. ### Skills The following repo-specific skills are available: - `/commit-helper` — Create commits and PRs with properly formatted messages and release notes. - `/file-crdb-issue` — File GitHub issues using CockroachDB templates and labeling conventions. - `/review-crdb` — Review code changes or PRs for correctness and reviewability. # Interaction Style * Be direct and honest. * Skip unnecessary acknowledgments. * Correct me when I'm wrong and explain why. * Suggest better alternatives if my ideas can be improved. * Focus on accuracy and efficiency. * Challenge my assumptions when needed. * Prioritize quality information and directness. ## README.md

--- CockroachDB is a cloud-native distributed SQL database designed to build, scale, and manage modern, data-intensive applications. - [What is CockroachDB?](#what-is-cockroachdb) - [Docs](#docs) - [Starting with Cockroach Cloud](#starting-with-cockroachcloud) - [Starting with CockroachDB](#starting-with-cockroachdb) - [Client Drivers](#client-drivers) - [Deployment](#deployment) - [Need Help?](#need-help) - [Contributing](#contributing) - [Design](#design) - [Comparison with Other Databases](#comparison-with-other-databases) - [See Also](#see-also) ## What is CockroachDB? CockroachDB is a distributed SQL database built on a transactional and strongly-consistent key-value store. It **scales** horizontally; **survives** disk, machine, rack, and even datacenter failures with minimal latency disruption and no manual intervention; supports **strongly-consistent** ACID transactions; and provides a familiar **SQL** API for structuring, manipulating, and querying data. For more details, see our [product overview](https://www.cockroachlabs.com/product/overview/), [FAQ](https://cockroachlabs.com/docs/stable/frequently-asked-questions.html) or [architecture document]( https://www.cockroachlabs.com/docs/stable/architecture/overview.html). ## Docs For guidance on installation, development, deployment, and administration, see our [User Documentation](https://cockroachlabs.com/docs/stable/). ## Starting with CockroachCloud We can run CockroachDB for you, so you don't have to run your own cluster. See our online documentation: [Quickstart with CockroachCloud](https://www.cockroachlabs.com/docs/cockroachcloud/quickstart.html) ## Starting with CockroachDB 1. Install CockroachDB: [using a pre-built executable](https://www.cockroachlabs.com/docs/stable/install-cockroachdb.html) or [build it from source](https://cockroachlabs.atlassian.net/wiki/spaces/CRDB/pages/181338446/Getting+and+building+CockroachDB+from+source). 2. [Start a local cluster](https://www.cockroachlabs.com/docs/stable/start-a-local-cluster.html) and connect to it via the [built-in SQL client](https://www.cockroachlabs.com/docs/stable/use-the-built-in-sql-client.html). 3. [Learn more about CockroachDB SQL](https://www.cockroachlabs.com/docs/stable/learn-cockroachdb-sql.html). 4. Use a PostgreSQL-compatible driver or ORM to [build an app with CockroachDB](https://www.cockroachlabs.com/docs/stable/hello-world-example-apps.html). 5. [Explore core features](https://www.cockroachlabs.com/docs/stable/demo-data-replication.html), such as data replication, automatic rebalancing, and fault tolerance and recovery. ## Client Drivers CockroachDB supports the PostgreSQL wire protocol, so you can use any available PostgreSQL client drivers to connect from various languages. - For recommended drivers that we've tested, see [Install Client Drivers](https://www.cockroachlabs.com/docs/stable/install-client-drivers.html). - For tutorials using these drivers, as well as supported ORMs, see [Example Apps](https://www.cockroachlabs.com/docs/stable/example-apps.html). ## Deployment - [CockroachCloud](https://www.cockroachlabs.com/docs/cockroachcloud/quickstart) - Steps to create a [free CockroachCloud cluster](https://cockroachlabs.cloud/signup?referralId=githubquickstart) on your preferred Cloud platform. - [Manual](https://www.cockroachlabs.com/docs/stable/manual-deployment.html) - Steps to deploy a CockroachDB cluster manually on multiple machines. - [Cloud](https://www.cockroachlabs.com/docs/stable/cloud-deployment.html) - Guides for deploying CockroachDB on various cloud platforms. - [Orchestration](https://www.cockroachlabs.com/docs/stable/orchestration.html) - Guides for running CockroachDB with popular open-source orchestration systems. ## Need Help? - [CockroachDB Community Slack](https://go.crdb.dev/p/slack) - Join our slack to connect with our engineers and other users running CockroachDB. - [CockroachDB Forum](https://forum.cockroachlabs.com/) and [Stack Overflow](https://stackoverflow.com/questions/tagged/cockroachdb) - Ask questions, find answers, and help other users. - [Troubleshooting documentation](https://www.cockroachlabs.com/docs/stable/troubleshooting-overview.html) - Learn how to troubleshoot common errors, cluster setup, and SQL query behavior. - For filing bugs, suggesting improvements, or requesting new features, help us out by [opening an issue](https://github.com/cockroachdb/cockroach/issues/new). ## Building from source See [our wiki](https://wiki.crdb.io/wiki/spaces/CRDB/pages/181338446/Getting+and+building+from+source) for more details. ## Contributing We welcome your contributions! If you're looking for issues to work on, try looking at the [good first issue list](https://github.com/cockroachdb/cockroach/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). We do our best to tag issues suitable for new external contributors with that label, so it's a great way to find something you can help with! See [our wiki](https://wiki.crdb.io/wiki/spaces/CRDB/pages/73204033/Contributing+to+CockroachDB) for more details. Engineering discussions take place on our public mailing list, [cockroach-db@googlegroups.com](https://groups.google.com/forum/#!forum/cockroach-db). Also please join our [Community Slack](https://go.crdb.dev/p/slack) (there's a dedicated #contributors channel!) to ask questions, discuss your ideas, and connect with other contributors. ## Design For an in-depth discussion of the CockroachDB architecture, see our [Architecture Guide](https://www.cockroachlabs.com/docs/stable/architecture/overview.html). For the original design motivation, see our [design doc](https://github.com/cockroachdb/cockroach/blob/master/docs/design.md). ## Licensing All versions released on or after November 18, 2024 (specifically, major version series v24.3 and later, and patch fixes for v23.1.29+, v23.2.16+, v24.1.7+, and v24.2.5+) are published under the [CockroachDB Software License (CSL)](./LICENSE). Source code in a given file is licensed under the CSL and the copyright belongs to The Cockroach Authors unless otherwise noted in the file or in a LICENSE or README file located in the same or a parent directory of the file. ## Comparison with Other Databases To see how key features of CockroachDB stack up against other databases, check out [CockroachDB in Comparison](https://www.cockroachlabs.com/docs/stable/cockroachdb-in-comparison.html). ## See Also - [Tech Talks](https://www.cockroachlabs.com/community/tech-talks/) (by CockroachDB founders, engineers, and customers!) - [CockroachDB User Documentation](https://cockroachlabs.com/docs/stable/) - [The CockroachDB Blog](https://www.cockroachlabs.com/blog/) - Key design documents - [Serializable, Lockless, Distributed: Isolation in CockroachDB](https://www.cockroachlabs.com/blog/serializable-lockless-distributed-isolation-cockroachdb/) - [Consensus, Made Thrive](https://www.cockroachlabs.com/blog/consensus-made-thrive/) - [Trust, But Verify: How CockroachDB Checks Replication](https://www.cockroachlabs.com/blog/trust-but-verify-cockroachdb-checks-replication/) - [Living Without Atomic Clocks](https://www.cockroachlabs.com/blog/living-without-atomic-clocks/) - [The CockroachDB Architecture Document](https://github.com/cockroachdb/cockroach/blob/master/docs/design.md)