Page Index

Space Index

0-9 ... 0 A ... 0 B ... 5 C ... 12 D ... 3 E ... 5
F ... 0 G ... 6 H ... 3 I ... 0 J ... 1 K ... 0
L ... 3 M ... 5 N ... 1 O ... 3 P ... 3 Q ... 0
R ... 4 S ... 2 T ... 4 U ... 5 V ... 0 W ... 3
X ... 0 Y ... 1 Z ... 0 !@#$ ... 0    




Page: Backporting a change to a release branch
All development starts on the master branch. In most cases, to add a commit to a patch release (or a beta/rc after a release branch has been created), you should submit a PR to master first and get it reviewed and merged there. PRs should be eligible for
Page: Ben's Go Emacs Setup
(This information was current as of 1/11/2016. As of 2022, it's rotted pretty badly, so I suggest looking elsewhere -Ben) In case you're interested, here's what I'm using in emacs now. I think these instructions will be at least somewhat repeatable. 1. Fi
Page: Bors Merge Bot
Overview To guard against merge skews we merge pull requests using a bot. Craig is that bot, an instance of bors-ng It compiles approved PRs as if they were merged, and merges them only after the CI on the original PR p
Page: Building and running tests
To build and run tests, just run make To run just presubmit checks (golint etc): make check Running the tests for a package: make test PKG=./sql Verbose test output: make test PKG=./sql TESTFLAGS='-v' Running tests, showing which tests are run and test fa
Page: Building from source on macOS
This guide is for users intending to develop CockroachDB. To USE CockroachDB consult these docs instead: - -


Page: Can I still commit/merge code if there is still work left to do?
Yes. Sometimes the work on a piece of code is sufficient for a proximate goal, although it does not yet reach the “ideal” target. We are OK with merging intermediate implementations, as long as the following holds: The implementation so far follows our en
Page: CLA Assistant stuck on PR
If your PR is unable to transition from the pending state, try these. X seems not to be a GitHub user The belonging to the author is checked against the list of GitHub accounts that signed the CLA. The GitHub account used to submit the pull req
Home page: CockroachDB
Welcome to the CockroachDB wiki space! This space is meant for technical documentation and guides specifically for contributors to CockroachDB itself. See also: CockroachDB code repository:
Page: CockroachDB Release Cycle
Overview CockroachDB targets a supported major release every 6 months, breaking down that time period into 5 months of development and 1 month of stabilization. For example, v21.1 is a major release. A major release is maintained by issuing periodic patch
Page: Code commenting guidelines
Comments are there to help the author of the code as well as current and future co-workers. Motivation and strategy Comments help yourself as much as your co-workers to remember the important bits: code you wrote 6 months ago might as well have been writt
Page: Code coverage
Coverage is computed in a nightly teamcity build This coverage ignores any automatically generated files such as protocol buffers as well as binaries that aren't necessary for run
Page: Code Labs
Various efforts have been made from time to time to create code labs: how-to documents that aim to help people understand the code by asking them to modify it themselves. The code labs live here. We don't have enough code labs, but we'd really like more!
Page: Code reviews
Page: Codelab: SQL↔KV hacking
This Codelab touches on the sql layer Insert node and how it communicates its writes to the KV layer. It also touches on lower-level (storage-level) concepts such as transactions and intents. As an excuse to touch interesting code points, we’ll hack toget
Page: Collecting a "debug zip" manually
When asked for help, the CockroachDB team often requests the output of the command cockroach debug zip. This utility automatically scrapes metadata about a cluster which can aid with debugging all kinds of issues. Sometimes, using cockroach debug zip is n
Page: Community Code of Conduct
The CockroachDB community’s Code of Conduct can be found at the following location:
Page: Contributing to CockroachDB
We made CockroachDB source-available to empower developers to fix and extend the product to better meet their needs. Nothing thrills us more than people so passionate about the product that they're willing to spend their own time to learn the codebase and


Page: Database Background
This list is a compilation of readings which are valuable to a general understanding of the operation of Cockroach. This list is extensive (but not exhaustive), don't feel you need to read everything here, it's provided as a way to drill down into topics
Page: Debugging with Delve
Note: In the past, Delve has garnered a reputation for randomly panicking and not living up to the expectations of a debugger. However, a couple of years have passed since then, and it is now possible to attach to and debug running cockroach clusters, mak
Page: Developing with Bazel
We’re partway through a migration of our build system to Bazel Bazel is a modern build system with better performance characteristics and correctness guarantees than we currently have with make/go build. Today, you can perform almost


Page: Engineering standards
Page: Error concepts and handling in CockroachDB
Error concepts Programmers do not usually like thinking about errors. When learning how to program, initially, programming assignments are silent about error handling, or at best dismissive. For many applications, the “best practice” for error handling is
Page: Error handling basics
Error Types We prefer the use of the CockroachDB errors library at This is a superset of Go's own errors and pkg/errors error
Page: Evaluate the complexity of your project
A good way to find a project properly sized for a first time contributor is to search for open issues with the label "help wanted" We separate three levels of complexity for projects: Low comp
Page: Execution tracing a SQL query
NB: “trace” or “tracing” herein refers to the go runtime’s tracing. This is not the distributed tracing, which is the instrumentation we add at the application level, although these certainly overlap in places. traceon / traceoff Adding traceon somefile.t



Page: Getting and building CockroachDB from source
Note that at least 4GB of RAM is required to build from source and run tests. Install prerequisites If you are on macOS, you may find the Building from source on macOS documentation useful. Either a working Docker install able to run GNU/Linux binaries (e
Page: Git Commit Messages
When you're ready to commit, be sure to write a Good Commit Message™. What's in a Good Commit Message™? We follow most general engineering best practices from other projects #GitCommitMessages-Howothersdoit using Git. Some additional guidelines specific t
Page: Git diff side by side
How to get a side by side diff with git diff or git difftool in the terminal. Alternative 1 Use icdiff, as instructed on install icdiff (from jeff
Page: GitHub Issue Labels
CockroachDB's GitHub repo uses a system of GitHub labels to organize issues. The labels are organized into groups based on a capital letter prefix. The labels are grouped to enhance discoverability and help suggest a standard set of labels that issues sho
Page: Go (Golang) coding guidelines
This coding guide is inspired from the Uber Go style guide at, with modifications specific to Cockroach Labs. Introduction These guidelines are the
Page: Go function argument patterns
Naive style: “require-everything” // Bad: brittle, hard to understand. MyFn("required arg", "foo", 0, nil, "bar", DefaultValue) // Still bad: more readable, but still brittle. If an argument is added // in the definition, or the order of arguments is chan


Page: High-complexity projects
These projects involve fundamental changes to the way CockroachDB works. What’s important to remember here is that supporting external development of these projects will take a non-trivial amount of time from the Cockroach team that would otherwise be spe
Page: How to ensure your code builds with Bazel
NOTE: This documentation is meant for people who are struggling with Bazel-only build failures. If instead you want a high-level guide to performing day-to-day development tasks using Bazel, check out the "Developing with Bazel" documentation. What is Baz
Page: How to ensure your tests can run in the Bazel sandbox
See also: How to ensure your code builds with Bazel This documentation is a work in progress; feel free to add any useful stuff that you may have uncovered. Background When Bazel executes tests via bazel test, its behavior differs from a standard go test



Page: Jargon: CockroachDB words for newcomers
saasSEO: glossary, terms, vocabulary, dictionary This page is Focusing here on those words and acronyms you may encounter in meetings or documents or Slack threads, but won't necessarily find explained



Page: Large scale testing
workload Workload refers both to the package and the tool. The package is built around an abstraction, called Generator, and the tool has various bits for working with generators. Generator is abstraction for a related collection of tables with (optionall
Page: Log and error redactability
Our customers routinely send crash reports and log files to us, but they want confidence that this data does not contain confidential information. How do we achieve this? For this purpose, the CockroachDB source code uses redactability. This is a crdb-spe
Page: Low-complexity projects
These cover things like bug fixes and small enhancements that do not involve any major architectural or design decisions. You should feel free to submit these for review as you come across them. Find or create an issue. Write the fix, include the appropri


Page: Maintaining CockroachDB
This page collects resources useful to the CockroachDB maintainers.
Page: Marking features as "not yet implemented"
Unimplemented errors occur when CRDB recognizes a SQL feature but it is not yet supported. These unimplemented errors can be used by the product team to help prioritize the roadmap. These errors are also useful to customers when they provide links to Gith
Page: Medium-complexity projects
For these projects, you should: Proactively reach out to the Cockroach team and discuss your proposal. One of our engineers will provide feedback on your design. Occasionally, you will be asked to contribute an RFC, too, in which case you should follow th
Page: Multi-tenant CockroachDB
Introduction and strategy Multi-tenant CockroachDB is a new way to structure the CockroachDB technology that achieves isolation between logical clusters. This is most useful when we share a common distributed storage across competing customers. (As an ana
Page: Multiple GOPATHs
Sometimes you want to work on different changes in parallel - most importantly, to be able to run a slow test on one change while developing another change. For this we need multiple clones of our repository (or multiple worktrees, see git-worktree http:/


Page: Nightly tests
Overview Every night, a set of tests run as part of the TeamCity project Nightlies These tests have a few common characteristics: They set up a temporary Cock


Page: Offline builds with Bazel
Unlike the make-driven build process which uses the checked-in sources in the vendor submodule, the Bazel build will download sources as needed. Under normal circumstances this should be transparent to the user, but if you are in an environment with no ne
Page: Organization of code into packages
We use Go packages to delimit units of functionality. We generally like smaller packages with a tight scope, but not so small that components that are always updated together are pulled away from each other by package boundaries. When to create new packag
Page: Organizing PRs and Commits
Short, simple projects produce a PR containing a single, small commit. However, we strongly encourage contributors to split up larger projects into multiple PRs or commits in order to make code reviews more effective. This happens mainly in two situations


Page: Page Index
Page: Productivity Tips
SourceGraph SourceGraph is a web-based source browser. It can enhance github with on-mouse-over information about types/function, links to jump to definition, language-aware searching. The enhanced repository can be accessed through
Page: Profiling CockroachDB
go tool pprof is a profiling tool built into Go. It is useful for understanding hotspots in your code. One can profile a running cockroach binary, or a specific go benchmark. Basics This blog post will get you



Page: Radu's vim setup
Quick and dirty tips for how to get started with vim and go. 1. Install pathogen mkdir -p ~/.vim/autoload ~/.vim/bundle curl -LSso ~/.vim/autoload/pathogen.vim And add to the top of ~/.vimr
Page: Rando scripts
The following code snippets are for general reuse. Some more scripts can be found here too: cockroachdb/scripts Configure git to fetch PRs (particularly nice with git log --decorate [try git config log.decorate auto]
Page: Release notes
We publish detailed release notes describing changes that impact external users of CockroachDB. The Docs team uses this script
Page: Reporting bugs in CockroachDB
I found a bug in CockroachDB! What should I do? If you believe your finding is security-related: please head to this page and follow instructions. If you can reproduce the problem relia


Page: SQL Syntax↔semantics Menagerie
This page outlines the relationship between: SQL syntax clauses, from the PostgreSQL dialect Algebraic-relational operators, provided by theory Nodes in the data structure (memo) used to represent logical plans during optimizations, that we call "relation
Page: Submitting your contribution
All contributors need to sign the Contributor License Agreement (Re-)Familiarize yourself with What is a Good CockroachDB PR. Create a local feature branch to do work on, ideally on one thing at a time. If you a


Page: TeamCity Continuous Integration (CI)
Overview We use JetBrains TeamCity for various continuous integration and testing tasks. Our instance is available at - you may sign in with your GitHub OAuth credentials. Pull request testing Team
Page: Testing CockroachDB
Here you can find resources on the various ways we test CockroachDB.
Page: Tracing operations with Jaeger, Zipkin and OpenTelemetry
CockroachDB has extensive verbose logging and distributed tracing instrumentation built-in. One way in which this instrumentation is useful is through 3rd party trace collectors like Jaeger and Zipkin. CRDB can be instructed to trace everything it does an
Page: Troubleshooting CockroachDB
Here you can find resources about analyzing and understanding an existing CockroachDB cluster.


Page: Understanding CockroachDB
Here you can find resources about learning and understanding CockroachDB and its ecosystem. Be sure to also check the online docs: CockroachDB product docs: Managed Cock
Page: Updating Go dependencies
CockroachDB uses vendoring to capture all its dependencies at a specific version. If your project requires a Go package that is not yet captured, you will need to add/update the dependencies. For this use the dependency README
Page: Updating PRs during review
During a review, the reviewer requests additional change to a PR. How to modify the PR to address reviewer comments? There are two main ways to do this: git commit --amend and git commit --fixup. Both are detailed below. The approaches proposed below refl
Page: Using ccache to speed up builds
Tired of recompiling our C++ libprotobuf and RocksDB every time you switch branches across commits to the vendor submodule? ccache is for you! ccache is a "compiler cache". It's a wrapper on top of all the C compilers that caches
Page: Using viewcore to analyze core dumps
Viewcore a tool for analyzing and exploring the memory in Go core dumps that was originally created by the Go team. It’s useful for debugging memory leaks, reproducible OOM issues, and worklo



Page: What is a Good CockroachDB PR
You have made some changes to CockroachDB and you want to submit it to the CockroachDB team for inclusion in the main release. How does this work? In summary, we will look at the following: Is this your first time submitting a PR? Check Your first Cockroa
Page: What to expect when you're expecting (someone to review your code at CRL)
At Cockroach Labs we take code reviewing seriously. This is for a number of reasons, some of which include: We have an open sourced repository and the quality of our code is a public reflection on our company. Databases are long-lived pieces of technology
Page: Working as a reviewer
We're all humans First and foremost, it's important to remember that the code you're reviewing was written by another human. To that end, you should consider the human side of reviewing code before getting to the technical aspects (a good primer of how t



Page: Your first CockroachDB PR
This document is a long-winded guide to preparing and submitting your first contribution to CockroachDB. It's primarily intended as required reading for new Cockroach Labs engineers, but may prove useful to external contributors too. The development cycle