clickhousectl-local-dev

# Local ClickHouse Development Setup This skill walks through setting up a complete local ClickHouse development environment using `clickhousectl`. Follow these steps in order. ## When to Apply Use this skill when the user wants to: - Build an application that needs an analytical database or ClickHouse specifically - Set up a local ClickHouse instance for development - Install ClickHouse on their machine - Create tables and start querying ClickHouse locally - Prototype or experiment with ClickHouse --- ## Step 1: Install clickhousectl Check if `clickhousectl` is already available: ```bash which clickhousectl ``` If not found, install it: ```bash curl -fsSL https://clickhouse.com/cli | sh ``` This installs `clickhousectl` to `~/.local/bin/clickhousectl` and creates a `chctl` alias. **If the command is still not found after install:** The user may need to add `~/.local/bin` to their PATH or open a new terminal session. Suggest: ```bash export PATH="$HOME/.local/bin:$PATH" ``` --- ## Step 2: Install ClickHouse Install the latest stable ClickHouse version: ```bash clickhousectl local install stable ``` This downloads the ClickHouse binary to `~/.clickhouse/versions/`. The binary is shared across projects so it only needs to be downloaded once. **Alternative version specifiers** (use if the user has a specific need): - `lts` — latest long-term support release - `25.12` — latest patch of a specific minor version - `25.12.5.44` — exact version Set the installed version as the default: ```bash clickhousectl local use stable ``` --- ## Step 3: Initialize the project From the user's project root directory: ```bash clickhousectl local init ``` This creates a standard folder structure: ``` clickhouse/ tables/ # CREATE TABLE statements materialized_views/ # Materialized view definitions queries/ # Saved queries seed/ # Seed data / INSERT statements ``` **Note:** This step is optional. If the user already has their own folder structure for SQL files, skip this and adapt the later steps to use their paths. --- ## Step 4: Start a local server ```bash clickhousectl local server start --name <name> ``` This starts a ClickHouse server in the background. Server data is stored in `.clickhouse/servers/<anem>/data/` within the project directory. **To check running servers and see their exposed ports:** ```bash clickhousectl local server list ``` --- ## Step 5: Create the schema Based on the user's application requirements, write CREATE TABLE SQL files. **Write each table definition to its own file** in `clickhouse/tables/`: ```bash # Example: clickhouse/tables/events.sql ``` ```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) ``` When designing schemas, if the `clickhouse-best-practices` skill is available, consult it for guidance on ORDER BY column selection, data types, and partitioning. **Apply the schema to the running server:** ```bash clickhousectl local client --name <name> --queries-file clickhouse/tables/events.sql ``` --- ## Step 6: Seed data (optional) If the user needs sample data for development, write INSERT statements to `clickhouse/seed/`: ```bash # Example: clickhouse/seed/events.sql ``` ```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"}'); ``` **Apply seed data:** ```bash clickhousectl local client --name <name> --queries-file clickhouse/seed/events.sql ``` --- ## Step 7: Verify the setup Confirm tables were created: ```bash clickhousectl local client --name <name> --query "SHOW TABLES" ``` Run a test query: ```bash clickhousectl local client --name <name> --query "SELECT count() FROM events" ``` --- If the user wants to use a managed ClickHouse service, use the `clickhousectl-cloud-deploy` skill to help the user deploy to ClickHouse Cloud.