clickhouse-cloud-management

ClickHouse Cloud 管理

ADR：2025-12-08-clickhouse-cloud-management-skill

自我迭代技能：此技能会在使用过程中持续改进。如果指令有误、参数发生变化，或需要变通方案，请立即修复此文件，不要拖延。只针对真实且可复现的问题进行更新。

概述

通过 HTTP 接口使用 SQL 命令管理 ClickHouse Cloud 用户和权限。此技能涵盖 ClickHouse Cloud 实例的数据库用户创建、权限授予和凭据管理。

架构文档原则：所有 ClickHouse 表和列的 COMMENT 都是唯一事实来源（SSoT）。创建表或列时，务必包含 COMMENT 子句。完整的 COMMENT SSoT 政策请参阅 quality-tools:clickhouse-architect。

何时使用此技能

在以下情况下调用此技能：

• 为 ClickHouse Cloud 创建数据库用户
• 管理用户权限（GRANT/REVOKE）
• 测试 ClickHouse Cloud 连通性
• 排查身份验证问题
• 了解 API 密钥与数据库用户的区别

关键概念

管理选项

ClickHouse Cloud 提供两种管理接口，功能各不相同：

任务	通过 SQL（CLI/HTTP）	通过 Cloud Console
创建数据库用户	CREATE USER	支持
授予权限	GRANT	支持
删除用户	DROP USER	支持
创建 API 密钥	不支持	仅可在此处创建

关键区别：数据库用户（通过 SQL 创建）用于向 ClickHouse 本身进行身份验证。API 密钥（通过控制台创建）用于向 ClickHouse Cloud 管理 API 进行身份验证。

连接详情

ClickHouse Cloud 仅向公网开放 HTTP 接口：

• 端口：443（HTTPS）
• 协议：HTTP（不是 ClickHouse 原生协议）
• 原生协议：需要 AWS PrivateLink（未配置企业环境时不可用）

密码要求

ClickHouse Cloud 执行严格的密码策略：

• 至少 12 个字符
• 至少包含 1 个大写字母
• 至少包含 1 个特殊字符

符合要求的密码示例：StrongPass@2025!

快速参考

创建只读用户

curl -s "https://default:PASSWORD@HOST:443/" --data-binary \
  "CREATE USER my_reader IDENTIFIED BY 'StrongPass@2025!' SETTINGS readonly = 1"

授予数据库访问权限

curl -s "https://default:PASSWORD@HOST:443/" --data-binary \
  "GRANT SELECT ON deribit.* TO my_reader"

删除用户

curl -s "https://default:PASSWORD@HOST:443/" --data-binary \
  "DROP USER my_reader"

如需完整的 SQL 模式和高级权限场景，请参阅 SQL 模式参考。

凭据来源

1Password 项目（Engineering Vault）

项目	用途
ClickHouse Cloud - API Key (Admin)	Cloud 管理 API（控制台操作）
ClickHouse Cloud - API Key (Developer Read-only)	Cloud 管理 API（只读）
gapless-deribit-clickhouse	数据库 default 用户凭据

获取凭据

# Database credentials (for SQL commands)
op item get "gapless-deribit-clickhouse" --vault Engineering --reveal

# API key (for cloud management API)
op item get "ClickHouse Cloud - API Key (Admin)" --vault Engineering --reveal

常见工作流

工作流 1：创建应用用户

1. 从 1Password 获取 default 用户凭据
2. 创建具有相应权限的新用户：

HOST="your-instance.clickhouse.cloud"
PASSWORD="default-user-password"

# Create user
curl -s "https://default:$PASSWORD@$HOST:443/" --data-binary \
  "CREATE USER app_user IDENTIFIED BY 'AppPass@2025!'"

# Grant specific database access
curl -s "https://default:$PASSWORD@$HOST:443/" --data-binary \
  "GRANT SELECT, INSERT ON mydb.* TO app_user"

工作流 2：验证用户是否存在

curl -s "https://default:$PASSWORD@$HOST:443/" --data-binary "SHOW USERS"

工作流 3：测试连接

curl -s "https://user:password@HOST:443/" --data-binary "SELECT 1"

预期输出：1（包含值 1 的单行）

故障排除

身份验证失败

• 确认密码符合复杂度要求
• 检查主机 URL 是否包含端口 443
• 确保使用 HTTPS（而不是 HTTP）

权限被拒绝

• 确认用户拥有所需的 GRANT 语句
• 检查数据库名和表名是否正确
• 确认用户创建时使用了正确的设置

连接超时

• ClickHouse Cloud 仅向公网开放端口 443
• 原生协议（端口 9440）需要 PrivateLink
• 使用 HTTP 接口，并通过 curl 或 clickhouse-client 的 HTTP 模式连接

创建用户后的后续步骤

创建 ClickHouse 用户后，调用 devops-tools:clickhouse-pydantic-config，使用新凭据生成 DBeaver 配置。

其他资源

参考文件

如需了解详细模式和高级技巧，请参阅：

• references/sql-patterns.md - 完整的 SQL 语法参考及示例

Python 驱动策略

对于连接 ClickHouse Cloud 的 Python 应用代码，请使用 clickhouse-connect（官方 HTTP 驱动）。请参阅 clickhouse-architect，了解推荐的代码模式，以及为何应避免使用 clickhouse-driver（社区驱动）。

相关技能

• quality-tools:clickhouse-architect - 架构设计、压缩编解码器、Python 驱动策略
• devops-tools:clickhouse-pydantic-config - DBeaver 配置生成
• devops-tools:doppler-secret-validation - 用于在 Doppler 中存储凭据
• devops-tools:doppler-workflows - 用于凭据轮换工作流

执行后复盘

此技能执行完成后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的指令或错误表格。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请相应更新用法示例和参数表格。
3. 是否需要变通处理？ — 如果你不得不临时调整（使用不同的标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时还需要采用相同的变通方法。

仅在问题确实存在且可复现时更新，不要基于猜测进行更新。