Development workflow

The day-to-day cycle for CockroachDB engineers and contributors.

One-time setup

1. Install prerequisites listed in getting started and docs/building.md.
2. Run ./dev doctor. It checks for missing toolchain components and prints fixes.
3. Optional but useful: echo 'ALWAYS_RUN_GAZELLE=1' >> ~/.bashrc so Bazel always regenerates BUILD.bazel files before tests.

Branching

CockroachDB uses a single mainline (master) plus active release branches (release-vXX.Y). Feature branches are personal and not pushed to the canonical repo.

git checkout master
git pull --rebase origin master
git checkout -b my-feature

Build and run

./dev build short                        # cockroach without DB Console
./cockroach start-single-node --insecure --listen-addr=localhost:26257
./cockroach sql --insecure --host=localhost:26257

For a quick multi-node demo without networking: ./cockroach demo --nodes=3 (pkg/cli/demo.go). For tests, prefer testserver (pkg/server/testserver.go) which is the same node implementation wrapped for in-process use.

Test loop

Run only the package you changed:

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

-v is important when combined with -f: without it, a misspelled filter silently passes by running zero tests.

For long-running flakes, use stress:

./dev test pkg/kv/kvserver --stress -f=TestReplica

Race-detect in CI is mandatory; reproduce locally with --race.

Code generation

Generated files are not checked in. The Bazel sandbox regenerates them on demand, but your IDE will not see the output until you "lift" it into the worktree:

./dev gen go             # all generated .go (protobuf, optgen, stringer, …)
./dev gen bazel          # update BUILD.bazel files (Gazelle)
./dev gen protobuf       # only protobuf
./dev gen                # everything (slow)

After editing a .proto file, the typical sequence is ./dev gen protobuf && ./dev gen bazel && ./dev test <pkg>.

If you add a new file, edit imports, or rename anything, run ./dev gen bazel so Gazelle keeps BUILD.bazel in sync. If you skip this step, Bazel will compile the wrong file set.

Format and lint

crlfmt -w -tab 2 pkg/your/file.go    # required before pushing
./dev lint --short                   # subset, fast
./dev lint                           # full lint, slower

crlfmt enforces 100-column source, 80-column comments, CRDB import grouping, and CRDB long-signature wrapping. It accepts one path argument (file or directory) at a time.

Cross-compile

./dev build --cross                  # default: linux x86_64
./dev build --cross=macos            # also linuxarm, macos, macosarm, windows

Outputs land in artifacts/. Cross-compilation requires a Docker-compatible runtime (Rancher Desktop or Podman; Docker Desktop is restricted for Cockroach Labs employees).

Local dependency overrides

If you need to iterate on an upstream Go module without re-vendoring, edit .bazelrc.user (gitignored):

echo 'build --override_repository=com_github_google_btree=/path/to/local/btree' >> .bazelrc.user

The local clone needs an empty WORKSPACE and BUILD.bazel files; generate the latter with gazelle -go_prefix=<import-path> -repo_root=..

For a no-clone alternative, edit the go_repository rule in DEPS.bzl directly and point its remote and commit to your fork.

Environment variables that change behavior

Many CockroachDB packages honor COCKROACH_* environment variables for tests and debugging. A few you'll see in CI:

• COCKROACH_LOG_DIR — override the log directory.
• COCKROACH_TRACE_SQL_QUERIES — emit a span per SQL statement.
• COCKROACH_USE_HTTP_PROFILES — alter /debug/pprof behavior.

The full list is centralised in pkg/util/envutil/env.go.

Submitting

git commit -m "pkg/sql: short summary

Detailed description, usually multi-paragraph.

Release note (bug fix): User-facing description.

Epic: CRDB-1234"
git push origin my-feature

Open a PR against master. Land with /trunk merge. The merge bot (craig[bot]) re-runs CI on the rebased commits and merges only if green.