clickhousectl、別名 chctl) を使用すると、端末、スクリプト、またはコーディングエージェントから ClickHouse Cloud を管理できます。このページでは、CLI のうち Cloud 関連の機能について説明します。すべてのコマンドグループやローカル開発、動作の詳細については、clickhousectl リファレンスを参照してください。
管理できる対象
clickhousectl cloud コマンドで管理できる対象は次のとおりです。
- サービス: ClickHouse Cloud サービスの作成、スケーリング、起動、停止、およびクエリ API 経由での SQL の実行。
- Managed Postgres (Beta): Postgres サービス、読み取りレプリカ、ポイントインタイム復元の作成と、それらの設定の変更。
- ClickPipes: オブジェクトストレージ、Kafka、Kinesis、Pub/Sub、Postgres、MySQL、MongoDB、BigQuery からのデータ取り込み。
- ClickStack: Managed ClickStack サービス上のソース、ダッシュボード、アラート、Webhook、保存済み検索、ロールの管理。
- ユーザー定義関数: 実行可能 UDF のローカルでのテストと、Cloud サービスへのデプロイ。
- バックアップ: バックアップの一覧表示、バックアップスケジュールの変更、新しいサービスへのバックアップの復元。
- 組織のアクセス管理: 組織、メンバー、招待、APIキー、アクティビティログ。
clickhousectl cloud <command> --help を実行してください。
インストール
~/.local/bin/clickhousectl と、その別名である chctl をインストールします。~/.local/bin が PATH に含まれていることを確認してください。npm、pip、uv など、その他のインストール方法についてはインストールを参照してください。
認証
ブラウザ経由の OAuth ログインは読み取り専用です。リソースを作成または変更するには、その変更を実行できるロールが付与された APIキー が必要です。clickhousectl cloud auth whoami でいつでも確認できます。複数の組織に所属している場合は、Cloud コマンドに --org-id <org-id> (または --org-name <name>) を指定してください。CI では、ログインせずに CLICKHOUSE_CLOUD_API_KEY と CLICKHOUSE_CLOUD_API_SECRET を設定します。認証情報の優先順位とログアウトについては、認証を参照してください。
例
サービスを作成してクエリを実行する
state が running になるまで clickhousectl cloud service get "$CH_ID" をポーリングしてください。
APIキーで最初にクエリを実行すると、clickhousectl はサービスのクエリ API エンドポイントにお使いのAPIキーを追加します。エンドポイントが存在しない場合は作成されます。新しいキーは作成されません。この動作を行わずにエラーとするには、--no-auto-enable を指定してください。OAuth を使用する場合、service query は読み取り専用の SELECT 文を実行します。クエリ API は約 30 秒でタイムアウトするため、長時間かかるクエリや一括ロードには clickhouse client を使用してください。
Managed Postgres サービスを作成する
create の実行時にしか返されないため、必ず保存しておいてください。--ip-allow を省略すると、ポート 5432 と 6432 がすべてのアドレスに対して開放されます。state が running になるまで待ってから、CA 証明書を使用して psql で接続してください。
ClickPipes、ClickStack、バックアップを確認する
ユーザー定義関数をデプロイする
clickhousectl local udf deploy my_udf を実行し、関数をテストしてください。
JSON 出力とコーディングエージェント
Cloud コマンドは--json を受け付けます。また、CLI はコーディングエージェントを検出すると自動的に JSON を選択します。この場合、cloud service query のデフォルトの出力形式は JSONEachRow になるため、出力をパースするスクリプトでは --format を指定してください (例:--format TabSeparated) 。詳しくは JSON 出力 および 終了コード を参照してください。ClickHouse agent skills は clickhousectl skills でインストールできます。
さらに詳しく
- clickhousectl リファレンス: すべてのコマンドグループ、ローカル開発、スキル、セルフアップデート、テレメトリーについて説明しています。
- リポジトリ内のガイド:
- リポジトリ内のリファレンス: 認証とアクセス、SQL とクエリ API、ClickPipe の設定、自動化と出力の契約