Set up docs MCP개요
자가 관리형 ClickHouse(OSS)에서 ClickHouse Cloud로 데이터를 마이그레이션하는 주요 방법은 두 가지입니다.
- 데이터를 직접 가져오거나 푸시하는
remoteSecure()함수를 사용하는 방법 - 클라우드 객체 스토리지를 통해
BACKUP/RESTORE명령을 사용하는 방법
이 마이그레이션 가이드는
BACKUP/RESTORE방식에 중점을 두며, 오픈 소스 ClickHouse의 데이터베이스 또는 전체 서비스를 S3 버킷을 통해 ClickHouse Cloud로 마이그레이션하는 실용적인 예시를 제공합니다.
사전 요구 사항
- Docker가 설치되어 있어야 합니다
- S3 버킷 및 IAM 사용자가 있어야 합니다
- 새 ClickHouse Cloud 서비스를 생성할 수 있어야 합니다
이 가이드의 단계를 쉽게 따라 하고 재현할 수 있도록, 2개의 세그먼트와 2개의 레플리카로 구성된 ClickHouse 클러스터용 Docker Compose 레시피 중 하나를 사용합니다.
OSS 준비
먼저 examples 리포지토리의 Docker Compose 구성을 사용해 ClickHouse 클러스터를 구동합니다. 이미 실행 중인 ClickHouse 클러스터가 있다면 클러스터를 구동하는 단계는 건너뛰어도 됩니다.
- examples 리포지토리를 로컬 머신에 복제합니다
- 터미널에서
examples/docker-compose-recipes/recipes/cluster_2S_2R디렉터리로cd합니다 - 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-clientMergeTree 테이블에서 ReplicatedMergeTree 테이블로
ClickHouse Cloud는 SharedMergeTree를 사용합니다.
Backup을 복원할 때 ClickHouse는 ReplicatedMergeTree 테이블을 자동으로 SharedMergeTree 테이블로 변환합니다.
클러스터를 실행 중이라면 이미 테이블에서 ReplicatedMergeTree 엔진을 사용하고 있을 가능성이 높습니다.
그렇지 않다면 Backup을 수행하기 전에 MergeTree 테이블을 ReplicatedMergeTree로 변환해야 합니다.
MergeTree 테이블을 ReplicatedMergeTree로 변환하는 방법을 보여주기 위해 먼저 MergeTree 테이블로 시작한 다음, 이를 나중에 ReplicatedMergeTree로 변환하겠습니다.
새 샘플 테이블을 생성하고 데이터를 적재하기 위해 New York taxi data guide의 처음 두 단계를 따르겠습니다.
편의를 위해 해당 단계도 아래에 포함되어 있습니다.
다음 명령을 실행하여 새 데이터베이스를 생성하고 S3 버킷의 데이터를 새 테이블에 삽입합니다:
CREATE DATABASE nyc_taxi;
CREATE TABLE nyc_taxi.trips_small_adapted (
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_adapted
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_adapted;그런 다음 이를 복제된 테이블로 ATTACH합니다:
ATTACH TABLE nyc_taxi.trips_small_adapted AS REPLICATED;마지막으로, 레플리카 메타데이터를 복원합니다:
SYSTEM RESTORE REPLICA nyc_taxi.trips_small_adapted;ReplicatedMergeTree로 변환되었는지 확인하세요:
SELECT engine
FROM system.tables
WHERE name = 'trips_small_adapted' AND database = 'nyc_taxi';┌─engine──────────────┐
│ ReplicatedMergeTree │
└─────────────────────┘이제 나중에 S3 버킷의 백업을 복원할 수 있도록 Cloud 서비스를 설정할 준비가 되었습니다.
ReplicatedMergeTree를 사용하는 분산 테이블
구성에서 여러 세그먼트에 걸쳐 분산 테이블을 사용하는 경우, 각 노드에 로컬 ReplicatedMergeTree 테이블이 필요하며, 쿼리 진입점 역할을 하는 Distributed 테이블도 필요합니다.
다음 명령을 실행하여 모든 클러스터 노드에 로컬 복제된 테이블을 생성하세요:
CREATE DATABASE IF NOT EXISTS nyc_taxi ON CLUSTER 'cluster_2S_2R';
CREATE TABLE nyc_taxi.trips_small_dist_local ON CLUSTER 'cluster_2S_2R'
(
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 = ReplicatedMergeTree('/clickhouse/tables/{database}/{table}/{shard}', '{replica}')
PRIMARY KEY (pickup_datetime, dropoff_datetime);그런 다음 이를 기반으로 Distributed 테이블을 생성합니다:
CREATE TABLE nyc_taxi.trips_small_dist ON CLUSTER 'cluster_2S_2R'
(
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 = Distributed('cluster_2S_2R', 'nyc_taxi', 'trips_small_dist_local', rand());분산 테이블을 통해 데이터를 삽입하세요:
INSERT INTO nyc_taxi.trips_small_dist
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'
);Cloud 준비
데이터를 새 Cloud 서비스로 복원하게 됩니다. 아래 단계에 따라 새 Cloud 서비스를 생성하십시오.
Cloud Console 열기
https://console.clickhouse.cloud/로 이동하십시오.
새 서비스 생성
서비스 구성 및 생성
원하는 리전과 구성을 선택한 다음 Create service를 클릭하십시오.
액세스 역할 생성
SQL 콘솔을 여십시오
S3 액세스 설정
S3에서 Backup을 복원하려면 ClickHouse Cloud와 S3 버킷 간의 보안 액세스를 구성해야 합니다.
-
"S3 데이터에 안전하게 액세스하기"의 단계에 따라 액세스 역할을 생성하고 role ARN을 가져오십시오.
-
이전 단계에서 얻은 role ARN을 추가하여 "S3 버킷 및 IAM role 생성 방법"에서 생성한 S3 버킷 정책을 업데이트하십시오.
업데이트된 S3 버킷 정책은 다음과 비슷합니다.
{
"Version": "2012-10-17",
"Id": "Policy123456",
"Statement": [
{
"Sid": "abc123",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::123456789123:role/ClickHouseAccess-001",
"arn:aws:iam::123456789123:user/docs-s3-user"
]
},
"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에 Backup할 수 있도록 허용합니다. - ClickHouse Cloud role (
ClickHouseAccess-001): Cloud 서비스가 S3에서 복원할 수 있도록 허용합니다.
Backup 수행하기(자가 관리형 배포)
각 세그먼트는 개별적으로 Backup해야 합니다. 각 세그먼트의 노드에 연결한 후, 세그먼트별로 고유한 대상 경로를 사용해 Backup 명령을 실행하십시오.
BUCKET_URL, KEY_ID, SECRET_KEY를 보유한 AWS 자격 증명으로 교체하십시오.
아직 없다면 가이드 "S3 버킷 및 IAM role 생성 방법"에서
이를 준비하는 방법을 확인할 수 있습니다.
세그먼트 1:
BACKUP DATABASE nyc_taxi
TO S3(
'BUCKET_URL/backup_s1.zip',
'KEY_ID',
'SECRET_KEY'
)세그먼트 2:
BACKUP DATABASE nyc_taxi
TO S3(
'BUCKET_URL/backup_s2.zip',
'KEY_ID',
'SECRET_KEY'
)모든 것이 올바르게 구성되어 있으면 아래와 유사한 응답이 표시되며 여기에는 Backup에 할당된 고유 ID와 Backup 상태가 포함됩니다.
Query id: efcaf053-75ed-4924-aeb1-525547ea8d45
┌─id───────────────────────────────────┬─status─────────┐
│ e73b99ab-f2a9-443a-80b4-533efe2d40b3 │ BACKUP_CREATED │
└──────────────────────────────────────┴────────────────┘이제 앞서 비어 있던 S3 버킷을 확인하면 몇 개의 폴더가 생성된 것을 볼 수 있습니다:
전체 마이그레이션을 수행하는 경우에는, 다음 명령으로 전체 서버를 Backup할 수 있습니다:
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;위 명령은 다음 항목을 Backup합니다:
- 모든 사용자 데이터베이스와 테이블
- 사용자 계정과 비밀번호
- 역할 및 권한
- 설정 프로필
- 행 정책
- 쿼터
- 사용자 정의 함수
다른 클라우드 서비스 제공업체(CSP)를 사용하는 경우 TO S3()(AWS와 GCP 모두) 및 TO AzureBlobStorage() 구문을 사용할 수 있습니다.
데이터베이스가 매우 큰 경우 Backup을 백그라운드에서 실행하도록 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 │
-- └─────────────────────────────────────┴───────────────────┘그런 다음 Backup ID를 사용하여 Backup 진행 상태를 모니터링할 수 있습니다:
SELECT *
FROM system.backups
WHERE id = 'abc123-def456-789'증분 Backup도 생성할 수 있습니다. Backup 전반에 대한 자세한 내용은 Backup 및 복원 문서를 참조하십시오.
ClickHouse Cloud로 복원
각 세그먼트의 Backup을 하나씩 순서대로 Cloud 서비스에 복원합니다. ROLE_ARN은
"S3 데이터에 안전하게 액세스하기"에서 얻은
값으로 설정합니다.
두 번째 복원부터(그리고 그 이후의 모든 복원에서도) 충돌로 실패하지 않고 세그먼트 데이터가 이미 복원된 테이블에
추가되도록 SETTINGS allow_non_empty_tables=true를 사용합니다.
세그먼트 1:
RESTORE DATABASE nyc_taxi
FROM S3(
'BUCKET_URL/backup_s1.zip',
extra_credentials(role_arn = 'ROLE_ARN')
)세그먼트 2:
RESTORE DATABASE nyc_taxi
FROM S3(
'BUCKET_URL/backup_s2.zip',
extra_credentials(role_arn = 'ROLE_ARN')
)
SETTINGS allow_non_empty_tables=true;전체 서비스도 비슷한 방식으로 복원할 수 있습니다:
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에서 데이터가 사용 가능한지 확인할 수 있습니다.
-- ClickHouse Cloud가 로컬 테이블의 모든 데이터를 복원합니다
SELECT count() from nyc_taxi.trips_small_dist_local;
3000317ClickHouse Cloud는 내부적으로 SharedMergeTree를 사용하므로 기존 분산 테이블은 더 이상 필요하지 않습니다. 이를 삭제하고, 쿼리에서 기존 테이블 이름을 그대로 사용할 수 있도록 뷰로 대체할 수 있습니다:
DROP TABLE drop table nyc_taxi.trips_small_dist;
CREATE VIEW nyc_taxi.trips_small_dist AS SELECT * FROM nyc_taxi.trips_small_dist_local;
SELECT count() from nyc_taxi.trips_small_dist;
3000317분산형이 아닌 ReplicatedMergeTree 테이블은 SharedMergeTree로 복원됩니다:
SELECT count() FROM nyc_taxi.trips_small_adapted;
3000317