Cluster Settings

On this page Carat arrow pointing down
CockroachDB v2.0 is no longer supported as of October 4, 2019. For more details, refer to the Release Support Policy.

This page shows you how to view and change CockroachDB's cluster-wide settings.

In contrast to cluster-wide settings, node-level settings apply to a single node. They are defined by flags passed to the cockroach start command when starting a node and cannot be changed without stopping and restarting the node. For more details, see Start a Node.


Cluster settings apply to all nodes of a CockroachDB cluster and control, for example, whether or not to share diagnostic details with Cockroach Labs as well as advanced options for debugging and cluster tuning.

They can be updated anytime after a cluster has been started, but only by the root user.


Many cluster settings are intended for tuning CockroachDB internals. Before changing these settings, we strongly encourage you to discuss your goals with Cockroach Labs; otherwise, you use them at your own risk.
SETTING TYPE DEFAULT DESCRIPTION string `` if set, JSON key to use during Google Cloud Storage operations
cloudstorage.http.custom_ca string `` custom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storage
cluster.organization string `` organization name
debug.panic_on_failed_assertions boolean false panic when an assertion fails rather than reporting
diagnostics.reporting.enabled boolean true enable reporting diagnostic metrics to cockroach labs
diagnostics.reporting.interval duration 1h0m0s interval at which diagnostics data should be reported
diagnostics.reporting.send_crash_reports boolean true send crash and panic reports
kv.allocator.lease_rebalancing_aggressiveness float 1E+00 set greater than 1.0 to rebalance leases toward load more aggressively, or between 0 and 1.0 to be more conservative about rebalancing leases
kv.allocator.load_based_lease_rebalancing.enabled boolean true set to enable rebalancing of range leases based on load and latency
kv.allocator.range_rebalance_threshold float 5E-02 minimum fraction away from the mean a store's range count can be before it is considered overfull or underfull
kv.allocator.stat_based_rebalancing.enabled boolean false set to enable rebalancing of range replicas based on write load and disk usage
kv.allocator.stat_rebalance_threshold float 2E-01 minimum fraction away from the mean a store's stats (like disk usage or writes per second) can be before it is considered overfull or underfull
kv.bulk_io_write.max_rate byte size 8.0 EiB the rate limit (bytes/sec) to use for writes to disk on behalf of bulk io ops
kv.bulk_sst.sync_size byte size 2.0 MiB threshold after which non-Rocks SST writes must fsync (0 disables)
kv.raft.command.max_size byte size 64 MiB maximum size of a raft command
kv.raft_log.synchronize boolean true set to true to synchronize on Raft log writes to persistent storage
kv.range.backpressure_range_size_multiplier float 2E+00 multiple of range_max_bytes that a range is allowed to grow to without splitting before writes to that range are blocked, or 0 to disable
kv.range_descriptor_cache.size integer 1000000 maximum number of entries in the range descriptor and leaseholder caches
kv.snapshot_rebalance.max_rate byte size 2.0 MiB the rate limit (bytes/sec) to use for rebalance snapshots
kv.snapshot_recovery.max_rate byte size 8.0 MiB the rate limit (bytes/sec) to use for recovery snapshots
kv.transaction.max_intents_bytes integer 256000 maximum number of bytes used to track write intents in transactions
kv.transaction.max_refresh_spans_bytes integer 256000 maximum number of bytes used to track refresh spans in serializable transactions
rocksdb.min_wal_sync_interval duration 0s minimum duration between syncs of the RocksDB WAL
server.consistency_check.interval duration 24h0m0s the time between range consistency checks; set to 0 to disable consistency checking
server.declined_reservation_timeout duration 1s the amount of time to consider the store throttled for up-replication after a reservation was declined
server.failed_reservation_timeout duration 5s the amount of time to consider the store throttled for up-replication after a failed reservation call
server.remote_debugging.mode string local set to enable remote debugging, localhost-only or disable (any, local, off)
server.shutdown.drain_wait duration 0s the amount of time a server waits in an unready state before proceeding with the rest of the shutdown process
server.shutdown.query_wait duration 10s the server will wait for at least this amount of time for active queries to finish
server.time_until_store_dead duration 5m0s the time after which if there is no new gossiped information about a store, it is considered dead
server.web_session_timeout duration 168h0m0s the duration that a newly created web session will be valid
sql.defaults.distsql enumeration 1 Default distributed SQL execution mode [off = 0, auto = 1, on = 2]
sql.distsql.distribute_index_joins boolean true if set, for index joins we instantiate a join reader on every node that has a stream; if not set, we use a single join reader
sql.distsql.interleaved_joins.enabled boolean true if set we plan interleaved table joins instead of merge joins when possible
sql.distsql.merge_joins.enabled boolean true if set, we plan merge joins when possible
sql.distsql.temp_storage.joins boolean true set to true to enable use of disk for distributed sql joins
sql.distsql.temp_storage.sorts boolean true set to true to enable use of disk for distributed sql sorts
sql.distsql.temp_storage.workmem byte size 64 MiB maximum amount of memory in bytes a processor can use before falling back to temp storage
sql.metrics.statement_details.dump_to_logs boolean false dump collected statement statistics to node logs when periodically cleared
sql.metrics.statement_details.enabled boolean true collect per-statement query statistics
sql.metrics.statement_details.threshold duration 0s minimum execution time to cause statistics to be collected
sql.trace.log_statement_execute boolean false set to true to enable logging of executed statements
sql.trace.session_eventlog.enabled boolean false set to true to enable session tracing
sql.trace.txn.enable_threshold duration 0s duration beyond which all transactions are traced (set to 0 to disable)
timeseries.resolution_10s.storage_duration duration 720h0m0s the amount of time to store timeseries data boolean true if set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhere
trace.debug.enable boolean false if set, traces for recent requests can be seen in the /debug page
trace.lightstep.token string `` if set, traces go to Lightstep using this token
trace.zipkin.collector string `` if set, traces go to the given Zipkin instance (example: ''); ignored if trace.lightstep.token is set.
version custom validation 2.0 set the active cluster version in the format '.'.

View Current Cluster Settings

Use the SHOW CLUSTER SETTING statement.

Change a Cluster Setting

Use the SET CLUSTER SETTING statement.

Before changing a cluster setting, please note the following:

  • Changing a cluster setting is not instantaneous, as the change must be propagated to other nodes in the cluster.

  • It's not recommended to change cluster settings upgrading to a new version of CockroachDB; wait until all nodes have been upgraded and then make the change.

See Also

Yes No
On this page

Yes No