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:

which clickhousectl

If not found, install it:

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:

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

Once installed, clickhousectl skills can be used to install the latest ClickHouse Agent Skills.

Step 2: Install ClickHouse and set the default

Install the latest ClickHouse version and set it as the system default:

clickhousectl local use latest

This installs ClickHouse, sets it as the default version used by clickhousectl local commands, and symlinks ~/.local/bin/clickhouse to the binary, putting clickhouse on your PATH (meaning you can invoke clickhouse directly, e.g. clickhouse client if needed).

You can use other version specifiers like stable, 26.4, 26.4.2.10 when needed.

Step 3: Initialize the project

From the user's project root directory:

This creates a standard folder structure:

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

This starts a ClickHouse server in the background.

To check running servers and see their exposed ports:

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/:

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:

Step 6: Seed data (optional)

If the user needs sample data for development, write INSERT statements to clickhouse/seed/:

Apply seed data:

Step 7: Verify the setup

Confirm tables were created:

Run a test query:

If the user wants to use a managed ClickHouse service, use the clickhousectl-cloud-deploy skill to help the user deploy to ClickHouse Cloud.