---
title: "clickhousectl v0.6.0 の新機能"
date: "2026-11-20T06:06:40.398Z"
author: "Al Brown"
category: "Product"
excerpt: "clickhousectl v0.6.0 では、Git と同じ方法でプロジェクトを検出し、パスワードなしで Cloud に接続できます。検索、シェル補完、フィードバック機能を追加したほか、すべてのインストールを検証します。"
---

# clickhousectl v0.6.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.5.0](https://clickhouse.com/ja/blog/clickhousectl-v0-5-0-jp) では 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 ログインは一度ログインし直す必要があります。[アップグレードに関する注意点](#upgrade-notes)を参照してください。

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

```bash
clickhousectl update
```

まだの場合は、以下のいずれか好みの方法でインストールしてください:

```bash
curl https://clickhouse.com/cli | sh
pip install clickhousectl
uv tool install clickhousectl
npm i -g clickhousectl
cargo install clickhousectl
```

## Git のように扱えるプロジェクト

0.5.x では、プロジェクト単位のコマンドはカレントディレクトリそのものを基準にしていました。プロジェクトルートでサーバーを起動したあと `src/` に `cd` すると、CLI からはそのサーバーが見えなくなっていました。0.6.0 では、`.git/` を含むディレクトリが Git のリポジトリルートになるのと同じように、`.clickhouse/` を含むディレクトリがプロジェクトルートになります。

プロジェクトのディレクトリで一度 `clickhousectl local init` を実行してください。以降、ローカルサーバー、Postgres インスタンス、保存済み API キー、UDF のソース、`.env` のフォバックはすべて、そのディレクトリまたは配下の任意のサブディレクトリから解決されます。

```bash
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` を設定するとディレクトリの探索はスキップされます:

```bash
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` は適用される設定を一覧表示します。

```bash
cat > clickhouse/config.d/logging.xml <<'XML'
<clickhouse>
    <logger><level>debug</level></logger>
</clickhouse>
XML
clickhousectl local clickhouse start dev
```

詳しくは[ローカル開発ガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/local-development.md)を参照してください。

## パスワードを扱わずに Cloud に接続する

Cloud API が `default` ユーザーのパスワードを返すのはサービス作成時の 1 回だけです。今回追加された機能により、このパスワードを目にする必要はほとんどなくなります。

### ブラウザ経由でサインインする対話型クライアント

`cloud clickhouse client` は、ネイティブ TLS プロトコル経由で Cloud サービスに対して `clickhouse client` を開きます。クライアントはブラウザを通じて Cloud ユーザーとしてサインインするため、サービスのパスワードは一切関与しません。ClickHouse 25.12 以降がインストールされている必要があり、`--` 以降の引数はそのまま `clickhouse client` に渡されます。

```bash
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 出力にも含まれないため、エージェントのコンテキストや実行ログに残ることはありません。

```bash
clickhousectl cloud clickhouse create --name analytics \
  --ip-allow 203.0.113.10/32 --dotenv .env.local
```

書き込み先のファイルはサービス作成前にチェックされます。作成後に書き込みが失敗した場合は、通常どおりパスワードを表示して終了コード 1 で終了するため、認証情報が失われることはありません。

既存のサービスに対しては、`cloud clickhouse dotenv` がパスワードを除いた同じ設定を書き込みます。読み取り操作なので、OAuth ログインでも動作します:

```bash
clickhousectl cloud clickhouse dotenv <service-id> --local
```

どちらも `CLICKHOUSE_HOST`、`CLICKHOUSE_PORT`、`CLICKHOUSE_HTTP_PORT`、`CLICKHOUSE_USER`、`CLICKHOUSE_SECURE=true` を書き込みます。既存のファイルはその場で編集され、該当するキーだけが置き換えられるため、作成時に書き込まれたパスワードはその後に `dotenv` を実行してもそのまま残ります。

詳しくは [Cloud サービスガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/cloud-service.md)を参照してください。

## `search` でコマンドを探す

エージェントは `--help` をたどって CLI の使い方を把握しますが、探している機能がコマンドではなくフラグである場合、この方法では見つけられません。たとえば「IP アクセスリスト」は `--ip-allow` です。新しく追加されたトップレベルの `search` は、コマンドをパス、フラグ、説明、エージェント向けコンテキストに基づいてランク付けし、それぞれについて一致したフラグを最大 3 件表示します。小規模な同義語テーブルにより、コンソール上の用語が CLI の用語にマッピングされます。

```bash
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` の両方が登録されます:

```bash
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 に必要な機能がなかったときやヘルプの記述で誤解が生じたときにこのコマンドを使うようコーディングエージェントに促しています。

