clickhousectl-local-dev

本地 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"

安装完成后，可以使用 clickhousectl skills 安装最新的 ClickHouse Agent Skills。

---

第 2 步：安装 ClickHouse 并设置默认版本

安装最新版本的 ClickHouse，并将其设为系统默认版本：

clickhousectl local use latest

这会安装 ClickHouse，将其设为 clickhousectl local 命令使用的默认版本，并将 ~/.local/bin/clickhouse 符号链接到该二进制文件，从而将 clickhouse 添加到 PATH 中（也就是说，你可以直接调用 clickhouse，例如在需要时执行 clickhouse client）。

需要时，也可以使用 stable、26.4、26.4.2.10 等其他版本指定符。

---

第 3 步：初始化项目

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

clickhousectl local init

这会创建标准的文件夹结构：

clickhouse/
  tables/                 # CREATE TABLE statements
  materialized_views/     # Materialized view definitions
  queries/                # Saved queries
  seed/                   # Seed data / INSERT statements

注意： 此步骤为可选项。如果用户已有自己的 SQL 文件夹结构，请跳过此步骤，并调整后续步骤以使用相应路径。

---

第 4 步：启动本地服务

clickhousectl local server start --name <name>

这会在后台启动 ClickHouse 服务。

查看运行中的服务及其公开端口：

clickhousectl local server list

---

第 5 步：创建架构

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

将每个表定义分别写入 clickhouse/tables/ 中的一个文件：

# Example: 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/：

# Example: 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。