clickhousectl v0.5.0 の新機能

clickhousectl (chctl) は、ローカル環境と ClickHouse Cloud の双方で ClickHouse と Postgres を扱える統合 CLI です。 ローカル環境では、ClickHouse のバージョン導入・切り替え、プロジェクト単位の ClickHouse サーバーおよび Docker ベースの Postgres の実行、クライアント接続を担います。Cloud 環境では、ClickHouse、ClickHouse Managed Postgres、ClickPipes、ClickStack、バックアップ、キー、メンバーのライフサイクル全体をカバーします。

v0.4.0 でベータを終了し、水平オートスケーリングと ClickPipe スキーマ自動検出を追加しました。v0.5.0 の主なハイライトは次のとおりです。

• UDF のエンドツーエンド対応: 雛形作成、ローカルテスト、Cloud へのデプロイを 1 つのコマンドで実行できます。
• ClickHouse Managed Postgres: メトリクス、サーバーログ、スロークエリパターン、HTTP 経由の読み取り専用 SQL、IP 許可ルールに対応しました。
• 一貫性と自動化対応の向上: セレクターの統一、--file 入力、組織(org)のグローバル選択、JSON エラー出力の徹底を実施しました。一部は破壊的変更となるため、破壊的変更をご確認ください。
• 保存済みクエリと Query API エンドポイント: 保存済みクエリが一般提供 (GA) となり、HTTP エンドポイントとして公開できるようになりました。
• BigQuery CDC ClickPipes: 一定間隔または cron スケジュールによる BigQuery からの継続的レプリケーションに対応しました。
• ClickStack の CLI 対応: ダッシュボード、アラート、Webhook、保存済み検索、ソース、ロールを CLI から操作できます。
• ヘルプでの必要権限表示: すべての Cloud コマンドで、実行に必要な API キーの権限を明示します。
• Cloud 機能カバー範囲の大幅拡大: サービス設定、スケーリングスケジュール、アップグレードウィンドウ、スナップショット、バックアップバケット、BYOC インフラストラクチャ、組織ロール、クォータ、クレジットに対応しました。

すでにインストール済みの場合は、その場でアップデートできます。

1clickhousectl update

未導入の場合は、以下の任意の方法でインストールしてください。

1curl https://clickhouse.com/cli | sh
2pip install clickhousectl
3uv tool install clickhousectl
4npm i -g clickhousectl
5cargo install clickhousectl

ユーザー定義関数: ローカルから Cloud へ #

