clickhousectl (別名 chctl) は、ローカル開発から ClickHouse Cloud までをカバーする ClickHouse 公式の CLI です。端末で操作するユーザー、スクリプト、コーディングエージェントのいずれからも利用できます。
clickhousectl では、次のことができます。
- ローカルの ClickHouse バージョンのインストールと切り替え、分離されたローカルサーバーの実行、SQL の実行
- Docker を利用した Postgres のローカル実行
- ClickHouse Cloud サービスの作成、設定、スケーリング、バックアップ、クエリ実行
- ClickHouse Managed Postgres サービスの作成、監視、設定、復元
- オブジェクトストレージ、Kafka、Kinesis、Pub/Sub、Postgres、MySQL、MongoDB、BigQuery をソースとする ClickPipes の作成と運用
- Managed ClickStack サービス上のソース、ダッシュボード、アラート、Webhook、保存済み検索、ロールの管理
- 実行可能 UDF のローカル開発と ClickHouse Cloud へのデプロイ
- 組織のメンバー、招待、APIキー、ロールの管理
- 公式の ClickHouse agent skills のコーディングエージェントへのインストール
clickhousectl <command> --help です。ほとんどのコマンドのヘルプの末尾には CONTEXT FOR AGENTS ブロックがあり、Cloud コマンドではそのコマンドに必要な APIキーのアクセス許可も記載されています。タスクごとの手順については、各セクションに記載されているガイドへのリンクを参照してください。Cloud を中心とした概要については、ClickHouse CLI を参照してください。
インストール
clickhousectl は macOS および Linux 上で動作し、ARM64 と x86_64 の両アーキテクチャに対応しています。
~/.local/bin/clickhousectl をインストールし、chctl という別名を作成します。~/.local/bin が PATH に含まれていることを確認してください。
パッケージマネージャーを使ってインストールすることもできます。
chctl という別名が作成されるのは、インストールスクリプトまたは npm でインストールした場合のみです。既存のインストールを更新するには、clickhousectl update を実行してください (自己更新を参照) 。
要件
- Docker (ローカルの Postgres を使用する場合のみ)
- Cloud コマンドを使用する場合は、ClickHouse Cloud アカウントが必要です。閲覧系のコマンドは、ブラウザ経由の OAuth 認証 (
cloud auth login) で実行できます。リソースの作成や変更を行うには APIキー が必要です。詳しくは 認証 を参照してください。
ローカル
ローカルコマンドは現在のディレクトリを対象に動作します。各プロジェクトのサーバーデータは.clickhouse/ に保存され、ClickHouse バイナリは ~/.clickhouse/ に置かれてすべてのプロジェクトで共有されます。CLI は親ディレクトリを検索しないため、ローカルコマンドはプロジェクトのルートディレクトリで実行してください。ワークフロー全体については、ローカル開発ガイドを参照してください。
インストールとバージョンの選択
local use は、必要に応じてバージョンをインストールし、以降のサーバー起動時のデフォルトに設定したうえで、~/.local/bin/clickhouse にシンボリックリンクを作成します。これにより、clickhouse client と clickhouse local を PATH 経由で利用できるようになります。シンボリックリンクを作成しない場合は --no-global を指定してください。そのパスに通常のファイルがすでに存在する場合、そのファイルには手を加えません。
local remove では、デフォルトのバージョンや、いずれかのプロジェクトで実行中のサーバーが使用しているバージョンは削除できません。--force を指定すると、該当するサーバーを停止してからバージョンを削除し、デフォルト設定とシンボリックリンクも解除します。
プロジェクトを初期化する
init の実行は任意です。ランタイムデータ用に git の管理対象外となる .clickhouse/ ディレクトリを作成するほか、コミット可能な SQL スキャフォールドとして clickhouse/ (tables/、materialized_views/、queries/、seed/、udfs/) と postgres/ (tables/、views/、functions/、queries/、seed/) を作成します。再実行した場合は、不足しているものだけが作成されます。
ローカルサーバーを起動する
.clickhouse/servers/<name>/data/ に専用のデータを持ち、サーバーを停止してもデータは次回の起動に備えて保持されます。名前を指定しない場合、最初のサーバーは default になります。default がすでに実行中であれば、新しい名前が自動生成されます。デフォルトのポートは HTTP が 8123、TCP が 9000 で、これらが使用中の場合は空いているポートが割り当てられます。
--version を指定すると、デフォルトを変更せずに、その起動時に使用するバージョンを選択できます。バージョンを指定せず、デフォルトも設定されていない状態で起動すると、latest がインストールされますが、デフォルトには設定されません。latest をデフォルトにするには、先に local use latest を実行してください。
ローカルクライアントで SQL を実行する
local client は、名前付きサーバーを実行しているのと同じ ClickHouse バイナリを使用して、そのサーバーに接続します (デフォルト名: default) 。-- 以降の引数は、そのまま clickhouse client に渡されます。出力と終了ステータスは JSON モードでも clickhouse client のものがそのまま返されるため、スクリプトで使用する場合は SQL の出力フォーマットを明示的に指定してください。
カスタムサーバー構成
XML または YAML 形式の部分的な設定ファイルを~/.clickhouse/configs/ に配置し、サーバー起動時にその名前を指定して選択します:
--config を付けずに起動すると、オーバーレイは解除されます。管理対象のデータパスとポートは、設定ファイルの値よりも常に優先されます。
接続情報を dotenv ファイルに書き込む
dotenv は、実行中のサーバーが実際に使用しているポートを読み取り、CLICKHOUSE_HOST、CLICKHOUSE_PORT、CLICKHOUSE_HTTP_PORT を書き込みます。ユーザー、パスワード、データベースを指定した場合は、それらも併せて書き込まれます。既存のファイルにあるその他の行はそのまま保持されます。ファイルはアプリケーションの dotenv ローダーで読み込んでください。出力されたプレビューを eval で実行してはいけません。
ローカル Postgres
ローカル Postgres は Docker 上で動作するため、Docker が起動している必要があります。Postgres 17 と 18 がサポートされており、18-alpine などのイメージタグも使用できます。新しいインスタンスではデフォルトで 18 が使用されます。
.env.local にはパスワードが含まれるため、バージョン管理の対象から除外してください。
ローカル UDFs
local udf は、clickhouse/udfs/<name>/ 内の実行可能 UDF をローカルサーバーにデプロイします。cloud udf は同じディレクトリを Cloud にアップロードします (Cloud での UDFs を参照) 。
init 以外のすべてのコマンドは --server <name>(デフォルトは default)を指定できます。deploy は Cloud と同じ方法で udf.json を検証します。サーバーが稼働中の場合は、関数を再読み込みし、関数が読み込まれたことを確認します。native ランタイムをローカルにデプロイできるのは、Linux の amd64 または arm64 ホストのみです。詳しくは ユーザー定義関数ガイド を参照してください。
認証
Cloud のコマンドでは、次の 2 種類の認証情報のいずれかを使用します。
まだClickHouse Cloudのアカウントをお持ちでない場合は、
clickhousectl cloud auth signup を実行すると、ブラウザでサインアップページが開きます。
OAuthログイン
~/.clickhouse/tokens.json にグローバルに保存され、自動的にリフレッシュされます。
OAuth は 読み取り専用 です。リソースを作成または変更するには、API キー でログインしてください。
APIキー
コマンドの実行に必要なロールを付与したAPIキーを作成し、保存します。対話型プロンプトで入力すれば、シークレットがシェルの履歴に残りません:.env ファイルからもこれらの変数を読み取ります。.env はバージョン管理の対象に含めないでください。
認証情報の確認と削除
whoami はどちらの種類の認証情報でも動作し、認証情報が拒否された場合は終了コード 4 で終了します。status は有効な認証情報が 1 つもない場合でも終了コード 0 を返すことがあるため、アクセスできるかどうかの確認には whoami を使用してください。ログアウトしても、環境変数の設定は解除されず、.env も変更されません。
認証情報の優先順位
利用可能なソースのうち、最初に見つかったものが使用されます:--api-keyおよび--api-secretフラグ.clickhouse/credentials.json- エクスポートされた環境変数
- 現在のディレクトリにある
.env内の変数 - グローバル OAuth トークン
cloud コマンドに --debug を指定すると、選択された認証情報のソースと API URL が stderr に出力されます:
組織を選択する
組織スコープのコマンドが組織を自動的に選択するのは、認証情報でアクセスできる組織が 1 つだけの場合に限られます。それ以外の場合は、--org-id を指定するか、--org-name に組織名を正確に指定してください:
--name で正確な名前を指定します。アクセス許可、制限付きキー、ログアウト時のクリーンアップについては、認証とアクセスを参照してください。
Cloud
Cloud コマンドは ClickHouse Cloud API を呼び出します。作成および更新のリクエストは、API に受け付けられた時点で応答が返されます。そのため、リソースが目的のステートに達するまでget をポーリングしてください。
サービス
running になるまで get を繰り返し実行してください。--ip-allow を省略すると、すべての IP (0.0.0.0/0) が許可されます。 エントリは IP_OR_CIDR=DESCRIPTION の形式で指定します。--backup-id を使用するとバックアップを新しいサービスに復元でき、--byoc-id を使用するとサービスを BYOC インフラストラクチャに配置できます。
サービスの更新、スケーリング、設定は次のように行います:
update は、指定したフラグのみを変更します。
サービス関連のその他のコマンドグループとして、settings (list、get、schema、set、unset)、scaling-schedule、upgrade-window、replica-aware-routing (ベータ)、snapshot (ベータ)、private-endpoint、backup-config、prometheus があります。詳しくは Cloud サービスの作成と運用 を参照してください。
クエリ API
cloud service query を使うと、ローカルの clickhouse バイナリやサービスのパスワードを用意しなくても、HTTP 経由で SQL ステートメントを 1 つ実行できます。
- OAuth では、読み取り専用の SQL アクセス権限を持つユーザー自身のアイデンティティでクエリが実行されます。サービスには何もバインドされません。
- APIキー: 初回の呼び出し時に、clickhousectl はユーザーのAPIキーをサービスのクエリ API エンドポイントに追加します。エンドポイントが存在しない場合は、
sql_console_adminロールを付与して作成します。既存のロール、オリジン、その他のキーのバインドはそのまま保持され、新しいキーは作成されません。CLI がエンドポイントを変更した場合は、stderr にBinding the authenticated API key to the Query API endpoint for service '<name>'...が出力されます。この処理を行わずにエラーとするには、--no-auto-enableを指定します。
cloud service repair-query-key <service-id> を実行して明示的に置き換えてください。
クエリ API が受け付けるのは、1 リクエストにつき 1 ステートメントのみです。SQL の実行が継続していても約 30 秒でタイムアウトすることがあるため、書き込みを再試行する前に結果を確認してください。複数ステートメントを含むスクリプト、一括ロード、長時間実行されるクエリには clickhouse client を使用してください。サービスの IP 許可リストで制限されるのは直接接続のみで、プロキシ経由のクエリ API の経路は対象外です。アイドル状態のサービスにクエリを実行するとサービスが起動しますが、停止中のサービスは cloud service start で起動する必要があります。
サービスのクエリ API エンドポイント、名前付き SQL エンドポイント、保存クエリを管理します:
query-endpoint create は、エンドポイントに紐付けられたすべてのキーのロールを置き換えます。詳細は SQL とクエリ API の動作を参照してください。
Managed Postgres
cloud postgres は ClickHouse Managed Postgres を管理するためのコマンドです。これらのコマンドはベータ版で、GCP はプライベートプレビュー段階です。
m6gd.large、c6gd.xlarge、r6gd.xlarge などがあります。GCP では --provider gcp を指定し、GCP のリージョンと c4-standard-lssd-4 などのサイズを指定します。
create で返されるパスワードと接続文字列は必ず保存してください。以降の get の応答では認証情報は返されず、新しい認証情報を取得するには reset-password を使用するしかありません。psql で接続する際は、sslmode=verify-full と CA ファイルを使用してください。
create 時にアクセス関連のフラグを省略すると、Postgres (5432) と PgBouncer (6432) に対して、すべての IPv4 アドレスおよび IPv6アドレスからのアクセスが許可されます。 ルールごとに --ip-allow IP_OR_CIDR:PORTS[=DESCRIPTION] を 1 つずつ指定するか、ルールを設定しない場合は --block-public-access を指定してください。ルールを 1 つでも指定すると、指定したルールのみが適用されます。
監視と復旧:
cloud postgres query は OAuth 認証のみに対応しているため、より優先度の高い APIキーのソースが有効になっている間は失敗します。監視には metrics、slow-queries、prometheus を使用します。restore は、--ip-allow または --block-public-access を指定しない限り、ソースの現在の IPv4 アクセスルールを復元済みサービスにコピーします。復元およびレプリカの作成では、パスワードは返されません。promote と switchover は、リクエストが受け付けられた時点で応答を返します。promote の実行後は、レプリカが isPrimary: true を返すまで postgres get --json をポーリングしてください。詳しくは Managed Postgres ガイド を参照してください。
ClickPipes
cloud clickpipe は、オブジェクトストレージ、Kafka、Kinesis、Pub/Sub、Postgres、MySQL、MongoDB、BigQuery からデータを取り込みます。ClickPipe の作成とスキーマ検出には、APIキーと稼働中の宛先サービスが必要です。ソースごとに専用の clickpipe create <source> サブコマンドが用意されています。使用できるフラグは、--help を付けて実行すると確認できます。
IAM role を使用して S3 からファイルを読み込みます。まずスキーマを検出してから、カラムを選択します。
--table-mapping は ReplacingMergeTree テーブルを作成するため、現在のステートを読み取る際は FINAL WHERE _peerdb_is_deleted = 0 を指定してください。Kafka パイプも同じ手順です。同じソース用フラグを指定して clickpipe schema-discover kafka を実行し、続いてカラムを渡します。
--replication-mode cdc と --replication-method を指定し、--table-mapping-json でテーブルごとにウォーターマークカラムまたはイベント関数を指定します。同期のスケジュールは --sync-cron または --sync-interval-seconds で設定します。既存のパイプは、次のように操作します。
update の前に Paused 状態にしておく必要があります。パイプを停止し、Paused になるまで get でポーリングしてから更新してください。サービスが更新処理の一環としてパイプを再開する場合があるため、start は get がまだ Paused を返す場合にのみ実行してください。--start-paused は、オブジェクトストレージ、Kafka、Kinesis、Pub/Sub で使用できます。その他のコマンドグループには、cdc-scaling、context get (GCP のワークロードアイデンティティの準備状態とプリンシパル) 、reverse-private-endpoint があります。詳細は ClickPipes ガイド および ClickPipe 設定リファレンス を参照してください。
ClickStack
cloud clickstack は、既存の Managed ClickStack サービスのソース、ダッシュボード、アラート、Webhook、保存済み検索、ロールを管理します。リソースはJSONファイルで指定します (--file を使用するか、stdin から読み込む場合は - を指定) 。読み取りは OAuth 認証に対応していますが、書き込みにはAPIキーが必要です。
get --json で現在のステートを保存し、変更したフィールドだけでなく定義全体を送信してください。詳しくは ClickStack ガイド を参照してください。
Cloud の UDFs
cloud udf は、組織スコープの実行可能 UDF とそのバージョン、およびサービスへの関連付けを管理します。deploy は、local udf でテストしたディレクトリをアップロードしてビルドの完了を待ち、そのバージョンを関連付けたうえで、デプロイが完了するまで待機します。
udf create、udf version create、udf attach (アイドルステートのサービスに対しては --wake を指定) 、udf detach、udf delete を使用します。これらのコマンドはリクエストが受理された時点で処理を返すため、udf get と udf attachment get をポーリングしてステートを確認してください。読み取り操作では OAuth を利用できますが、書き込み操作には APIキーが必要です。詳しくはユーザー定義関数ガイドを参照してください。
組織とアクセス
cloud org のサブコマンドでは --org-id を指定します。ID を位置引数として渡すことはできません。org usage で取得できる期間は最大 31 日です。org には、quota、balance、notification-types、role(カスタム組織ロール)、byoc(BYOC インフラストラクチャ)のサブコマンドもあります。通知機能はベータ版です。
メンバー、招待、APIキーを管理します:
key create で --ip-allow を省略すると、すべてのネットワークアクセスが拒否されます。この点はサービス作成時とは異なります。シークレットは一度しか表示されません。key list は、--all を指定しない限り 1 ページ分のみを返します。key update では、省略したフラグの設定はそのまま維持されますが、--clear-expiry、--clear-roles、--clear-ip-allow を指定すると、対応する設定が削除されます。
バックアップ
cloud backup bucket (get、create、update、delete) を使用すると、プロバイダー固有のJSONファイルをもとに、ユーザー所有のバックアップバケット (BYOB) を設定できます。詳しくは、Cloud サービスガイドのバックアップのセクションを参照してください。
JSON 出力
構造化されたデータを返すコマンドでは--json を指定できます。対象には、ローカル、Cloud、skills、update、telemetry の各コマンドが含まれます。
AI_AGENT を設定する任意のツールなど) を検出すると、自動的に JSON が選択されます。ただし、SQL クライアントとネイティブクライアントはそれぞれ独自のフォーマットを維持します。cloud service query は JSON モードでは JSONEachRow を返し、local client の出力は常にネイティブフォーマットです。クエリの出力をパースするスクリプトでは、--format を明示的に指定してください。
JSON モードでは、ランタイムエラーは、安定した code と message を含むオブジェクトとして stderr に出力されます。
error.code に基づいて行ってください。使用方法に関するエラーは従来どおりテキストで出力され、終了コードは 2 になります。出力形式とエラーコードについては、自動化と出力の契約を参照してください。
終了コード
local client、local postgres client など、ネイティブクライアントに処理を引き渡すコマンドでは、そのクライアント自身の終了ステータスがそのまま返されます。
エージェントスキル
公式の ClickHouse agent skills をコーディングエージェントにインストールします。--global を指定するとホームディレクトリにインストールされます。共有の .agents/skills/ ディレクトリは常にインストール対象に含まれます。端末を使用しない環境では、--agent、--all、--detected-only のいずれかを指定する必要があります。サポートされているエージェント名を確認するには、clickhousectl skills --help を実行してください。
セルフアップデート
テレメトリー
clickhousectl は、開発の参考にするため匿名の使用状況データを収集します。初回実行時は通知が表示されるだけで、データは一切送信されません。無効化しない限り、次回以降の実行から収集が始まります。
各イベントには以下の情報が含まれます。
- コマンドパスと、明示的に指定されたフラグおよび引数の名前(値は一切含みません)
- 実行結果と終了コード
- コマンドを打ち間違えた場合は、CLI が提案したコマンド名またはフラグ名(入力した内容は一切含みません)
- ランタイムエラー発生時は、範囲が限定されたカテゴリ情報(失敗したステージと種類、許可リストに含まれる HTTP ステータス、再試行・プロビジョニングステート・所要時間の各カテゴリ)
- CLI のバージョン、OS とアーキテクチャ、CI 上での実行かどうか、検出されたコーディングエージェント
-- 以降の引数、エラーメッセージが記録されることはありません。インストール ID やデバイス ID も使用しません。
オプトアウトするには:
CHCTL_TELEMETRY_DEBUG=1 を設定すると、データを一切送信せずにペイロードを stderr に出力します。詳しくは テレメトリーの詳細 を参照してください。