cockroach

The cockroach binary is the database itself. It implements every server- and client-facing role: start, start-single-node, init, sql, cert, node, decommission, dump, debug, demo, tsdump, userfile, mt, auth-session, and many more.

Source layout

• pkg/cmd/cockroach/main.go — entry point. Calls cli.Main().
• pkg/cli/ (~150 .go files) — every subcommand. The package is intentionally heterogeneous: it pulls together SQL, KV, security, and observability code and is jointly owned by many teams.

High-level subcommand groups

Group	Files	Examples
Cluster lifecycle	start*.go, init.go, decommission*.go	start, init, node decommission
SQL clients	sql_client.go, clisqlshell/, clisqlclient/, clisqlexec/	sql, nodelocal upload, userfile
Certificates	cert.go, mt_cert.go	cert create-ca, cert create-node, mt cert create-tenant
Demo	demo.go, democluster/	demo, demo --nodes=3
Debug	debug.go (~62 KB), debug_*.go	debug zip, debug pebble, debug recover loss-of-quorum
Doctor	doctor.go	debug doctor cluster, debug doctor zipdir
Generation	gen.go	gen man, gen autocomplete, gen settings-list
Time series dump	tsdump.go, tsdump_upload.go	debug tsdump, debug tsdump upload
Multitenant	mt*.go	mt start-sql, mt proxy
Observability	zip*.go	debug zip, debug merge-logs

Start command

pkg/cli/start.go (~63 KB) is the largest single file and implements cockroach start. It:

• Parses flags (pkg/cli/flags.go, ~65 KB).
• Configures logging, profiling, and trace sinks.
• Builds a *server.Config (pkg/server/config.go).
• Calls server.NewServer, then s.Start(ctx).
• Waits for the OS signal that means "shut down" and runs s.Drain(...).

The companion files start_unix.go, start_windows.go, start_jemalloc.go, and start_linux_test.go cover platform specifics (signal handling, jemalloc tuning, prelink workarounds).

SQL shell

pkg/cli/clisqlshell/ is a featureful SQL REPL with line editing, syntax highlighting, prompt customization, completion against crdb_internal, and \set meta-commands. It is shared between cockroach sql and the standalone cockroach-sql.

debug

cockroach debug is a kitchen sink. Notable subcommands:

• debug zip (zip*.go) — capture cluster diagnostics.
• debug pebble — Pebble's own tool; works against the on-disk store.
• debug recover (debug_recover_loss_of_quorum.go, ~40 KB) — offline loss-of-quorum recovery.
• debug check-store — sanity-check a store directory.
• debug merge-logs — chronologically merge logs from a node set.
• debug send-kv-batch — manually craft and send a BatchRequest.
• debug job-trace — extract a job's trace.
• debug doctor — descriptor-correctness checks; consumes the same logic as cockroach debug zip analysis.
• debug ear — encrypt/decrypt store keys.

Config and context

• pkg/cli/context.go (~27 KB) — globally shared CLI context (server addr, certs, log dir, …).
• pkg/cli/flags.go (~65 KB) — flag definitions.
• pkg/cli/clientflags/, pkg/cli/cliflagcfg/ — shared flag plumbing.
• pkg/cli/clienturl/ — postgres URL helpers (server address resolution, CA discovery).

Testing

CLI test infrastructure lives in pkg/cli/testutils.go, pkg/cli/cli_test.go, and pkg/cli/interactive_tests/ (a pile of expect-style scripts for the SQL shell). Integration tests use testserver from pkg/server/.

Generated artifacts

cockroach gen produces:

• Man pages (gen man).
• Bash/zsh completion (gen autocomplete).
• Markdown help dumps for the docs site.
• A list of all cluster settings (gen settings-list).
• haproxy.cfg for an existing cluster.

These are wired into gen.go and gen_dashboard.go.

Related pages

• Server — what start boots.
• SQL — what sql connects to.
• Security — what cert produces.
• apps/cockroach-sql — the standalone SQL client.