On this page 
Warning:
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.
Note:
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.Overview
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.
Settings
Warning:
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 |
|---|---|---|---|
cloudstorage.gs.default.key |
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 |
timeseries.storage.enabled |
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: '127.0.0.1:9411'); 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
SET CLUSTER SETTINGSHOW CLUSTER SETTING- Diagnostics Reporting
- Start a Node
- Use the Built-in SQL Client
Was this helpful?
