使用备份命令将自管理 ClickHouse 迁移到 ClickHouse Cloud

概述

将数据从自管理 ClickHouse（OSS）迁移到 ClickHouse Cloud 主要有两种方法：

使用 remoteSecure() 函数，直接拉取/推送数据。
通过云对象存储使用 BACKUP/RESTORE 命令。

本迁移指南重点介绍 BACKUP/RESTORE 方法，并提供一个通过 S3 bucket 将开源 ClickHouse 中的数据库或完整服务迁移到 Cloud 的实用示例。

先决条件

已安装 Docker
已有一个 S3 bucket 和 IAM 用户
能够创建一个新的 ClickHouse Cloud 服务

为便于读者跟随并复现本指南中的步骤，我们将使用一个 Docker Compose 配置，搭建一个包含两个分片、每个分片有两个副本的 ClickHouse 集群。

需要集群

这种备份方法要求使用 ClickHouse 集群，因为必须将表从 MergeTree 引擎转换为 ReplicatedMergeTree。如果你只运行单个实例，请改为按照"在自管理 ClickHouse 与 ClickHouse Cloud 之间使用 remoteSecure 进行迁移"中的步骤操作。

OSS 准备工作

我们首先会使用示例仓库中的一个 Docker Compose 配置来启动一个 ClickHouse 集群。如果你已经有一个正在运行的 ClickHouse 集群，可以跳过这一步。

将 examples 仓库克隆到本地环境。
在终端中 cd 到 examples/docker-compose-recipes/recipes/cluster_2S_2R。
确保 Docker 已在运行，然后启动 ClickHouse 集群：

docker compose up

你应该会看到：

[+] Running 7/7
 ✔ Container clickhouse-keeper-01  Created  0.1s
 ✔ Container clickhouse-keeper-02  Created  0.1s
 ✔ Container clickhouse-keeper-03  Created  0.1s
 ✔ Container clickhouse-01         Created  0.1s
 ✔ Container clickhouse-02         Created  0.1s
 ✔ Container clickhouse-04         Created  0.1s
 ✔ Container clickhouse-03         Created  0.1s

在该文件夹的根目录中打开一个新的终端窗口，并运行以下命令连接到集群的第一个节点：

docker exec -it clickhouse-01 clickhouse-client

创建示例数据

ClickHouse Cloud 使用 SharedMergeTree。在恢复备份时，ClickHouse 会自动将使用 ReplicatedMergeTree 的表转换为 SharedMergeTree 表。

如果您正在运行一个集群，您的表很可能已经在使用 ReplciatedMergeTree 引擎。如果没有，则需要在备份之前将所有 MergeTree 表转换为 ReplicatedMergeTree。

为了演示如何将 MergeTree 表转换为 ReplicatedMergeTree，我们将从一个 MergeTree 表开始，并在稍后将其转换为 ReplicatedMergeTree。我们将按照 New York taxi data guide 的前两步来创建一个示例表并向其中加载数据。为方便起见，这些步骤在下方再次列出。

运行以下命令以创建一个新数据库，并从 S3 存储桶中向一个新表插入数据：

CREATE DATABASE nyc_taxi;

CREATE TABLE nyc_taxi.trips_small (
    trip_id             UInt32,
    pickup_datetime     DateTime,
    dropoff_datetime    DateTime,
    pickup_longitude    Nullable(Float64),
    pickup_latitude     Nullable(Float64),
    dropoff_longitude   Nullable(Float64),
    dropoff_latitude    Nullable(Float64),
    passenger_count     UInt8,
    trip_distance       Float32,
    fare_amount         Float32,
    extra               Float32,
    tip_amount          Float32,
    tolls_amount        Float32,
    total_amount        Float32,
    payment_type        Enum('CSH' = 1, 'CRE' = 2, 'NOC' = 3, 'DIS' = 4, 'UNK' = 5),
    pickup_ntaname      LowCardinality(String),
    dropoff_ntaname     LowCardinality(String)
)
ENGINE = MergeTree
PRIMARY KEY (pickup_datetime, dropoff_datetime);

INSERT INTO nyc_taxi.trips_small
SELECT
    trip_id,
    pickup_datetime,
    dropoff_datetime,
    pickup_longitude,
    pickup_latitude,
    dropoff_longitude,
    dropoff_latitude,
    passenger_count,
    trip_distance,
    fare_amount,
    extra,
    tip_amount,
    tolls_amount,
    total_amount,
    payment_type,
    pickup_ntaname,
    dropoff_ntaname
FROM s3(
    'https://datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi/trips_{0..2}.gz',
    'TabSeparatedWithNames'
);

运行以下命令将该表 DETACH。

DETACH TABLE nyc_taxi.trips_small;

然后将其附加为副本：

ATTACH TABLE nyc_taxi.trips_small AS REPLICATED;

最后，恢复副本元数据：

SYSTEM RESTORE REPLICA nyc_taxi.trips_small;

检查是否已转换为 ReplicatedMergeTree：

SELECT engine
FROM system.tables
WHERE name = 'trips_small' AND database = 'nyc_taxi';

┌─engine──────────────┐
│ ReplicatedMergeTree │
└─────────────────────┘

现在，您已经可以继续配置 Cloud 服务，为稍后从 S3 存储桶中恢复备份做准备。

Cloud 准备工作

你将把数据恢复到一个新的 Cloud 服务中。按照以下步骤创建一个新的 Cloud 服务。

打开 Cloud 控制台

访问 https://console.clickhouse.cloud/

创建一个新服务

配置并创建服务

选择目标区域和配置，然后点击 Create service。

创建访问角色

打开 SQL 控制台。

设置 S3 访问

要从 S3 恢复备份，需要在 ClickHouse Cloud 与 S3 bucket 之间配置安全访问。

按照 "安全访问 S3 数据" 中的步骤创建访问角色并获取该角色的 ARN。
在 "如何创建 S3 bucket 和 IAM 角色" 中创建的 S3 bucket 策略基础上，添加上一步获得的角色 ARN。

更新后的 S3 bucket 策略类似如下：

{
    "Version": "2012-10-17",
    "Id": "Policy123456",
    "Statement": [
        {
            "Sid": "abc123",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
#highlight-start                  
                    "arn:aws:iam::123456789123:role/ClickHouseAccess-001",
                    "arn:aws:iam::123456789123:user/docs-s3-user"
#highlight-end                            
                ]
            },
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::ch-docs-s3-bucket",
                "arn:aws:s3:::ch-docs-s3-bucket/*"
            ]
        }
    ]
}

该策略包含两个 ARN：

IAM user (docs-s3-user)：允许自管理 ClickHouse 集群将数据备份到 S3
ClickHouse Cloud role (ClickHouseAccess-001)：允许 Cloud 服务从 S3 恢复数据

执行备份（在自管理部署中）

要对单个数据库进行备份，请在连接到 OSS 部署的 clickhouse-client 中运行以下命令：

BACKUP DATABASE nyc_taxi
TO S3(
  'BUCKET_URL',
  'KEY_ID',
  'SECRET_KEY'
)

将 BUCKET_URL、KEY_ID 和 SECRET_KEY 替换为您自己的 AWS 凭证。指南 "How to create an S3 bucket and IAM role" 介绍了在您尚未拥有这些凭证时如何获取它们。

如果一切配置正确，您会看到类似下面的响应，其中包含分配给该备份的唯一 ID 以及备份的状态。

Query id: efcaf053-75ed-4924-aeb1-525547ea8d45

┌─id───────────────────────────────────┬─status─────────┐
│ e73b99ab-f2a9-443a-80b4-533efe2d40b3 │ BACKUP_CREATED │
└──────────────────────────────────────┴────────────────┘

如果你检查之前空的 S3 存储桶，现在会看到其中已经出现了一些文件夹：

如果你正在执行完整迁移，则可以运行以下命令来备份整个服务器：

BACKUP
TABLE system.users,
TABLE system.roles,
TABLE system.settings_profiles,
TABLE system.row_policies,
TABLE system.quotas,
TABLE system.functions,
ALL EXCEPT DATABASES INFORMATION_SCHEMA, information_schema, system
TO S3(
  'BUCKET_ID',
  'KEY_ID',
  'SECRET_ID'
)
SETTINGS
  compression_method='lzma',
  compression_level=3;

上述命令备份的内容包括：

所有用户数据库和表
用户账户和密码
角色和权限
设置配置文件
行级策略
配额
用户定义函数

如果你使用的是其他云服务提供商（CSP），可以使用 TO S3()（适用于 AWS 和 GCP）以及 TO AzureBlobStorage() 语法。

对于非常大的数据库，建议使用 ASYNC 在后台执行备份：

BACKUP DATABASE my_database 
TO S3('https://your-bucket.s3.amazonaws.com/backup.zip', 'key', 'secret')
ASYNC;
       
-- Returns immediately with backup ID
-- Example result:
-- ┌─id──────────────────────────────────┬─status────────────┐
-- │ abc123-def456-789                   │ CREATING_BACKUP   │
-- └─────────────────────────────────────┴───────────────────┘

之后即可使用该备份 ID 来监控备份进度：

SELECT * 
FROM system.backups 
WHERE id = 'abc123-def456-789'

还可以执行增量备份。有关备份的一般信息，请参阅备份与恢复文档。

恢复到 ClickHouse Cloud

要恢复单个数据库，请在你的 Cloud 服务中运行以下查询，将其中的 AWS 凭证替换为你的实际值，并将 ROLE_ARN 设置为你在“安全访问 S3 数据”中按照步骤获取的输出值。

RESTORE DATABASE nyc_taxi
FROM S3(
    'BUCKET_URL',
    extra_credentials(role_arn = 'ROLE_ARN')
)

同样可以通过类似方式执行完整服务还原：

RESTORE
    TABLE system.users,
    TABLE system.roles,
    TABLE system.settings_profiles,
    TABLE system.row_policies,
    TABLE system.quotas,
    ALL EXCEPT DATABASES INFORMATION_SCHEMA, information_schema, system
FROM S3(
    'BUCKET_URL',
    extra_credentials(role_arn = 'ROLE_ARN')
)

现在在 Cloud 中运行以下查询，即可看到该数据库和表已经成功恢复到 Cloud：

SELECT count(*) FROM nyc_taxi.trips_small;
3000317

概述​

OSS 准备工作​

创建示例数据​

Cloud 准备工作​

打开 Cloud 控制台​

创建一个新服务​

配置并创建服务​

创建访问角色​

设置 S3 访问​

执行备份（在自管理部署中）​

恢复到 ClickHouse Cloud​

概述