clickhousectl-local-dev

ローカル ClickHouse 開発環境のセットアップ

このスキルでは、clickhousectl を使用して完全なローカル ClickHouse 開発環境をセットアップする手順を説明します。以下の手順を順番に実行してください。

適用するタイミング

次のような要望がある場合に、このスキルを使用します。

• 分析データベース、または ClickHouse を必要とするアプリケーションを構築する
• 開発用のローカル ClickHouse インスタンスをセットアップする
• マシンに ClickHouse をインストールする
• テーブルを作成して、ローカルで ClickHouse へのクエリを開始する
• ClickHouse のプロトタイプを作成したり、実験したりする

---

手順 1：clickhousectl をインストールする

clickhousectl がすでに利用可能か確認します。

which clickhousectl

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

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

これにより、clickhousectl が ~/.local/bin/clickhousectl にインストールされ、chctl エイリアスが作成されます。

インストール後もコマンドが見つからない場合： ~/.local/bin を PATH に追加するか、新しいターミナルセッションを開く必要がある場合があります。次のように案内してください。

export PATH="$HOME/.local/bin:$PATH"

インストール後は、clickhousectl skills を使用して最新の ClickHouse Agent Skills をインストールできます。

---

手順 2：ClickHouse をインストールしてデフォルトに設定する

最新バージョンの ClickHouse をインストールし、システムのデフォルトに設定します。

clickhousectl local use latest

これにより、ClickHouse がインストールされ、clickhousectl local コマンドで使用するデフォルトバージョンに設定されます。また、~/.local/bin/clickhouse からバイナリへのシンボリックリンクが作成され、clickhouse が PATH に追加されます（つまり、必要に応じて clickhouse client のように、clickhouse を直接実行できます）。

必要に応じて、stable、26.4、26.4.2.10 など、ほかのバージョン指定子も使用できます。

---

手順 3：プロジェクトを初期化する

ユーザーのプロジェクトのルートディレクトリで、次を実行します。

clickhousectl local init

標準的なフォルダー構造が作成されます。

clickhouse/
  tables/                 # CREATE TABLE statements
  materialized_views/     # Materialized view definitions
  queries/                # Saved queries
  seed/                   # Seed data / INSERT statements

注： この手順は省略可能です。ユーザーが SQL ファイル用のフォルダー構造をすでに用意している場合は、この手順を飛ばし、以降の手順ではそのパスを使用するように調整してください。

---

手順 4：ローカルサーバーを起動する

clickhousectl local server start --name <name>

ClickHouse サーバーがバックグラウンドで起動します。

実行中のサーバーと公開ポートを確認するには：

clickhousectl local server list

---

手順 5：スキーマを作成する

ユーザーのアプリケーション要件に基づいて、CREATE TABLE の SQL ファイルを作成します。

各テーブル定義は、clickhouse/tables/ 内の個別のファイルに記述します。

# Example: clickhouse/tables/events.sql

CREATE TABLE IF NOT EXISTS events (
    timestamp DateTime,
    user_id UInt32,
    event_type LowCardinality(String),
    properties String
)
ENGINE = MergeTree()
ORDER BY (event_type, timestamp)

スキーマを設計する際に clickhouse-best-practices スキルが利用できる場合は、ORDER BY 列の選択、データ型、パーティショニングに関するガイダンスを参照してください。

実行中のサーバーにスキーマを適用します。

clickhousectl local client --name <name> --queries-file clickhouse/tables/events.sql

---

手順 6：データをシードする（省略可能）

開発用のサンプルデータが必要な場合は、clickhouse/seed/ に INSERT 文を記述します。

# Example: clickhouse/seed/events.sql

INSERT INTO events (timestamp, user_id, event_type, properties) VALUES
    ('2024-01-01 00:00:00', 1, 'page_view', '{"page": "/home"}'),
    ('2024-01-01 00:01:00', 2, 'click', '{"button": "signup"}');

シードデータを適用します。

clickhousectl local client --name <name> --queries-file clickhouse/seed/events.sql

---

手順 7：セットアップを確認する

テーブルが作成されたことを確認します。

clickhousectl local client --name <name> --query "SHOW TABLES"

テストクエリを実行します。

clickhousectl local client --name <name> --query "SELECT count() FROM events"

---

ユーザーがマネージド ClickHouse サービスを利用したい場合は、clickhousectl-cloud-deploy スキルを使用して、ClickHouse Cloud へのデプロイを支援してください。