メインコンテンツへスキップ
ClickHouse CLI (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キー、アクティビティログ。
各コマンドで使用できるフラグと、必要な 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、バックアップを確認する

これらの読み取り系コマンドは OAuth 認証で利用できます。ClickPipe の作成や ClickStack のリソースの変更には APIキーが必要です。詳しくは、以下のリポジトリ内のガイドを参照してください。

ユーザー定義関数をデプロイする

まずはローカルサーバーに対して clickhousectl local udf deploy my_udf を実行し、関数をテストしてください。

JSON 出力とコーディングエージェント

Cloud コマンドは --json を受け付けます。また、CLI はコーディングエージェントを検出すると自動的に JSON を選択します。この場合、cloud service query のデフォルトの出力形式は JSONEachRow になるため、出力をパースするスクリプトでは --format を指定してください (例:--format TabSeparated) 。詳しくは JSON 出力 および 終了コード を参照してください。ClickHouse agent skills は clickhousectl skills でインストールできます。

さらに詳しく