clickhousectl (别名 chctl) 是 ClickHouse 的官方命令行客户端,覆盖从本地开发到 ClickHouse Cloud 的全流程。无论是在终端中直接操作的用户,还是脚本和编程智能体,都可以使用它。
使用 clickhousectl,您可以:
- 安装并切换本地 ClickHouse 版本、运行相互隔离的本地服务器,以及执行 SQL
- 在本地运行基于 Docker 的 Postgres
- 创建、配置、扩缩容、备份和查询 ClickHouse Cloud 服务
- 创建、监控、配置和恢复 ClickHouse Managed Postgres 服务
- 创建并运维以对象存储、Kafka、Kinesis、Pub/Sub、Postgres、MySQL、MongoDB 和 BigQuery 为数据源的 ClickPipes
- 管理 托管 ClickStack 服务上的数据源、仪表盘、告警、Webhook、保存的搜索和角色
- 在本地开发可执行用户定义函数,并将其部署到 ClickHouse Cloud
- 管理组织成员、邀请、API 密钥和角色
- 将官方 ClickHouse agent skills 安装到编程智能体中
clickhousectl <command> --help 的输出为准。大多数命令的帮助信息末尾都附有 CONTEXT FOR AGENTS 块;对于 Cloud 命令,该部分还会列出所需的 API key 权限。如需了解具体任务的操作步骤,请参阅各节中的指南链接。如需了解面向 Cloud 的概览,请参阅 ClickHouse 命令行客户端。
安装
clickhousectl 支持 MacOS 和 Linux 系统,适用于 ARM64 和 x86_64 架构。
~/.local/bin/clickhousectl,并创建 chctl 别名。请确保 ~/.local/bin 已添加到 PATH 中。
你也可以通过包管理器安装:
只有安装脚本和 npm 会创建
chctl 别名。如需更新已安装的版本,请运行 clickhousectl update (参见自更新) 。
前提条件
- Docker (仅在使用本地 Postgres 时需要)
- 如需使用 Cloud 命令,需要一个 ClickHouse Cloud 账户。只读类命令可通过浏览器 OAuth 登录 (
cloud auth login) 后使用;创建或修改资源则需要 API key。请参阅身份验证。
本地
本地命令作用于当前目录。每个项目的服务器数据保存在.clickhouse/ 中,而 ClickHouse 二进制文件则全局共享,统一存放在 ~/.clickhouse/ 中。命令行客户端不会向上级目录查找,因此请在项目根目录下运行本地命令。完整工作流请参阅本地开发指南。
安装并选择版本
local use 会在需要时安装该版本,将其设为今后启动服务器时使用的默认版本,并为其创建指向 ~/.local/bin/clickhouse 的符号链接,使 clickhouse client 和 clickhouse local 可通过 PATH 直接调用。传入 --no-global 可跳过创建符号链接。如果该路径下已存在普通文件,则保持原样,不做改动。
local remove 不允许删除默认版本,也不允许删除任何项目中正在运行的服务器所使用的版本。使用 --force 会停止这些服务器并删除该版本,同时清除默认版本设置和符号链接。
初始化项目
init 为可选步骤。它会创建一个被 git 忽略的 .clickhouse/ 目录,用于存放运行时数据,同时生成可提交到版本库的 SQL 脚手架:clickhouse/ (tables/、materialized_views/、queries/、seed/、udfs/) 和 postgres/ (tables/、views/、functions/、queries/、seed/) 。重复运行该命令时,只会补建缺失的部分。
运行本地服务器
.clickhouse/servers/<name>/data/ 中,停止服务器后数据会保留,供下次启动时使用。若未指定名称,第一个服务器名为 default;如果 default 已在运行,则会自动生成一个新名称。默认端口为 HTTP 8123 和 TCP 9000,若这些端口已被占用,则会自动分配空闲端口。
--version 用于指定本次启动所用的版本,不会更改默认版本。如果直接启动时既未指定版本,也未设置默认版本,则会安装 latest,但不会将其设为默认版本;如需将其设为默认版本,请先运行 local use latest。
使用本地客户端运行 SQL
local client 会使用运行该服务器的同一个 ClickHouse 二进制文件,连接到指定名称的服务器 (默认名称:default) 。-- 之后的参数会原样传递给 clickhouse client。输出和退出状态均来自 clickhouse client,即使在 JSON 模式下也是如此,因此在脚本中使用时,请自行设置 SQL 输出格式。
自定义服务器配置
将包含部分配置项的 XML 或 YAML config 文件放入~/.clickhouse/configs/,然后在启动服务器时按名称选用该配置:
--config 启动,覆盖文件将被移除。托管的数据路径和端口始终优先于 config 中的配置值。
将连接详情写入 dotenv 文件
dotenv 会读取当前运行中的服务器的实际端口,并写入 CLICKHOUSE_HOST、CLICKHOUSE_PORT 和 CLICKHOUSE_HTTP_PORT;如果传入了用户、密码和数据库,也会一并写入。已有文件中的其他行将保持不变。请使用应用程序自带的 dotenv 加载器加载该文件;切勿对输出的预览内容执行 eval。
本地 Postgres
本地 Postgres 运行在 Docker 中,因此需要确保 Docker 正在运行。支持 Postgres 17 和 18,包括18-alpine 等镜像标签;新实例默认使用 18。
.env.local 中包含该密码,请勿将其纳入版本控制。
本地 UDFs
local udf 会将 clickhouse/udfs/<name>/ 下的可执行用户定义函数部署到本地服务器,而 cloud udf 则会将同一目录上传到 Cloud (参见 Cloud 中的 UDFs) 。
init 外,所有命令都支持 --server <name> 参数 (默认值为 default) 。deploy 会采用与 Cloud 相同的方式验证 udf.json。如果服务器正在运行,它会重新加载函数,并确认该函数已成功加载。native 运行时仅支持在 Linux amd64 或 arm64 主机上本地部署。请参阅用户自定义函数指南。
身份验证
Cloud 命令支持以下两种凭证类型:
如果您还没有 ClickHouse Cloud 账户,
clickhousectl cloud auth signup 会在浏览器中打开注册页面。
OAuth 登录
~/.clickhouse/tokens.json,并自动刷新。
OAuth 访问仅为 只读。如需创建或更改资源,请使用 API key 登录。
API key
创建一个 API key,为其分配命令所需的角色,然后保存。使用交互式提示输入,可避免密钥被记录到 shell 历史记录中:.env 文件中读取这些变量。请勿将 .env 文件纳入版本控制。
检查并清除凭证
whoami 支持任一类型的凭证;如果凭证被拒绝,则以退出码 4 退出。即使所有凭证均无效,status 也可能返回退出码 0,因此请使用 whoami 来测试访问权限。注销不会清除环境变量,也不会修改 .env。
凭证优先级
系统按以下顺序查找凭证,使用第一个可用的来源:--api-key和--api-secret标志.clickhouse/credentials.json- 已导出的环境变量
- 当前目录下
.env文件中的变量 - 全局 OAuth 令牌
cloud 命令加上 --debug,即可将所选的凭证来源和 API URL 输出到 stderr:
选择组织
对于组织级别的命令,仅当你的凭证恰好只能访问一个组织时,才会自动选择该组织。否则,请传入--org-id,或传入 --org-name 并指定完整准确的组织名称:
--name。有关权限、受限 API 密钥以及登出清理的说明,请参阅身份验证与访问。
Cloud
Cloud 命令会调用 ClickHouse Cloud API。创建和更新请求在被 API 接受后即会返回,因此请轮询get,直到资源达到所需状态。
服务
get,直到状态变为 running。省略 --ip-allow 将允许所有 IP (0.0.0.0/0) 访问。 条目格式为 IP_OR_CIDR=DESCRIPTION。使用 --backup-id 可将备份恢复到新服务中,使用 --byoc-id 可将服务部署到 BYOC 基础设施中。
更新、扩缩容和配置服务:
update 只会更改你传入的标志。
其他服务命令组包括 settings (list、get、schema、set、unset) 、scaling-schedule、upgrade-window、replica-aware-routing (Beta) 、snapshot (Beta) 、private-endpoint、backup-config 和 prometheus。请参阅创建和运维 云服务。
查询 API
cloud service query 通过 HTTP 执行单条 SQL 语句,既不需要本地 clickhouse 二进制文件,也不需要服务密码:
- OAuth 以您的身份运行查询,仅具有只读 SQL 访问权限,不会向服务绑定任何内容。
- API key: 首次调用时,clickhousectl 会将您的 API key 添加到该服务的查询 API 端点;如果端点尚不存在,则会以
sql_console_admin角色创建该端点。现有的角色、来源及其他 key 绑定均会保留,也不会创建新的 key。命令行客户端更改该端点时,会向 stderr 输出Binding the authenticated API key to the Query API endpoint for service '<name>'...。如需在这种情况下直接报错,请传入--no-auto-enable。
cloud service repair-query-key <service-id> 显式将其替换。
查询 API 每个请求仅接受一条语句。请求可能在约 30 秒后超时,但 SQL 仍会继续执行,因此在重试写入操作之前,请先检查结果。对于多语句脚本、批量加载和长时间运行的查询,请使用 clickhouse client。服务 IP 允许列表仅限制直接连接,不限制经代理的查询 API 路由。查询处于空闲状态的服务会将其唤醒;已停止的服务则必须先使用 cloud service start 启动。
管理服务的查询 API 端点、命名 SQL 端点和已保存的查询:
query-endpoint create 会替换绑定到该端点的所有密钥的角色。请参阅 SQL 与查询 API 行为。
Managed Postgres
cloud postgres 用于管理 ClickHouse Managed Postgres。这些命令目前处于 Beta 阶段,对 GCP 的支持则处于私有预览阶段。
m6gd.large、c6gd.xlarge 和 r6gd.xlarge。在 GCP 上,请传入 --provider gcp,并指定 GCP 区域以及 c4-standard-lssd-4 等规格。
请妥善保存 create 返回的密码和连接字符串。此后的 get 响应均不会返回凭证,如需新凭证,只能通过 reset-password 获取。使用 psql 连接时,请指定 sslmode=verify-full 和 CA 文件。
如果在创建时未指定访问控制标志,Postgres (5432) 和 PgBouncer (6432) 将对所有 IPv4 和 IPv6 地址开放访问。 每条规则需传入一个 --ip-allow IP_OR_CIDR:PORTS[=DESCRIPTION];如不设置任何规则,请传入 --block-public-access。一旦传入规则,便只有所列规则生效。
监控与恢复:
cloud postgres query 仅支持 OAuth,因此当优先级更高的 API key 来源处于活跃状态时,该命令会执行失败。metrics、slow-queries 和 prometheus 用于监控。restore 会将源服务当前的 IPv4 访问规则复制到恢复后的服务上,除非您传入 --ip-allow 或 --block-public-access。恢复和创建副本操作的返回结果中不包含密码。promote 和 switchover 在请求被接受后即返回;执行 promote 后,请轮询 postgres get --json,直到副本报告 isPrimary: true。详见 Managed Postgres 指南。
ClickPipes
cloud clickpipe 可从对象存储、Kafka、Kinesis、Pub/Sub、Postgres、MySQL、MongoDB 和 BigQuery 摄取数据。创建管道和执行模式发现均需要 API key 以及一个正在运行的目标服务。每种数据源都有对应的 clickpipe create <source> 子命令;加上 --help 运行该子命令,即可查看其支持的标志。
通过 IAM role 从 S3 加载文件。先发现 schema,再选择所需的列:
--table-mapping 会创建 ReplacingMergeTree 表,因此读取当前状态时请使用 FINAL WHERE _peerdb_is_deleted = 0。Kafka 管道的做法与此相同:使用相同的源端标志运行 clickpipe schema-discover kafka,然后传入相应的列:
--replication-mode cdc 和 --replication-method,并在 --table-mapping-json 中为每个表指定水位线列或事件函数;可通过 --sync-cron 或 --sync-interval-seconds 设置同步调度计划。管理现有数据管道:
Paused 状态,才能执行 update:先停止管道,轮询 get 直到其状态变为 Paused,然后再执行更新。服务可能会在更新过程中自动恢复管道,因此只有当 get 仍显示 Paused 时,才需要运行 start。--start-paused 适用于对象存储、Kafka、Kinesis 和 Pub/Sub。其他命令组包括 cdc-scaling、context get (用于查看 GCP 工作负载身份的就绪状态及主体) 以及 reverse-private-endpoint。详见 ClickPipes 指南和 ClickPipe 配置参考文档。
ClickStack
cloud clickstack 用于管理现有托管 ClickStack 服务中的数据源、仪表盘、告警、Webhook、保存的搜索和角色。资源以 JSON 文件形式提供 (通过 --file 指定,或使用 - 从 stdin 读取) 。读取操作支持 OAuth 认证,写入操作则需要 API key。
get --json 保存当前状态,然后提交完整的定义,而不是只提交已更改的字段。请参阅 ClickStack 指南。
Cloud 中的 UDFs
cloud udf 用于管理组织级别的可执行用户定义函数、它们的版本及其与服务的关联。deploy 会上传你用 local udf 测试过的目录,等待构建版本完成,关联该版本,然后等待部署完成:
udf create、udf version create、udf attach (若服务处于空闲状态,需加上 --wake) 、udf detach 和 udf delete。这些命令在请求被接受后即会返回,可通过轮询 udf get 和 udf attachment get 查看进度。读取操作支持 OAuth,写入操作则需要 API key。详情请参阅用户自定义函数指南。
组织与访问
cloud org 子命令通过 --org-id 指定组织,不接受位置参数形式的 ID。org usage 的查询范围最长为 31 天。org 还提供 quota、balance、notification-types、role (自定义组织角色) 和 byoc (BYOC 基础设施) 子命令。通知功能目前处于 Beta 阶段。
管理成员、邀请和 API 密钥:
key create 中省略 --ip-allow 会拒绝所有网络访问,这一点与创建服务时不同。密钥仅显示一次。除非传入 --all,否则 key list 只返回一页结果。执行 key update 时,未指定的标志会保留原有设置,而 --clear-expiry、--clear-roles 和 --clear-ip-allow 则会清除相应设置。
备份
cloud backup bucket (get、create、update、delete) 可根据特定提供商的 JSON 文件配置自带 (BYO) 备份桶。详见 云服务指南 中的备份部分。
JSON 输出
返回结构化数据的命令均支持--json 参数,包括本地命令、Cloud 命令,以及 skills、update 和 telemetry 命令:
AI_AGENT 的工具) 时,会自动选择 JSON 格式。SQL 客户端和原生客户端则沿用各自的格式:cloud service query 在 JSON 模式下返回 JSONEachRow,而 local client 的输出始终为原生格式。需要解析查询输出的脚本应显式传入 --format。
在 JSON 模式下,运行时错误会以对象形式输出到 stderr,其中包含稳定不变的 code 以及 message:
error.code 而非错误消息进行分支判断。用法错误仍以纯文本形式输出,退出码为 2。有关输出格式和错误码的详细说明,请参阅自动化与输出约定。
退出码
local client、local postgres client 以及其他移交给原生客户端执行的命令,会直接透传该客户端自身的退出状态。
智能体技能
将官方 ClickHouse agent skills 安装到你的编程智能体中:--global 安装到您的主目录下。共享的 .agents/skills/ 目录始终会被包含在内。如果没有终端,则必须传入 --agent、--all 或 --detected-only。运行 clickhousectl skills --help 可查看受支持的智能体名称。
自动更新
遥测数据
clickhousectl 会收集匿名用量数据,用于指导后续开发。首次运行时仅显示一条通知,不会发送任何数据;从之后的运行开始收集数据,除非您将其禁用。
每个事件包含:
- 命令路径,以及显式传入的标志和参数的名称,绝不包含其值
- 执行结果和退出码
- 对于输错的命令,记录命令行客户端建议的命令或标志名称,绝不记录您实际输入的内容
- 对于运行时故障,记录有限的分类信息:失败阶段和类型、允许列表内的 HTTP 状态码,以及重试、预配状态和耗时的分类
- 命令行客户端版本、OS 和架构、是否在 CI 中运行,以及检测到的 编程智能体
-- 之后的参数以及错误消息均不会被记录,也不会使用任何安装 ID 或设备 ID。
如需选择退出:
CHCTL_TELEMETRY_DEBUG=1 后,载荷将仅打印到 stderr,不会发送任何数据。详情请参见遥测数据详情。