```bash
clickhousectl feedback "postgres client should accept a database name"
```

メッセージは最大 500 文字です。CLI のバージョン、OS、アーキテクチャ、コーディングエージェントが検出されたかどうか、有効な認証情報が属する Cloud 組織の ID とあわせて送信されます。氏名、メールアドレス、キー、組織名は一切含まれません。フィードバックは明示的な操作であるため、`telemetry disable` や `DO_NOT_TRACK` によってブロックされることはありません。送信される内容の詳細はすべて[フィードバックリファレンス](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/feedback.md)に記載されています。

## 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` に表示されます。

```bash
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 ガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/managed-postgres.md)を参照してください。

## ClickHouse サービスの設定

**削除保護。**`clickhouse create --deletion-protection` で有効にするか、あとから `clickhouse update --deletion-protection true|false` で変更できます。保護されたサービスに対して `clickhouse delete` を実行するとエラーコード `deletion_protected` で拒否され、エラーの `command` フィールドには保護を解除するための `update` コマンドが入ります。`--force` を付けた場合も停止前にサービスがチェックされるため、保護されたサービスが停止されることもありません。

```bash
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` を再度渡してください。

```bash
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 サービスガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/cloud-service.md)を参照してください。

## ClickPipes

これまで Kafka、Kinesis、オブジェクトストレージ、Pub/Sub のパイプを作成する際は、検出されたフィールドを 1 つずつ手作業で `--column` フラグに書き写す必要がありました。今回、これら 4 種類の `create` で `--columns-from <PATH|->` を指定できるようになり、`clickpipe schema-discover --json` の出力をそのまま読み込めるようになりました。ソースの各フィールドに加え、デフォルトで無効化されていないすべてのメタデータフィールドが宛先カラムになり、型も検出されたとおりに使われます。

```bash
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 ガイド](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

ダッシュボードとアラートで PromQL チャートを扱えるようになりました。`dashboard create`、`update`、`validate`、およびインラインのアラートチャートにおいて、チャート設定の `configType` を `promql` にすると、種別が `promql` のソースに対して `expressions` をクエリできます。0.5.0 では、API に到達する前に CLI 側のチャートチェックがこれを拒否していました。

`alert list` にサーバーサイドのフィルタ `--tag`、`--search`、`--source`、`--state` が追加されました。同じフラグを繰り返し指定すると、複数の値のいずれかに一致するものを絞り込めます。

```bash
clickhousectl cloud clickstack alert list <service-id> --state ALERT --state PENDING --tag checkout
```

`source create|update --file` において、ログソースで OpenTelemetry の `eventNameExpression` フィールドと `severityNumberExpression` フィールドを、メトリクスソースおよび PromQL ソースで `minAutoGranularity` を指定できるようになりました。

CLI は引き続き `--file` のボディに含まれる未知のキーを送信前に拒否しますが、値の検証は API に委ねるようになりました。ClickStack に新しいチャート種別や列挙値が追加された際、CLI の新リリースを待たずにそのまま利用できます。

詳しくは [ClickStack ガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/clickstack.md)を参照してください。

## 組織と BYOC

ベータ版のコマンドグループが新しく追加されました:

- `cloud org byoc access` は、ClickHouse の担当者が BYOC インフラストラクチャにアクセスできるタイミングを制御します。`--mode always` で常時許可、`--mode never` で拒否、`--mode window` で `--start` から `--duration` 秒間だけ許可します。
- `cloud org preview` は、組織に提供されているプレビュー機能を一覧表示し、オン・オフを切り替えます。
- `cloud member notification-settings` は、ロールのデフォルト通知設定に対するメンバー個人の上書き設定を一覧表示し、フラグまたは `--file` のボディから更新します。

```bash
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 email
```

`cloud org role list` とロール名による検索がすべてのページをたどるようになり、ロールが 250 件を超える組織でも漏れなく取得できるようになりました。`cloud activity list` はデフォルトで直近 7 日間を返すようになりました。アクティビティの多い組織で全履歴を返すと、エージェントのコンテキストを圧迫してしまうためです。それより前のエントリを取得するには `--from-date` を渡してください。`--to-date` は指定した当日を含むようになりました。

## 自動化とエージェントを見据えた設計

### 非同期コマンドがポーリング対象を明示

Cloud への非同期の書き込みコマンドは、API がリクエストを受け付けた時点で制御を返します。エージェントはドキュメント内の完了条件の表をほとんど読まないため、何をポーリングすべきか推測していました。こうしたコマンドの `--json` 出力には、解決済みの読み取りコマンド、確認すべきフィールド、完了または失敗を表す値が入った `next` オブジェクトが含まれるようになりました:

```json
"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` が付かないため、それらで何を確認すべきかは[自動化リファレンス](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/automation.md)に記載されています。

