managing-cluster-settings

クラスター設定の管理

CockroachDB クラスター設定をレビュー、監査、変更します。手順を提示する前に、このスキルはコンテキストを収集し、利用可能な設定と、オペレーターのティアに応じて推奨する変更方法を判断します。

このスキルを使用する場面

• 本番環境への対応状況を把握するためにクラスター構成を監査する
• デフォルト値から逸脱している設定を特定する
• パフォーマンス、レプリケーション、アドミッションコントロールを調整する
• アップグレード後やインシデント後に設定を確認する
• 自分のティアで変更可能な設定を把握する
• エンタープライズライセンスのインストールと更新を管理する（Self-Hosted）

バージョン管理の場合： upgrading-cluster-version を使用してください。アップグレード中に設定を変更しないでください。 ヘルスチェックの場合： reviewing-cluster-health を使用してください。

---

ステップ 1：コンテキストの収集

必須のコンテキスト

質問	選択肢	重要な理由
デプロイメントのティアは？	Self-Hosted、Advanced、BYOC、Standard、Basic	表示および変更できる設定を決定します
目的は？	監査／レビュー、パフォーマンス調整、特定の問題の修正、アップグレード後の検証	使用するクエリと手順を決定します

追加のコンテキスト（ティア別）

Self-Hosted の場合：

質問	選択肢	重要な理由
SQL アクセスレベルは？	admin、MODIFYCLUSTERSETTING、VIEWCLUSTERSETTING	利用可能な操作を決定します
特定の設定または領域は？	例：「timeout」、「replication」、「gc」	関連する設定に検索対象を絞り込みます
現在アップグレードの途中ですか？	はい、いいえ	ローリングアップグレード中は設定を変更してはいけません

Advanced または BYOC の場合：

質問	選択肢	重要な理由
SQL アクセスレベルは？	admin、limited	利用可能な操作を決定します
特定の設定または領域は？	例：「timeout」、「rangefeed」	検索対象を絞り込みます

Standard または Basic の場合： 追加のコンテキストは必要ありません。設定へのアクセスは制限されています。主な調整手段はセッション変数です。

コンテキストに応じた案内

ティア	設定へのアクセス	移動先
Self-Hosted	全設定	Self-Hosted の設定
Advanced / BYOC	大半の設定（一部制限あり）	Advanced / BYOC の設定
Standard	制限あり	Standard の設定
Basic	最小限	Basic の設定

---

監査クエリ（すべてのティア）

これらの読み取り専用クエリは、Self-Hosted と Advanced／BYOC で使用できます。Standard と Basic では表示が制限される場合があります。以下のティア別セクションを参照してください。

デフォルト以外の設定

SELECT variable, value, setting_type, description
FROM [SHOW ALL CLUSTER SETTINGS]
WHERE value != default_value ORDER BY variable;

本番環境で重要な設定

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',
  'cluster.preserve_downgrade_option',
  'sql.defaults.idle_in_transaction_session_timeout'
) ORDER BY variable;

gc.ttlseconds はクラスター設定ではなくゾーン構成のパラメーターです。該当するテーブル、データベース、またはレンジに対して SHOW ZONE CONFIGURATION FOR ... で確認してください。

キーワードで検索

SELECT variable, value, description FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable LIKE '%<keyword>%' OR description LIKE '%<keyword>%'
ORDER BY variable;

その他の監査クエリについては、sql-queries リファレンスを参照してください。 本番環境で推奨される設定については、recommended-values リファレンスを参照してください。

---

Self-Hosted の設定

適用条件： ティア = Self-Hosted

すべてのクラスター設定とノードレベルの起動フラグを完全に制御できます。

設定の変更

SHOW CLUSTER SETTING <name>;          -- Document current value first
SET CLUSTER SETTING <name> = <value>; -- Apply
SHOW CLUSTER SETTING <name>;          -- Verify

デフォルトへのリセット

RESET CLUSTER SETTING <name>;

ノードレベルの設定（ノードの再起動が必要）

ノードレベルの設定は cockroach start のフラグであり、実行時には変更できません。変更するには、ノードをドレインし、プロセスを停止して、フラグを更新した後、再起動します。performing-cluster-maintenance を参照してください。

起動フラグの完全な一覧については、node-level-settings リファレンスを参照してください。

ライセンス管理

CockroachDB Self-Hosted では、バックアップ／復元、変更フィード、保存時の暗号化、マルチリージョン機能などを利用するためにエンタープライズライセンスが必要です。ライセンスはクラスター設定として保存されます。

現在のライセンスを確認する：

SHOW CLUSTER SETTING cluster.organization;
SHOW CLUSTER SETTING enterprise.license;

ライセンスをインストールまたは更新する：

SET CLUSTER SETTING cluster.organization = '<organization-name>';
SET CLUSTER SETTING enterprise.license = '<license-key>';

ライセンスが有効であることを確認する：

SELECT * FROM [SHOW CLUSTER SETTING enterprise.license];

