Page Index

Space Index

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



Page: Adding, Updating and Deleting external dependencies
CockroachDB uses vendoring to capture all its dependencies at a specific version. If your project requires an external package that is not yet captured, you will need to add/update the dependencies. When ADDING or UPDATING dependencies, the update needs 4


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
Page: Cluster virtualization and Multi-tenant CockroachDB
Introduction and strategy Cluster virtualization 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, i.e. multi-t
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’ve migrated the cockroach 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 all day-to-


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. If using Bazel to build Cockroach (for master and v22.1 onward),
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 gro
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: Guidelines for Cluster Settings, CLI flags and Env vars
Note: these are a work in progress; check with #technical-leads-council for questions/clarification. Cluster settings Appropriateness Guideline: Consider appropriateness of a cluster setting versus some other configuration mechanism. A behavior specific t


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: How to investigate a Go test failure
Here is a list of recent Go test failures, in case you wanted to check out a few. CI jobs file issues when a test fails on a release branch,


Page: Issue and Epic Refs in Commits and PRs
Amidst a large and ever-growing volume of changes, connecting work to product roadmap epics via GitHub Issue and Jira Epic references (Issue and Epic Refs) improves the ability to make the connection between product changes and roadmap epics for the docs


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: Meeting notes
Incomplete tasks from meetings Decisions from meetings All meeting notes
Page: Multiple GOPATHs
Note: with the switch to Bazel, the build system does not have the same dependency on GOPATH and you can check out and build as many clones of the cockroach repo as you want in different locations. This information is kept here as written for reference or


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: Overview of all test frameworks
Any project usually needs a combination of multiple types of tests simultaneously: both unit and integration tests – the latter especially if there are user-facing features. Unit testing Unit tests are valuable to ensure that a single component or functio


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: Rail's Neovim setup
I use AstroNvim as my neovim distro. The up to date config can be found in my dotfiles repo The config uses AstroNvim abstraction, but it can be transla
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. Engineers provide "Release note" texts in their cockroach repo commits. These are then aggregated and edited by th
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: Roachtest overview
Roachtest is a test framework for integration testing of CockroachDB. In a nutshell, it consists of: a test suite in the crdb repo (pkg/cmd/roachtest/tests) a framework that invokes roachprod under the hood (roachprod is our general-purpose manual testing
Page: Roachtest vs TestServer/TestCluster
For testing CockroachDB we commonly use two separate frameworks: for unit tests (one bit of functionality at a time), we use the TestServer/TestCluster framework. for integration tests (using the entire CockroachDB server product as a customer would), we


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. TeamCity CI is deprecated
Page: Testing CockroachDB
Overview of all test frameworks The following sub-page detail our test mechanisms further.
Page: TestServer and TestCluster
Overview TestServer and TestCluster are two frameworks we built to create Go unit tests for CockroachDB, for tests that need a functional SQL layer and/or KV layer. TestServer simulates a single CockroachDB node. TestCluster simulates a multi-node Cockroa
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 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
Note: With the switch to Bazel, ccache is much less valuable. You should not need to have it installed and installing it is likely to impact your build in other ways. Finally, we have fewer C/C++ dependencies than we used to (e.g. no more RocksDB), and th
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



Copyright (C) Cockroach Labs.
Attention: This documentation is provided on an "as is" basis, without warranties or conditions of any kind, either express or implied, including, without limitation, any warranties or conditions of title, non-infringement, merchantability, or fitness for a particular purpose.