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

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:

Task	Via SQL (CLI/HTTP)	Via Cloud Console
Create database user	CREATE USER	Supported
Grant permissions	GRANT	Supported
Delete user	DROP USER	Supported
Create API key	Not possible	Only 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 条目（工程密码库）

Item	Purpose
ClickHouse Cloud - API Key (Admin)	Cloud management API (console operations)
ClickHouse Cloud - API Key (Developer Read-only)	Cloud management API (read-only)
gapless-deribit-clickhouse	Database `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

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：创建应用用户

Retrieve
```
default
```
user credentials from 1Password
Create new user with appropriate permissions:

bash

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

从1Password获取
```
default
```
用户凭证
创建具备适当权限的新用户：

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!'"

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:

(single row with value 1)

bash

curl -s "https://user:password@HOST:443/" --data-binary "SELECT 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

用户创建后的后续步骤

After creating a ClickHouse user, invoke devops-tools:clickhouse-pydantic-config
to generate DBeaver configuration with the new credentials.

创建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

。

clickhouse-cloud-management

Original

Translation

ClickHouse Cloud Management

ClickHouse Cloud 管理

Overview

概述

When to Use This Skill

适用场景

Key Concepts

核心概念

Management Options

管理选项

Connection Details

连接详情

Password Requirements

密码要求

Quick Reference

快速参考

Create Read-Only User

创建只读用户

Grant Database Access

授予数据库访问权限

Delete User

删除用户

Credential Sources

凭证来源

1Password Items (Engineering Vault)

1Password 条目（工程密码库）

Retrieving Credentials

检索凭证

Database credentials (for SQL commands)

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

API key (for cloud management API)

API密钥（用于云管理API）

Common Workflows

常见工作流

Workflow 1: Create Application User

工作流1：创建应用用户

Create user

创建用户

Grant specific database access

授予特定数据库访问权限

Workflow 2: Verify User Exists

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

Workflow 3: Test Connection

工作流3：测试连接

Troubleshooting

故障排查

Authentication Failed

认证失败

Permission Denied

权限被拒绝

Connection Timeout

连接超时

Next Steps After User Creation

用户创建后的后续步骤

Additional Resources

额外资源

Reference Files

参考文件

Python Driver Policy

Python驱动策略

Related Skills

相关技能