Back to Details

clickhouse-cloud-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ClickHouse Cloud Management

ClickHouse Cloud 管理

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

Overview

概述

ClickHouse Cloud user and permission management via SQL commands over HTTP interface. This skill covers database user creation, permission grants, and credential management for ClickHouse Cloud instances.
通过HTTP接口执行SQL命令来管理ClickHouse Cloud的用户与权限。该技能涵盖ClickHouse Cloud实例的数据库用户创建、权限授予以及凭证管理。

When to Use This Skill

适用场景

Invoke this skill when:
  • Creating database users for ClickHouse Cloud
  • Managing user permissions (GRANT/REVOKE)
  • Testing ClickHouse Cloud connectivity
  • Troubleshooting authentication issues
  • Understanding API key vs database user distinction
在以下场景中调用该技能：
  • 为ClickHouse Cloud创建数据库用户
  • 管理用户权限（GRANT/REVOKE操作）
  • 测试ClickHouse Cloud连接性
  • 排查认证问题
  • 理解API密钥与数据库用户的区别

Key Concepts

核心概念

Management Options

管理选项

ClickHouse Cloud provides two management interfaces with different capabilities:
TaskVia SQL (CLI/HTTP)Via Cloud Console
Create database userCREATE USERSupported
Grant permissionsGRANTSupported
Delete userDROP USERSupported
Create API keyNot possibleOnly here
Key distinction: Database users (created via SQL) authenticate to ClickHouse itself. API keys (created via console) authenticate to the ClickHouse Cloud management API.
ClickHouse Cloud提供两种具备不同能力的管理界面：
任务通过SQL（CLI/HTTP）通过云控制台
创建数据库用户CREATE USER支持
授予权限GRANT支持
删除用户DROP USER支持
创建API密钥无法实现仅在此处操作
关键区别：通过SQL创建的数据库用户用于向ClickHouse本身认证。通过控制台创建的API密钥用于向ClickHouse Cloud管理API认证。

Connection Details

连接详情

ClickHouse Cloud exposes only HTTP interface publicly:
  • Port: 443 (HTTPS)
  • Protocol: HTTP (not native ClickHouse protocol)
  • Native protocol: Requires AWS PrivateLink (not available without enterprise setup)
ClickHouse Cloud仅公开HTTP接口：
  • 端口：443（HTTPS）
  • 协议：HTTP（非原生ClickHouse协议）
  • 原生协议：需要AWS PrivateLink（无企业配置则无法使用）

Password Requirements

密码要求

ClickHouse Cloud enforces strong password policy:
  • Minimum 12 characters
  • At least 1 uppercase letter
  • At least 1 special character
Example compliant password: 
StrongPass@2025!
ClickHouse Cloud强制执行强密码策略：
  • 至少12个字符
  • 至少1个大写字母
  • 至少1个特殊字符
合规密码示例：
StrongPass@2025!

Quick Reference

快速参考

Create Read-Only User

创建只读用户

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

Grant Database Access

授予数据库访问权限

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

Delete User

删除用户

bash
curl -s "https://default:PASSWORD@HOST:443/" --data-binary \
  "DROP USER my_reader"
For comprehensive SQL patterns and advanced permission scenarios, see SQL Patterns Reference.
bash
curl -s "https://default:PASSWORD@HOST:443/" --data-binary \
  "DROP USER my_reader"
如需完整的SQL模式和高级权限场景，请参阅SQL模式参考。

Credential Sources

凭证来源

1Password Items (Engineering Vault)

1Password 条目（工程密码库）

ItemPurpose
ClickHouse Cloud - API Key (Admin)Cloud management API (console operations)
ClickHouse Cloud - API Key (Developer Read-only)Cloud management API (read-only)
gapless-deribit-clickhouseDatabase 
default
user credentials
条目用途
ClickHouse Cloud - API Key (Admin)云管理API（控制台操作）
ClickHouse Cloud - API Key (Developer Read-only)云管理API（只读）
gapless-deribit-clickhouse数据库
default
用户凭证

Retrieving Credentials

检索凭证

bash
undefined
bash
undefined

Database credentials (for SQL commands)

数据库凭证（用于SQL命令）

op item get "gapless-deribit-clickhouse" --vault Engineering --reveal
op item get "gapless-deribit-clickhouse" --vault Engineering --reveal

