--- title: "clickhousectl v0.5.0 の新機能" date: "2026-11-03T08:13:31.185Z" author: "Al Brown" category: "Product" excerpt: "clickhousectl v0.5.0 では、ローカルから Cloud への UDF 移行、ClickHouse Managed Postgres のオブザーバビリティ、コマンド体系の標準化、各 Cloud コマンドに必要な API キー権限の一覧表示に対応しました。" --- # clickhousectl v0.5.0 の新機能 [`clickhousectl`](https://github.com/ClickHouse/clickhousectl) (`chctl`) は、ローカル環境と ClickHouse Cloud の双方で ClickHouse と Postgres を扱える統合 CLI です。 ローカル環境では、ClickHouse のバージョン導入・切り替え、プロジェクト単位の ClickHouse サーバーおよび Docker ベースの Postgres の実行、クライアント接続を担います。Cloud 環境では、ClickHouse、ClickHouse Managed Postgres、ClickPipes、ClickStack、バックアップ、キー、メンバーのライフサイクル全体をカバーします。 [v0.4.0](https://clickhouse.com/blog/clickhousectl-v0-4-0) でベータを終了し、水平オートスケーリングと ClickPipe スキーマ自動検出を追加しました。v0.5.0 の主なハイライトは次のとおりです。 - **UDF のエンドツーエンド対応**: 雛形作成、ローカルテスト、Cloud へのデプロイを 1 つのコマンドで実行できます。 - **ClickHouse Managed Postgres**: メトリクス、サーバーログ、スロークエリパターン、HTTP 経由の読み取り専用 SQL、IP 許可ルールに対応しました。 - **一貫性と自動化対応の向上**: セレクターの統一、`--file` 入力、組織(org)のグローバル選択、JSON エラー出力の徹底を実施しました。一部は**破壊的変更**となるため、[破壊的変更](#breaking-changes)をご確認ください。 - **保存済みクエリと Query API エンドポイント**: 保存済みクエリが一般提供 (GA) となり、HTTP エンドポイントとして公開できるようになりました。 - **BigQuery CDC ClickPipes**: 一定間隔または cron スケジュールによる BigQuery からの継続的レプリケーションに対応しました。 - **ClickStack の CLI 対応**: ダッシュボード、アラート、Webhook、保存済み検索、ソース、ロールを CLI から操作できます。 - **ヘルプでの必要権限表示**: すべての Cloud コマンドで、実行に必要な API キーの権限を明示します。 - **Cloud 機能カバー範囲の大幅拡大**: サービス設定、スケーリングスケジュール、アップグレードウィンドウ、スナップショット、バックアップバケット、BYOC インフラストラクチャ、組織ロール、クォータ、クレジットに対応しました。 すでにインストール済みの場合は、その場でアップデートできます。 ```bash clickhousectl update ``` 未導入の場合は、以下の任意の方法でインストールしてください。 ```bash curl https://clickhouse.com/cli | sh pip install clickhousectl uv tool install clickhousectl npm i -g clickhousectl cargo 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`。 ```bash clickhousectl local udf init my_udf clickhousectl local udf deploy my_udf clickhousectl local client --query "SELECT my_udf(1)" clickhousectl cloud udf deploy my_udf --service ``` 詳細は [ユーザー定義関数ガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/user-defined-functions.md) を参照してください。 ## 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 :[=]` ルールまたは `--block-public-access` を受け付け、`postgres update` は `--add-ip-allow` および `--remove-ip-allow ` でルールの追加・削除を行います(IPv4 のみ)。復元 API の仕様上、未指定では全アドレスに開放されてしまうため、`postgres restore` は復元元サービスの IP ルールを復元先サービスへ自動的にコピーします。 ```bash clickhousectl cloud postgres slow-queries list \ --from-date 2026-10-14T00:00:00Z --to-date 2026-10-15T00:00:00Z --sort-by p95_duration clickhousectl cloud postgres logs --from-date ... --to-date ... --severity ERROR clickhousectl cloud postgres query --query "SELECT version()" clickhousectl cloud postgres update --add-ip-allow '203.0.113.0/24:5432..6432=office' ``` 詳細は [ClickHouse Managed Postgres ガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/managed-postgres.md) を参照してください。 ## 一貫性のあるコマンド体系 0.5.0 ではコマンドの入力形式を標準化し、1 つのコマンドを覚えれば他のコマンドの構造も把握できるようにしました。これは人間の利用者にとっても重要ですが、コマンド間の規則性を学習するエージェントにとってはさらに大きな意味を持ちます。新しいルールは以下のとおりです。 - サブコマンドのパスを最後まで指定した上で、既存リソースを**位置引数の ID** で渡す。 - または、**`--name`** でリソースの完全一致名を指定する。 - 組織の選択には **`--org-id` または `--org-name`** を使用し、`cloud` 以降の任意の位置で指定可能。 - リソース名の変更には **`--new-name`** を使用する。 ほとんどの変更では従来の指定形式も非表示のエイリアスとして維持されていますが、一部は既存のスクリプトに影響する破壊的変更となっています。 ### 破壊的変更 | 変更点 | 0.4.x | 0.5.0 | | --- | --- | --- | | 更新時(`service`、`postgres`、`key`、`org update`)の名称変更フラグ。`--name` は対象の*選択*に使用されるように変更 | `cloud service update --name reporting` | `cloud service update --new-name reporting` | | 組織コマンド(`org get`、`update`、`usage`、`prometheus`)において、位置引数 ID ではなく他のコマンド同様に `--org-id` / `--org-name` で組織を選択。組織はリソースではなくスコープとして扱う | `cloud org get ` | `cloud org get --org-id `(または `--org-name prod`) | | ClickPipe スキーマ自動検出の引数順序(Kafka、Kinesis、オブジェクトストレージ、Pub/Sub) | `cloud clickpipe schema-discover kafka ...` | `cloud clickpipe schema-discover kafka ...` | | ネイティブのクライアント・サーバー引数は `--` の後に配置必須。従来は未認識のフラグが無言で無視されていた | `local client dev --some-native-flag` | `local client dev -- --some-native-flag` | | `postgres promote` / `switchover` から `--wait` / `--wait-timeout` を削除 | `cloud postgres promote --wait` | `cloud postgres promote ` を実行後、`cloud postgres get ` をポーリング | | GCP Postgres のサイズ名を API に合わせて変更(エイリアスなし)。C4/C4A/C4D に `-lssd-` を追加、Z3 に `highmem` を追加 | `--size c4-standard-4` | `--size c4-standard-lssd-4`(`z3-highlssd-8` → `z3-highmem-highlssd-8`) | | API で受け付けなくなったため、`service create` から `--encryption-key` / `--encryption-role` を削除 | `cloud service create ... --encryption-key ` | 削除(`service get` では引き続きフィールドを表示) | 旧形式のコマンドは利用法エラー(終了コード 2)で失敗し、意図せず解釈されることはありません。 ### 追加機能(旧形式も引き続き動作) | 変更点 | 0.4.x | 0.5.0 | | --- | --- | --- | | グローバル組織選択 | 末端のコマンドでのみ `--org-id` を指定可能 | `cloud --org-name prod service list`。任意の深さで指定可能 | | 各所での名前による選択(サービス、Postgres、キー、ClickPipes、ロール、BYOC、エンドポイント、ClickStack)。メンバーや招待には `--email` を使用 | `cloud service query --id ` / クエリでのみ `--name` が使用可能 | `cloud service get --name analytics`、`cloud clickpipe get --name ingest-orders` | | ローカルインスタンス名の位置引数化 | コマンドごとに `--name` と位置引数が混在 | `local postgres start app`、`local server dotenv dev`(`--name` は非表示エイリアス) | | JSON ドキュメント入力 | `--config-file` / `--settings-file` / `--file` | `--file `(対応箇所では標準入力に `-` が使用可能。旧指定は非表示エイリアス) | | Postgres 復元/リードレプリカ作成時の復元元を名前で指定 | 復元元 ID のみ | `--source-name primary` | ## 保存済みクエリと Query API エンドポイント `cloud saved-query` では、デフォルトパラメータ付きの保存済みクエリの作成、更新、削除が行えます。これらの操作は一般提供 (GA) となり、ベータ表示が外れました。`cloud query-api-endpoint` を使用すると、Query API エンドポイントを管理し、保存済みクエリを HTTP エンドポイントとして公開できます。これにより、ClickHouse からダッシュボードやアプリケーションへ直接データを配信することが可能になります。組織にエンドポイントが存在すると `query-api-endpoint list` や `--name` による参照がデコードエラーで失敗していた問題も修正されました。 ```bash clickhousectl cloud saved-query create --name top_pages --database default \ --sql-file top_pages.sql --param limit=10 ``` 詳細は [Query API リファレンス](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/query-api.md) を参照してください。 ## 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=` プレフィックスを付けない限り UTC)。チューニング用のフラグとして、取得の並列度、可視性遅延、取得ウィンドウサイズが用意されています。無効な組み合わせは、サービスアカウントキーが読み込まれる前にローカル側でエラーになります。 ```bash clickhousectl cloud clickpipe create bigquery --name orders-cdc ... \ --replication-mode cdc --replication-method query_based --sync-cron '*/15 * * * *' \ --table-mapping-json '{"sourceDatasetName":"shop","sourceTable":"orders","targetTable":"orders","queryCdcWatermarkColumn":"updated_at"}' ``` `--service-account-file` や `--staging-path` を含めた完全な例は、[ClickPipe 設定リファレンス](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/clickpipe-configuration.md) の「Configure BigQuery CDC」に記載されています。 その他の更新点として、MongoDB のテーブルマッピングで `structuredIngestion`(単一の JSON カラムではなく、型付きカラム、除外、ソートキー、パーティショニング)がサポートされ、MySQL パイプでは Cloud SQL 向けに `--mysql-type cloudsqlmysql` を受け付けるようになりました。 さらに細かな追加点として、Postgres TLS 制御、GCP ワークロードアイデンティティ、Kinesis Protobuf スキーマ(およびアクセスキーからの認証推定)、Kafka AWS Glue スキーマレジストリ、MongoDB 初期ロードの並列度、BigQuery スナップショットのチューニング、ソースチューニングオプション、ストリーミングテーブル定義、対応パイプの一時停止状態での開始、DNS ターゲットが挙げられます。また、送信前の事前検証が強化され、ポート範囲、スケール範囲、挿入サイズ、必須のオブジェクトストレージカラムが事前にチェックされるようになりました。 ```bash clickhousectl cloud clickpipe stop clickhousectl cloud clickpipe update --file patch.json clickhousectl cloud clickpipe start ``` 詳細は [ClickPipes ガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/clickpipes.md) および [ClickPipe 設定リファレンス](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/clickpipe-configuration.md) を参照してください。 ## 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)に照らしてチェックされるため、タイポがあった場合も無言で無視されることなくローカル側でエラーになります。 ```bash clickhousectl cloud clickstack source list clickhousectl cloud clickstack dashboard validate --file dashboard.json clickhousectl cloud clickstack dashboard create --file dashboard.json clickhousectl cloud clickstack webhook validate --file webhook.json clickhousectl cloud clickstack webhook create --file webhook.json clickhousectl cloud clickstack alert create --file alert.json ``` 詳細は [ClickStack ガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/clickstack.md) を参照してください。 ## サービス設定 CLI から管理できる Cloud サービス設定が大幅に増えました。 - `service settings`: ClickHouse 設定スキーマを読み取り、型付きの値で設定の取得・更新を実行。 - `service scaling-schedule`: 時間ベースのスケーリングスケジュール。 - `service upgrade-window`: アップグレードの実施時間帯の制御。 - `service profile list`: 特定リージョンで利用可能なサービスプロファイルの確認。 - `service wake`: アイドル状態のサービスを明示的に起動。 - `service snapshot` (ベータ): スナップショットの一覧表示およびスナップショット設定の管理。 - `service replica-aware-routing`。 - IP 許可リストの説明文(description)。 ```bash clickhousectl cloud service settings set --setting 'enable_analyzer=1' clickhousectl cloud service scaling-schedule set --file schedule.json ``` 詳細は [Cloud サービスガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/cloud-service.md) を参照してください。 ## バックアップ `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` で残りの操作をカバーします。プライベートエンドポイントの設定とタグ付けもサポートされています。 ```bash clickhousectl cloud org byoc validate ... clickhousectl cloud org byoc create ... clickhousectl cloud org byoc progress ... ``` ## 認証とアイデンティティ `cloud auth whoami` は現在有効な認証情報の背後にあるアイデンティティを表示し、`auth login` と `auth status` はそれを検証して表示するようになりました。初めて `service query` を実行する際、CLI は個別のクエリキーを発行するのではなく自身の API キーをバインドするようになったため、すでに付与されているロールがそのまま適用されます。空の API キー認証情報は拒否され、`--debug` ではどの認証情報ソースがなぜ選択されたかが示されます。 ```bash clickhousectl cloud auth whoami ``` ## コマンドが必要な権限を明示 すべての Cloud コマンドのヘルプで、背後で実行される API 呼び出しに必要な API キー権限が表示されるようになりました。この一覧は API 定義から自動生成されるため、常に API の最新仕様と同期しています。エージェントはコマンドを実行する前にこれを確認し、呼び出しエラーで初めて気づくのではなく、手持ちのキーで十分かどうかを事前に判断できます。また、必要なコマンドを実行するための権限が不足している場合に、エージェントが一時的な権限昇格を要求できるようにする今後の機能の基盤にもなっています。 ```bash clickhousectl cloud service create --help ... API key permission: control-plane:organization:create-service API key permission: control-plane:service:manage ``` ## 自動化とエージェント向けに最適化 - **徹底した JSON エラー出力**: `--json` モード(またはエージェントが検出された場合)、認証エラーやキャンセルを含むすべての Cloud 実行時エラーが構造化された JSON エラーとして出力されます。終了コードも統一されています: 1 エラー、2 利用法エラー、3 キャンセル、4 認証が必要。 - **管理コマンドの構造化出力**: ドキュメント化された JSON 出力仕様に対応([自動化リファレンス](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/automation.md) を参照)。 - **`--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](https://github.com/ArctypeZach) 氏、およびインストール失敗時に `clickhouse --version` のエラー出力を表示するようにしてくれた [@ylw510](https://github.com/ylw510) 氏([#993](https://github.com/ClickHouse/clickhousectl/pull/993))に感謝します。