디스크로/에서 BACKUP / RESTORE
디스크로/에서 BACKUP / RESTORE
ClickHouse 백업은 로컬 디스크나 S3 디스크 같은 저장 디스크로 생성할 수 있습니다. 이 문서에서는 Disk() 백업 엔진을 설정하고 테이블을 백업·복원하는 방법과 증분 백업, 암호화, tar 아카이브, 파티션 복원 같은 고급 기능을 설명할게요.
출처: 문서
본문
구문
-- 핵심 명령
BACKUP | RESTORE
--- 무엇을 백업/복원할지 (또는 제외할지)
TABLE [db.]table_name [AS [db.]table_name_in_backup] |
DICTIONARY [db.]dictionary_name [AS [db.]name_in_backup] |
DATABASE database_name [AS database_name_in_backup] |
TEMPORARY TABLE table_name [AS table_name_in_backup] |
VIEW view_name [AS view_name_in_backup] |
[EXCEPT TABLES ...] |
ALL [EXCEPT {TABLES|DATABASES}...] } [,...]
---
[ON CLUSTER 'cluster_name']
--- 어디에서 백업하거나 복원할지
TO|FROM
File('<path>/<filename>') |
Disk('<disk_name>', '<path>/') |
S3('<S3 endpoint>/<path>', '<Access key ID>', '<Secret access key>', '<extra_credentials>') |
AzureBlobStorage('<connection string>/<url>', '<container>', '<path>', '<account name>', '<account key>')
--- 추가 설정
[SETTINGS ...]
[ASYNC]
각 명령의 자세한 내용은 “명령 요약(command summary)”를 참고하세요.
디스크용 백업 대상 구성하기
로컬 디스크용 백업 대상 구성하기
아래 예제들에서 백업 대상이 Disk('backups', '1.zip')으로 지정된 것을 볼 수 있습니다. Disk 백업 엔진을 사용하려면 먼저 아래 경로에 백업 대상을 지정하는 파일을 추가해야 합니다:
/etc/clickhouse-server/config.d/backup_disk.xml
예를 들어 아래 구성은 backups라는 디스크를 정의한 다음 그 디스크를 backups 의 allowed_disk 목록에 추가합니다:
<clickhouse>
<storage_configuration>
<disks>
<backups>
<type>local</type>
<path>/backups/</path>
</backups>
</disks>
</storage_configuration>
<backups>
<allowed_disk>backups</allowed_disk>
<allowed_path>/backups/</allowed_path>
</backups>
</clickhouse>
S3 디스크용 백업 대상 구성하기
ClickHouse 스토리지 구성에 S3 디스크를 구성하여 S3로 BACKUP/RESTORE할 수도 있습니다. 로컬 디스크에서처럼 /etc/clickhouse-server/config.d에 파일을 추가해 디스크를 구성하세요.
<clickhouse>
<storage_configuration>
<disks>
<s3_plain>
<type>s3_plain</type>
<endpoint></endpoint>
<access_key_id></access_key_id>
<secret_access_key></secret_access_key>
</s3_plain>
</disks>
<policies>
<s3>
<volumes>
<main>
<disk>s3_plain</disk>
</main>
</volumes>
</s3>
</policies>
</storage_configuration>
<backups>
<allowed_disk>s3_plain</allowed_disk>
</backups>
</clickhouse>
S3 디스크에 대한 BACKUP/RESTORE는 로컬 디스크와 같은 방식으로 수행됩니다:
BACKUP TABLE data TO Disk('s3_plain', 'cloud_backup');
RESTORE TABLE data AS data_restored FROM Disk('s3_plain', 'cloud_backup');
- 이 디스크는
MergeTree자체에는 사용하지 말고BACKUP/RESTORE에만 사용해야 합니다. - 테이블이 S3 스토리지를 사용하고 디스크 타입이 다르면, 파츠를 대상 버킷으로 복사하기 위해
CopyObject호출을 사용하지 않고 다운로드·업로드하므로 매우 비효율적입니다. 이 경우BACKUP ... TO S3(<endpoint>)구문을 사용하는 것이 좋습니다.
로컬 디스크로 백업/복원하기 사용 예시
테이블 백업 및 복원
이 예제에서 백업과 복원할 테스트 데이터베이스와 테이블을 만들려면 아래 명령을 실행하세요.
데이터베이스와 테이블을 만듭니다:
CREATE DATABASE test_db;
CREATE TABLE test_db.test_table (
id UUID,
name String,
email String,
age UInt8,
salary UInt32,
created_at DateTime,
is_active UInt8,
department String,
score Float32,
country String
) ENGINE = MergeTree()
ORDER BY id;
천 행의 임의 데이터를 전처리하고 삽입합니다:
INSERT INTO test_table (id, name, email, age, salary, created_at, is_active, department, score, country)
SELECT
generateUUIDv4() as id,
concat('User_', toString(rand() % 10000)) as name,
concat('user', toString(rand() % 10000), '@example.com') as email,
18 + (rand() % 65) as age,
30000 + (rand() % 100000) as salary,
now() - toIntervalSecond(rand() % 31536000) as created_at,
rand() % 2 as is_active,
arrayElement(['Engineering', 'Marketing', 'Sales', 'HR', 'Finance', 'Operations'], (rand() % 6) + 1) as department,
rand() / 4294967295.0 * 100 as score,
arrayElement(['USA', 'UK', 'Germany', 'France', 'Canada', 'Australia', 'Japan', 'Brazil'], (rand() % 8) + 1) as country
FROM numbers(1000);
다음으로 아래 경로에 백업 대상을 지정하는 파일을 만들어야 합니다:
/etc/clickhouse-server/config.d/backup_disk.xml
<clickhouse>
<storage_configuration>
<disks>
<backups>
<type>local</type>
<path>/backups/</path> -- MacOS에서는 /Users/backups/ 선택
</backups>
</disks>
</storage_configuration>
<backups>
<allowed_disk>backups</allowed_disk>
<allowed_path>/backups/</allowed_path> -- MacOS에서는 /Users/backups/ 선택
</backups>
</clickhouse>
clickhouse-server가 실행 중이라면 변경 사항이 적용되도록 재시작해야 합니다.
테이블을 백업하려면 다음을 실행할 수 있습니다:
BACKUP TABLE test_db.test_table TO Disk('backups', '1.zip')
테이블이 비어 있다면 다음 명령으로 백업에서 복원할 수 있습니다. 위 RESTORE는 테이블 test.table에 데이터가 있으면 실패합니다. allow_non_empty_tables=true 설정은 RESTORE TABLE이 비어 있지 않은 테이블에 데이터를 삽입할 수 있게 합니다. 이는 테이블의 기존 데이터와 백업에서 추출한 데이터가 섞이게 됩니다. 따라서 이 설정은 테이블에서 데이터 중복을 유발할 수 있으므로 주의해서 사용해야 합니다.
테이블은 새 이름으로 복원하거나 백업할 수 있습니다. 이 백업의 백업 아카이브는 다음 구조를 가집니다.
zip 외의 다른 형식도 사용할 수 있습니다. 자세한 내용은 아래의 "tar 아카이브로 백업하기"를 참고하세요.
디스크로 증분 백업
ClickHouse에서 기본 백업(base backup)은 그다음의 증분 백업들이 만들어지는 초기 전체 백업입니다. 증분 백업은 기본 백업 이후의 변경 사항만 저장하므로, 어떤 증분 백업에서든 복원하려면 기본 백업을 계속 유지해야 합니다. 기본 백업 대상은 base_backup 설정으로 지정할 수 있습니다.
증분 백업은 기본 백업에 의존합니다. 증분 백업에서 복원하려면 기본 백업을 계속 사용할 수 있어야 합니다.
테이블의 증분 백업을 만들려면 먼저 기본 백업을 만드세요. 그런 다음 SETTINGS base_backup = ...을 지정하여 증분 백업을 만듭니다. 증분 백업과 기본 백업의 모든 데이터는 다음 명령으로 새 테이블 test_db.test_table2에 복원할 수 있습니다:
RESTORE TABLE test_db.test_table FROM Disk('backups', 'incremental.zip', base_1.zip') AS test_db.test_table2
백업 보안 설정하기
디스크에 쓰이는 백업에는 파일에 비밀번호를 적용할 수 있습니다. 비밀번호는 password 설정으로 지정할 수 있습니다.
비밀번호 보호는 ZIP 아카이브(.zip, .zipx)에서만 지원됩니다. 비밀번호가 허용되려면 백업 경로가 .zip 또는 .zipx로 끝나야 합니다. 다른 형식(예: tar 아카이브 및 비아카이브 경로)에서 비밀번호를 사용하면 BAD_ARGUMENTS 오류가 발생합니다: Password is not applicable, backup cannot be encrypted.
비밀번호로 보호된 백업을 복원하려면 password 설정으로 다시 비밀번호를 지정해야 합니다.
tar 아카이브로 백업하기
백업은 zip 아카이브로만 저장할 수 있는 것이 아니라 tar 아카이브로도 저장할 수 있습니다. 기능은 zip과 동일하며, tar 아카이브에서는 비밀번호 보호가 지원되지 않는다는 점만 다릅니다. 또한 tar 아카이브는 다양한 압축 방법을 지원합니다.
압축 방법을 변경하려면 백업 이름에 올바른 파일 접미사를 붙여야 합니다. 예를 들어 tar 아카이브를 gzip으로 압축하려면 .tar.gz 접미사를 사용하세요.
지원되는 압축 파일 접미사는:
tar.gz.tgztar.bz2tar.lzma.tar.zst.tzst.tar.xz
압축 설정
압축 방법과 압축 수준은 각각 compression_method와 compression_level 설정으로 지정할 수 있습니다.
특정 파티션 복원하기
테이블과 연관된 특정 파티션만 복원해야 한다면 그것들을 지정할 수 있습니다. 네 개의 파츠로 된 간단한 파티셔닝된 테이블을 만들고 데이터를 삽입한 다음 첫 번째와 네 번째 파티션만 백업해 보겠습니다. 파티션 1과 4를 백업하고 복원하려면 백업 쿼리에 PARTITION 절과 함께 BACKUP TABLE ... PARTITION ... TO Disk(...) 형태를 사용할 수 있습니다.