Configuration

Overview

CockroachDB provides multiple configuration mechanisms for controlling node behavior and cluster-wide settings. Configuration can be specified through command-line flags, environment variables, and SQL-based cluster settings.

Configuration Methods

Command-Line Flags

Flags are specified when starting a node:

cockroach start \
  --store=path=/mnt/data \
  --listen-addr=0.0.0.0:26257 \
  --cache=25% \
  --max-sql-memory=25%

Environment Variables

Many flags have corresponding environment variable equivalents:

export COCKROACH_INSECURE=true
export COCKROACH_HOST=localhost:26257
cockroach sql

Cluster Settings

Cluster-wide settings are modified via SQL:

SET CLUSTER SETTING cluster.organization = 'Acme Company';

Node Configuration Flags

Network Configuration

Listen Addresses

—listen-addrThe address for inter-node communication:

--listen-addr=0.0.0.0:26257

Default: localhost:26257—advertise-addrThe address advertised to other nodes:

--advertise-addr=node1.example.com:26257

—sql-addrSeparate address for SQL connections:

--sql-addr=0.0.0.0:26258

—http-addrAdmin UI and HTTP API address:

--http-addr=0.0.0.0:8080

Default: localhost:8080

Port Configuration

Default ports:

26257: SQL and inter-node communication
8080: Admin UI and HTTP API

Custom ports:

cockroach start \
  --listen-addr=:26000 \
  --http-addr=:8000

Storage Configuration

Store Specification

Basic store:

--store=path=/mnt/data

Store with attributes:

--store=attrs=ssd,path=/mnt/ssd1

Store with size limit:

--store=path=/mnt/data,size=100GiB

Multiple stores:

--store=attrs=ssd,path=/mnt/ssd1,size=100GiB \
--store=attrs=ssd,path=/mnt/ssd2,size=100GiB \
--store=attrs=hdd,path=/mnt/hdd1,size=1TiB

In-memory store (testing only):

--store=type=mem,size=1GiB

Memory Configuration

Cache Settings

—cacheSize of the cache for storing key-value data:

# Absolute size
--cache=2GiB

# Percentage of system memory
--cache=25%

Default: 128 MiB (or 25% of system memory)The cache stores frequently accessed data to reduce disk I/O.

SQL Memory

—max-sql-memoryMaximum memory for SQL operations:

# Absolute size
--max-sql-memory=4GiB

# Percentage of system memory
--max-sql-memory=25%

Default: 128 MiB (or 25% of system memory)Controls memory available for:

Query execution
Sorting operations
Hash joins
Intermediate query results

Go Memory Limit

—max-go-memoryGo runtime memory limit:

--max-go-memory=8GiB

Can also use GOMEMLIMIT environment variable:

export GOMEMLIMIT=8GiB

Locality Configuration

Locality Tiers

Configure node locality for geo-distributed deployments:

--locality=region=us-east,zone=us-east-1a,rack=rack1

Common patterns:

--locality=cloud=aws,region=us-east-1,zone=us-east-1a

Locality enables:

Replica placement preferences
Follower reads from nearby nodes
Geo-partitioning
Latency-based load balancing

Security Configuration

Certificate Configuration

Secure mode (production):

cockroach start \
  --certs-dir=/path/to/certs \
  --store=path=/mnt/data

Required certificates:

ca.crt: Certificate authority
node.crt: Node certificate
node.key: Node private key

Insecure mode (development only):

cockroach start --insecure

Never use --insecure in production. All traffic is unencrypted and unauthenticated.

Join Configuration

Join Addresses

Specify nodes to connect to when starting:

--join=node1:26257,node2:26257,node3:26257

Best practices:

List 3-5 stable nodes
Use DNS names or stable IPs
Same join list for all nodes
Nodes don’t need to be running
Can include self-reference

Examples:

# DNS-based
--join=cockroach.example.com:26257

# Multiple addresses
--join=10.0.1.1:26257,10.0.1.2:26257,10.0.1.3:26257

# With custom port
--join=node1:26000,node2:26000

Logging Configuration

Log Output Configuration

cockroach start \
  --log='file-defaults: {dir: /var/log/cockroach}'

Log Configuration Options

Log Flags

—log-dir (deprecated, use --log):

--log-dir=/var/log/cockroach

Equivalent to:

--log='file-defaults: {dir: /var/log/cockroach}'

—log-file-verbosity (deprecated):

--log-file-verbosity=WARNING

Equivalent to:

--log='file-defaults: {filter: WARNING}'

—log-file-max-size (deprecated):

--log-file-max-size=10MiB

Equivalent to:

--log='file-defaults: {max-file-size: 10MiB}'

See Logging Configuration for comprehensive logging setup.

Cluster Settings

Viewing Cluster Settings

SHOW CLUSTER SETTINGS;

Modifying Cluster Settings

-- Set a string setting
SET CLUSTER SETTING cluster.organization = 'Acme Company';

-- Set a numeric setting
SET CLUSTER SETTING kv.range_descriptor_cache.size = '128MiB';

-- Set a boolean setting
SET CLUSTER SETTING sql.stats.automatic_collection.enabled = true;

-- Set a duration setting
SET CLUSTER SETTING server.time_until_store_dead = '5m0s';

-- Reset to default
RESET CLUSTER SETTING cluster.organization;

Important Cluster Settings

Performance Settings

