clickhousectl-local-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Local ClickHouse Development Setup

本地ClickHouse开发环境搭建

This skill walks through setting up a complete local ClickHouse development environment using

clickhousectl

. Follow these steps in order.

本技能将引导你使用

clickhousectl

搭建完整的本地ClickHouse开发环境，请按顺序执行以下步骤。

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

当用户有以下需求时可使用本技能：

构建需要分析型数据库或明确需要使用ClickHouse的应用
搭建本地ClickHouse开发实例
在本机安装ClickHouse
建表并开始在本地查询ClickHouse数据
对ClickHouse进行原型验证或功能试验

Step 1: Install clickhousectl

步骤1：安装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

~/.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"

先检查是否已经安装了

clickhousectl

：

bash

which clickhousectl

如果未找到，执行安装：

bash

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

该命令会将

clickhousectl

安装到

~/.local/bin/clickhousectl

路径下，同时会创建

chctl

别名。

如果安装后仍找不到命令： 用户可能需要将

~/.local/bin

添加到PATH中，或者开启新的终端会话。建议执行：

bash

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

Step 2: Install ClickHouse

步骤2：安装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

安装最新稳定版ClickHouse：

bash

clickhousectl local install stable

该命令会将ClickHouse二进制文件下载到

~/.clickhouse/versions/

路径下。该二进制文件可在多个项目间共享，因此仅需下载一次。

可选版本标识（用户有特定需求时使用）：

```
lts
```
— 最新长期支持版本
```
25.12
```
— 指定次版本的最新补丁版
```
25.12.5.44
```
— 精确版本号

将已安装的版本设为默认版本：

bash

clickhousectl local use stable

Step 3: Initialize the project

步骤3：初始化项目

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.

在用户的项目根目录下执行：

bash

clickhousectl local init

该命令会创建标准的目录结构：

clickhouse/
  tables/                 # CREATE TABLE 建表语句
  materialized_views/     # 物化视图定义
  queries/                # 已保存的查询语句
  seed/                   # 种子数据 / INSERT 插入语句

注意： 本步骤为可选操作。如果用户已经有自己的SQL文件目录结构，可以跳过此步骤，后续步骤适配其路径即可。

Step 4: Start a local server

步骤4：启动本地服务器

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

bash

clickhousectl local server start --name <name>

该命令会在后台启动ClickHouse服务器，服务器数据存储在项目目录下的

.clickhouse/servers/<name>/data/

路径中。

要查看运行中的服务器及其暴露的端口：

bash

clickhousectl local server list

Step 5: Create the schema

步骤5：创建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

undefined

根据用户的应用需求，编写CREATE TABLE SQL文件。

将每个表的定义单独写入
clickhouse/tables/
下的独立文件中：

bash

undefined

Example: clickhouse/tables/events.sql

示例：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


```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)

设计Schema时，如果有

clickhouse-best-practices

技能可用，可以参考该技能获取ORDER BY字段选择、数据类型、分区相关的指导。

将Schema应用到运行中的服务器：

bash

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

Step 6: Seed data (optional)

步骤6：导入种子数据（可选）

If the user needs sample data for development, write INSERT statements to

clickhouse/seed/

bash

undefined

如果用户需要开发用的样本数据，可以将INSERT语句写入

clickhouse/seed/

目录下：

bash

undefined

Example: clickhouse/seed/events.sql

示例：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


```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"}');

应用种子数据：

bash

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

Step 7: Verify the setup

步骤7：验证搭建结果

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.

确认表已创建成功：

bash

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

执行测试查询：

bash

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

如果用户想要使用托管的ClickHouse服务，可以使用

clickhousectl-cloud-deploy

技能帮助用户部署到ClickHouse Cloud。