Configuration

CockroachDB takes configuration from three layers, in increasing order of dynamicity:

1. Command-line flags to cockroach start (and friends).
2. Environment variables, mostly prefixed COCKROACH_.
3. Cluster settings, settable at runtime via SQL.

Command-line flags

Defined in pkg/cli/flags.go (and a few feature-specific files like flags_cert.go). The full list is also produced by:

cockroach start --help
cockroach gen man           # man pages
cockroach gen autocomplete  # bash/zsh completion

Important start-time flags include:

• --store — repeatable; one per data store. Accepts path=..., size=..., attrs=..., provisioned-rate=....
• --listen-addr, --advertise-addr, --http-addr — RPC and HTTP endpoints.
• --certs-dir, --insecure — TLS material.
• --locality — region=...,zone=...,az=... to place this node.
• --cache, --max-sql-memory — RAM budgets.
• --join — comma-separated node addresses for the initial join.
• --max-offset, --max-tombstone-count — clock and engine knobs.

Environment variables

pkg/util/envutil/env.go registers COCKROACH_* variables. Notable examples:

Variable	Purpose
COCKROACH_LOG_DIR	Default log directory
COCKROACH_LOG_MAX_SIZE	Log rotation size
COCKROACH_AUTO_BALLAST	Pre-allocate disk ballast
COCKROACH_DISABLE_QUIESCENCE	Disable Raft quiescence (debug)
COCKROACH_RAFT_LOG_MAX_SIZE	Raft log truncation
COCKROACH_USE_TENANT_NAME	Default tenant for shells
COCKROACH_DEV_LICENSE	Development license override

Run grep -r EnvOrDefault... pkg/util/envutil to see every registration call. The full set is also part of the diagnostic output.

Cluster settings

Cluster settings live in system.settings and are managed by pkg/settings/. The dump:

cockroach gen settings-list           # markdown
SELECT * FROM crdb_internal.cluster_settings;
SET CLUSTER SETTING <name> = ...;

Settings are typed (bool, int, float, string, duration, enum, byte size, version). They are classified as:

• Public — documented for end users.
• Reserved — internal, may change without notice.
• Sensitive — encrypted at rest.

There are over 1500 cluster settings; representative groups:

Prefix	Purpose
kv.*	KV behavior (leases, rangefeed, allocator)
kv.closed_timestamp.*	Closed-timestamp cadence
kv.snapshot_rebalance.*	Snapshot rate limiting
sql.*	SQL behavior (defaults, optimizer hints)
sql.distsql.*	Distributed SQL
sql.stats.*	SQL statistics retention
server.*	HTTP and admin
server.shutdown.*	Drain timing
changefeed.*	CDC tuning
bulkio.*	Backup/restore/IMPORT throughput
admission.*	Admission control
storage.*	Pebble and shared storage
cluster.preserve_downgrade_option	Pin cluster version
version	The cluster version

Session variables

Per-connection settings — SET <var> = ... — live in pkg/sql/sessiondata/ and pkg/sql/vars.go. The catalog SHOW ALL exposes them; some have Postgres-equivalent names (e.g. default_transaction_isolation).

Where to read what's currently in effect

• crdb_internal.cluster_settings and crdb_internal.session_variables — current values.
• crdb_internal.feature_usage — counts of recently-used features.
• cockroach debug zip — bundles all of the above for support.

Related pages

• systems/settings — implementation.
• systems/cluster-version-and-upgrade — the version setting.
• apps/cockroach — flag surface.