clickhouse-cloud-management

ClickHouse Cloud 管理

ADR：2025-12-08-clickhouse-cloud-management-skill

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある場合、パラメーターが変化した場合、または回避策が必要だった場合は、先送りせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合のみ更新してください。

概要

HTTP インターフェース経由の SQL コマンドを使った ClickHouse Cloud のユーザーおよび権限管理です。このスキルでは、ClickHouse Cloud インスタンスのデータベースユーザーの作成、権限の付与、認証情報の管理について説明します。

スキーマドキュメントの原則：すべての ClickHouse テーブルおよびカラムの COMMENT が、唯一の信頼できる情報源（SSoT）です。テーブルまたはカラムを作成するときは、必ず COMMENT 句を含めてください。COMMENT に関する SSoT ポリシーの詳細は、quality-tools:clickhouse-architect を参照してください。

このスキルを使う場面

以下の場合にこのスキルを呼び出してください。

• ClickHouse Cloud のデータベースユーザーを作成するとき
• ユーザー権限を管理するとき（GRANT／REVOKE）
• ClickHouse Cloud への接続をテストするとき
• 認証の問題をトラブルシューティングするとき
• API キーとデータベースユーザーの違いを確認するとき

主な概念

管理オプション

ClickHouse Cloud には、機能の異なる 2 つの管理インターフェースがあります。

タスク	SQL 経由（CLI／HTTP）	Cloud Console 経由
データベースユーザーの作成	CREATE USER	対応
権限の付与	GRANT	対応
ユーザーの削除	DROP USER	対応
API キーの作成	不可	ここでのみ可能

重要な違い：データベースユーザー（SQL 経由で作成）は ClickHouse 自体の認証に使用します。API キー（コンソール経由で作成）は ClickHouse Cloud 管理 API の認証に使用します。

接続の詳細

ClickHouse Cloud がパブリックに公開しているのは HTTP インターフェースのみです。

• ポート：443（HTTPS）
• プロトコル：HTTP（ClickHouse ネイティブプロトコルではありません）
• ネイティブプロトコル：AWS PrivateLink が必要です（エンタープライズ向けのセットアップなしでは利用できません）

パスワード要件

ClickHouse Cloud では、強力なパスワードポリシーが適用されます。

• 12 文字以上
• 大文字を 1 文字以上含む
• 特殊文字を 1 文字以上含む

要件を満たすパスワードの例：StrongPass@2025!

クイックリファレンス

読み取り専用ユーザーを作成する

curl -s "https://default:PASSWORD@HOST:443/" --data-binary \
  "CREATE USER my_reader IDENTIFIED BY 'StrongPass@2025!' SETTINGS readonly = 1"

データベースへのアクセス権を付与する

curl -s "https://default:PASSWORD@HOST:443/" --data-binary \
  "GRANT SELECT ON deribit.* TO my_reader"

ユーザーを削除する

curl -s "https://default:PASSWORD@HOST:443/" --data-binary \
  "DROP USER my_reader"

SQL のパターンや高度な権限設定の詳細については、SQL パターンのリファレンスを参照してください。

認証情報の取得元

1Password のアイテム（Engineering Vault）

アイテム	用途
ClickHouse Cloud - API Key (Admin)	クラウド管理 API（コンソール操作）
ClickHouse Cloud - API Key (Developer Read-only)	クラウド管理 API（読み取り専用）
gapless-deribit-clickhouse	データベースの default ユーザーの認証情報

認証情報の取得

# Database credentials (for SQL commands)
op item get "gapless-deribit-clickhouse" --vault Engineering --reveal

# API key (for cloud management API)
op item get "ClickHouse Cloud - API Key (Admin)" --vault Engineering --reveal

一般的なワークフロー

ワークフロー 1：アプリケーションユーザーを作成する

1. 1Password から default ユーザーの認証情報を取得します
2. 適切な権限を付与して新しいユーザーを作成します。

HOST="your-instance.clickhouse.cloud"
PASSWORD="default-user-password"

# Create user
curl -s "https://default:$PASSWORD@$HOST:443/" --data-binary \
  "CREATE USER app_user IDENTIFIED BY 'AppPass@2025!'"

# Grant specific database access
curl -s "https://default:$PASSWORD@$HOST:443/" --data-binary \
  "GRANT SELECT, INSERT ON mydb.* TO app_user"

ワークフロー 2：ユーザーの存在を確認する

curl -s "https://default:$PASSWORD@$HOST:443/" --data-binary "SHOW USERS"

ワークフロー 3：接続をテストする

curl -s "https://user:password@HOST:443/" --data-binary "SELECT 1"

期待される出力：1（値 1 の単一行）

トラブルシューティング

認証に失敗する

• パスワードが複雑さの要件を満たしていることを確認してください
• ホスト URL にポート 443 が含まれていることを確認してください
• HTTPS（HTTP ではなく）を使用していることを確認してください

権限が拒否される

• ユーザーに必要な GRANT 文が設定されていることを確認してください
• データベース名とテーブル名が正しいことを確認してください
• 正しい設定でユーザーが作成されたことを確認してください

接続がタイムアウトする

• ClickHouse Cloud がパブリックに公開しているポートは 443 のみです
• ネイティブプロトコル（ポート 9440）には PrivateLink が必要です
• curl または clickhouse-client の HTTP モードで HTTP インターフェースを使用してください

ユーザー作成後の次のステップ

ClickHouse ユーザーを作成した後、devops-tools:clickhouse-pydantic-config を呼び出して、新しい認証情報を使った DBeaver の設定を生成します。

追加リソース

リファレンスファイル

詳細なパターンや高度なテクニックについては、以下を参照してください。

• references/sql-patterns.md - 例を含む SQL 構文の完全なリファレンス

Python ドライバーのポリシー

ClickHouse Cloud に接続する Python アプリケーションコードでは、clickhouse-connect（公式の HTTP ドライバー）を使用してください。推奨されるコードパターンと、clickhouse-driver（コミュニティ製）を避ける理由については、clickhouse-architect を参照してください。

関連スキル

• quality-tools:clickhouse-architect - スキーマ設計、圧縮コーデック、Python ドライバーのポリシー
• devops-tools:clickhouse-pydantic-config - DBeaver 設定の生成
• devops-tools:doppler-secret-validation - Doppler への認証情報の保存
• devops-tools:doppler-workflows - 認証情報のローテーションワークフロー

実行後の振り返り

このスキルの実行後、完了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラー表を修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、それに合わせて使用例とパラメーター表を更新します。
3. 回避策が必要でしたか？ — 別のフラグや追加手順などの工夫が必要だった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新します。

問題が実際に再現可能な場合にのみ更新してください。推測に基づく更新はしないでください。