Cluster settings

pkg/settings/ is the registry of runtime-tunable knobs in CockroachDB. Every settable value is registered at process startup with a name, type, default, and visibility class; values are read via thread-safe accessors and watched for changes by pkg/server/settingswatcher/.

Purpose

Make almost every operational behavior tunable without rebuilding or restarting. Settings are persisted in system.settings and propagated to every node by a rangefeed-driven watcher.

Files

pkg/settings/
├── BUILD.bazel
├── setting.go            // base Setting interface and Class enum
├── bool.go / int.go / …  // typed setting impls
├── version.go            // VersionSetting (used for clusterversion)
├── values.go             // settings.Values (per-process value bag)
├── registry.go           // global registry
├── rule_registry.go      // observability rules
└── …

Setting kinds

Type	Builder	Notes
Bool	RegisterBoolSetting
Int	RegisterIntSetting	optional WithMinimum, WithMaximum
Float	RegisterFloatSetting
Duration	RegisterDurationSetting	accepts Go duration strings
String	RegisterStringSetting
ByteSize	RegisterByteSizeSetting	accepts "16 MiB"
Enum	RegisterEnumSetting	typed enums
Validated string	RegisterValidatedStringSetting	with custom validator
Version	RegisterVersionSetting	only used by clusterversion
Protected	RegisterProtectedSetting	for secret values, rotated via cluster admin

Visibility classes

• SystemOnly — only visible/writable from the system tenant.
• SystemVisible — visible to tenants, only writable by the system tenant.
• TenantWritable — settable independently by each tenant.
• TenantReadOnly — host-controlled, readable by tenants.

docs/configuration.md documents the policy.

Watchers

pkg/server/settingswatcher/ subscribes to a rangefeed of system.settings and updates settings.Values on every node within seconds of a change. pkg/server/tenantsettingswatcher/ does the same for system.tenant_settings.

Reading a setting

var fooEnabled = settings.RegisterBoolSetting(
    settings.SystemVisible,
    "kv.foo.enabled",
    "whether foo is enabled",
    true,
)

if fooEnabled.Get(&st.SV) {
    // …
}

st.SV is a per-process *settings.Values. In tests, use cluster.MakeTestingClusterSettings().

Cluster admin commands

• SHOW ALL CLUSTER SETTINGS — list every setting with current value.
• SHOW CLUSTER SETTING <name> — single value.
• SET CLUSTER SETTING <name> = <value> — change.
• RESET CLUSTER SETTING <name> — restore default.

The settings table is system.settings and is also surfaced via crdb_internal.cluster_settings.

Related pages

• Cluster version & upgrade — the version itself is a setting.
• Server — settingswatcher lives there.
• SQL — most session variables also have a backing cluster setting.