跳转到主要内容
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 登录

这会打开浏览器,通过 OAuth device flow 进行身份验证。令牌会全局保存到 ~/.clickhouse/tokens.json,并自动刷新。
OAuth 访问仅为 只读。如需创建或更改资源,请使用 API key 登录。

API key

创建一个 API key,为其分配命令所需的角色,然后保存。使用交互式提示输入,可避免密钥被记录到 shell 历史记录中:
登录时会校验该密钥,并输出其所属的身份。被 API 拒绝的密钥不会被保存,且命令以退出码 4 退出。如果无法访问 API,密钥仍会被保存,但会输出一条警告。 在 CI 及其他自动化场景中,请通过您的密钥管理器注入密钥,而不要将其保存到本地:
在开发环境中,命令行客户端还会从当前目录下的 .env 文件中读取这些变量。请勿将 .env 文件纳入版本控制。

检查并清除凭证

whoami 支持任一类型的凭证;如果凭证被拒绝,则以退出码 4 退出。即使所有凭证均无效,status 也可能返回退出码 0,因此请使用 whoami 来测试访问权限。注销不会清除环境变量,也不会修改 .env。

凭证优先级

系统按以下顺序查找凭证,使用第一个可用的来源:
  1. --api-key 和 --api-secret 标志
  2. .clickhouse/credentials.json
  3. 已导出的环境变量
  4. 当前目录下 .env 文件中的变量
  5. 全局 OAuth 令牌
为任意 cloud 命令加上 --debug,即可将所选的凭证来源和 API URL 输出到 stderr:

选择组织

对于组织级别的命令,仅当你的凭证恰好只能访问一个组织时,才会自动选择该组织。否则,请传入 --org-id,或传入 --org-name 并指定完整准确的组织名称:
大多数资源命令接受一个位置参数 ID 或精确的 --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 基础设施中。 更新、扩缩容和配置服务:
每个副本的内存须为 4 GB 的整数倍,未付费服务最高 120 GB,付费服务最高 356 GB,副本数最多 50 个。组织和仓库层面的限制可能会使这些上限更低。横向自动扩缩容需要先为组织启用对应功能。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。
对于由早期版本命令行客户端保存了服务专属 key 的服务,该 key 仍具有更高的优先次序。如果 API 拒绝该 key,可使用 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 的支持则处于私有预览阶段。
AWS 规格包括 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,再选择所需的列:
使用 CDC (变更数据捕获) 复制 Postgres。TLS 默认会进行验证;如果是 Managed Postgres 数据源,请导出其 CA 证书并传入:
--table-mapping 会创建 ReplacingMergeTree 表,因此读取当前状态时请使用 FINAL WHERE _peerdb_is_deleted = 0。Kafka 管道的做法与此相同:使用相同的源端标志运行 clickpipe schema-discover kafka,然后传入相应的列:
BigQuery 数据管道默认执行快照同步。如需使用 CDC (变更数据捕获) ,请传入 --replication-mode cdc 和 --replication-method,并在 --table-mapping-json 中为每个表指定水位线列或事件函数;可通过 --sync-cron 或 --sync-interval-seconds 设置同步调度计划。管理现有数据管道:
CDC 管道必须先处于 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。
每次更新 ClickStack 都会替换整个资源。 请先使用 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 命令:
当命令行客户端检测到编程智能体 (例如 Claude Code、Cursor、Codex、Gemini CLI、Goose 或 Devin,或任何设置了 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 可查看受支持的智能体名称。

自动更新

命令行客户端还会在后台检查更新 (每 24 小时最多一次) ,并在有新版本可用时输出提示信息。

遥测数据

clickhousectl 会收集匿名用量数据,用于指导后续开发。首次运行时仅显示一条通知,不会发送任何数据;从之后的运行开始收集数据,除非您将其禁用。 每个事件包含:
  • 命令路径,以及显式传入的标志和参数的名称,绝不包含其值
  • 执行结果和退出码
  • 对于输错的命令,记录命令行客户端建议的命令或标志名称,绝不记录您实际输入的内容
  • 对于运行时故障,记录有限的分类信息:失败阶段和类型、允许列表内的 HTTP 状态码,以及重试、预配状态和耗时的分类
  • 命令行客户端版本、OS 和架构、是否在 CI 中运行,以及检测到的 编程智能体
参数值、SQL、凭证、资源标识符、-- 之后的参数以及错误消息均不会被记录,也不会使用任何安装 ID 或设备 ID。 如需选择退出:
设置 CHCTL_TELEMETRY_DEBUG=1 后,载荷将仅打印到 stderr,不会发送任何数据。详情请参见遥测数据详情。