### 条件分岐に使える終了コードとエラーコード

- **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 で証明を検証してください:

```bash
gh attestation verify "clickhousectl-${TARGET}-${VERSION}.tar.gz" -R ClickHouse/clickhousectl
```

`update` 自体の安全性も高まっています:

- 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 時間後に短縮されました。

詳しくは[リリース検証](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/install-verification.md)を参照してください。

## 認証

**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 ターゲットに対してサインインできるようになりました。

詳しくは[認証リファレンス](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/authentication.md)を参照してください。

## ローカル開発の改善

**自分でコンパイルした ClickHouse ビルドを実行できます。** `local install --binary <PATH>` を実行すると、指定したファイルが `~/.clickhouse/versions/` にコピーされ、そのコピーに対して `--version` を実行して返ってきたバージョン名でインストールされます。インストール後は、`local use`、`clickhouse start --version`、`local remove` で他のインストールと同じように扱えます。再ビルド後に置き換える場合は `--force` を渡してください。

```bash
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` を報告します。

詳しくは[ローカル開発ガイド](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/local-development.md)を参照してください。

## コマンド名の変更

`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`](https://crates.io/crates/clickhouse-cloud-api) の上に構築されています。0.6.0 からは、アップグレード時に呼び出し側の Rust コードで何を変更すべきかを記載した [CHANGELOG](https://github.com/ClickHouse/clickhousectl/blob/main/crates/clickhouse-cloud-api/CHANGELOG.md) が用意されました。今回のリリースにおける主な変更点は次のとおりです:

- タイムスタンプフィールドが `chrono` の型から `jiff::Timestamp` になりました。通信上の形式はこれまでどおり UTC の RFC 3339 です。
- 必須フィールドを持つリクエスト構造体は `Default` を実装しなくなりました。API 側で新たに必須となったフィールドが `..Default::default()` によって暗黙のうちに埋められてしまうのを防ぐためです。
- クレートが `reqwest` を再エクスポートするようになり、事前構築した HTTP クライアントでライブラリと同じバージョンを使えるようになりました。

## 謝辞

カスタム API ターゲットに対する OAuth デバイスログインを追加してくれた [Emanuele De Cupis](https://github.com/balanza) ([#1082](https://github.com/ClickHouse/clickhousectl/pull/1082))、Postgres から Beta ラベルを外してくれた [@divyenduz](https://github.com/divyenduz) ([#1382](https://github.com/ClickHouse/clickhousectl/pull/1382))、そして Postgres 19 を追加してくれた [Andrey Chudnovskiy](https://github.com/achudnovskij) ([#1462](https://github.com/ClickHouse/clickhousectl/pull/1462)) に感謝します。