Setting	Description	Default
`kv.range_descriptor_cache.size`	Range descriptor cache size	64 MiB
`kv.raft.command.max_size`	Maximum Raft command size	64 MiB
`sql.distsql.distribute_index_joins`	Enable distributed index joins	true
`sql.stats.automatic_collection.enabled`	Auto-collect table statistics	true

Replication Settings

Setting	Description	Default
`kv.snapshot_rebalance.max_rate`	Maximum rebalance rate	32 MiB/s
`kv.snapshot_recovery.max_rate`	Maximum recovery rate	32 MiB/s
`server.time_until_store_dead`	Store considered dead after	5m0s

SQL Settings

Setting	Description	Default
`sql.defaults.default_int_size`	Default integer size (4 or 8)	8
`sql.defaults.serial_normalization`	Serial type normalization	rowid
`sql.log.slow_query.latency_threshold`	Log slow queries threshold	0s (disabled)

Diagnostics Settings

Setting	Description	Default
`diagnostics.reporting.enabled`	Enable diagnostic reporting	true
`cluster.organization`	Organization name	empty
`enterprise.license`	Enterprise license key	empty

Environment Variables

Common Environment Variables

Variable	Purpose	Example
`COCKROACH_INSECURE`	Enable insecure mode	`export COCKROACH_INSECURE=true`
`COCKROACH_HOST`	Default host	`export COCKROACH_HOST=localhost:26257`
`COCKROACH_CERTS_DIR`	Certificate directory	`export COCKROACH_CERTS_DIR=/certs`
`GOMEMLIMIT`	Go memory limit	`export GOMEMLIMIT=8GiB`
`GOGC`	Go GC percentage	`export GOGC=50`

Development Variables

# Skip telemetry
export COCKROACH_SKIP_ENABLING_DIAGNOSTIC_REPORTING=true

# Debug mode
export COCKROACH_DEBUG_MODE=true

Configuration Files

CockroachDB does not use traditional configuration files. Instead:

Command-line flags: Set at node startup
Cluster settings: Stored in system.settings table
Environment variables: Set in shell environment

To persist configuration, use init scripts or systemd unit files to set flags and environment variables.

Resource Limits

File Descriptors

CockroachDB requires high file descriptor limits:

# Check current limit
ulimit -n

# Set limit (requires root)
ulimit -n 35000

Recommended minimum: 35,000 file descriptors Permanent configuration in /etc/security/limits.conf:

cockroach soft nofile 35000
cockroach hard nofile 35000

Memory Limits

Recommended memory allocation:

Cache: 25% of system memory
SQL Memory: 25% of system memory
Go Runtime: Remaining system memory

Example for 16GB system:

cockroach start \
  --cache=4GiB \
  --max-sql-memory=4GiB \
  --max-go-memory=8GiB

Best Practices

Configuration Recommendations

Document all changes: Maintain a record of non-default settings
Test in staging: Validate configuration changes before production
Use percentages for memory: Adapts to different hardware
Set explicit locality: Required for geo-distributed deployments
Monitor resource usage: Adjust settings based on actual workload
Use secure mode: Always use certificates in production
Consistent configuration: Use same settings across similar nodes
Version awareness: Some settings require specific CockroachDB versions

Troubleshooting

Configuration Issues

Invalid flag values:

Check flag syntax and units (GiB vs GB)
Verify flag is supported in your version
Review startup logs for error messages

Setting not taking effect:

Cluster settings require SQL connection
Some settings require node restart
Check permissions for setting modification

Memory issues:

Increase --cache and --max-sql-memory
Check system memory availability
Monitor OOM events in system logs

Getting Started

Architecture

SQL Reference

Administration

Operations

Performance

Overview

Configuration Methods

Command-Line Flags

Environment Variables

Cluster Settings

Node Configuration Flags

Network Configuration

Storage Configuration

Memory Configuration

Locality Configuration

Security Configuration

Join Configuration

Logging Configuration

Log Output Configuration

Log Configuration Options

Cluster Settings

Viewing Cluster Settings

Modifying Cluster Settings

Important Cluster Settings

Environment Variables

Common Environment Variables

Development Variables

Configuration Files

Resource Limits

File Descriptors

Memory Limits

Best Practices

Troubleshooting

Configuration Issues

See Also

Build docs developers (and LLMs) love

Getting Started

Architecture

SQL Reference

Administration

Operations

Performance

​Overview

​Configuration Methods

​Command-Line Flags

​Environment Variables

​Cluster Settings

​Node Configuration Flags

​Network Configuration

​Storage Configuration

​Memory Configuration

​Locality Configuration

​Security Configuration

​Join Configuration

​Logging Configuration

​Log Output Configuration

​Log Configuration Options

​Cluster Settings

​Viewing Cluster Settings

​Modifying Cluster Settings

​Important Cluster Settings

​Environment Variables

​Common Environment Variables

​Development Variables

​Configuration Files

​Resource Limits

​File Descriptors

​Memory Limits

​Best Practices

​Troubleshooting

​Configuration Issues

​See Also

Build docs developers (and LLMs) love

Overview

Configuration Methods

Command-Line Flags

Environment Variables

Cluster Settings

Node Configuration Flags

Network Configuration

Storage Configuration

Memory Configuration

Locality Configuration

Security Configuration

Join Configuration

Logging Configuration

Log Output Configuration

Log Configuration Options

Cluster Settings

Viewing Cluster Settings

Modifying Cluster Settings

Important Cluster Settings

Environment Variables

Common Environment Variables

Development Variables

Configuration Files

Resource Limits

File Descriptors

Memory Limits

Best Practices

Troubleshooting

Configuration Issues

See Also