Getting started

This page summarizes how to build, test, and run CockroachDB from source. The canonical reference is docs/building.md; if that document and this page disagree, the docs file wins.

Prerequisites

• 4 GB of RAM minimum, 8 GB+ recommended.
• Go matching go.mod (currently the version pinned by the Bazel toolchain). Required only for IDE work — Bazel ships its own toolchain.
• macOS: full XCode (not just CLI tools), then brew install autoconf cmake bazelisk make gpatch.
• Linux (Debian/Ubuntu): sudo apt install build-essential cmake autoconf bison patch libncurses-dev. Install bazelisk separately.
• A Docker-compatible runtime is required for cross-compilation: Rancher Desktop or Podman are recommended.

Run ./dev doctor before anything else — it prints actionable diagnostics for missing dependencies.

Build

CockroachDB uses Bazel as its build system. The wrapper ./dev (source: pkg/cmd/dev/) handles the common cases.

./dev build short          # cockroach without DB Console (faster)
./dev build                # full cockroach binary
./dev build pkg/util/log   # compile a single package as a check

The output binary is staged at ./cockroach in the repo root.

Run

./cockroach start-single-node --insecure --listen-addr=localhost:26257
./cockroach sql --insecure --host=localhost:26257

For a multi-node demo cluster without networking, use ./cockroach demo (pkg/cli/demo.go). For a real cluster, see the start and init subcommands documented at https://www.cockroachlabs.com/docs/stable/cockroach-start.html.

Test

./dev test pkg/sql                     # all unit tests in a package
./dev test pkg/sql -f=TestParse -v     # filter by name; -v warns on no match
./dev test pkg/sql --count=5           # rerun
./dev test pkg/sql --stress            # run under stress
./dev test pkg/sql --race              # race detector
./dev testlogic --files=F --subtests=S --config=C   # SQL logic tests

Test frameworks in use:

• Go unit tests — the bulk of the suite, in the same package as the code under test.
• Data-driven tests — cockroachdb/datadriven, with inputs and expected outputs in testdata/ directories.
• SQL logic tests — pkg/sql/logictest/, run by ./dev testlogic.
• Roachtests — long-running cluster tests that boot real CockroachDB processes (pkg/cmd/roachtest).

Code generation

Many files are generated and not checked into the repo; running ./dev test or ./dev build regenerates dependencies inside the Bazel sandbox automatically. To make generated files visible to your IDE:

./dev gen go               # protobuf, cgo stubs, all .go generation
./dev generate bazel       # update BUILD.bazel files (Gazelle)
./dev generate protobuf    # only .proto outputs

./dev generate (no args) regenerates everything and is slow.

Format and lint

crlfmt -w -tab 2 path/to/file.go     # CockroachDB-specific formatter
./dev lint --short

crlfmt enforces 100-column lines, 80-column comments, CRDB import grouping, and CRDB signature wrapping. It accepts one path at a time.

Common pitfalls

• A dev invocation that fails with stale BUILD.bazel files needs ./dev generate bazel.
• After editing .proto files, run ./dev generate protobuf.
• broken_in_bazel-tagged tests do not run under ./dev test. Use go test directly or fix the breakage; ping dev-inf for help.
• New go:generate directives are not executed in the Bazel sandbox; mirror the logic in a Bazel rule.

Where to go next

• Code structure: Architecture
• Domain vocabulary: Glossary
• Submitting a PR: How to contribute, docs/commits-and-prs.md
• Style: docs/style.md
• Backporting fixes: docs/backporting.md