跳转到主要内容
ClickHouse 命令行客户端 (clickhousectl,别名 chctl) 支持通过终端、脚本或编程智能体来管理 ClickHouse Cloud。本页介绍该命令行客户端中与 Cloud 相关的功能。如需了解所有命令组、本地开发以及完整的行为说明,请参阅 clickhousectl 参考文档。

可管理的内容

clickhousectl cloud 命令涵盖以下功能:
  • 服务: 创建、扩缩容、启动和停止 ClickHouse Cloud 服务,并通过查询 API 对其执行 SQL。
  • Managed Postgres (Beta) : 创建 Postgres 服务、只读副本和时间点恢复,并修改其配置。
  • ClickPipes: 从对象存储、Kafka、Kinesis、Pub/Sub、Postgres、MySQL、MongoDB 和 BigQuery 摄取数据。
  • ClickStack: 在托管 ClickStack 服务上管理数据源、仪表盘、告警、Webhook、保存的搜索和角色。
  • 用户自定义函数: 在本地测试可执行 UDF,然后将其部署到云服务。
  • 备份: 列出备份、修改备份计划,以及将备份恢复到新服务。
  • 组织访问: 管理组织、成员、邀请、API 密钥和活动日志。
运行 clickhousectl cloud <command> --help 可查看任意命令的参数及其所需的 API key 权限。

安装

该脚本会安装 ~/.local/bin/clickhousectl,并创建别名 chctl。请确保 ~/.local/bin 已添加到 PATH 中。如需通过 npm、pip、uv 或其他方式安装,请参阅安装。

身份验证

通过浏览器 OAuth 登录仅具有只读权限。如需创建或更改资源,必须使用 API key,且该 API key 所关联的角色须具备执行相应更改的权限。
登录时会验证凭证并输出当前身份。您可以随时运行 clickhousectl cloud auth whoami 查看当前身份。如果您属于多个组织,请在 Cloud 命令中添加 --org-id <org-id> (或 --org-name <name>) 。在 CI 环境中,无需登录,只需设置 CLICKHOUSE_CLOUD_API_KEY 和 CLICKHOUSE_CLOUD_API_SECRET 即可。有关凭证的优先级以及如何登出,请参阅身份验证。

示例

创建并查询服务

创建命令会在服务开始运行之前就返回。请轮询 clickhousectl cloud service get "$CH_ID",直到 state 变为 running。 首次使用 API key 执行查询时,clickhousectl 会将您的 API key 添加到该服务的查询 API 端点 (如端点尚不存在则会先创建) ,但不会创建新的 key。如果希望在这种情况下直接报错,请传入 --no-auto-enable。使用 OAuth 时,service query 只能执行只读的 SELECT 语句。查询 API 的超时时间约为 30 秒,因此对于耗时较长的查询和批量加载,请使用 clickhouse client。

创建托管 Postgres 服务

只有 create 命令会返回密码和连接字符串,请务必妥善保存。如果省略 --ip-allow,端口 5432 和 6432 将对所有地址开放。等待 state 变为 running 后,即可使用 CA 证书通过 psql 进行连接。

检查 ClickPipes、ClickStack 和备份

这些只读命令支持 OAuth 认证。创建 ClickPipe 或修改 ClickStack 资源则需要使用 API key,详见下方的代码仓库指南。

部署用户自定义函数

请先针对本地服务器运行 clickhousectl local udf deploy my_udf,对该函数进行测试。

JSON 输出与编程智能体

Cloud 命令支持 --json 参数;命令行客户端在检测到编程智能体时,会自动切换为 JSON 输出。此时 cloud service query 默认采用 JSONEachRow 格式,因此需要解析其输出的脚本应显式指定 --format,例如 --format TabSeparated。详见 JSON 输出和退出码。可通过 clickhousectl skills 安装 ClickHouse agent skills。

了解更多