managing-cluster-settings
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseManaging Cluster Settings
集群设置管理
Reviews, audits, and modifies CockroachDB cluster settings. Before providing procedures, this skill gathers context to determine which settings are available and which modification approach to recommend for the operator's tier.
查看、审计和修改CockroachDB集群设置。在提供操作步骤前，本技能会先收集上下文信息，以确定操作员所在层级可使用的设置以及推荐的修改方式。
When to Use This Skill
何时使用此技能
- Auditing cluster configuration for production readiness
- Identifying settings that deviate from defaults
- Tuning performance, replication, or admission control
- Verifying settings after an upgrade or incident
- Understanding which settings are modifiable on your tier
- Managing enterprise license installation and renewal (Self-Hosted)
For version management: Use upgrading-cluster-version — do not change settings during an upgrade.
For health checks: Use reviewing-cluster-health.
- 审计集群配置是否符合生产就绪要求
- 识别与默认值不符的设置
- 调优性能、复制或准入控制
- 升级或事件发生后验证设置
- 了解所在层级可修改的设置
- 管理企业许可证的安装与续订（Self-Hosted模式）
版本管理相关： 请使用upgrading-cluster-version —— 升级期间请勿修改设置。
健康检查相关： 请使用reviewing-cluster-health。
Step 1: Gather Context
步骤1：收集上下文信息
Required Context
必填上下文
| Question | Options | Why It Matters |
|---|---|---|
| Deployment tier? | Self-Hosted, Advanced, BYOC, Standard, Basic | Determines which settings are viewable and modifiable |
| Goal? | Audit/review, Tune performance, Fix specific issue, Post-upgrade verification | Directs which queries and procedures to use |
| 问题 | 选项 | 重要性 |
|---|---|---|
| 部署层级？ | Self-Hosted、Advanced、BYOC、Standard、Basic | 决定可查看和修改的设置范围 |
| 目标？ | 审计/查看、性能调优、修复特定问题、升级后验证 | 指导使用的查询语句和操作流程 |
Additional Context (by tier)
各层级补充上下文
If Self-Hosted:
| Question | Options | Why It Matters |
|---|---|---|
| SQL access level? | admin, MODIFYCLUSTERSETTING, VIEWCLUSTERSETTING | Determines available operations |
| Specific setting or area? | e.g., "timeout", "replication", "gc" | Narrows search to relevant settings |
| Currently mid-upgrade? | Yes, No | Settings must NOT be changed during rolling upgrades |
If Advanced or BYOC:
| Question | Options | Why It Matters |
|---|---|---|
| SQL access level? | admin, limited | Determines available operations |
| Specific setting or area? | e.g., "timeout", "rangefeed" | Narrows search |
If Standard or Basic: No additional context needed — settings access is limited. Session variables are the primary tuning mechanism.
若为Self-Hosted模式：
| 问题 | 选项 | 重要性 |
|---|---|---|
| SQL访问级别？ | admin、MODIFYCLUSTERSETTING、VIEWCLUSTERSETTING | 决定可执行的操作 |
| 特定设置或领域？ | 例如："timeout"、"replication"、"gc" | 缩小搜索范围至相关设置 |
| 当前是否正在升级？ | 是、否 | 滚动升级期间绝对不能修改设置 |
若为Advanced或BYOC模式：
| 问题 | 选项 | 重要性 |
|---|---|---|
| SQL访问级别？ | admin、受限 | 决定可执行的操作 |
| 特定设置或领域？ | 例如："timeout"、"rangefeed" | 缩小搜索范围 |
若为Standard或Basic模式： 无需补充上下文 —— 设置访问权限受限，会话变量是主要调优机制。
Context-Driven Routing
基于上下文的流程路由
| Tier | Settings Access | Go To |
|---|---|---|
| Self-Hosted | Full | Self-Hosted Settings |
| Advanced / BYOC | Most (some restricted) | Advanced / BYOC Settings |
| Standard | Limited | Standard Settings |
| Basic | Minimal | Basic Settings |
| 层级 | 设置访问权限 | 跳转至 |
|---|---|---|
| Self-Hosted | 完全权限 | Self-Hosted设置 |
| Advanced / BYOC | 大部分权限（部分受限） | Advanced / BYOC设置 |
| Standard | 受限 | Standard设置 |
| Basic | 极少权限 | Basic设置 |
Audit Queries (All Tiers)
审计查询（所有层级）
These read-only queries work on Self-Hosted and Advanced/BYOC. Standard and Basic may have restricted visibility — see tier-specific sections below.
这些只读查询适用于Self-Hosted和Advanced/BYOC模式。Standard和Basic模式可能存在可见性限制 —— 请查看各层级专属章节。
Non-Default Settings
非默认设置
sql
SELECT variable, value, setting_type, description
FROM [SHOW ALL CLUSTER SETTINGS]
WHERE value != default_value ORDER BY variable;sql
SELECT variable, value, setting_type, description
FROM [SHOW ALL CLUSTER SETTINGS]
WHERE value != default_value ORDER BY variable;Production-Critical Settings
生产关键设置
sql
SELECT variable, value FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable IN (
'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled',
'server.time_until_store_dead', 'admission.kv.enabled',
'gc.ttlseconds', 'cluster.preserve_downgrade_option',
'sql.defaults.idle_in_transaction_session_timeout'
) ORDER BY variable;sql
SELECT variable, value FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable IN (
'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled',
'server.time_until_store_dead', 'admission.kv.enabled',
'gc.ttlseconds', 'cluster.preserve_downgrade_option',
'sql.defaults.idle_in_transaction_session_timeout'
) ORDER BY variable;Search by Keyword
按关键字搜索
sql
SELECT variable, value, description FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable LIKE '%<keyword>%' OR description LIKE '%<keyword>%'
ORDER BY variable;See sql-queries reference for additional audit queries.
See recommended-values reference for production-recommended settings.
sql
SELECT variable, value, description FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable LIKE '%<keyword>%' OR description LIKE '%<keyword>%'
ORDER BY variable;更多审计查询请参考sql-queries reference。
生产推荐设置请参考recommended-values reference。
Self-Hosted Settings
Self-Hosted设置
Applies when: Tier = Self-Hosted
Full control over all cluster settings and node-level start flags.
适用场景： 层级 = Self-Hosted
可完全控制所有集群设置和节点级启动参数。
Modify a Setting
修改设置
sql
SHOW CLUSTER SETTING <name>; -- Document current value first
SET CLUSTER SETTING <name> = <value>; -- Apply
SHOW CLUSTER SETTING <name>; -- Verifysql
SHOW CLUSTER SETTING <name>; -- 先记录当前值
SET CLUSTER SETTING <name> = <value>; -- 应用修改
SHOW CLUSTER SETTING <name>; -- 验证修改Reset to Default
重置为默认值
sql
RESET CLUSTER SETTING <name>;sql
RESET CLUSTER SETTING <name>;Node-Level Settings (require node restart)
节点级设置（需重启节点）
Node-level settings are flags and cannot be changed at runtime. To change: drain the node, stop the process, update flags, restart. See performing-cluster-maintenance.
cockroach startSee node-level-settings reference for the complete list of start flags.
节点级设置为参数，无法在运行时修改。修改步骤：排空节点、停止进程、更新参数、重启节点。请参考performing-cluster-maintenance。
cockroach start完整启动参数列表请参考node-level-settings reference。
License Management
许可证管理
CockroachDB Self-Hosted requires an enterprise license for features like backup/restore, changefeeds, encryption at rest, and multi-region capabilities. The license is stored as a cluster setting.
Check current license:
sql
SHOW CLUSTER SETTING cluster.organization;
SHOW CLUSTER SETTING enterprise.license;Install or renew a license:
sql
SET CLUSTER SETTING cluster.organization = '<organization-name>';
SET CLUSTER SETTING enterprise.license = '<license-key>';Verify license is active:
sql
SELECT * FROM [SHOW CLUSTER SETTING enterprise.license];License expiry: Expired licenses do not cause data loss or cluster unavailability. Enterprise features (backups, CDC, EAR) stop working until renewed. Core features remain available. Monitor license expiry proactively.
CockroachDB Core (free): If running without an enterprise license, no license management is needed. Core features are always available.
CockroachDB Self-Hosted模式需要企业许可证才能使用备份/恢复、变更馈送、静态加密、多区域功能等特性。许可证存储为集群设置。
查看当前许可证：
sql
SHOW CLUSTER SETTING cluster.organization;
SHOW CLUSTER SETTING enterprise.license;安装或续订许可证：
sql
SET CLUSTER SETTING cluster.organization = '<organization-name>';
SET CLUSTER SETTING enterprise.license = '<license-key>';验证许可证是否激活：
sql
SELECT * FROM [SHOW CLUSTER SETTING enterprise.license];许可证过期： 许可证过期不会导致数据丢失或集群不可用，但企业特性（备份、CDC、EAR）会停止工作，直至续订。核心特性仍可正常使用。请主动监控许可证到期时间。
CockroachDB Core（免费版）： 若未使用企业许可证，则无需管理许可证。核心特性始终可用。
Advanced / BYOC Settings
Advanced / BYOC设置
Applies when: Tier = Advanced or BYOC
Most SQL-level cluster settings are modifiable. Infrastructure-level settings are managed by Cockroach Labs.
适用场景： 层级 = Advanced或BYOC
大多数SQL级集群设置可修改。基础设施级设置由Cockroach Labs管理。
Modifiable (common examples)
可修改设置（常见示例）
sql
SET CLUSTER SETTING sql.defaults.idle_in_transaction_session_timeout = '300s';
SET CLUSTER SETTING sql.defaults.statement_timeout = '30s';
SET CLUSTER SETTING kv.rangefeed.enabled = true;
-- gc.ttlseconds is a zone configuration parameter, not a cluster setting
ALTER RANGE default CONFIGURE ZONE USING gc.ttlseconds = 86400;sql
SET CLUSTER SETTING sql.defaults.idle_in_transaction_session_timeout = '300s';
SET CLUSTER SETTING sql.defaults.statement_timeout = '30s';
SET CLUSTER SETTING kv.rangefeed.enabled = true;
-- gc.ttlseconds是区域配置参数，而非集群设置
ALTER RANGE default CONFIGURE ZONE USING gc.ttlseconds = 86400;Restricted (managed by CRL)
受限设置（由CRL管理）
Settings managed by Cockroach Labs that cannot be modified:
server.time_until_store_deadkv.snapshot_rebalance.max_rate- (use Cloud Console for upgrades)
cluster.preserve_downgrade_option - Node-level flags (,
--cache) — managed by CRL--max-sql-memory
If a modification is rejected, the error will indicate the setting is managed by CockroachDB Cloud. Use Cloud Console or contact support.
License: Enterprise license is managed automatically by Cockroach Labs on Advanced/BYOC. No customer action needed.
See cloud-restricted-settings reference for the full list.
以下设置由Cockroach Labs管理，无法修改：
server.time_until_store_deadkv.snapshot_rebalance.max_rate- （升级请使用云控制台）
cluster.preserve_downgrade_option - 节点级参数（、
--cache）—— 由CRL管理--max-sql-memory
若修改被拒绝，错误信息会提示该设置由CockroachDB Cloud管理。请使用云控制台或联系支持人员。
许可证： Advanced/BYOC模式下的企业许可证由Cockroach Labs自动管理，无需用户操作。
完整受限设置列表请参考cloud-restricted-settings reference。
Standard Settings
Standard设置
Applies when: Tier = Standard
Standard is a multi-tenant managed service. Most cluster settings are not modifiable because changes could affect other tenants. Use session variables as the primary tuning mechanism.
适用场景： 层级 = Standard
Standard是多租户托管服务。大多数集群设置不可修改，因为修改可能影响其他租户。请使用会话变量作为主要调优机制。
Session Variables (recommended approach)
会话变量（推荐方式）
sql
-- Per-session
SET statement_timeout = '30s';
-- Default for all sessions (preferred over sql.defaults.*)
ALTER ROLE ALL SET statement_timeout = '30s';
ALTER ROLE ALL SET idle_in_transaction_session_timeout = '300s';sql
-- 单会话生效
SET statement_timeout = '30s';
-- 所有会话默认生效（优先于sql.defaults.*）
ALTER ROLE ALL SET statement_timeout = '30s';
ALTER ROLE ALL SET idle_in_transaction_session_timeout = '300s';What You Can Configure
可配置项
- Session-level timeouts and defaults via and
SETALTER ROLE - SQL-level behavior through session variables
- 通过和
SET设置会话级超时和默认值ALTER ROLE - 通过会话变量调整SQL级行为
What Is Managed by CRL
由CRL管理的项
- All infrastructure settings (replication, admission control, storage)
- Compute and networking — configured via Cloud Console
Note: may return a limited set of settings on Standard.
SHOW ALL CLUSTER SETTINGS- 所有基础设施设置（复制、准入控制、存储）
- 计算和网络配置 —— 通过云控制台操作
注意： 在Standard模式下，可能仅返回有限的设置。
SHOW ALL CLUSTER SETTINGSBasic Settings
Basic设置
Applies when: Tier = Basic
Basic is a serverless offering with minimal settings access. Infrastructure is fully managed and auto-scales. Use session variables for SQL-level tuning.
适用场景： 层级 = Basic
Basic是无服务器产品，设置访问权限极少。基础设施完全托管并自动扩缩容。请使用会话变量进行SQL级调优。
Session Variables
会话变量
sql
SET statement_timeout = '30s';
ALTER ROLE ALL SET statement_timeout = '30s';sql
SET statement_timeout = '30s';
ALTER ROLE ALL SET statement_timeout = '30s';Cloud Console Configuration
云控制台配置项
- Spending limits
- IP allowlists
- Region selection
All other configuration is managed by Cockroach Labs. If more control over settings is needed, consider upgrading to Standard or Advanced.
- 支出限制
- IP白名单
- 区域选择
所有其他配置均由Cockroach Labs管理。若需要更多设置控制权，可考虑升级至Standard或Advanced模式。
Safety Considerations
安全注意事项
Read-only queries are safe on all tiers.
Before modifying any setting:
- Document the current value (for rollback)
- Verify you are NOT mid-upgrade
- Understand the impact (check field)
description - Change one setting at a time
- Monitor for 15-30 minutes before making additional changes
Risk levels:
- Low: ,
sql.defaults.statement_timeoutdiagnostics.reporting.enabled - Medium: ,
gc.ttlsecondskv.snapshot_rebalance.max_rate - High: ,
cluster.preserve_downgrade_optionadmission.kv.enabled
Critical: Never change settings during a rolling upgrade. Cluster settings affect ALL workloads on the cluster — prefer session variables for narrower scope when possible.
See safety-guide reference for detailed risk assessments per setting.
所有层级的只读查询都是安全的。
修改任何设置前：
- 记录当前值（用于回滚）
- 确认当前未处于升级过程中
- 了解修改影响（查看字段）
description - 每次仅修改一个设置
- 修改后监控15-30分钟再进行其他修改
风险等级：
- 低风险： 、
sql.defaults.statement_timeoutdiagnostics.reporting.enabled - 中风险： 、
gc.ttlsecondskv.snapshot_rebalance.max_rate - 高风险： 、
cluster.preserve_downgrade_optionadmission.kv.enabled
关键提示： 滚动升级期间绝对不要修改设置。集群设置会影响集群上的所有工作负载 —— 若需更窄范围的调整，优先使用会话变量。
各设置的详细风险评估请参考safety-guide reference。
Troubleshooting
故障排查
| Issue | Tier | Fix |
|---|---|---|
| "permission denied" on SET | SH/ADV/BYOC | Grant MODIFYCLUSTERSETTING or use admin role |
| "managed by Cloud" error | ADV/BYOC | Setting restricted on this tier; use Cloud Console or contact support |
| Setting not visible | STD/BAS | Expected — limited settings visibility on multi-tenant/serverless tiers |
| No visible effect | SH/ADV/BYOC | Check for session variable override; verify with SHOW |
| Setting reverted after upgrade | SH | Re-apply; document in operational runbook |
| Enterprise features stopped working | SH | License expired; renew with SET CLUSTER SETTING enterprise.license |
| "enterprise license required" error | SH | Install license or use core-only alternative |
| 问题 | 层级 | 解决方法 |
|---|---|---|
| 执行SET时提示"permission denied" | SH/ADV/BYOC | 授予MODIFYCLUSTERSETTING权限或使用admin角色 |
| 提示"managed by Cloud"错误 | ADV/BYOC | 该设置在此层级受限；请使用云控制台或联系支持人员 |
| 设置不可见 | STD/BAS | 属于正常情况 —— 多租户/无服务器层级的设置可见性有限 |
| 修改后无可见效果 | SH/ADV/BYOC | 检查是否存在会话变量覆盖；使用SHOW命令验证 |
| 升级后设置被还原 | SH | 重新应用设置；并记录到操作手册中 |
| 企业特性停止工作 | SH | 许可证已过期；使用SET CLUSTER SETTING enterprise.license命令续订 |
| 提示"enterprise license required"错误 | SH | 安装许可证或使用仅核心特性的替代方案 |
References
参考资料
Skill references:
- SQL audit queries
- Recommended production values
- Node-level settings (start flags)
- Cloud-restricted settings
- Safety guide
Related skills:
- reviewing-cluster-health
- upgrading-cluster-version
Official CockroachDB Documentation:
技能参考：
- SQL审计查询
- 生产推荐值
- 节点级设置（启动参数）
- 云受限设置
- 安全指南
相关技能：
- reviewing-cluster-health
- upgrading-cluster-version
官方CockroachDB文档：