ClickHouse Cloud へのデプロイ

このスキルは clickhousectl を使用した ClickHouse Cloud へのデプロイを案内します。アカウント設定、CLI認証、サービス作成、スキーママイグレーション、およびアプリケーション接続をカバーします。以下のステップを順に実行してください。

適用する場合

ユーザーが以下を希望する場合、このスキルを使用します:

• ClickHouse アプリケーションを本番環境にデプロイする
• ClickHouse をマネージドクラウドサービスとしてホストする
• ローカル ClickHouse セットアップから ClickHouse Cloud に移行する
• ClickHouse Cloud サービスを作成する
• ClickHouse Cloud を初めてセットアップする

---

ステップ 1: ClickHouse Cloud にサインアップ

クラウドコマンドを使用する前に、ユーザーは ClickHouse Cloud アカウントが必要です。

ユーザーに質問してください: 「ClickHouse Cloud アカウントをお持ちですか?」

アカウントを持っていない場合、以下を説明します:

ClickHouse Cloud は完全にマネージされたサービスで、ClickHouse を実行します — インフラストラクチャの保守は不要で、自動スケーリング、バックアップ、アップグレードが含まれています。無料試用版があるため、クレジットカードなしで開始できます。

アカウントを作成するには、以下にアクセスしてください: https://clickhouse.cloud

メール、Google、または GitHub アカウントでサインアップしてください。コンソールにログインしたら、お知らせください。次のステップに進みます。

ユーザーがサインアップしたか、既にアカウントを持っていることを確認してから、先に進んでください。

---

ステップ 2: CLI を認証

まず、clickhousectl がインストールされていることを確認します。以下で確認します:

which clickhousectl

見つからない場合、インストールします:

curl -fsSL https://clickhouse.com/cli | sh

次に認証します。状況に応じて 2 つのオプションから選択してください:

重要: OAuth ログインは読み取り専用です。 ブラウザログイン (オプション A) は読み取り専用アクセスを付与します — 組織、サービス、既存のサービスをリスト表示できますが、サービスの作成、変更、削除はできません。破壊的または変更を加えるクラウド操作 (サービス作成、削除、スケーリングなど) には、API キー認証 (オプション B) が必須です。このワークフローにクラウドリソースの作成または変更が含まれる場合、オプション B を使用する必要があります。

オプション A: ブラウザログイン (読み取り専用アクセス)

ブラウザを開くことができるユーザーがいる場合、および既存のクラウドリソースの検査のみが必要な場合 (組織のリスト表示、サービスのリスト表示、データのクエリ) に使用します。OAuth デバイスフローを使用します — API キーは必要ありません。

ユーザーに以下を実行するよう指示します:

clickhousectl cloud login

これは URL とコードを出力します。ユーザーはブラウザで URL を開き、コードを確認して、ClickHouse Cloud アカウントでログインします。ブラウザフローが完了すると、CLI は自動的に認証情報を受け取ります。

これは読み取り専用のステップで十分です (例: cloud org list、cloud service get、cloud service client)。リソースを作成または変更するステップについては、API キー認証に切り替えます。

オプション B: API キー認証 (破壊的操作に必須)

クラウドリソースを作成、変更、または削除する場合 (例: cloud service create、cloud service delete) にこのオプションを使用します。ブラウザが利用できないヘッドレス/CI 環境でも使用します。--api-key と --api-secret の両方が必須です — ユーザーが片方のみを提供した場合、両方が必要であることを伝えてください。

clickhousectl cloud login --api-key <key> --api-secret <secret>

ユーザーがまだ API キーを持っていない場合、作成を案内します:

ClickHouse Cloud コンソールで:

1. 左サイドバーの歯車アイコン (設定) をクリック
2. API Keys に移動
3. Create API Key をクリック
4. 名前を付け (例: "cli")、Admin ロールを選択
5. Generate API Key をクリック
6. Key ID と Key Secret の両方をコピー — シークレットは一度だけ表示されます

---

認証が機能することを確認するには:

clickhousectl cloud org list

これはユーザーの組織を返すはずです。

---

ステップ 3: クラウドサービスを作成

API キー認証が必須です。 サービス作成は変更操作です。ステップ 2 でブラウザログイン (オプション A) で認証した場合、先に進む前に API キー認証 (オプション B) で再認証する必要があります。

新しい ClickHouse Cloud サービスを作成します:

clickhousectl cloud service create --name <service-name>

出力にはサービス ID とデフォルトユーザーパスワードが含まれます — 後続のコマンドのために記録してください。

サービスが準備完了するまで待機します。 作成後、サービスはプロビジョニングに少し時間がかかります。ステータスを確認します:

clickhousectl cloud service get <service-id>

"state" フィールドを grep して "running" かどうか確認できます。

---

ステップ 4: スキーマをマイグレート

ユーザーがローカルテーブル定義を持っている場合 (例: clickhousectl-local-dev スキルから)、それらをクラウドサービスにマイグレートします。

cloud service client を使用してクラウドサービスに対してクエリを実行します — エンドポイント、ポート、TLS 設定を自動的に検索します。必要なのはサービス名 (または --id) とステップ 3 のパスワードだけです。

clickhouse/tables/ からローカルスキーマファイルを読み込んで、各ファイルをクラウドサービスに適用します:

clickhousectl cloud service client --name <service-name> \
  --queries-file clickhouse/tables/<table>.sql

依存関係順に適用します — マテリアライズドビューで参照されるテーブルは最初に作成する必要があります。

マテリアライズドビューも適用します (存在する場合):

clickhousectl cloud service client --name <service-name> \
  --queries-file clickhouse/materialized_views/<view>.sql

--user フラグのデフォルトは default です。ユーザーが異なるデータベースユーザーを持っている場合、--user <username> を渡します。

---

ステップ 5: デプロイを検証

クラウドサービスに接続して、テーブルが存在することを確認します:

clickhousectl cloud service client --name <service-name> --query "SHOW TABLES"

スキーマが正しいことを確認するためにテストクエリを実行します:

clickhousectl cloud service client --name <service-name> --query "DESCRIBE TABLE <table-name>"

---

ステップ 6: アプリケーション設定を更新

ユーザーのアプリケーション設定用にサービスエンドポイントを取得します:

clickhousectl cloud service get <service-id>

ユーザーに接続詳細を提供します:

• Host: サービス get 出力から
• Port: HTTPS の場合は 8443 / ネイティブ TLS の場合は 9440
• User: default
• Password: ステップ 3 (サービス作成) のパスワード
• SSL/TLS: 必須 (Cloud では常に有効)

接続文字列の例 (ユーザーの言語/フレームワークに適応させてください):

Python (clickhouse-connect):

import clickhouse_connect

client = clickhouse_connect.get_client(
    host='<cloud-host>',
    port=8443,
    username='default',
    password='<password>',
    secure=True
)

Node.js (@clickhouse/client):

import { createClient } from '@clickhouse/client'

const client = createClient({
  url: 'https://<cloud-host>:8443',
  username: 'default',
  password: '<password>',
})

Go (clickhouse-go):

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{"<cloud-host>:9440"},
    Auth: clickhouse.Auth{
        Username: "default",
        Password: "<password>",
    },
    TLS: &tls.Config{},
})

ユーザーがハードコーディングするのではなく、パスワードを環境変数またはシークレットマネージャーに保存することを提案します。

本番環境ではデフォルトユーザーを使用しないことをユーザーに提案します。アプリケーション用のユーザーを作成する必要があります。