API key (for cloud management API)

API密钥（用于云管理API）

op item get "ClickHouse Cloud - API Key (Admin)" --vault Engineering --reveal
undefined
op item get "ClickHouse Cloud - API Key (Admin)" --vault Engineering --reveal
undefined

Common Workflows

常见工作流

Workflow 1: Create Application User

工作流1：创建应用用户

  1. Retrieve 
    default
    user credentials from 1Password
  2. Create new user with appropriate permissions:
bash
HOST="your-instance.clickhouse.cloud"
PASSWORD="default-user-password"
  1. 从1Password获取
    default
    用户凭证
  2. 创建具备适当权限的新用户：
bash
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!'"
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"
undefined
curl -s "https://default:$PASSWORD@$HOST:443/" --data-binary
"GRANT SELECT, INSERT ON mydb.* TO app_user"
undefined

Workflow 2: Verify User Exists

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

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

Workflow 3: Test Connection

工作流3：测试连接

bash
curl -s "https://user:password@HOST:443/" --data-binary "SELECT 1"
Expected output: 
1
(single row with value 1)
bash
curl -s "https://user:password@HOST:443/" --data-binary "SELECT 1"
预期输出：
1
（单行值为1）

Troubleshooting

故障排查

Authentication Failed

认证失败

  • Verify password meets complexity requirements
  • Check host URL includes port 443
  • Ensure using HTTPS (not HTTP)
  • 验证密码是否符合复杂度要求
  • 检查主机URL是否包含端口443
  • 确保使用HTTPS（而非HTTP）

Permission Denied

权限被拒绝

  • Verify user has required GRANT statements
  • Check database and table names are correct
  • Confirm user was created with correct settings
  • 验证用户是否拥有所需的GRANT语句
  • 检查数据库和表名是否正确
  • 确认用户创建时配置正确

Connection Timeout

连接超时

  • ClickHouse Cloud only exposes port 443 publicly
  • Native protocol (port 9440) requires PrivateLink
  • Use HTTP interface with curl or clickhouse-client HTTP mode
  • ClickHouse Cloud仅公开端口443
  • 原生协议（端口9440）需要PrivateLink
  • 使用curl或clickhouse-client的HTTP模式通过HTTP接口连接

Next Steps After User Creation

用户创建后的后续步骤

<!-- ADR: 2025-12-10-clickhouse-skill-delegation -->
After creating a ClickHouse user, invoke 
devops-tools:clickhouse-pydantic-config
 to generate DBeaver configuration with the new credentials.
<!-- ADR: 2025-12-10-clickhouse-skill-delegation -->
创建ClickHouse用户后，调用**
devops-tools:clickhouse-pydantic-config
**来生成包含新凭证的DBeaver配置。

Additional Resources

额外资源

Reference Files

参考文件

For detailed patterns and advanced techniques, consult:
  • references/sql-patterns.md - Complete SQL syntax reference with examples
如需详细的模式和高级技术，请查阅：
  • references/sql-patterns.md - 包含示例的完整SQL语法参考

Python Driver Policy

Python驱动策略

For Python application code connecting to ClickHouse Cloud, use 
clickhouse-connect
(official HTTP driver). See 
clickhouse-architect
 for recommended code patterns and why to avoid 
clickhouse-driver
(community).
对于连接ClickHouse Cloud的Python应用代码，请使用
clickhouse-connect
（官方HTTP驱动）。有关推荐的代码模式以及为何避免使用
clickhouse-driver
（社区版），请参阅
clickhouse-architect
。

Related Skills

相关技能

  • quality-tools:clickhouse-architect
    - Schema design, compression codecs, Python driver policy
  • devops-tools:clickhouse-pydantic-config
    - DBeaver configuration generation
  • devops-tools:doppler-secret-validation
    - For storing credentials in Doppler
  • devops-tools:doppler-workflows
    - For credential rotation workflows
  • quality-tools:clickhouse-architect
    - Schema设计、压缩编解码器、Python驱动策略
  • devops-tools:clickhouse-pydantic-config
    - DBeaver配置生成
  • devops-tools:doppler-secret-validation
    - 用于在Doppler中存储凭证
  • devops-tools:doppler-workflows
    - 用于凭证轮换工作流