Update to CockroachDB

{
  "description": "Reviews, audits, and modifies CockroachDB cluster settings. Self-Hosted has full control over all settings and start flags. Advanced/BYOC can modify most SQL-level settings but infrastructure settings are managed by CRL. Standard has limited settings access — session variables are the primary tuning mechanism. Basic has minimal settings — use session variables and Cloud Console. Use when auditing configuration, tuning performance, or troubleshooting settings-related issues.",
  "included_files": [
    {
      "relative_path": "references/cloud-restricted-settings.md",
      "size_in_bytes": 5009
    },
    {
      "relative_path": "references/node-level-settings.md",
      "size_in_bytes": 4630
    },
    {
      "relative_path": "references/recommended-values.md",
      "size_in_bytes": 4480
    },
    {
      "relative_path": "references/safety-guide.md",
      "size_in_bytes": 6928
    },
    {
      "relative_path": "references/sql-queries.md",
      "size_in_bytes": 6040
    }
  ],
  "name": "managing-cluster-settings",
  "skill_md_contents": "---\nname: managing-cluster-settings\ndescription: Reviews, audits, and modifies CockroachDB cluster settings. Self-Hosted has full control over all settings and start flags. Advanced/BYOC can modify most SQL-level settings but infrastructure settings are managed by CRL. Standard has limited settings access — session variables are the primary tuning mechanism. Basic has minimal settings — use session variables and Cloud Console. Use when auditing configuration, tuning performance, or troubleshooting settings-related issues.\ncompatibility: Self-Hosted has full control with admin role. Advanced/BYOC can modify most settings. Standard has limited SET CLUSTER SETTING access. Basic has minimal access. All tiers support SHOW CLUSTER SETTING for visible settings.\n---\n\n# Managing Cluster Settings\n\nReviews, 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.\n\n## When to Use This Skill\n\n- Auditing cluster configuration for production readiness\n- Identifying settings that deviate from defaults\n- Tuning performance, replication, or admission control\n- Verifying settings after an upgrade or incident\n- Understanding which settings are modifiable on your tier\n- Managing enterprise license installation and renewal (Self-Hosted)\n\n**For version management:** Use [upgrading-cluster-version](../upgrading-cluster-version/SKILL.md) — do not change settings during an upgrade.\n**For health checks:** Use [reviewing-cluster-health](../reviewing-cluster-health/SKILL.md).\n\n---\n\n## Step 1: Gather Context\n\n### Required Context\n\n| Question | Options | Why It Matters |\n|----------|---------|----------------|\n| **Deployment tier?** | Self-Hosted, Advanced, BYOC, Standard, Basic | Determines which settings are viewable and modifiable |\n| **Goal?** | Audit/review, Tune performance, Fix specific issue, Post-upgrade verification | Directs which queries and procedures to use |\n\n### Additional Context (by tier)\n\n**If Self-Hosted:**\n\n| Question | Options | Why It Matters |\n|----------|---------|----------------|\n| **SQL access level?** | admin, MODIFYCLUSTERSETTING, VIEWCLUSTERSETTING | Determines available operations |\n| **Specific setting or area?** | e.g., \"timeout\", \"replication\", \"gc\" | Narrows search to relevant settings |\n| **Currently mid-upgrade?** | Yes, No | Settings must NOT be changed during rolling upgrades |\n\n**If Advanced or BYOC:**\n\n| Question | Options | Why It Matters |\n|----------|---------|----------------|\n| **SQL access level?** | admin, limited | Determines available operations |\n| **Specific setting or area?** | e.g., \"timeout\", \"rangefeed\" | Narrows search |\n\n**If Standard or Basic:** No additional context needed — settings access is limited. Session variables are the primary tuning mechanism.\n\n### Context-Driven Routing\n\n| Tier | Settings Access | Go To |\n|------|----------------|-------|\n| Self-Hosted | Full | [Self-Hosted Settings](#self-hosted-settings) |\n| Advanced / BYOC | Most (some restricted) | [Advanced / BYOC Settings](#advanced--byoc-settings) |\n| Standard | Limited | [Standard Settings](#standard-settings) |\n| Basic | Minimal | [Basic Settings](#basic-settings) |\n\n---\n\n## Audit Queries (All Tiers)\n\nThese read-only queries work on Self-Hosted and Advanced/BYOC. Standard and Basic may have restricted visibility — see tier-specific sections below.\n\n### Non-Default Settings\n\n```sql\nSELECT variable, value, setting_type, description\nFROM [SHOW ALL CLUSTER SETTINGS]\nWHERE value != default_value ORDER BY variable;\n```\n\n### Production-Critical Settings\n\n```sql\nSELECT variable, value FROM [SHOW ALL CLUSTER SETTINGS]\nWHERE variable IN (\n  'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled',\n  'server.time_until_store_dead', 'admission.kv.enabled',\n  'cluster.preserve_downgrade_option',\n  'sql.defaults.idle_in_transaction_session_timeout'\n) ORDER BY variable;\n```\n\n`gc.ttlseconds` is a zone-config parameter, not a cluster setting; check with `SHOW ZONE CONFIGURATION FOR ...` against the relevant table/database/range.\n\n### Search by Keyword\n\n```sql\nSELECT variable, value, description FROM [SHOW ALL CLUSTER SETTINGS]\nWHERE variable LIKE '%<keyword>%' OR description LIKE '%<keyword>%'\nORDER BY variable;\n```\n\nSee [sql-queries reference](references/sql-queries.md) for additional audit queries.\nSee [recommended-values reference](references/recommended-values.md) for production-recommended settings.\n\n---\n\n## Self-Hosted Settings\n\n**Applies when:** Tier = Self-Hosted\n\nFull control over all cluster settings and node-level start flags.\n\n### Modify a Setting\n\n```sql\nSHOW CLUSTER SETTING <name>;          -- Document current value first\nSET CLUSTER SETTING <name> = <value>; -- Apply\nSHOW CLUSTER SETTING <name>;          -- Verify\n```\n\n### Reset to Default\n\n```sql\nRESET CLUSTER SETTING <name>;\n```\n\n### Node-Level Settings (require node restart)\n\nNode-level settings are `cockroach start` flags and cannot be changed at runtime. To change: drain the node, stop the process, update flags, restart. See [performing-cluster-maintenance](../perform-cluster-maintenance/SKILL.md).\n\nSee [node-level-settings reference](references/node-level-settings.md) for the complete list of start flags.\n\n### License Management\n\nCockroachDB 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.\n\n**Check current license:**\n```sql\nSHOW CLUSTER SETTING cluster.organization;\nSHOW CLUSTER SETTING enterprise.license;\n```\n\n**Install or renew a license:**\n```sql\nSET CLUSTER SETTING cluster.organization = '<organization-name>';\nSET CLUSTER SETTING enterprise.license = '<license-key>';\n```\n\n**Verify license is active:**\n```sql\nSELECT * FROM [SHOW CLUSTER SETTING enterprise.license];\n```\n\n**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.\n\n**CockroachDB Core (free):** If running without an enterprise license, no license management is needed. Core features are always available.\n\n---\n\n## Advanced / BYOC Settings\n\n**Applies when:** Tier = Advanced or BYOC\n\nMost SQL-level cluster settings are modifiable. Infrastructure-level settings are managed by Cockroach Labs.\n\n### Modifiable (common examples)\n\n```sql\nSET CLUSTER SETTING sql.defaults.idle_in_transaction_session_timeout = '300s';\nSET CLUSTER SETTING sql.defaults.statement_timeout = '30s';\nSET CLUSTER SETTING kv.rangefeed.enabled = true;\n-- gc.ttlseconds is a zone configuration parameter, not a cluster setting\nALTER RANGE default CONFIGURE ZONE USING gc.ttlseconds = 86400;\n```\n\n### Restricted (managed by CRL)\n\nSettings managed by Cockroach Labs that cannot be modified:\n- `server.time_until_store_dead`\n- `kv.snapshot_rebalance.max_rate`\n- `cluster.preserve_downgrade_option` (use Cloud Console for upgrades)\n- Node-level flags (`--cache`, `--max-sql-memory`) — managed by CRL\n\nIf a modification is rejected, the error will indicate the setting is managed by CockroachDB Cloud. Use Cloud Console or contact support.\n\n**License:** Enterprise license is managed automatically by Cockroach Labs on Advanced/BYOC. No customer action needed.\n\nSee [cloud-restricted-settings reference](references/cloud-restricted-settings.md) for the full list.\n\n---\n\n## Standard Settings\n\n**Applies when:** Tier = Standard\n\nStandard 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.\n\n### Session Variables (recommended approach)\n\n```sql\n-- Per-session\nSET statement_timeout = '30s';\n\n-- Default for all sessions (preferred over sql.defaults.*)\nALTER ROLE ALL SET statement_timeout = '30s';\nALTER ROLE ALL SET idle_in_transaction_session_timeout = '300s';\n```\n\n### What You Can Configure\n\n- Session-level timeouts and defaults via `SET` and `ALTER ROLE`\n- SQL-level behavior through session variables\n\n### What Is Managed by CRL\n\n- All infrastructure settings (replication, admission control, storage)\n- Compute and networking — configured via Cloud Console\n\n**Note:** `SHOW ALL CLUSTER SETTINGS` may return a limited set of settings on Standard.\n\n---\n\n## Basic Settings\n\n**Applies when:** Tier = Basic\n\nBasic is a serverless offering with minimal settings access. Infrastructure is fully managed and auto-scales. Use session variables for SQL-level tuning.\n\n### Session Variables\n\n```sql\nSET statement_timeout = '30s';\nALTER ROLE ALL SET statement_timeout = '30s';\n```\n\n### Cloud Console Configuration\n\n- Spending limits\n- IP allowlists\n- Region selection\n\nAll other configuration is managed by Cockroach Labs. If more control over settings is needed, consider upgrading to Standard or Advanced.\n\n---\n\n## Safety Considerations\n\n**Read-only queries are safe on all tiers.**\n\n**Before modifying any setting:**\n1. Document the current value (for rollback)\n2. Verify you are NOT mid-upgrade\n3. Understand the impact (check `description` field)\n4. Change one setting at a time\n5. Monitor for 15-30 minutes before making additional changes\n\n**Risk levels:**\n- **Low:** `sql.defaults.statement_timeout`, `diagnostics.reporting.enabled`\n- **Medium:** `kv.snapshot_rebalance.max_rate`, `gc.ttlseconds` (zone-config parameter — same risk class)\n- **High:** `cluster.preserve_downgrade_option`, `admission.kv.enabled`\n\n**Critical:** Never change settings during a rolling upgrade. Cluster settings affect ALL workloads on the cluster — prefer session variables for narrower scope when possible.\n\nSee [safety-guide reference](references/safety-guide.md) for detailed risk assessments per setting.\n\n## Troubleshooting\n\n| Issue | Tier | Fix |\n|-------|------|-----|\n| \"permission denied\" on SET | SH/ADV/BYOC | Grant MODIFYCLUSTERSETTING or use admin role |\n| \"managed by Cloud\" error | ADV/BYOC | Setting restricted on this tier; use Cloud Console or contact support |\n| Setting not visible | STD/BAS | Expected — limited settings visibility on multi-tenant/serverless tiers |\n| No visible effect | SH/ADV/BYOC | Check for session variable override; verify with SHOW |\n| Setting reverted after upgrade | SH | Re-apply; document in operational runbook |\n| Enterprise features stopped working | SH | License expired; renew with SET CLUSTER SETTING enterprise.license |\n| \"enterprise license required\" error | SH | Install license or use core-only alternative |\n\n## References\n\n**Skill references:**\n- [SQL audit queries](references/sql-queries.md)\n- [Recommended production values](references/recommended-values.md)\n- [Node-level settings (start flags)](references/node-level-settings.md)\n- [Cloud-restricted settings](references/cloud-restricted-settings.md)\n- [Safety guide](references/safety-guide.md)\n\n**Related skills:**\n- [reviewing-cluster-health](../reviewing-cluster-health/SKILL.md)\n- [upgrading-cluster-version](../upgrading-cluster-version/SKILL.md)\n\n**Official CockroachDB Documentation:**\n- [Cluster Settings](https://www.cockroachlabs.com/docs/stable/cluster-settings)\n- [SET CLUSTER SETTING](https://www.cockroachlabs.com/docs/stable/set-cluster-setting)\n- [Production Checklist](https://www.cockroachlabs.com/docs/stable/recommended-production-settings)\n"
}