実行可能 UDF(ユーザー定義関数)の完全なワークフローが整いました。local udf init は UDF ディレクトリ(udf.json 定義と Python スクリプト、またはネイティブの amd64//arm64/ バイナリ)の雛形を生成します。local udf deploy でローカルサーバーへインストールし、通常の SQL でテストできます。動作確認後、cloud udf deploy を実行すれば、ディレクトリのパッケージ化、UDF(または新バージョン)の作成、サービスへのアタッチ、サービスの起動までを 1 ステップで完了します。

より詳細な制御向けに、低レベルの Cloud コマンドも利用可能です (ベータ): cloud udf create、version create、attach / detach(--wake 付与可能)、attachment list。

1clickhousectl local udf init my_udf
2clickhousectl local udf deploy my_udf
3clickhousectl local client --query "SELECT my_udf(1)"
4clickhousectl cloud udf deploy my_udf --service <service-id>

詳細は ユーザー定義関数ガイド を参照してください。

ClickHouse Managed Postgres: オブザーバビリティ、クエリ実行、ネットワークアクセス #

ターミナルから ClickHouse Managed Postgres サービスを確認できるようになりました。postgres metrics はサービスメトリクスをコンパクトな時系列で返し、postgres logs はサーバーログをテーブル形式で表示します(重大度や本文テキストでの絞り込みが可能)。postgres slow-queries は、合計・平均・p95・p99 の実行時間、CPU、行数、WAL などでソートした正規化クエリパターンを一覧表示します。get では特定パターンの直近の実行状況を確認できます。postgres prometheus は既存のスクレイピング環境向けに生の Prometheus エンドポイントを公開します。エージェントも同じコマンドを使って低速な Postgres の根本原因分析を行えます。

cloud postgres query は、OAuth ログインを使用して HTTP 経由で読み取り専用 SQL を実行できるため、psql、ネットワーク経路、パスワードは不要です。その他にも、postgres backup list(Status カラム付き)、postgres list でのプロバイダー表示、検証済みの config 入力が新機能として加わりました。postgres get は復旧可能な最古の時点を表示します。設定書き込み(--set、--pg-config-file)は、autovacuum の閾値、checkpoint_timeout、wal_buffers、io_method、default_toast_compression を含む 29 項目以上の Postgres 設定を受け付けます。Enum 値は送信前に検証されます。

CLI からネットワークアクセスを設定することも可能です。postgres create は繰り返し指定可能な --ip-allow <IP_OR_CIDR>:<PORTS>[=<DESCRIPTION>] ルールまたは --block-public-access を受け付け、postgres update は --add-ip-allow および --remove-ip-allow <RULE_ID> でルールの追加・削除を行います(IPv4 のみ)。復元 API の仕様上、未指定では全アドレスに開放されてしまうため、postgres restore は復元元サービスの IP ルールを復元先サービスへ自動的にコピーします。

1clickhousectl cloud postgres slow-queries list <postgres-id> \
2  --from-date 2026-10-14T00:00:00Z --to-date 2026-10-15T00:00:00Z --sort-by p95_duration
3clickhousectl cloud postgres logs <postgres-id> --from-date ... --to-date ... --severity ERROR
4clickhousectl cloud postgres query <postgres-id> --query "SELECT version()"
5clickhousectl cloud postgres update <postgres-id> --add-ip-allow '203.0.113.0/24:5432..6432=office'

詳細は ClickHouse Managed Postgres ガイド を参照してください。

一貫性のあるコマンド体系 #

0.5.0 ではコマンドの入力形式を標準化し、1 つのコマンドを覚えれば他のコマンドの構造も把握できるようにしました。これは人間の利用者にとっても重要ですが、コマンド間の規則性を学習するエージェントにとってはさらに大きな意味を持ちます。新しいルールは以下のとおりです。

• サブコマンドのパスを最後まで指定した上で、既存リソースを位置引数の ID で渡す。
• または、--name でリソースの完全一致名を指定する。
• 組織の選択には --org-id または --org-name を使用し、cloud 以降の任意の位置で指定可能。
• リソース名の変更には --new-name を使用する。

ほとんどの変更では従来の指定形式も非表示のエイリアスとして維持されていますが、一部は既存のスクリプトに影響する破壊的変更となっています。

破壊的変更 #

旧形式のコマンドは利用法エラー(終了コード 2)で失敗し、意図せず解釈されることはありません。

追加機能(旧形式も引き続き動作) #

保存済みクエリと Query API エンドポイント #

cloud saved-query では、デフォルトパラメータ付きの保存済みクエリの作成、更新、削除が行えます。これらの操作は一般提供 (GA) となり、ベータ表示が外れました。cloud query-api-endpoint を使用すると、Query API エンドポイントを管理し、保存済みクエリを HTTP エンドポイントとして公開できます。これにより、ClickHouse からダッシュボードやアプリケーションへ直接データを配信することが可能になります。組織にエンドポイントが存在すると query-api-endpoint list や --name による参照がデコードエラーで失敗していた問題も修正されました。

1clickhousectl cloud saved-query create <service-id> --name top_pages --database default \
2  --sql-file top_pages.sql --param limit=10

詳細は Query API リファレンス を参照してください。

ClickPipes #

本リリースでは ClickPipes のサポートが大幅に拡充されました。最大の目玉は clickpipe update で、CDC の一時停止 → 更新 → 再開の流れを含め、実行中のパイプの設定を安全に変更できる完全な更新コマンドです。CDC パイプでは、高度なテーブルマッピング(テーブルエンジンの選択を含む。Postgres では ReplacingMergeTree がデフォルト)、転送先データベースの選択、CDC スケーリングに対応しました。

BigQuery CDC。 従来 clickpipe create bigquery はスナップショットのみをサポートしていました。今回のリリースより、--replication-mode cdc または cdc_only が指定可能になり、--replication-method query_based(各テーブルで queryCdcWatermarkColumn を指定)または events_based(各テーブルで eventsFunction、appends、changes のいずれかを指定)と組み合わせて使用できます。同期は --sync-interval-seconds または --sync-cron による cron スケジュールで実行されます(CRON_TZ=<zone> プレフィックスを付けない限り UTC)。チューニング用のフラグとして、取得の並列度、可視性遅延、取得ウィンドウサイズが用意されています。無効な組み合わせは、サービスアカウントキーが読み込まれる前にローカル側でエラーになります。

1clickhousectl cloud clickpipe create bigquery <service-id> --name orders-cdc ... \
2  --replication-mode cdc --replication-method query_based --sync-cron '*/15 * * * *' \
3  --table-mapping-json '{"sourceDatasetName":"shop","sourceTable":"orders","targetTable":"orders","queryCdcWatermarkColumn":"updated_at"}'

--service-account-file や --staging-path を含めた完全な例は、ClickPipe 設定リファレンス の「Configure BigQuery CDC」に記載されています。

その他の更新点として、MongoDB のテーブルマッピングで structuredIngestion(単一の JSON カラムではなく、型付きカラム、除外、ソートキー、パーティショニング)がサポートされ、MySQL パイプでは Cloud SQL 向けに --mysql-type cloudsqlmysql を受け付けるようになりました。

さらに細かな追加点として、Postgres TLS 制御、GCP ワークロードアイデンティティ、Kinesis Protobuf スキーマ(およびアクセスキーからの認証推定)、Kafka AWS Glue スキーマレジストリ、MongoDB 初期ロードの並列度、BigQuery スナップショットのチューニング、ソースチューニングオプション、ストリーミングテーブル定義、対応パイプの一時停止状態での開始、DNS ターゲットが挙げられます。また、送信前の事前検証が強化され、ポート範囲、スケール範囲、挿入サイズ、必須のオブジェクトストレージカラムが事前にチェックされるようになりました。

1clickhousectl cloud clickpipe stop <service-id> <clickpipe-id>
2clickhousectl cloud clickpipe update <service-id> <clickpipe-id> --file patch.json
3clickhousectl cloud clickpipe start <service-id> <clickpipe-id>

詳細は ClickPipes ガイド および ClickPipe 設定リファレンス を参照してください。

ClickStack #

Cloud サービス内の ClickStack(オブザーバビリティ)リソース(データソース、ロール、ダッシュボード、アラート、Webhook、保存済み検索)を管理するための新しいコマンドグループ cloud clickstack が追加されました。ダッシュボードやアラートをリポジトリ内に JSON として保持して CI から適用したり、エージェントにダッシュボードを作成させたりできます。dashboard validate は作成前に定義を検証し、webhook validate は Webhook に対して同様の検証を行います。

CLI は最新の ClickStack API 仕様をサポートしています。

• ダッシュボードは 4 種類のフィルターすべて(クエリ式、静的リスト、Prometheus ラベル、ソースフィルター)、積み上げ折れ線グラフタイル、時系列ヒートマップ、lineInterpolation に対応しています。
• アラートでは、タイルや保存済み検索の代わりにインラインの chartConfig(source: inline)を使用できます。channel/channels は任意指定となり、新しい displayName および tags フィールドを透過的に渡せます。name は Handlebars のタイトルテンプレートになりました。alert list は displayName を表示し、--name はどちらのフィールドにもマッチします。
• ロール権限は統合先(ClickHouse または MongoDB)に照らしてチェックされるため、タイポがあった場合も無言で無視されることなくローカル側でエラーになります。

1clickhousectl cloud clickstack source list <service-id>
2clickhousectl cloud clickstack dashboard validate <service-id> --file dashboard.json
3clickhousectl cloud clickstack dashboard create <service-id> --file dashboard.json
4clickhousectl cloud clickstack webhook validate <service-id> --file webhook.json
5clickhousectl cloud clickstack webhook create <service-id> --file webhook.json
6clickhousectl cloud clickstack alert create <service-id> --file alert.json

詳細は ClickStack ガイド を参照してください。

サービス設定 #

CLI から管理できる Cloud サービス設定が大幅に増えました。

• service settings: ClickHouse 設定スキーマを読み取り、型付きの値で設定の取得・更新を実行。
• service scaling-schedule: 時間ベースのスケーリングスケジュール。
• service upgrade-window: アップグレードの実施時間帯の制御。
• service profile list: 特定リージョンで利用可能なサービスプロファイルの確認。
• service wake: アイドル状態のサービスを明示的に起動。
• service snapshot (ベータ): スナップショットの一覧表示およびスナップショット設定の管理。
• service replica-aware-routing。
• IP 許可リストの説明文(description)。

1clickhousectl cloud service settings set <service-id> --setting 'enable_analyzer=1'
2clickhousectl cloud service scaling-schedule set <service-id> --file schedule.json

詳細は Cloud サービスガイド を参照してください。

バックアップ #

backup bucket はサービス専用のバックアップバケット(ストレージの持ち込み)を管理し、service backup-config は暗号化を含むバックアップ設定を管理します。バックアップのタイムスタンプは UTC に正規化されるようになりました。AWS バックアップバケットでは、--file の本文で iamRoleExternalId を受け付けます(作成時は必須。更新時は、現在の値を保持する場合は省略、変更する場合は値を設定、クリアする場合は null を設定)。

組織、ガバナンス、BYOC #

組織レベルの新しいコマンドが追加されました: org role(カスタムロール)、org quota、org balance(クレジット残高)、org prometheus(自動検出)、org notifications (ベータ)。組織の通知をページ送りで取得し、重大度、タイプ、リソース、日付範囲で絞り込めます。org byoc は BYOC インフラストラクチャをエンドツーエンドで管理します: validate でクラウドアカウントの準備状況を確認し、create(VPC 持ち込みフラグを含む)でプロビジョニングを実行、progress でプロビジョニング状況を追跡し、get、update、delete で残りの操作をカバーします。プライベートエンドポイントの設定とタグ付けもサポートされています。

1clickhousectl cloud org byoc validate ...
2clickhousectl cloud org byoc create ...
3clickhousectl cloud org byoc progress ...

認証とアイデンティティ #

cloud auth whoami は現在有効な認証情報の背後にあるアイデンティティを表示し、auth login と auth status はそれを検証して表示するようになりました。初めて service query を実行する際、CLI は個別のクエリキーを発行するのではなく自身の API キーをバインドするようになったため、すでに付与されているロールがそのまま適用されます。空の API キー認証情報は拒否され、--debug ではどの認証情報ソースがなぜ選択されたかが示されます。

1clickhousectl cloud auth whoami

コマンドが必要な権限を明示 #

すべての Cloud コマンドのヘルプで、背後で実行される API 呼び出しに必要な API キー権限が表示されるようになりました。この一覧は API 定義から自動生成されるため、常に API の最新仕様と同期しています。エージェントはコマンドを実行する前にこれを確認し、呼び出しエラーで初めて気づくのではなく、手持ちのキーで十分かどうかを事前に判断できます。また、必要なコマンドを実行するための権限が不足している場合に、エージェントが一時的な権限昇格を要求できるようにする今後の機能の基盤にもなっています。

1clickhousectl cloud service create --help
2...
3  API key permission: control-plane:organization:create-service
4  API key permission: control-plane:service:manage

自動化とエージェント向けに最適化 #

• 徹底した JSON エラー出力: --json モード(またはエージェントが検出された場合)、認証エラーやキャンセルを含むすべての Cloud 実行時エラーが構造化された JSON エラーとして出力されます。終了コードも統一されています: 1 エラー、2 利用法エラー、3 キャンセル、4 認証が必要。
• 管理コマンドの構造化出力: ドキュメント化された JSON 出力仕様に対応(自動化リファレンス を参照)。
• --all によるページネーション: API キー向けのページネーション、および ClickStack 向けのセレクターページネーション。
• 標準出力パイプの切断(| head)を静かに処理。
• ヘルプ内のエージェントコンテキストブロックをコマンドツリー全体で標準化・チェック。
• エージェント検出において、agents.md の AI_AGENT 変数を最優先で参照するように変更。従来の AGENT 変数に未認識の値が入っていても JSON 出力に切り替わらなくなりました(既知のエージェント名または AGENT=1 の場合は引き続き切り替わります)。
• ページネーション付きリスト出力の一貫性: UDF リストは、cloud key list と同じ構造である nextCursor を持つトップレベルの result 配列を返します。

ローカル開発環境の改善 #

ローカル開発環境に対しても一連の修正が行われました。

• 設定の再読み込みを跨いでもサーバーポートが保持されるようになりました。
• Postgres の SQL ファイルと標準入力が Docker 経由でストリーミングされるようになりました(psql のパイプ処理が動作)。
• 実行時の .gitignore が init によって復元されるようになりました。
• ダウンロードが条件付きになり、最新のビルドが再利用されるようになりました。
• 破損したメタデータや Docker の失敗に関するエラーメッセージがわかりやすくなりました。
• 匿名の Postgres ボリュームがコンテナとともに削除されるようになりました。

ローカル向けの新機能の主軸は、前述の local udf です。

謝辞 #

本リリースにおける UDF 関連の開発を共同で主導してくれた Zach Naimon 氏、およびインストール失敗時に clickhouse --version のエラー出力を表示するようにしてくれた @ylw510 氏(#993)に感謝します。