Skip to main content
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.
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.
This page provides information on:

Settings

These cluster settings have a broad impact on CockroachDB internals and affect all applications, workloads, and users running on a CockroachDB cluster. For some settings, a session setting could be a more appropriate scope.
Use ALTER ROLE ALL SET {sessionvar} = {val} instead of the sql.defaults.* cluster settings. This allows you to set a default value for all users for any session variable that applies during login, making the sql.defaults.* cluster settings redundant.
SettingTypeDefaultDescriptionDeployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckAdvanced/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionAll
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingAll
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingAll
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingAll
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlAdvanced/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlAll
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlAll
restore.default_direct_download.enabled
(alias: backup.restore.default_experimental_copy.enabled)
booleanfalseif enabled, RESTORE defaults to experimental fast copy mode when the backup is compatible, falling back to a normal restore otherwiseAll
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPAll
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failAll
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsAll
bulkio.import.row_count_validation.mode
(alias: bulkio.import.row_count_validation.unsafe.mode)
enumerationasynccontrols validation of imported data via INSPECT jobs. Options: ‘off’ (no validation), ‘async’ (background validation), ‘sync’ (blocking validation). If disabled, IMPORT will not perform a post-import row count check. [off = 0, async = 1, sync = 2]All
bulkio.merge.file_size
byte size1.0 GiBtarget size for individual data files produced during local only merge phasesAll
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upAdvanced/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.All
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillAll
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestAll
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesAll
changefeed.default_range_distribution_strategy
enumerationdefaultcontrols how changefeed work is distributed across nodes. ‘default’ defers to DistSQL for node selection and work distribution. ‘balanced_simple’ uses DistSQL for node selection but then attempts to evenly distribute ranges across those selected nodes for better load balancing. this setting does not override locality restrictions and can be overridden per-changefeed using the ‘range_distribution_strategy’ option. [default = 0, balanced_simple = 1]All
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferAll
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledAll
changefeed.external_connection.apply_uri_path_and_params.enabled
booleantrueif enabled, the path of an external:// sink URI is applied to the URI of the external connection it names, as are the topic_name and topic_prefix parameters when the connection leaves them unset, and any other parameter is an error; if disabled, the path and parameters are ignoredAll
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationAll
changefeed.span_checkpoint.lag_threshold
(alias: changefeed.frontier_highwater_lag_checkpoint_threshold)
duration10m0sthe amount of time a changefeed’s lagging (slowest) spans must lag behind its leading (fastest) spans before a span-level checkpoint to save leading span progress is written; if 0, span-level checkpoints due to lagging spans is disabledAll
changefeed.kafka.max_request_size
byte size256 MiBthe maximum number of uncompressed bytes sent in a single request to a Kafka broker; lowering this value helps avoid spurious “message too large” errors that can occur when multiple messages are combined into a single batch; this setting is overridden by the per-changefeed Flush { MaxBytes: <int> } optionAll
changefeed.kafka_v2_error_details.enabled
booleantrueif enabled, Kafka v2 sinks will include the message key, size, and MVCC timestamp in message too large errorsAll
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedAll
changefeed.resolved_timestamp.min_update_interval
(alias: changefeed.min_highwater_advance)
duration0sminimum amount of time that must have elapsed since the last time a changefeed’s resolved timestamp was updated before it is eligible to be updated again; default of 0 means no minimum interval is enforced but updating will still be limited by the average time it takes to checkpoint progressAll
changefeed.mvcc_ordered.buffer_size
byte size1.0 MiBcontrols when an mvcc_ordered changefeed spills its reordering buffer to temporary storage and how many bytes it releases at a timeAll
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsAll
changefeed.partition_alg.enabled
booleanfalseif enabled, allows specifying the partition_alg changefeed option to choose between fnv-1a (default) and murmur2 hash functions for Kafka partitioningAll
changefeed.permissions.require_external_io_implicit_access.enabled
(alias: changefeed.permissions.require_external_io_implicit_access)
booleantrueif enabled, a changefeed to a destination that the node authenticates to with implicit credentials requires the EXTERNALIOIMPLICITACCESS system privilegeAll
changefeed.progress.frontier_persistence.interval
duration30sminimum amount of time that must elapse before a changefeed will persist its entire span frontier againAll
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationAll
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampAll
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesAll
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueAll
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadAll
cloudstorage.azure.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.azure.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.azure.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.azure.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.external_connection.reject_query_parameters.enabled
booleantruewhen enabled, external:// URIs with query parameters fail with an error; when disabled, query parameters are silently ignoredAll
cloudstorage.gs.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.gs.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.gs.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.gs.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.http.custom_ca
stringcustom root CA (appended to system’s default CAs) for verifying certificates when interacting with HTTPS storageAll
cloudstorage.http.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.http.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.http.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.http.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.nodelocal.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.nodelocal.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.nodelocal.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.nodelocal.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.nullsink.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.nullsink.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.nullsink.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.nullsink.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.s3.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.s3.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.s3.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.s3.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsAll
cloudstorage.userfile.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.userfile.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.userfile.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cloudstorage.userfile.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroAll
cluster.auto_upgrade.enabled
booleantruewhen true, enables automatic finalization of major version upgrades once all cluster nodes are running an upgraded binaryAll
cluster.organization
stringorganization nameAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetAll
debug.zip.redact_addresses.enabled
booleanfalseenables the redaction of hostnames and ip addresses in debug zipAll
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.All
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesAll
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedAll
enterprise.license
stringthe encoded cluster licenseAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portAll
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)All
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueAll
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueAll
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueAll
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueAll
feature.infer_rbr_region_col_using_constraint.enabled
booleanfalseset to true to enable looking up the region column via a foreign key constraint in a REGIONAL BY ROW table, false to disable; default is falseAll
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueAll
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueAll
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueAll
feature.vector_index.enabled
booleantrueset to true to enable vector indexes, false to disable; default is trueAll
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedAll
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store’s lease count can be before it is considered for lease-transfersAdvanced/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationautowhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2, multi-metric only = 3, multi-metric and count = 4, auto = 5]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to qps the cluster will attempt to balance qps among stores, if set to cpu the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesAdvanced/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store’s QPS (such as queries per second) can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store’s range count can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store’s cpu usage can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsAdvanced/Self-Hosted
kv.bulk_io_write.min_capacity_remaining_fraction
float0.05remaining store capacity fraction below which bulk ingestion requests are rejectedAdvanced/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_auto_tune.enabled
booleanfalseif enabled, observed network latency between leaseholders and their furthest follower will be used to adjust closed timestamp policies for rangesranges configured to serve global reads. kv.closed_timestamp.lead_for_global_reads_override takes precedence if set.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range’s closed timestamp; set to 0 to disable the side-transportAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_pacing_refresh_interval
duration10msthe refresh interval for the task pacer that controls pacing of sending sidetransport updates to avoid overloading the system when many connections are waitingAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_pacing_smear_interval
duration1msthe smear interval for the task pacer that controls the amount of time each paced batch is going to take when broadcasting sidetransport updatesAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsAll
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can’t retry internally, so should be long enough to allow quorum/lease recovery)All
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesAll
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedAll
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesAll
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]All
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologAdvanced/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.raft.leader_fortification.fraction_enabled
float1controls the fraction of ranges for which the raft leader fortification protocol is enabled. Leader fortification is needed for a range to use a Leader lease. Set to 0.0 to disable leader fortification and, by extension, Leader leases. Set to 1.0 to enable leader fortification for all ranges and, by extension, use Leader leases for all ranges which do not require expiration-based leases. Set to a value between 0.0 and 1.0 to gradually roll out Leader leases across the ranges in a cluster.Advanced/Self-Hosted
kv.range.range_size_hard_cap
byte size8.0 GiBhard cap on the maximum size a range is allowed to grow to withoutsplitting before writes to the range are blocked. Takes precedence over all other configurationsAdvanced/Self-Hosted
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedAdvanced/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedAll
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Advanced/Self-Hosted
kv.replica_raft.leaderless_unavailable_threshold
duration1m0sduration after which leaderless replicas is considered unavailable. Set to 0 to disable leaderless replica availability checksAdvanced/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Advanced/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Advanced/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsAdvanced/Self-Hosted
kv.transaction.max_intents_and_locks
integer0maximum count of inserts or durable locks for a single transactions, 0 to disableAll
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsAll
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsAll
kv.transaction.randomized_anchor_key.enabled
booleanfalsedictates whether a transactions anchor key is randomized or notAll
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedAll
kv.transaction.write_buffering.enabled
booleantrueif enabled, transactional writes are buffered on the clientAll
kv.transaction.write_buffering.max_buffer_size
byte size4.0 MiBif non-zero, defines that maximum size of the buffer that will be used to buffer transactional writes per-transactionAll
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusAll
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusAll
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusAll
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusAll
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the —store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueAdvanced/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.enabled
booleantrueif set to true, snapshot ingests will be subject to disk write control in ACAdvanced/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.min_rate.enabled
booleantrueif set to true, snapshot ingests will be admitted at a minimum rate when kvadmission.store.provisioned_bandwidth is set to a non-zero value. Disabling this setting can lead to snapshots being starved out by foreground traffic.Advanced/Self-Hosted
logical_replication.producer.node_burst_limit
byte size0 Bburst limit on number of bytes per node across logical replication producer jobs. If unset, defaults to logical_replication.producer.node_rate_limitAll
logical_replication.producer.node_rate_limit
byte size0 Blimit on number of bytes per second per node across logical replication producer jobs if non-zeroAll
obs.ash.buffer_size
integer0number of ASH samples to retain in memory, or 0 to auto-size the buffer based on available memory (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.compaction.enabled
booleantrueenable pruning of system.active_session_history by the compaction jobAll
obs.ash.compaction.interval
duration1h0m0show often the ASH compaction job runs to prune system.active_session_historyAll
obs.ash.compaction.retention_period
duration168h0m0sthe age beyond which persisted ASH samples are deleted by the compaction jobAll
obs.ash.enabled
booleantrueenable active session history sampling (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.enrichment.cache.flush_interval
duration1show often the ASH enrichment cache flushes buffered writes so they become visible for resolution regardless of the node’s statement rate (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.enrichment.cache.max_entries
integer65536maximum number of per-execution entries retained in the ASH enrichment cache (set to 0 to disable) (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.enrichment.enabled
booleantrueif true, the ASH sampler enriches each sample with per-execution attributes (app_name, user, plan_gist, canary_stats, txn_id, session_id) cached on the gateway node (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.enrichment.query_tags.enabled
booleanfalseif true, the ASH sampler enriches each sample with the statement’s sqlcommenter query tags (requires obs.ash.enrichment.enabled and sql.sqlcommenter.enabled)All
obs.ash.enrichment.queue.lifetime
duration10smaximum time the ASH enricher retries resolving a sample’s attributes before leaving it un-enriched (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.enrichment.queue.max_entries
integer16384maximum number of samples awaiting ASH enrichment; oldest entries are left un-enriched when exceeded (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.enrichment.rpc.timeout
duration500msper-node timeout for outbound ASH enrichment RPCs (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.flush.enabled
booleantrueif set, in-memory ASH samples are periodically flushed to system.active_session_historyAll
obs.ash.flush.interval
duration10m0sthe interval at which ASH samples are flushed to system.active_session_historyAll
obs.ash.kv_sample_pull.enabled
booleanfalseif set, separate-process tenant SQL pods pull their KV-side ASH samples from KV nodes into the local ring bufferAll
obs.ash.kv_sample_pull.interval
duration10show often a separate-process tenant SQL pod pulls its KV-side ASH samplesAll
obs.ash.labels.enabled
booleanfalseinclude labels attached to work states in active session history samplesAll
obs.ash.labels.kv_batch_key.enabled
booleanfalsetag KV batches with their start key and range ID in active session history samplesAdvanced/Self-Hosted
obs.ash.labels.kv_sync_wait.enabled
booleanfalseinclude concurrency wait labels in active session history samplesAll
obs.ash.log_interval
duration10m0sinterval between periodic ASH top-N workload summary logs; also used as the lookback window for ASH reports written by the env sampler profiler (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.log_top_n
integer10maximum number of entries in periodic ASH workload summary, ranked by sample count descending (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.ash.response_limit
integer10000maximum number of ASH samples returned per node in fan-out responsesAll
obs.ash.sample_interval
duration1sinterval between ASH samples (in shared-process virtual clusters, only the system virtual cluster’s value takes effect)All
obs.metrics_scrape.default_visibility
enumerationallcontrols the default metric visibility level for the metrics scrape endpoints [internal = -1, all = 0, support = 1, essential = 2]All
obs.tablemetadata.automatic_updates.enabled
booleanfalseenables automatic updates of the table metadata cache system.table_metadataAll
obs.tablemetadata.data_valid_duration
duration20m0sthe duration for which the data in system.table_metadata is considered validAll
physical_replication.producer.node_burst_limit
byte size0 Bburst limit on number of bytes per node across physical replication producer jobs. If unset, defaults to physical_replication.producer.node_rate_limitAll
physical_replication.producer.node_rate_limit
byte size0 Blimit on number of bytes per second per node across physical replication producer jobs if non-zeroAll
restore.wait_for_span_config_conformance.enabled
booleanfalseif enabled, RESTORE will ensure span config conformance before ingestionAll
schemachanger.backfiller.max_buffer_size
byte size512 MiBthe maximum memory one ingestion worker uses to buffer index entries during an index backfill; each node runs bulkio.index_backfill.ingest_concurrency such workers and their buffers draw on —max-sql-memory. A larger buffer produces fewer and larger files for storage to compactAll
security.client_cert.san_required.enabled
booleanfalsemandates that client certs contain a SAN and that non-privileged users bind via an identity map or exact subject DN (no CN fallback)Advanced/Self-hosted (read-write); Basic/Standard (read-only)
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
security.external_io.enforce_external_io_implicit_access.enabled
booleantrueif enabled, statements accessing a destination that the node authenticates to with implicit credentials require the EXTERNALIOIMPLICITACCESS system privilege in backup KMS URIs, IMPORT schema_uri, PCR replication source and ALTER BACKUP collection URIsAll
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]All
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableAll
security.provisioning.ldap.enabled
booleanfalseenables automatic creation of SQL users upon successful LDAP loginAll
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)All
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.All
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationAll
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsAll
server.child_metrics.high_cardinality.max_label_values
integer1000maximum number of distinct label value combinations kept as child metrics by a single high-cardinality metric; samples for new combinations beyond the limit are reported under the overflow label value; 0 reports all samples under overflowAll
server.child_metrics.include_aggregate.enabled
booleantrueinclude the reporting of the aggregate time series when child metrics are enabled. This cluster setting has no effect if child metrics are disabled.All
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicAll
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.All
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Advanced/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogAll
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedAll
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationAll
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutAll
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.All
server.http.base_path
string/path to redirect the user to upon succcessful loginAll
server.identity_map.configuration
stringsystem-identity to database-username mappingsAll
server.jwt_authentication.audience
stringsets accepted audience values for JWT logins over the SQL interfaceAll
server.jwt_authentication.claim
stringsets the JWT claim that is parsed to get the username; may be a simple claim name (e.g. email) or a JSON Pointer per RFC 6901 (e.g. /kubernetes.io/serviceaccount/uid)All
server.jwt_authentication.client.timeout
duration15ssets the client timeout for external calls made during JWT authentication (e.g. fetching JWKS, etc.)All
server.jwt_authentication.enabled
booleanfalseenables or disables JWT login for the SQL interfaceAll
server.jwt_authentication.issuers.configuration
(alias: server.jwt_authentication.issuers)
stringsets accepted issuer values for JWT logins over the SQL interface which can be a single issuer URL string or a JSON string containing an array of issuer URLs or a JSON object containing map of issuer URLS to JWKS URIsAll
server.jwt_authentication.issuers.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while fetching JWKSAll
server.jwt_authentication.jwks
string{“keys”:[]}sets the public key set for JWT logins over the SQL interface (JWKS format)All
server.jwt_authentication.jwks_auto_fetch.enabled
booleanfalseenables or disables automatic fetching of JWKS from the issuer’s well-known endpoint or JWKS URI set in JWTAuthIssuersConfig. If this is enabled, the server.jwt_authentication.jwks will be ignored.All
server.ldap_authentication.client.tls_certificate
stringsets the client certificate PEM for establishing mTLS connection with LDAP serverAll
server.ldap_authentication.client.tls_key
stringsets the client key PEM for establishing mTLS connection with LDAP serverAll
server.ldap_authentication.domain.custom_ca
stringsets the PEM encoded custom root CA for verifying domain certificates when establishing connection with LDAP serverAll
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesAll
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesAll
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.All
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.All
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointAll
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)All
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)All
server.oidc_authentication.client.timeout
duration15ssets the client timeout for external calls made during OIDC authentication (e.g. authorization code flow, etc.)All
server.oidc_authentication.client_id
stringsets OIDC client idAll
server.oidc_authentication.client_secret
stringsets OIDC client secretAll
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleAll
server.oidc_authentication.pkce.enabled
booleanfalseenables PKCE (Proof Key for Code Exchange) for OIDC authentication flowAll
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)All
server.oidc_authentication.provider.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while authenticating through the OIDC providerAll
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)All
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required redirect_urls key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)All
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with openid)All
server.oidc_authentication.tls_insecure_skip_verify.enabled
booleanfalseif true, TLS certificate verification is skipped for connections to the OIDC provider (insecure)All
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedAdvanced/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeAll
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the —drain-wait parameter for cockroach node drain may need adjustment after changing this setting)All
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the —drain-wait parameter for cockroach node drain may need adjustment after changing this setting. —drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)All
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the —drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Advanced/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the —drain-wait parameter for cockroach node drain may need adjustment after changing this setting)All
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it’s unresponsive (Linux and Darwin only). The value 0 is the operating system default.All
server.sql_tcp_keep_alive.idle
duration0stime with no network activity before sending a TCP keepalive probe (Linux and Darwin only). If 0, the value of server.sql_tcp_keep_alive.interval is used. The value 0 is the operating system default.All
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent out. The value 0 is the operating system default.All
server.sql_tcp_user.timeout
duration0sspecifies the maximum amount of time that transmitted data can remain unacknowledged before the underlying TCP connection is forcefully closed. (Linux and Darwin only). The value 0 is the operating system default.All
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadAll
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMAll
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptAll
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case. This setting only applies when adding new users or altering an existing user’s password; it will not affect existing logins.All
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]All
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)All
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)All
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costAll
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)All
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256All
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedAll
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validAll
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsAdvanced/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantAdvanced/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesAdvanced/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesAll
sql.auth.external_connection.require_usage_privilege.enabled
booleantruedetermines whether the USAGE privilege checks added in v26.4 are enforced on external connections; checks that predate v26.4, including those on BACKUP, RESTORE, and IMPORT, apply regardlessAll
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectAll
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipAll
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdAll
sql.auth.skip_underlying_view_privilege_checks.enabled
booleanfalsedetermines whether to skip privilege checks on tables underlying views. When enabled, users with SELECT privileges on a view can query it regardless of their privileges on the underlying tables, and row-level security policies are evaluated as the invoking user rather than the view owner. This restores pre-v26.2 behavior.All
sql.catalog.allow_leased_descriptors.enabled
booleantrueif true, catalog views (crdb_internal, information_schema, pg_catalog) can use leased descriptors for improved performanceAll
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheAll
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsAll
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeAll
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsAll
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsAll
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)All
sql.crdb_internal.tsdb_query.max_rows
integer500000maximum number of rows a single crdb_internal.tsdb_query call may return; queries that would return more error before any rows are surfaced. Set to 0 to disable the row cap (calls remain bounded by SQL memory accounting).All
sql.crdb_internal.tsdb_query.max_time_range
duration168h0m0smaximum effective time range that a single crdb_internal.tsdb_query call may cover; the requested end_time is first clamped to the current wall-clock time before this cap is checkedAll
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedAll
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedAll
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedAll
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedAll
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan; set large_full_scan_rows > 0 to allow small full table scans estimated to read fewer than large_full_scan_rows
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.large_full_scan_rows
float0default value for large_full_scan_rows session variable which determines the table size at which full scans are considered large and disallowed when disallow_full_table_scans is set to true; set to 0 to reject all full table or full index scans when disallow_full_table_scans is true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the ‘results_buffer_size’ parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 1, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE… SET
All
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageAll
sql.guardrails.max_row_size_err
byte size80 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableAll
sql.guardrails.max_row_size_log
byte size16 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableAll
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableAll
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexAll
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionAll
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationAll
sql.insights.anomaly_detection.memory_limit
byte size10 MiBthe maximum amount of memory allowed for tracking statement latenciesAll
sql.insights.commit_latency_threshold
duration100msamount of time after which a transaction is considered slow because it spent a disproportionate amount of time in the commit phase. Use 0 to disable.All
sql.insights.compaction.enabled
booleantrueenable pruning of the execution-insights system tables by the compaction jobAll
sql.insights.compaction.interval
duration1h0m0show often the execution-insights compaction job runs to prune the system tablesAll
sql.insights.compaction.retention_period
duration168h0m0sthe age beyond which persisted execution insights are deleted by the compaction jobAll
sql.insights.cooldown.duration
duration5m0swindow during which a repeated execution insight for the same transaction fingerprint, statement fingerprint, problem, and cause is dropped to preserve retention diversity; 0 to disableAll
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsAll
sql.insights.flush.enabled
booleantrueif set, execution insights are periodically flushed to the system tablesAll
sql.insights.flush.interval
duration10m0sthe interval at which execution insights are flushed to the system tablesAll
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemAll
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.All
sql.log.failed_query.enabled
booleanfalsewhen set to true, every SQL statement that ends in an error is logged to a secondary logger on each node as a failed_query eventAll
sql.log.failed_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries that end in an error are logged to a separate failed_query_internal event. Must have sql.log.failed_query.enabled set for this setting to have any effect.All
sql.log.redact_names.enabled
booleanfalseif set, schema object identifers are redacted in SQL statements that appear in event logsAll
sql.log.scan_row_count_misestimate.enabled
booleanfalsewhen set to true, log a warning when a scan’s actual row count differs significantly from the optimizer’s estimateAll
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.All
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.All
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeAll
sql.log.user_audit
stringuser/role-based audit logging configurationAll
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.All
sql.metrics.application_name.enabled
booleanfalsewhen enabled, SQL metrics would export application name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.All
sql.metrics.database_name.enabled
booleanfalsewhen enabled, SQL metrics would export database name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.All
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsAll
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryAll
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryAll
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryAll
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryAll
sql.metrics.routine_name.enabled
booleanfalsewhen enabled, sql.routine.exec.latency records per-routine child metrics labeled by routine name and signatureAll
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedAll
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsAll
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.All
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDAll
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryAll
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.All
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsAll
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)All
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionAll
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentAll
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityAll
sql.procedures.plpgsql.late_binding.enabled
booleanfalsewhen true, PL/pgSQL procedure bodies are not resolved at creation time; references are resolved at CALL time instead, matching PostgreSQL PL/pgSQL semantics. Does not affect LANGUAGE SQL procedures or functionsAll
sql.schema.approx_max_object_count
integer20000approximate maximum number of schema objects allowed in the cluster; the check uses cached statistics, so the actual count may slightly exceed this limit; set to 0 to disableAll
sql.schema.auto_unlock.enabled
booleantruecontrols whether DDL operations will attempt to automatically unlock and re-lock schema_locked tables. When this setting is false, DDL on schema_locked tables is blocked unless the user manually unlocks the table first. The schema_locked storage parameter improves changefeed performance by locking the table’s schema from the perspective of the changefeed.All
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
sql.schema.validate_virtual_computed_columns.enabled
booleanfalseif true, adding a virtual computed column validates its expression against existing rows before the column is published; if false (the default), that validation is skipped and virtual computed columns are evaluated lazily when read, so a bad expression surfaces as a query-time errorAll
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsAll
sql.sqlcommenter.enabled
booleanfalseenables support for sqlcommenter. Key value parsed from sqlcommenter comments will be included in sql insights and sql logs. See https://google.github.io/sqlcommenter/ for more details.All
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesAll
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeAll
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshAll
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshAll
sql.stats.automatic_extremes_concurrency_limit
integer128determines the maximum number of concurrent automatic partial USING EXTREMES table statistics collection jobsAll
sql.stats.automatic_full_collection.enabled
booleantrueautomatic full statistics collection modeAll
sql.stats.automatic_full_concurrency_limit
integerSee description.determines the maximum number of concurrent automatic full table statistics collection jobs. The default value is computed as the number of vCPUs in a node divided by 2.All
sql.stats.automatic_node_worker_count
integer2determines the maximum number of concurrent automatic table statistics collection jobs initiated by the same nodeAll
sql.stats.automatic_partial_collection.enabled
booleantrueautomatic partial statistics collection modeAll
sql.stats.automatic_partial_collection.fraction_stale_rows
float0.05target fraction of stale rows per table that will trigger a partial statistics refreshAll
sql.stats.automatic_partial_collection.min_stale_rows
integer100target minimum number of stale rows per table that will trigger a partial statistics refreshAll
sql.stats.canary_fraction
float0probability that table statistics will use canary mode instead of stable mode for query planning [0.0-1.0]All
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobAll
sql.stats.detailed_latency_metrics.enabled
booleanfalselabel latency metrics with the statement fingerprint. Workloads with tens of thousands of distinct query fingerprints should leave this setting false. (experimental, affects performance for workloads with high fingerprint cardinality)All
sql.stats.enum_type_rehydration.enabled
booleantruere-stamp cached histograms in place when an enum type’s version changes, instead of re-reading the table’s statisticsAll
sql.stats.error_on_concurrent_create_stats.enabled
booleanfalseset to true to error on concurrent CREATE STATISTICS jobs, instead of skipping themAll
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskAll
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourAll
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesAll
sql.stats.forecasts.independent_histograms.enabled
booleantruewhen true, forecast a histogram based on its own goodness of fit even when row counts do not follow a linear trend, using the latest observed row count to scale the forecasted histogramAll
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationAll
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastAll
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastAll
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionAll
sql.stats.histogram_buckets.include_most_common_values.enabled
booleantruewhether to include most common values as histogram bucketsAll
sql.stats.histogram_buckets.max_fraction_most_common_values
float0.1maximum fraction of histogram buckets to use for most common valuesAll
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeAll
sql.stats.histogram_samples.count
integer0number of rows sampled for histogram construction during table statistics collection. Not setting this or setting a value of 0 means that a reasonable sample size will be automatically picked based on the table size.All
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeAll
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsAll
sql.stats.non_indexed_json_histograms.enabled
booleanfalseset to true to collect table statistics histograms on non-indexed JSON columnsAll
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsAll
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every successful CREATE STATISTICS jobAll
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestAll
sql.stats.response.show_internal.enabled
booleanfalsedeprecated: use the DB Console UI toggle instead. Controls if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesAll
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerAll
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesAll
sql.stats.table_statistics_cache.capacity
integer1024the maximum number of table statistics entries stored in the LRU cache. Each cache entry corresponds to a single table.All
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsAll
sql.status.active_query_text.max_bytes
byte size16 KiBmaximum length in bytes of the active and last-active SQL text retained per session and surfaced by SHOW CLUSTER QUERIES, SHOW CLUSTER SESSIONS, and the corresponding crdb_internal virtual tables; longer text is truncated with a trailing ellipsis. Larger values increase the memory used to serialize sessions and the size of the responsesAll
sql.subset_unique_fks.enabled
booleantrueif true, foreign keys may be backed by a unique constraint that covers only a strict subset of the foreign key’s referenced columns (e.g. a parent with UNIQUE(a) can back an FK that references (a, b)); set to false to require strict matching, as required by the SQL standard and PostgreSQLAll
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelAll
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingAll
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to ‘transaction’, this value is ignored.All
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to ‘statement’, events are sampled at the statement execution level. If set to ‘transaction’, events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]All
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to ‘statement’, this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.All
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.All
sql.temp_object_cleaner.batch_size
integer1000number of temporary objects to drop per transaction during cleanupAll
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsAll
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upAll
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsAll
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdAll
sql.trace.txn.enable_threshold
duration0senables transaction traces for transactions exceeding this duration, used with sql.trace.txn.sample_rateAll
sql.trace.txn.include_internal.enabled
booleantrueenables tracing internal transactions as well as external workload using sample rate and threshold settingsAll
sql.trace.txn.jaeger_json_output.enabled
booleanfalseenables Jaeger JSON output for transaction traces in logsAll
sql.trace.txn.sample_rate
float1enables probabilistic transaction tracing. It should be used in conjunction with sql.trace.txn.enable_threshold. A percentage of transactions between 0 and 1.0 will have tracing enabled, and only those which exceed the configured threshold will be logged.All
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)All
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobAll
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.All
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobAll
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.All
sql.ttl.index_scan.auto_max_expired_fraction
float0.05the TTL job finds expired rows through a secondary index on the expiration column (instead of scanning the primary index) only when the estimated fraction of expired rows is below this value; 0 disables the index-scan path and 1 always uses a usable indexAll
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledAll
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsAll
sql.txn.repeatable_read_isolation.enabled
(alias: sql.txn.snapshot_isolation.enabled)
booleanfalseset to true to allow transactions to use the REPEATABLE READ isolation level if specified by BEGIN/SET commandsAll
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedAll
sql.vecindex.stalled_op.timeout
duration100msamount of time before other vector index workers will assist with a stalled background fixupAll
storage.delete_compaction_excise.enabled
booleantrueset to false to direct Pebble to not partially excise sstables in delete-only compactionsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationAdvanced/Self-Hosted
storage.ingestion.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in ingestion sstablesAll
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationAll
storage.sstable.compression_algorithm
enumerationfastestdetermines the compression algorithm to use for Pebble stores [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, balanced = 6, good = 7, fast = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.unhealthy_write_duration
duration20sduration for disk write operations, beyond which the disk will be reported as unhealthy for higher layer actionsAdvanced/Self-Hosted
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationAdvanced/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereAdvanced/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
timeseries.storage.resolution_1m.ttl
duration240h0m0sthe maximum age of time series data stored at the 1 minute resolution. Data older than this is subject to rollup and deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsAll
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.All
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedAll
trace.span_registry.enabled
booleanfalseif set, ongoing traces can be seen at https://<ui>/#/debug/tracezAll
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.All
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeAll
ui.default_timezone
stringthe default timezone used to format timestamps in the uiAll
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the ‘ui.default_timezone’ setting instead. ‘ui.default_timezone’ takes precedence over this setting. [etc/utc = 0, america/new_york = 1]All
version
version26.4set the active cluster version in the format ‘<major>.<minor>‘All

View current cluster settings

Use the SHOW CLUSTER SETTING statement.

Change a cluster setting

Cluster settings can be updated via SQL command while the cluster is running. Use the SET CLUSTER SETTING statement. Before changing a cluster setting, note the following:
  • Changing a cluster setting is not instantaneous, as the change must be propagated to other nodes in the cluster.
  • Do not change cluster settings while upgrading to a new version of CockroachDB. Wait until all nodes have been upgraded before you make the change.

Sensitive settings

You can prevent users without sufficient permissions from viewing the values of cluster settings that CockroachDB classifies as sensitive. By default, users with the VIEWCLUSTERSETTING privilege can view the values of all settings displayed when using the SHOW CLUSTER SETTING statement and the DB Console Advanced Debug > Cluster Settings page. If you enable the option to redact sensitive settings, the sensitive setting values are hidden from those users, and visible only to users with the admin role or the MODIFYCLUSTERSETTING privilege. To enable this redaction of sensitive setting values, set the cluster setting server.redact_sensitive_settings.enabled to true:
The table summarizes when sensitive setting values are visible or redacted: The following are sensitive settings whose values are redacted:

See also