clickhousectl-cloud-deploy

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

ClickHouse Cloud API キーで clickhousectl を認証します。

API キーを作成する

ClickHouse Cloud コンソールでの作成方法をユーザーに案内します。

1. 左側のサイドバーにある歯車アイコン（設定）をクリックします
2. API Keys に移動します
3. Create API Key をクリックします
4. 名前を付けます（例：「clickhousectl」）
5. キーに Admin ロールを選択します。cloud service query は初回使用時にサービスごとのクエリエンドポイント用 API キーを自動プロビジョニングしますが、その作成には権限が必要なため、Admin が必要です。Developer スコープのキーではサービスを管理できますが、自動プロビジョニングを完了できない場合があります。
6. Generate API Key をクリックします
7. Key ID と Key Secret の両方をコピーします。シークレットが表示されるのは一度だけです

キーで clickhousectl を認証する

ユーザーに、同じ作業ディレクトリで新しいターミナルタブを開き、そこで Key ID と Secret を指定してログインコマンドを実行するよう依頼します。これにより、シークレットがチャットセッションに含まれずに済みます。完了したら戻って知らせるよう伝えてください。

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

--api-key と --api-secret は両方とも必須です。どちらか一方しか持っていない場合は、両方必要だと伝えてください。

---

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

clickhousectl cloud org list

これにより、ユーザーの組織が表示されます。

---

ステップ 3：クラウドサービスを作成する

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

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

出力から HTTPS ホストとポートを .env に CLICKHOUSE_HOST と CLICKHOUSE_PORT として追加します。.env が gitignore されていることを確認してください。

次に、サービスの状態が running になるまでポーリングします。

clickhousectl cloud service get <service-id>

---

ステップ 4：スキーマを移行する

ユーザーがローカルのテーブル定義（例：clickhousectl-local-dev スキルを使用して作成したもの）を持っている場合は、クラウドサービスに移行します。

cloud service query を使用すると、HTTP 経由でクラウドサービスに対して SQL を実行できます。サービス名または --id を渡してください。

clickhouse/tables/ からローカルのスキーマファイルを読み込み、それぞれをクラウドサービスに適用します。

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

依存関係の順に適用してください。マテリアライズドビューが参照するテーブルは、先に作成する必要があります。

マテリアライズドビューも存在する場合は適用してください。

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

特定のデータベースを対象にするには、--database <name> を渡してください。

---

ステップ 5：デプロイを確認する

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

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

テストクエリを実行し、スキーマが正しいことを確認します。

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

---

ステップ 6：アプリケーション専用のユーザーを作成する

default ユーザーには完全な管理者権限があるため、アプリケーションでは使用しないでください。ステップ 4 でデプロイしたスキーマに限定した専用ユーザーを作成します。

強力なランダムパスワードを生成し、ユーザーを作成する前に認証情報を .env に追記してください。これにより、後続のステップが失敗してもパスワードが保存されます。

PASSWORD=$(openssl rand -base64 32)
echo "CLICKHOUSE_USER=app_user" >> .env
echo "CLICKHOUSE_PASSWORD=$PASSWORD" >> .env

次に、ユーザーを作成し、アプリケーションに必要な最小限の権限を付与します。<database> はスキーマがあるデータベースに置き換えてください（多くの場合は default です）。

clickhousectl cloud service query --name <service-name> --query \
  "CREATE USER app_user IDENTIFIED BY '$PASSWORD'"

clickhousectl cloud service query --name <service-name> --query \
  "GRANT SELECT, INSERT ON <database>.* TO app_user"

アプリケーションに合わせて権限を調整してください。

• 読み取り専用アプリケーション → INSERT を削除します
• 独自のテーブルを作成・削除する必要がある場合 → データベースに対して CREATE TABLE, DROP TABLE も付与します（ただし、代わりに管理者ユーザーとしてマイグレーションを実行することを推奨します）
• 複数のデータベースを使用する場合 → データベースごとに GRANT を繰り返すか、ON <database>.<table> を使ってテーブルごとに範囲を指定します

ユーザーが存在し、想定どおりの権限が付与されていることを確認します。

clickhousectl cloud service query --name <service-name> --query "SHOW GRANTS FOR app_user"

ClickHouse では後からパスワードを確認できないため、.env を紛失した場合は、ALTER USER app_user IDENTIFIED BY '<new>' を使ってユーザーのパスワードをリセットする必要があります。

---

これで、アプリケーションは .env の認証情報を使って ClickHouse Cloud に接続できます。