clickhousectl-local-dev

Original：🇺🇸 English

Translated

Use when a user wants to build an application with ClickHouse, set up a local ClickHouse development environment, install ClickHouse, create a local server, create tables, or start developing with ClickHouse. Covers the full flow from zero to a working local ClickHouse setup.

2installs

Sourceclickhouse/agent-skills

Added on2026-04-09

NPX Install

npx skill4agent add clickhouse/agent-skills clickhousectl-local-dev

SKILL.md Content

View Translation Comparison →

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.

clickhousectl-local-dev

NPX Install

Tags

SKILL.md Content

Local ClickHouse Development Setup

When to Apply

Step 1: Install clickhousectl

Step 2: Install ClickHouse

Step 3: Initialize the project

Step 4: Start a local server

Step 5: Create the schema

Step 6: Seed data (optional)

Step 7: Verify the setup