ライセンスの有効期限： ライセンスの有効期限が切れても、データが失われたり、クラスターが利用できなくなったりすることはありません。更新されるまで、エンタープライズ機能（バックアップ、CDC、EAR）は動作しなくなります。コア機能は引き続き利用できます。ライセンスの有効期限を事前に確認してください。

CockroachDB Core（無料）： エンタープライズライセンスなしで実行する場合、ライセンス管理は不要です。コア機能は常に利用できます。

---

高度な設定／BYOC 設定

適用対象： Tier = Advanced または BYOC

SQL レベルのクラスター設定のほとんどは変更可能です。インフラストラクチャレベルの設定は Cockroach Labs が管理します。

変更可能な設定（一般的な例）

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;

制限対象（CRL が管理）

Cockroach Labs が管理し、変更できない設定：

• server.time_until_store_dead
• kv.snapshot_rebalance.max_rate
• cluster.preserve_downgrade_option（アップグレードには Cloud Console を使用してください）
• ノードレベルのフラグ（--cache、--max-sql-memory）— CRL が管理します

変更が拒否された場合、エラーにその設定が CockroachDB Cloud によって管理されていることが示されます。Cloud Console を使用するか、サポートにお問い合わせください。

ライセンス： Advanced／BYOC では、エンタープライズライセンスは Cockroach Labs によって自動的に管理されます。お客様による操作は不要です。

全一覧については、クラウド制限設定のリファレンスを参照してください。

---

Standard の設定

適用対象： Tier = Standard

Standard はマルチテナント型のマネージドサービスです。変更が他のテナントに影響する可能性があるため、ほとんどのクラスター設定は変更できません。主なチューニング手段としてセッション変数を使用してください。

セッション変数（推奨される方法）

-- 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';

設定できる項目

• SET と ALTER ROLE によるセッションレベルのタイムアウトとデフォルト値
• セッション変数による SQL レベルの動作

CRL が管理する項目

• すべてのインフラストラクチャ設定（レプリケーション、アドミッション制御、ストレージ）
• コンピューティングとネットワーク — Cloud Console から設定します

注： Standard では、SHOW ALL CLUSTER SETTINGS で返される設定が限られている場合があります。

---

Basic の設定

適用対象： Tier = Basic

Basic は、設定へのアクセスが最小限のサーバーレスサービスです。インフラストラクチャは完全に管理され、自動的にスケールします。SQL レベルのチューニングにはセッション変数を使用してください。

セッション変数

SET statement_timeout = '30s';
ALTER ROLE ALL SET statement_timeout = '30s';

Cloud Console での設定

• 支出制限
• IP 許可リスト
• リージョンの選択

その他の設定はすべて Cockroach Labs が管理します。設定をより細かく制御する必要がある場合は、Standard または Advanced へのアップグレードを検討してください。

---

安全上の考慮事項

読み取り専用クエリは、すべてのティアで安全です。

設定を変更する前に：

1. 現在の値を記録します（ロールバック用）
2. アップグレードの実行中ではないことを確認します
3. 影響を理解します（description フィールドを確認してください）
4. 一度に変更する設定は1つだけにします
5. 追加の変更を行う前に、15～30分間監視します

リスクレベル：

• 低： sql.defaults.statement_timeout、diagnostics.reporting.enabled
• 中： kv.snapshot_rebalance.max_rate、gc.ttlseconds（ゾーン設定パラメーター — 同じリスククラス）
• 高： cluster.preserve_downgrade_option、admission.kv.enabled

重要： ローリングアップグレード中は、設定を絶対に変更しないでください。クラスター設定はクラスター上のすべてのワークロードに影響するため、可能であれば、より範囲を限定できるセッション変数を優先してください。

各設定の詳細なリスク評価については、安全ガイドのリファレンスを参照してください。

トラブルシューティング

問題	ティア	対処方法
SET で「permission denied」が発生する	SH/ADV/BYOC	MODIFYCLUSTERSETTING を付与するか、管理者ロールを使用します
「managed by Cloud」エラーが発生する	ADV/BYOC	このティアでは設定が制限されています。Cloud Console を使用するか、サポートにお問い合わせください
設定が表示されない	STD/BAS	想定どおりです。マルチテナント／サーバーレスティアでは、表示できる設定が限られています
目に見える効果がない	SH/ADV/BYOC	セッション変数による上書きがないか確認し、SHOW で検証します
アップグレード後に設定が元に戻る	SH	再適用し、運用ランブックに記録します
エンタープライズ機能が動作しなくなった	SH	ライセンスの有効期限が切れています。SET CLUSTER SETTING enterprise.license で更新します
「enterprise license required」エラーが発生する	SH	ライセンスをインストールするか、コア機能のみの代替手段を使用します

参考資料

スキルの参考資料：

• SQL 監査クエリ
• 本番環境に推奨される値
• ノードレベルの設定（起動フラグ）
• Cloud で制限される設定
• 安全性ガイド

関連スキル：

• reviewing-cluster-health
• upgrading-cluster-version

CockroachDB 公式ドキュメント：

• クラスタ設定
• SET CLUSTER SETTING
• 本番環境チェックリスト