Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Follow the directions on "Getting and building CockroachDB from source" or "Building from source on macOS" to get your development environment set up.

Note that you do need a full installation of XCode to build on macOS. (No, a command-line tools instance does not suffice.) If you’ve already installed a command-line tools instance as part of setting up Homebrew or other tools, switch to the full XCode instance and accept the XCode license agreement with:


./dev build short also works as an aliasand will stage the binary at ./cockroach. Bazel will pretty-print build output to the terminal.


./dev build (or equivalently, ./dev build cockroach) is a synonym for thiswill do the same and will stage the binary at ./cockroach like above.

dev build is a light wrapper for bazel build that supports aliases for common targets (for example, ./dev build crlfmt instead of the harder-to-remember bazel build @com_github_cockroachdb_crlfmt//:crlfmt). dev also copies binaries out of the Bazel output directories for you into your workspace; for example, bazel build pkg/cmd/cockroach-short puts the binary in _bazel/bin/pkg/cmd/cockroach-short/cockroach-short_/cockroach-short, but if you dev build short the binary will be staged at ./cockroach instead.


  • dev test has a --stress flag for running tests under stress and --race for running tests with the race detector enabled.

  • Next to the test.log file produced by your test, you can find a test.xml file. This file contains specific information on each test run and its status, as well as timing information.

  • The -v argument to dev test will result in more verbose logging as well as more detailed information written to the test.xml. You can make this the default behavior on your machine by adding test --test_env=GO_TEST_WRAP_TESTV=1 to your .bazelrc.user file.

  • As with dev build, dev test allows you to pass additional arguments directly to Bazel by putting them after --: for example, dev test pkg/sql/types -- --verbose_failures --sandbox_debug.

  • To get test results printed as tests are being run add -v -- --test_output streamed to the test command. Note that this reduces test parallelism.For more tips on debugging test failures, see “How to

  • To attach a debugger to a hung dev test process tack -- -c dbg to the end of your command and it will disable stripping which breaks dlv (

  • For more tips on debugging test failures, see “How to ensure your tests can run in the Bazel sandbox


dev/bazel command

equivalent non-bazel command

./dev build

make build

./dev build short

make buildshort

./dev build pkg/sql/...

make build PKG=./pkg/sql/...

./dev test

make test

./dev test pkg/sql/parser -f TestParse

make test PKG=./pkg/sql/parser TESTS=TestParse

./dev test pkg/sql/parser -f TestParse --test-args '-test.count=5 -show-logs'

make test PKG=./pkg/sql/parser TESTS=TestParse TESTFLAGS='-count=5 -show-logs'

./dev bench pkg/sql/parser -f BenchmarkParse

make bench PKG=./pkg/sql/parser BENCHES=BenchmarkParse

./dev build --cross

build/ mkrelease

./dev builder


./dev testlogic base --files=fk --subtests=20042 --config=local

make testbaselogic FILES=fk SUBTESTS=20042 TESTCONFIG=local

Add build --define gotags=bazel,gss,X,Y to .bazelrc.user, then running dev

make ... TAGS=X,Y

Add gc_goopts = ["S"], to the go_library target in the BUILD.bazel file for the package you’re interested in, then running dev

make ... GOFLAGS=-gcflags=-S

General dev tips


Update the go_repository() declaration in DEPS.bzl for your dependency to point to a new remote and commit (see top-level comment in DEPS.bzl for more information), then build/test

Update local sources in vendor including your changes, then build/test

General dev tips

The top-level dev script uses Bazel to build pkg/cmd/dev before running unless another dev binary with the same increasing integer ID has already been built. Generally dev will invoke the dev binary “as of” that commit, which should usually be the correct behavior. However, if the default behavior does not work for some reason, you can find all the built versions of dev under bin/dev-versions.

A (hopefully) fast and error proof dev workflow

TODO(a UI developer): fill in gaps for UI dev workflow

11. Switch to a new branch

2. If your workflow involves an IDE, generate your protos ./dev gen protobuf

  • Your IDE relies on generated files for many tasks (e.g. code navigation, IntelliSense, debugging), and will complain unless you have re-generated those files.

    • If you need to re-generate all generated go files, use the slower ./dev gen go

    • If the above fails, run the slowest ./dev gen to update all of your generated files.

    • You may recall that with make , this step was not necessary. If you’re curious why, see this slack thread.


3. If your workflow involves UI development, you’ll want additionally do the following:

Code Block
./dev gen protobuf 
./dev generate js
# start a cockroach node, e.g.
./dev build && ./cockroach start-single-node
# in separate window, start UI watch for incremental UI builds
./dev ui watch
# now you're ready to write UI code!

4. Write some code!

  • If you add new files or imports, run ./dev gen bazel before compiling or running a test. compilepkg: missing strict dependencies: is usually the indicator that ./dev gen bazel needs to be re-run.

    • to skip this step, see tip below on ALWAYS_RUN_GAZELLE

  • Build the binary: ./dev build short

45. Run a test

  • On an IDE: your normal workflow should work if your generated files are up to date (See step 2).

  • From the command line: ./dev test [path/to/pkg] --filter [test_name]

56. Before opening/updating a PR: