clickhousectl-cloud-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deploy to ClickHouse Cloud

部署到ClickHouse Cloud

This skill walks through deploying to ClickHouse Cloud using

clickhousectl

. It covers account setup, CLI authentication, service creation, schema migration, and connecting your application. Follow these steps in order.

本技能介绍如何使用

clickhousectl

部署到ClickHouse Cloud，内容覆盖账号设置、CLI身份验证、服务创建、schema迁移以及应用连接，你需要按顺序执行以下步骤。

When to Apply

适用场景

Use this skill when the user wants to:

Deploy their ClickHouse application to production
Host ClickHouse as a managed cloud service
Migrate from a local ClickHouse setup to ClickHouse Cloud
Create a ClickHouse Cloud service
Set up ClickHouse Cloud for the first time

当用户有以下需求时使用本技能：

将他们的ClickHouse应用部署到生产环境
将ClickHouse作为托管云服务运行
从本地ClickHouse部署环境迁移到ClickHouse Cloud
创建ClickHouse Cloud服务
首次搭建ClickHouse Cloud环境

Step 1: Sign up for ClickHouse Cloud

步骤1：注册ClickHouse Cloud账号

Before using any cloud commands, the user needs a ClickHouse Cloud account.

Ask the user: "Do you already have a ClickHouse Cloud account?"

If they do not have an account, explain:

ClickHouse Cloud is a fully managed service that runs ClickHouse for you — no infrastructure to maintain, automatic scaling, backups, and upgrades included. There's a free trial so you can get started without a credit card.

To create an account, go to: https://clickhouse.cloud

Sign up with your email, Google, or GitHub account. Once you're in the console, let me know and we'll continue with the next step.

Wait for the user to confirm they have signed up or already have an account before proceeding.

在使用任何云命令之前，用户需要有一个ClickHouse Cloud账号。

询问用户："你是否已经拥有ClickHouse Cloud账号？"

如果他们没有账号，解释：

ClickHouse Cloud是一款全托管服务，为你运行ClickHouse，无需维护基础设施，包含自动扩缩容、备份和升级能力。平台提供免费试用，你无需信用卡即可上手。

要创建账号，请访问：https://clickhouse.cloud

使用邮箱、Google或GitHub账号注册。进入控制台后请告知我，我们继续执行下一步。

等待用户确认已完成注册或已有账号后再继续操作。

Step 2: Authenticate the CLI

步骤2：CLI身份验证

First, ensure

clickhousectl

is installed. Check with:

bash

which clickhousectl

If not found, install it:

bash

curl -fsSL https://clickhouse.com/cli | sh

Now authenticate. There are three options — choose based on the situation:

首先确保已安装

clickhousectl

，执行以下命令检查：

bash

which clickhousectl

如果未找到，执行安装：

bash

curl -fsSL https://clickhouse.com/cli | sh

现在开始身份验证，有三种选项，根据场景选择：

Option A: Browser login (preferred)

选项A：浏览器登录（推荐）

This is the best option when a human is available to open a browser. It uses OAuth device flow — no API keys needed.

Instruct the user to run:

bash

clickhousectl cloud login

This prints a URL and a code. The user opens the URL in their browser, confirms the code, and logs in with their ClickHouse Cloud account. The CLI automatically receives credentials once the browser flow completes.

当有操作人员可以打开浏览器时这是最佳选择，使用OAuth设备流，无需API密钥。

指导用户执行：

bash

clickhousectl cloud login

这会输出一个URL和验证码，用户在浏览器中打开该URL，确认验证码，然后登录自己的ClickHouse Cloud账号。浏览器流程完成后，CLI会自动获取凭证。

Option B: Non-interactive API key auth (for headless/CI environments)

选项B：非交互式API密钥验证（适用于无头/CI环境）

If there is no human in the loop (e.g., CI/CD, automated scripts), use API key authentication. Both

--api-key

and

--api-secret

are required — if the user provides one without the other, tell them both are needed.

bash

clickhousectl cloud login --api-key <key> --api-secret <secret>

If the user doesn't have API keys yet, guide them to create one:

In the ClickHouse Cloud console:

Click the gear icon (Settings) in the left sidebar

Go to API Keys

Click Create API Key

Give it a name (e.g., "cli") and select the Admin role

Click Generate API Key

Copy both the Key ID and the Key Secret — the secret is only shown once

To verify authentication works:

bash

clickhousectl cloud org list

This should return the user's organization.

如果没有人工参与（比如CI/CD、自动化脚本），使用API密钥验证。

--api-key

和

--api-secret

两个参数都为必填，如果用户只提供了其中一个，告知需要同时提供两个参数。

bash

clickhousectl cloud login --api-key <key> --api-secret <secret>

如果用户还没有API密钥，指导他们创建：

在ClickHouse Cloud控制台中：

点击左侧边栏的齿轮图标（设置）

进入API Keys页面

点击Create API Key

为密钥命名（比如"cli"）并选择Admin角色

点击Generate API Key

复制Key ID和Key Secret——密钥仅会展示一次

验证身份验证是否生效：

bash

clickhousectl cloud org list

这应该会返回用户的组织信息。

Step 3: Create a cloud service

步骤3：创建云服务

Create a new ClickHouse Cloud service:

bash

clickhousectl cloud service create --name <service-name>

