clickhousectl (chctl) は、手元のラップトップと ClickHouse Cloud の両方で ClickHouse と Postgres を操作できる単一の CLI です。ローカルでは ClickHouse のインストールとバージョンの切り替え、プロジェクト単位の ClickHouse サーバーや Docker ベースの Postgres の実行、クライアントの接続を行います。Cloud では ClickHouse、ClickHouse Managed Postgres、ClickPipes、ClickStack、バックアップ、キー、メンバーのライフサイクル全体をカバーします。
v0.5.0 では UDF をローカルから Cloud へ展開できるようにし、ClickHouse Managed Postgres のオブザーバビリティを追加し、コマンド体系を統一しました。v0.6.0 の主な変更点は次のとおりです:
- Git のように扱えるプロジェクト: プロジェクトのどのサブディレクトリからでもコマンドを実行でき、環境変数でプロジェクトルートを固定でき、サーバー設定をリポジトリにチェックインできます。
- パスワード不要の Cloud 接続:
cloud clickhouse clientはブラウザ経由でサインインし、create --dotenvはワンタイムパスワードを.envに書き込んでターミナルには表示しません。 search、シェル補完、feedback: キーワードからコマンドやフラグを探し、Tab で補完し、CLI でできなかったことを開発チームに伝えられます。- ClickHouse Managed Postgres: サービスが一般提供 (GA) となり、CLI では Postgres 19、AWS PrivateLink エンドポイント、スタンバイ数、削除保護に対応しました。
- ディスカバリ出力からの ClickPipes 作成:
--columns-fromでschema-discoverの出力をそのままパイプの宛先カラムにできます。 - 検証付きのインストール: インストールスクリプト、
update、npm が、ダウンロードのたびにリリースのチェックサムと照合します。インストールは GitHub API に依存しなくなりました。
このうちいくつかは既存の挙動を変更しており、0.5.x で保存された OAuth ログインは一度ログインし直す必要があります。アップグレードに関する注意点を参照してください。
すでにインストール済みの場合は、その場でアップデートできます:
clickhousectl updateまだの場合は、以下のいずれか好みの方法でインストールしてください:
curl https://clickhouse.com/cli | sh
pip install clickhousectl
uv tool install clickhousectl
npm i -g clickhousectl
cargo install clickhousectlGit のように扱えるプロジェクト
0.5.x では、プロジェクト単位のコマンドはカレントディレクトリそのものを基準にしていました。プロジェクトルートでサーバーを起動したあと src/ に cd すると、CLI からはそのサーバーが見えなくなっていました。0.6.0 では、.git/ を含むディレクトリが Git のリポジトリルートになるのと同じように、.clickhouse/ を含むディレクトリがプロジェクトルートになります。
プロジェクトのディレクトリで一度 clickhousectl local init を実行してください。以降、ローカルサーバー、Postgres インスタンス、保存済み API キー、UDF のソース、.env のフォバックはすべて、そのディレクトリまたは配下の任意のサブディレクトリから解決されます。
clickhousectl local init
clickhousectl local clickhouse start dev
cd src/app
clickhousectl local client dev --query "SELECT version()"最も近い .clickhouse/ が優先されるため、プロジェクトの中にネストされた別のプロジェクトは独立したプロジェクトとして扱われます。上位ディレクトリへの探索はホームディレクトリで止まるため、グローバルな ~/.clickhouse/ が配下のディレクトリのプロジェクトとして扱われることはありません。.clickhouse/ は Git の無視対象になるため、リポジトリをクローンしたあとに一度 local init を実行してください。local init なしでサーバーを起動することも引き続き可能です。
プロジェクトルートを明示的に指定する
スクリプト、CI ジョブ、モノレポでは、コマンドをどこで実行しても同じ 1 つのプロジェクトルートを使いたい場面がよくあります。CLICKHOUSECTL_PROJECT_DIR を設定するとディレクトリの探索はスキップされます:
export CLICKHOUSECTL_PROJECT_DIR=~/code/app
clickhousectl local init # initializes ~/code/app, not the current directory
clickhousectl local clickhouse start # state in ~/code/app/.clickhouse/リポジトリにチェックインできるサーバー設定
これまで名前付きの設定は --config を付けたときだけ、しかもホームディレクトリ配下からしか適用されませんでした。起動のたびに適用される設定はなく、リポジトリ経由でチーム内に設定を共有することもできませんでした。今回のリリースから、local clickhouse start の実行時には --config ファイルの前に次の config.d ディレクトリが両方マージされます:
| 場所 | 適用対象 | タイミング |
|---|---|---|
~/.clickhouse/config.d/ | このマシン上のすべてのサーバー | 毎回の起動時 |
プロジェクトルート内の clickhouse/config.d/ | このプロジェクト内のすべてのサーバー | 毎回の起動時 |
~/.clickhouse/configs/ | 名前を指定したサーバー | --config NAME 指定時のみ |
あとのレイヤーほど優先され、CLI が管理するデータパスとポートは常に最後に適用されます。local init は clickhouse/config.d/ の雛形を作成し、local clickhouse configs は適用される設定を一覧表示します。
cat > clickhouse/config.d/logging.xml <<'XML'
<clickhouse>
<logger><level>debug</level></logger>
</clickhouse>
XML
clickhousectl local clickhouse start dev詳しくはローカル開発ガイドを参照してください。
パスワードを扱わずに Cloud に接続する
Cloud API が default ユーザーのパスワードを返すのはサービス作成時の 1 回だけです。今回追加された機能により、このパスワードを目にする必要はほとんどなくなります。
ブラウザ経由でサインインする対話型クライアント
cloud clickhouse client は、ネイティブ TLS プロトコル経由で Cloud サービスに対して clickhouse client を開きます。クライアントはブラウザを通じて Cloud ユーザーとしてサインインするため、サービスのパスワードは一切関与しません。ClickHouse 25.12 以降がインストールされている必要があり、-- 以降の引数はそのまま clickhouse client に渡されます。
clickhousectl local install latest
clickhousectl cloud clickhouse client <service-id>
clickhousectl cloud clickhouse client --name analytics -q "SELECT version()" -- --format CSVブラウザでの操作には人が介在する必要があるため、CI やエージェントでは引き続き cloud clickhouse query を使用してください。
.env への接続設定の書き込み
cloud clickhouse create --dotenv は、新規サービスの接続設定とワンタイムパスワードを .env (または指定したファイル) に書き込みます。パスワードの書き込み先はそのファイルだけになります。人間向けの出力にも JSON 出力にも含まれないため、エージェントのコンテキストや実行ログに残ることはありません。
clickhousectl cloud clickhouse create --name analytics \
--ip-allow 203.0.113.10/32 --dotenv .env.local書き込み先のファイルはサービス作成前にチェックされます。作成後に書き込みが失敗した場合は、通常どおりパスワードを表示して終了コード 1 で終了するため、認証情報が失われることはありません。
既存のサービスに対しては、cloud clickhouse dotenv がパスワードを除いた同じ設定を書き込みます。読み取り操作なので、OAuth ログインでも動作します:
clickhousectl cloud clickhouse dotenv <service-id> --localどちらも CLICKHOUSE_HOST、CLICKHOUSE_PORT、CLICKHOUSE_HTTP_PORT、CLICKHOUSE_USER、CLICKHOUSE_SECURE=true を書き込みます。既存のファイルはその場で編集され、該当するキーだけが置き換えられるため、作成時に書き込まれたパスワードはその後に dotenv を実行してもそのまま残ります。
詳しくは Cloud サービスガイドを参照してください。
search でコマンドを探す
エージェントは --help をたどって CLI の使い方を把握しますが、探している機能がコマンドではなくフラグである場合、この方法では見つけられません。たとえば「IP アクセスリスト」は --ip-allow です。新しく追加されたトップレベルの search は、コマンドをパス、フラグ、説明、エージェント向けコンテキストに基づいてランク付けし、それぞれについて一致したフラグを最大 3 件表示します。小規模な同義語テーブルにより、コンソール上の用語が CLI の用語にマッピングされます。
clickhousectl search ip access list
cloud clickhouse create Create a service
--ip-allow Allowed IP/CIDR, optionally IP_OR_CIDR=DESCRIPTION (repeatable)
cloud clickhouse update Update service configuration
--add-ip-allow IP/CIDR to add, optionally IP_OR_CIDR=DESCRIPTION (repeatable)
--remove-ip-allow IP or CIDR to remove from the service allow list (repeatable)
cloud postgres create Create a Postgres service
--ip-allow Allowed IPv4 address or CIDR and ports (repeatable)
...--limit で返されるコマンド数を設定でき (デフォルトは 5)、--json で results 配列が返ります。一致するものがなくても空の配列を返して終了コード 0 で終了します。オフラインで動作し、状態には一切触れません。
シェル補完
コマンドツリーが深いため、0.6.0 では bash、zsh、fish 向けの Tab 補完を追加しました。シェルの起動ファイルに 1 行追加するだけで、clickhousectl と chctl の両方が登録されます:
eval "$(clickhousectl completions bash)" # ~/.bashrc
eval "$(clickhousectl completions zsh)" # ~/.zshrc, after compinit
clickhousectl completions fish | source # ~/.config/fish/config.fish補完の対象はコマンド、フラグ、ローカルサーバー名、Postgres インスタンス名、インストール済みバージョンです。Tab を押すたびにインストール済みの CLI を実行するため、update のあとも常に最新の状態に保たれます。オフラインで動作し、テレメトリは記録しません。
CLI でできなかったことを伝える
テレメトリからわかるのはどのコマンドが実行されたかであり、利用者が何をしようとしていたかではありません。clickhousectl feedback は開発チームに短い自由記述のメッセージを送信するコマンドで、ヘルプ内のエージェント向けコンテキストでも、CLI に必要な機能がなかったときやヘルプの記述で誤解が生じたときにこのコマンドを使うようコーディングエージェントに促しています。
clickhousectl feedback "postgres client should accept a database name"メッセージは最大 500 文字です。CLI のバージョン、OS、アーキテクチャ、コーディングエージェントが検出されたかどうか、有効な認証情報が属する Cloud 組織の ID とあわせて送信されます。氏名、メールアドレス、キー、組織名は一切含まれません。フィードバックは明示的な操作であるため、telemetry disable や DO_NOT_TRACK によってブロックされることはありません。送信される内容の詳細はすべてフィードバックリファレンスに記載されています。
ClickHouse Managed Postgres
Cloud API で Postgres の操作がベータを卒業したことに伴い、cloud postgres から Beta ラベルが外れました。また、このリリースではターミナルから設定できる項目が新しく追加されています。
**Postgres 19。**Postgres 19 が有効になっている組織では、postgres create --pg-version 19 を指定できます。
**AWS PrivateLink 経由のプライベートエンドポイント (ベータ)。**新しい cloud postgres private-endpoint グループは、AWS 上の Postgres サービス向けにエンドポイントサービスを作成し、接続を許可する VPC エンドポイントを承認し、到達を許可する追加リージョンを管理します。API は送信された各リストを丸ごと置き換える仕様のため、update は現在のエンドポイントを読み取り、変更をマージして、変更のあったリストだけを送信します。ある VPC エンドポイントを承認したことで別のエンドポイントの承認が取り消されることはありません。
スタンバイ数。create と update の --standby-count 0|1|2 でホットスタンバイの数を設定します。none では 0、async では 1、sync では 1 または 2 を指定できます。指定された --ha-type が受け付けない数を渡すと、リクエストを送信する前に使い方エラーとして失敗します。スタンバイ数は get と list に表示されます。
削除保護。postgres update --deletion-protection true を実行すると、オフに戻すまでそのサービスに対する delete が API で拒否されるようになります。削除保護が有効になっている組織に適用され、設定の状態は get と list に表示されます。
clickhousectl cloud postgres create --name app-db --region us-east-1 --size <size> \
--pg-version 19 --ha-type sync --standby-count 2
clickhousectl cloud postgres private-endpoint create <postgres-id>
clickhousectl cloud postgres private-endpoint update <postgres-id> \
--add-vpc-endpoint 'vpce-0123456789abcdef0=Production VPC'
clickhousectl cloud postgres update <postgres-id> --deletion-protection trueその他の細かな変更点:
logs、metrics、slow-queries list、slow-queries get、backup listで、サービス ID の代わりに--name <postgres-name>を指定できるようになりました。slow-queries listに、各パターンのデータベース、ユーザー、オペレーション、アプリケーションが表示されるようになりました。これらはslow-queries getで必要になるキーです。logs --severityはリクエスト送信前にサポート対象のレベルと照合されます。config patchとconfig replaceで--file -を指定して標準入力からドキュメントを読み込めるようになりました。--sizeで GCP の新しいローカル SSD サイズを受け付けるようになり、ヘルプにプロバイダーごとの小規模なサイズが記載されました。switchoverのヘルプに動作内容の説明が追加されました。新しくプロビジョニングされたサーバーへプライマリを移動することで、HA なしのサービスでも動作します。
詳しくは ClickHouse Managed Postgres ガイドを参照してください。
ClickHouse サービスの設定
削除保護。clickhouse create --deletion-protection で有効にするか、あとから clickhouse update --deletion-protection true|false で変更できます。保護されたサービスに対して clickhouse delete を実行するとエラーコード deletion_protected で拒否され、エラーの command フィールドには保護を解除するための update コマンドが入ります。--force を付けた場合も停止前にサービスがチェックされるため、保護されたサービスが停止されることもありません。
clickhousectl cloud clickhouse create --name prod --deletion-protection
clickhousectl cloud clickhouse update <service-id> --deletion-protection false
clickhousectl cloud clickhouse delete <service-id>**JWT 認証プロバイダー (ベータ)。**Enterprise ティアでは、cloud clickhouse jwt-provider を使って、お使いの ID プロバイダーが発行した JWT でサービスにサインインできるようになります。トークンの保持者には、トークンのロールクレームに記載された ClickHouse ロールが付与されます。update は設定全体を置き換えるため、維持したい場合は --roles-claim を再度渡してください。
clickhousectl cloud clickhouse jwt-provider create <service-id> corp-sso \
--issuer https://auth.example.com --audience analytics \
--jwks-url https://auth.example.com/.well-known/jwks.json \
--roles-claim clickhouse:roles**インスタンスプロファイル。**Enterprise および BYOC の組織では、clickhouse scale --profile でインスタンスプロファイルを変更できます。利用可能なプロファイルは clickhouse profile list で確認できます。
任意のリージョン指定。clickhouse create --region が任意のリージョン ID を受け付け、バリデーションを Cloud 側に委ねるようになりました。これにより、公開リストにないプライベートリージョンもパブリックリージョンと同じように扱えます。Cloud がリージョンを拒否した際、既知のリージョンに綴りの近いものがあればエラーメッセージで提示されます。この用途で 0.5.1 に追加された --custom-region は --region の非推奨エイリアスとなり、1.0.0 で削除される予定です。
このほか、clickhouse delete --force は停止を最大 10 分待ち、タイムアウトした場合は何も削除しないようになりました。また、backup list でサービス ID の代わりに --name <service-name> を指定できるようになりました。
詳しくは Cloud サービスガイドを参照してください。
ClickPipes
これまで Kafka、Kinesis、オブジェクトストレージ、Pub/Sub のパイプを作成する際は、検出されたフィールドを 1 つずつ手作業で --column フラグに書き写す必要がありました。今回、これら 4 種類の create で --columns-from <PATH|-> を指定できるようになり、clickpipe schema-discover --json の出力をそのまま読み込めるようになりました。ソースの各フィールドに加え、デフォルトで無効化されていないすべてのメタデータフィールドが宛先カラムになり、型も検出されたとおりに使われます。
clickhousectl cloud clickpipe schema-discover object-storage <service-id> \
--storage-type s3 --source-url 'https://example-bucket.s3.amazonaws.com/events/**' \
--format JSONEachRow --iam-role "$S3_IAM_ROLE_ARN" --json > discovery.json
clickhousectl cloud clickpipe create object-storage <service-id> \
--name events-snapshot --storage-type s3 \
--source-url 'https://example-bucket.s3.amazonaws.com/events/**' \
--format JSONEachRow --iam-role "$S3_IAM_ROLE_ARN" \
--database default --table events \
--columns-from discovery.json --start-paused不要なフィールドを除外したい場合は先に discovery.json を編集し、カラムを追加したい場合は --column を併用してください。--columns-from - は標準入力を読み取るため、ディスカバリの出力をそのままパイプで create に渡せます。また、schema-discover に Virtual カラムと Disabled By Default カラムが新しく追加され、_topic や _path など ClickPipes が付与するメタデータフィールドがどれであるか判別できるようになりました。
新しいオプション:
- MongoDB:
--table-mapping-jsonでmongoConfigを指定できるようになりました。{"persistDeletedDocuments": true}を指定すると、削除されたドキュメントの_idだけでなく、削除直前のドキュメント全体が保持されます。 - Postgres と MySQL:
--use-json-native-format trueを指定すると、JSON カラムがStringではなく ClickHouse ネイティブのJSON型として保存されます。作成時にのみ選択でき、組織側でこの機能が有効になっている必要があります。 - オブジェクトストレージ: TabSeparated 形式向けに
createとschema-discoverで--skip-first-lines <N>を、createとsettings updateで--object-storage-max-file-size <BYTES>を指定できるようになりました。 - リバースプライベートエンドポイント:
VPC_ENDPOINT_SERVICEに対して--custom-private-dns-mapping NAME=TARGET_IDを指定できるようになりました。ターゲットにはuse1-az1のようなアベイラビリティゾーン ID を指定します。 clickpipe listと--nameによる検索がすべてのページをたどるようになり、新しいフラグを付けなくても全パイプを参照できるようになりました。
また、リクエスト送信前により多くのミスを検出するようになり、コマンドの実行結果もより明確に伝わるようになりました:
- Kafka の作成とスキーマディスカバリでは認証が必須になり、Kafka、Kinesis、Pub/Sub の作成ではカラム指定が必須になりました。これらは従来から API 側で常に拒否されていたリクエストですが、ローカルで使い方エラーとして失敗するようになりました。
- 認証情報を読み取る前に、各ソースのフラグがチェックされるようになりました。
- API が開始リクエストを受け付けたものの適用しなかった場合、
clickpipe startは専用のエラーコード (clickpipe_still_pausing、clickpipe_start_not_applied、またはCompleted状態のパイプに対するclickpipe_start_no_effect) を返して終了コード 1 で終了します。 cdc-scaling updateは--cpu-millicoresと--memory-gbの両方を必須とし、変更が完了したのではなく受け付けられたことを示すメッセージを出力します。- パイプ全体の更新ではルートの
settingsオブジェクトが適用されないため、clickpipe updateはこれを拒否するようになりました。代わりにclickpipe settings updateを使用してください。
詳しくは ClickPipes ガイドおよび ClickPipe 設定リファレンスを参照してください。
ClickStack
ダッシュボードとアラートで PromQL チャートを扱えるようになりました。dashboard create、update、validate、およびインラインのアラートチャートにおいて、チャート設定の configType を promql にすると、種別が promql のソースに対して expressions をクエリできます。0.5.0 では、API に到達する前に CLI 側のチャートチェックがこれを拒否していました。
alert list にサーバーサイドのフィルタ --tag、--search、--source、--state が追加されました。同じフラグを繰り返し指定すると、複数の値のいずれかに一致するものを絞り込めます。
clickhousectl cloud clickstack alert list <service-id> --state ALERT --state PENDING --tag checkoutsource create|update --file において、ログソースで OpenTelemetry の eventNameExpression フィールドと severityNumberExpression フィールドを、メトリクスソースおよび PromQL ソースで minAutoGranularity を指定できるようになりました。
CLI は引き続き --file のボディに含まれる未知のキーを送信前に拒否しますが、値の検証は API に委ねるようになりました。ClickStack に新しいチャート種別や列挙値が追加された際、CLI の新リリースを待たずにそのまま利用できます。
詳しくは ClickStack ガイドを参照してください。
組織と BYOC
ベータ版のコマンドグループが新しく追加されました:
cloud org byoc accessは、ClickHouse の担当者が BYOC インフラストラクチャにアクセスできるタイミングを制御します。--mode alwaysで常時許可、--mode neverで拒否、--mode windowで--startから--duration秒間だけ許可します。cloud org previewは、組織に提供されているプレビュー機能を一覧表示し、オン・オフを切り替えます。cloud member notification-settingsは、ロールのデフォルト通知設定に対するメンバー個人の上書き設定を一覧表示し、フラグまたは--fileのボディから更新します。
clickhousectl cloud org byoc access update <byoc-id> --mode window \
--start 2026-11-10T09:00:00Z --duration 14400
clickhousectl cloud org preview list
clickhousectl cloud member notification-settings update <user-id> --effect disabled \
--notification service_backup_failed --resource <service-id> --channel emailcloud org role list とロール名による検索がすべてのページをたどるようになり、ロールが 250 件を超える組織でも漏れなく取得できるようになりました。cloud activity list はデフォルトで直近 7 日間を返すようになりました。アクティビティの多い組織で全履歴を返すと、エージェントのコンテキストを圧迫してしまうためです。それより前のエントリを取得するには --from-date を渡してください。--to-date は指定した当日を含むようになりました。
自動化とエージェントを見据えた設計
非同期コマンドがポーリング対象を明示
Cloud への非同期の書き込みコマンドは、API がリクエストを受け付けた時点で制御を返します。エージェントはドキュメント内の完了条件の表をほとんど読まないため、何をポーリングすべきか推測していました。こうしたコマンドの --json 出力には、解決済みの読み取りコマンド、確認すべきフィールド、完了または失敗を表す値が入った next オブジェクトが含まれるようになりました:
"next": {
"command": "clickhousectl cloud clickhouse get 1234-... --org-id 5678-... --json",
"field": "state",
"until": ["running"],
"fail_on": ["failed"],
"interval_seconds": 5
}command をそのまま実行し、field の値が until のいずれかになった時点で停止してください。対象は、ClickHouse サービスの作成・開始・ウェイク・停止・削除、Postgres の作成・リストア・リードレプリカ作成・リサイズ・昇格、ClickPipe の開始・停止・再同期、CDC スケーリング、リバースプライベートエンドポイントの作成です。Postgres のスイッチオーバーや HA の変更など、確実な完了シグナルがないコマンドには next が付かないため、それらで何を確認すべきかは自動化リファレンスに記載されています。
条件分岐に使える終了コードとエラーコード
- **403 が認証エラーとして扱われなくなりました。**これまで Cloud API の 403 はすべて
auth_requiredとともに終了コード 4 で終了していたため、クォータやポリシーによる拒否であっても、エージェントは有効なキーを持っているのに再ログインを試みていました。今後 403 はhttp_4xxとサーバーのメッセージを返して終了コード 1 で終了します。終了コード 4 は 401、認証情報の欠落、認証情報チェックの拒否に対して引き続き使われます。 - **不正な入力は常に終了コード 2 で終了します。**これまで、パース後にチェックされるものの決して成功し得ない入力 (未知の
--provider、形式の誤った--ip-allow、未知のフィールドを含む--fileボディなど) は終了コード 1 で終了していました。未設定のシェル変数などでよく起きる空のリソース ID も使い方エラーとなり、リクエストは送信されません。 - **
resource_not_foundが文字どおりの意味になりました。**ID または--nameで指定したリソースが存在しない場合に一貫してこのコードが返され、commandフィールドにはそのスコープ内に実際に存在するリソースを確認するためのコマンドが入ります。まだ存在するサービスに対する削除が API に拒否された場合はhttp_4xxが返されます。 - エラーが問題箇所を具体的に示すようになりました。
--fileが読み取れない場合はフラグ名とパスを示します。ボディの構造が誤っている場合は、policies[0].permissions[0]のように問題のある値の JSON パスを示します。ヘルプには--fileボディのフィールド一覧が表示され、列挙値のエラーでは指定可能な値が列挙されます。 - 統一された JSON エラーエンベロープ。
updateとskillsの失敗時、およびauth login、logout、signupも JSON モードに従うようになりました。ローカルエラーではmessageに clickhousectl 自身の要約を入れ、外部プログラム (ClickHouse、Docker、OS) からの出力テキストはdetailsに入れます。
その他の細かな変更点
- コーディングエージェントが検出された環境でも、
CLICKHOUSECTL_AUTO_JSON=0を設定すると人間向けの出力を維持できます。明示的に--jsonを指定した場合はそちらが優先されます。 - リサイズ、HA、CDC スケーリングの更新では、変更が完了したのではなく受け付けられたことを示すメッセージが出力されます。
-で始まるページネーションカーソルを受け付けるようになり、ヒントが提示するすべてのlistコマンドはパース可能かどうか検証されています。
検証付きのインストールとより安全なアップデート
これまで、インストールスクリプト、npm の postinstall、update はいずれも単一のダウンロードパスへの TLS 通信を信頼するのみで、バイナリ自体の検証は行っていませんでした。v0.6.0 からは、すべてのリリースでアーカイブに対する SHA256SUMS ファイルと GitHub のビルド来歴証明 (attestation) を公開します。アーカイブは builds.clickhouse.com から配信され、SHA256SUMS は GitHub リリースから読み取られるため、アーカイブを配信するサーバー自身がその正当性を保証する構造にはなりません。
| インストール経路 | 検証内容 |
|---|---|
| インストールスクリプト | アーカイブを GitHub リリースの SHA256SUMS と照合。不一致の場合は何もインストールしない |
clickhousectl update | 展開前に同じ照合を実施。不一致の場合はインストール済みバイナリをそのまま維持 |
| npm | 公開時に npm パッケージへ埋め込まれた SHA256SUMS とアーカイブを照合 |
| pip、uv、pipx | 個別のダウンロードはなし。バイナリは PyPI が配信する wheel 内に同梱 |
cargo install | crates.io のソースからビルド。Cargo がインデックスのチェックサムと照合 |
アーカイブがこのリポジトリのリリースワークフローによってビルドされたことを確認するには、GitHub CLI で証明を検証してください:
gh attestation verify "clickhousectl-${TARGET}-${VERSION}.tar.gz" -R ClickHouse/clickhousectlupdate 自体の安全性も高まっています:
- npm、pip、uv、pipx が管理しているバイナリの上書きを拒否し、該当パッケージマネージャーのアップグレードコマンドを表示します。
- 新しいバイナリで
--versionが正常に実行できたことを確認してからバイナリを入れ替えます。失敗した場合は古いバイナリがそのまま残ります。 - 最新バージョンの解決先が builds.clickhouse.com になりました。0.5.0 では未認証リクエストが IP あたり毎時 60 回に制限されている GitHub API に問い合わせていたため、
updateが403 rate limit exceededで失敗することがありました。0.5.x でこのエラーに遭遇した場合は、インストールスクリプトを再実行してください。 - バックグラウンドのアップデート確認は
CLICKHOUSECTL_NO_UPDATE_CHECK=1でオフにできます。--versionがネットワーク待ちで最大 10 秒ブロックすることはなくなり、確認に失敗した場合の再試行間隔も 1 日後から 1 時間後に短縮されました。
詳しくはリリース検証を参照してください。
認証
OAuth ログインが認可サーバーに紐づけられます。 cloud auth login は認可サーバーの設定をトークンと一緒に保存するようになり、以降のリフレッシュではその保存済み設定が使われます。0.5.x で保存されたログインにはこの設定が含まれないため、auth status では OAuth が Login required と表示され、Cloud コマンドは再ログインを促すメッセージを出して終了コード 4 で終了します。アップグレード後に一度 clickhousectl cloud auth login を実行してください。
保存済みの API キーは、保存対象の API に対してのみ機能します。 auth login --api-key で --url を指定して本番以外の API に対してキーを検証すると、その API もキーと一緒に保存されます。後から別の API を指定してコマンドを実行すると、キーを送信せずに終了コード 4 で終了します。
保存済み認証情報はフェイルクローズで動作します。 credentials.json が存在するのに読み取れない場合、Cloud コマンドはそのファイル名を示したエラーを出して停止します。意図していない環境変数や OAuth の認証情報へ CLI がそのままフォールバックすることはなくなりました。リフレッシュできない OAuth ログインは、以前は削除されていましたが、保持されたまま Expired として報告されるようになります。トークンはアトミックに書き込まれ、リフレッシュはロックされるため、2 つのコマンドが同時に実行されてもファイルが破損することはありません。
保存済みのクエリキーは廃止されました。 0.5.0 以降、cloud clickhouse query は有効な API キーを対象サービスの Query API エンドポイントにバインドしています。0.6.0 では、以前のバージョンが作成・保存していたサービス単位の古いキーの使用を終了します (キー自体は組織内に残っています)。あわせて repair-query-key も削除されます。残っているレコードは、そのサービスに対する次回のクエリまたは削除時に消去され、そこに記録されていたキーに対する cloud key delete コマンドが CLI に表示されます。読み取り専用の API キーは自身をバインドできないため、query_key_bind_forbidden エラーとともに、書き込み権限を持つキーでバインドするためのコマンドを表示して失敗するようになりました。
その他、認証情報から複数の組織にアクセスでき、どれを使うか指定されていない場合、コマンドは終了コード 2 で終了し、各組織の ID と名前を一覧表示します。--org-name が複数の組織に一致した場合は、--org-id に渡すための ID が一覧表示されます。また、CLICKHOUSECTL_AUTH_URL と CLICKHOUSECTL_CLIENT_ID を設定することで、OAuth デバイスフローからカスタム API ターゲットに対してサインインできるようになりました。
詳しくは認証リファレンスを参照してください。
ローカル開発の改善
自分でコンパイルした ClickHouse ビルドを実行できます。 local install --binary <PATH> を実行すると、指定したファイルが ~/.clickhouse/versions/ にコピーされ、そのコピーに対して --version を実行して返ってきたバージョン名でインストールされます。インストール後は、local use、clickhouse start --version、local remove で他のインストールと同じように扱えます。再ビルド後に置き換える場合は --force を渡してください。
clickhousectl local install --binary ~/ClickHouse/build/programs/clickhouseその他、一連の修正も行われています:
- 停止したサーバーは、前回実行していたバージョンで再起動するようになりました。以前は
stopが記録されたバージョンを消去していたため、その後に--versionを付けずにstartを実行するとデータディレクトリがデフォルトバージョンで起動され、暗黙のうちにアップグレードまたはダウングレードされていました。 - サーバー名を受け取るコマンドで名前を省略した場合、選択ルールが一本化されました。
defaultという名前のサーバーがあればそれを選び、なければプロジェクト内にそのエンジンのサーバーが 1 台だけある場合にそれを選びます。複数ありdefaultがない場合は、server_selection_requiredで失敗して名前の一覧を表示します。removeは推測を行いません。 listなどの読み取り専用コマンドがカレントディレクトリに.clickhouse/を作成しなくなりました。- ポートチェックがワイルドカードおよび
::1のリスナーを検出し、ポート 0 や HTTP と TCP で同一のポート番号を拒否するようになりました。また、ポートを省略した場合にもう一方のリスナーが使用中のポートが選ばれることはなくなりました。 - サーバープロセスの検索が
pgrep、ps、lsofを使わずネイティブに行われるようになり、保存されている PID も ClickHouse サーバーであることが確認されてから信頼されるようになりました。 local clickhouse stop、remove、local removeで Docker が不要になりました。- Intel macOS でバージョンを厳密指定したインストールが再び動作するようになりました。
dotenvが$やその他のシェル特殊文字を含む値をクォートするようになりました。
ローカルの Postgres についても以下の変更があります:
local postgres clientは、最初に失敗したステートメントでスクリプトを停止し、終了コード 3 で終了するようになりました。以前は--queries-fileやパイプで渡したスクリプトが失敗しても、エラーを表示して終了コード 0 で終了していました。残りのステートメントも実行したい場合は-- -v ON_ERROR_STOP=0を渡してください。- 新規コンテナは
clickhousectl-pg-<project hash>-<name>-<major>という名前になるため、2 つのプロジェクトで同じインスタンス名を使えるようになりました。既存のコンテナの名前はそのまま維持されます。 - 再開しようとしたインスタンスのポートがすでに使用されている場合、
port_in_useで失敗するようになりました。すでに停止しているインスタンスの停止は成功し、already_stoppedを報告します。
詳しくはローカル開発ガイドを参照してください。
コマンド名の変更
local server は local clickhouse に、cloud service は cloud clickhouse に変更され、両エンジンの短縮エイリアスとして ch と pg が用意されました。旧コマンド名も引き続き動作します。ローカルでは、各エンジンの list と stop-all はそのエンジンのみを対象とするようになり、local status で両方が表示されます。
アップグレード時の注意点
リネームされたコマンドは旧表記も維持されているため、ほとんどのスクリプトはそのまま動作し続けます。以下の変更については、対応が必要になるか、既存スクリプトから見える挙動が変わります。
破壊的変更
| 変更点 | 0.5.x | 0.6.0 |
|---|---|---|
| 以前のバージョンで保存された OAuth ログインが使用不可に | 保存済みログインをリフレッシュして使用 | auth status に Login required と表示。clickhousectl cloud auth login を一度実行してください |
local server list と local server stop-all の対象が ClickHouse のみに | いずれも ClickHouse と Postgres の両方を一覧表示・停止 | 両エンジンの一覧表示は local status、Postgres の停止は local postgres stop-all |
repair-query-key の削除、およびサービス単位で保存されていたクエリキーの廃止 | cloud service repair-query-key <id> | クエリは有効な API キーをバインド。残っている clickhousectl-query-<service-name> キーは cloud key delete で削除してください |
| Kafka ClickPipe の作成とディスカバリで認証が必須に。Kafka、Kinesis、Pub/Sub の作成でカラム指定が必須に | リクエスト送信後に API が拒否 (終了コード 1) | リクエスト送信前に使い方エラー (終了コード 2)。--auth または認証情報フラグ、および --column または --columns-from を渡してください |
ローカルコマンドの JSON project_scope | parent_projects_searched が存在 | kind は project_root、current_directory、env_override のいずれか。parent_projects_searched は削除 |
挙動の変更
| 変更点 | 0.5.x | 0.6.0 |
|---|---|---|
| プロジェクトスコープ | カレントディレクトリそのもの | カレントディレクトリからホームディレクトリまで親をたどって最も近い .clickhouse/。共有の親ディレクトリにある .clickhouse/ が配下ディレクトリのプロジェクトになるため、各プロジェクトで local init を実行してください |
| 認証情報に起因しない Cloud API の 403 | 終了コード 4、auth_required | 終了コード 1、http_4xx |
| パース後に見つかった不正な入力 | 終了コード 1、コード other | 終了コード 2、使い方エラー |
ファイルまたはパイプ入力のスクリプトを使った local postgres client | ステートメントが失敗しても続行し、終了コード 0 で終了 | 最初に失敗したステートメントで停止し、終了コード 3 で終了 |
日付指定なしの cloud activity list | 全履歴 | 直近 7 日間。それ以前を取得するには --from-date を渡してください |
npm、pip、uv、pipx でインストールされた環境での clickhousectl update | パッケージ管理下のバイナリを上書き | 拒否し、パッケージマネージャーのアップグレードコマンドを表示 |
サービス作成時の --custom-region | CLI が認識していないリージョンを送信 | --region の非推奨エイリアスとなり、1.0.0 で削除予定 |
スクリプトまたは update による v0.6.0 より前のリリースのインストール | チェックサムなしでインストール | 該当リリースには SHA256SUMS がないため拒否 |
Rust API ライブラリ
clickhousectl は、CLI と歩調を合わせてリリースされる ClickHouse Cloud API 向けの型付き Rust クライアント clickhouse-cloud-api の上に構築されています。0.6.0 からは、アップグレード時に呼び出し側の Rust コードで何を変更すべきかを記載した CHANGELOG が用意されました。今回のリリースにおける主な変更点は次のとおりです:
- タイムスタンプフィールドが
chronoの型からjiff::Timestampになりました。通信上の形式はこれまでどおり UTC の RFC 3339 です。 - 必須フィールドを持つリクエスト構造体は
Defaultを実装しなくなりました。API 側で新たに必須となったフィールドが..Default::default()によって暗黙のうちに埋められてしまうのを防ぐためです。 - クレートが
reqwestを再エクスポートするようになり、事前構築した HTTP クライアントでライブラリと同じバージョンを使えるようになりました。
謝辞
カスタム API ターゲットに対する OAuth デバイスログインを追加してくれた Emanuele De Cupis (#1082)、Postgres から Beta ラベルを外してくれた @divyenduz (#1382)、そして Postgres 19 を追加してくれた Andrey Chudnovskiy (#1462) に感謝します。



