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 和备份
部署用户自定义函数
clickhousectl local udf deploy my_udf,对该函数进行测试。
JSON 输出与编程智能体
Cloud 命令支持--json 参数;命令行客户端在检测到编程智能体时,会自动切换为 JSON 输出。此时 cloud service query 默认采用 JSONEachRow 格式,因此需要解析其输出的脚本应显式指定 --format,例如 --format TabSeparated。详见 JSON 输出和退出码。可通过 clickhousectl skills 安装 ClickHouse agent skills。
了解更多
- clickhousectl 参考文档:涵盖所有命令组、本地开发、技能、自更新以及遥测数据。
- 代码仓库中的指南:
- 代码仓库中的参考文档:身份验证与访问、SQL 与查询 API、ClickPipe 配置以及自动化与输出契约。