The output includes the service ID and default user password — note it for subsequent commands.

Wait for the service to be ready. After creation, the service takes a moment to provision. Check its status:

bash

clickhousectl cloud service get <service-id>

You can grep the "state" field to see if it is "running".

创建新的ClickHouse Cloud服务：

bash

clickhousectl cloud service create --name <service-name>

输出内容包含服务ID和默认用户密码——请记录下来用于后续命令。

等待服务就绪。 创建完成后，服务需要一点时间完成资源配置，检查其状态：

bash

clickhousectl cloud service get <service-id>

你可以grep "state"字段查看是否为"running"。

Step 4: Migrate schemas

步骤4：迁移schemas

If the user has local table definitions (e.g., from using the

clickhousectl-local-dev

skill), migrate them to the cloud service.

Use

cloud service client

to run queries against the cloud service — it looks up the endpoint, port, and TLS settings automatically. You just need the service name (or

--id

) and the password from step 3.

Read the local schema files from

clickhouse/tables/

and apply each one to the cloud service:

bash

clickhousectl cloud service client --name <service-name> \
  --queries-file clickhouse/tables/<table>.sql

Apply them in dependency order — tables referenced by materialized views should be created first.

Also apply materialized views if they exist:

bash

clickhousectl cloud service client --name <service-name> \
  --queries-file clickhouse/materialized_views/<view>.sql

The

--user

flag defaults to

default

. If the user has a different database user, pass

--user <username>

如果用户有本地表定义（比如使用过

clickhousectl-local-dev

技能），将其迁移到云服务。

使用

cloud service client

对云服务执行查询——它会自动查找端点、端口和TLS配置，你只需要服务名称（或

--id

）和步骤3中得到的密码。

读取
clickhouse/tables/
下的本地schema文件，将每个文件应用到云服务：

bash

clickhousectl cloud service client --name <service-name> \
  --queries-file clickhouse/tables/<table>.sql

按依赖顺序应用——被物化视图引用的表需要优先创建。

如果存在物化视图也需要应用：

bash

clickhousectl cloud service client --name <service-name> \
  --queries-file clickhouse/materialized_views/<view>.sql

--user

参数默认为

default

，如果用户有其他数据库用户，传入

--user <username>

。

Step 5: Verify the deployment

步骤5：验证部署

Connect to the cloud service and confirm tables exist:

bash

clickhousectl cloud service client --name <service-name> --query "SHOW TABLES"

Run a test query to confirm the schema is correct:

bash

clickhousectl cloud service client --name <service-name> --query "DESCRIBE TABLE <table-name>"

连接到云服务确认表存在：

bash

clickhousectl cloud service client --name <service-name> --query "SHOW TABLES"

执行测试查询确认schema正确：

bash

clickhousectl cloud service client --name <service-name> --query "DESCRIBE TABLE <table-name>"

Step 6: Update application config

步骤6：更新应用配置

Retrieve the service endpoint for the user's application config:

bash

clickhousectl cloud service get <service-id>

Provide the user with the connection details:

Host: from the service
```
get
```
output
Port:
```
8443
```
for HTTPS /
```
9440
```
for native TLS
User:
```
default
```
Password: the password from step 3 (service creation)
SSL/TLS: required (always enabled on Cloud)

Example connection strings (adapt to the user's language/framework):

Python (clickhouse-connect):

python

import clickhouse_connect

client = clickhouse_connect.get_client(
    host='<cloud-host>',
    port=8443,
    username='default',
    password='<password>',
    secure=True
)

Node.js (@clickhouse/client):

javascript

import { createClient } from '@clickhouse/client'

const client = createClient({
  url: 'https://<cloud-host>:8443',
  username: 'default',
  password: '<password>',
})

Go (clickhouse-go):

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{"<cloud-host>:9440"},
    Auth: clickhouse.Auth{
        Username: "default",
        Password: "<password>",
    },
    TLS: &tls.Config{},
})

Suggest the user store the password in an environment variable or secrets manager rather than hardcoding it.

Suggest the user should not use the default user in production. A user should be created just for their app.

获取服务端点用于用户的应用配置：

bash

clickhousectl cloud service get <service-id>

为用户提供连接详情：

**主机地址：**来自服务
```
get
```
命令的输出
**端口：**HTTPS用
```
8443
```
/ 原生TLS用
```
9440
```
用户名：
```
default
```
**密码：**步骤3（服务创建）中得到的密码
**SSL/TLS：**必填（Cloud上始终开启）

示例连接字符串（适配用户的语言/框架）：

Python (clickhouse-connect):

python

import clickhouse_connect

client = clickhouse_connect.get_client(
    host='<cloud-host>',
    port=8443,
    username='default',
    password='<password>',
    secure=True
)

Node.js (@clickhouse/client):

javascript

import { createClient } from '@clickhouse/client'

const client = createClient({
  url: 'https://<cloud-host>:8443',
  username: 'default',
  password: '<password>',
})

Go (clickhouse-go):

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{"<cloud-host>:9440"},
    Auth: clickhouse.Auth{
        Username: "default",
        Password: "<password>",
    },
    TLS: &tls.Config{},
})

建议用户将密码存储在环境变量或密钥管理器中，不要硬编码。

建议用户生产环境不要使用默认用户，应该为应用单独创建用户。