ローカル 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"

---

ステップ 2: ClickHouse をインストール

最新の安定版 ClickHouse をインストールします:

clickhousectl local install stable

これにより ClickHouse バイナリが ~/.clickhouse/versions/ にダウンロードされます。バイナリはプロジェクト間で共有されるため、一度だけダウンロードすればよいです。

代替バージョン指定子 (ユーザーが特定のニーズがある場合に使用):

• lts — 最新のロングタームサポートリリース
• 25.12 — 特定のマイナーバージョンの最新パッチ
• 25.12.5.44 — 正確なバージョン

インストールしたバージョンをデフォルトとして設定します:

clickhousectl local use stable

---

ステップ 3: プロジェクトを初期化

ユーザーのプロジェクトルートディレクトリから:

clickhousectl local init

これにより標準的なフォルダ構造が作成されます:

clickhouse/
  tables/                 # CREATE TABLE ステートメント
  materialized_views/     # マテリアライズドビュー定義
  queries/                # 保存されたクエリ
  seed/                   # シードデータ / INSERT ステートメント

注: このステップはオプションです。ユーザーが既に SQL ファイル用の独自のフォルダ構造を持っている場合は、このステップをスキップして後続のステップをそれらのパスに適応させてください。

---

ステップ 4: ローカルサーバーを起動

clickhousectl local server start --name <name>

これにより ClickHouse サーバーがバックグラウンドで起動します。サーバーデータはプロジェクトディレクトリ内の .clickhouse/servers/<name>/data/ に保存されます。

実行中のサーバーを確認し、公開されているポートを確認する:

clickhousectl local server list

---

ステップ 5: スキーマを作成

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

各テーブル定義を clickhouse/tables/ 内の独立したファイルに記述します:

# 例: 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: シードデータ (オプション)

ユーザーが開発用のサンプルデータが必要な場合、INSERT ステートメントを clickhouse/seed/ に記述します:

# 例: 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 にデプロイするのを支援します。