메인 콘텐츠로 건너뛰기

​
구문

-- 핵심 명령어
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]
각 명령에 대한 자세한 내용은 “명령 요약”을 확인하십시오.

​
디스크용 백업 대상 구성

​
로컬 디스크용 백업 대상 구성

아래 예시에서는 백업 대상이 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 storage를 사용하고 디스크 유형이 서로 다르면, 파트를 대상 버킷으로 복사할 때 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;
무작위 데이터 1,000행을 삽입합니다:
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가 실행 중이면 변경 사항을 적용하려면 다시 시작해야 합니다.
테이블을 백업하려면 다음 명령을 실행하세요:
Query
BACKUP TABLE test_db.test_table TO Disk('backups', '1.zip')
Response
   ┌─id───────────────────────────────────┬─status─────────┐
1. │ 065a8baf-9db7-4393-9c3f-ba04d1e76bcd │ BACKUP_CREATED │
   └──────────────────────────────────────┴────────────────┘
테이블이 비어 있으면 다음 명령으로 백업에서 테이블을 복원할 수 있습니다:
Query
RESTORE TABLE test_db.test_table FROM Disk('backups', '1.zip')
Response
   ┌─id───────────────────────────────────┬─status───┐
1. │ f29c753f-a7f2-4118-898e-0e4600cd2797 │ RESTORED │
   └──────────────────────────────────────┴──────────┘
위 RESTORE는 테이블 test.table에 데이터가 있으면 실패합니다. 설정 allow_non_empty_tables=true를 사용하면 RESTORE TABLE이 비어 있지 않은 테이블에도 데이터를 삽입할 수 있습니다. 이 경우 테이블에 있던 기존 데이터와 백업에서 추출한 데이터가 섞이게 됩니다. 따라서 이 설정은 테이블에 데이터 중복을 일으킬 수 있으므로 주의해서 사용해야 합니다.
이미 데이터가 있는 테이블을 복원하려면 다음을 실행하세요: 
RESTORE TABLE test_db.test_table FROM Disk('backups', '1.zip')
SETTINGS allow_non_empty_tables=true
새 이름으로 테이블을 복원하거나 백업할 수 있습니다: 
RESTORE TABLE test_db.test_table AS test_db.test_table_renamed FROM Disk('backups', '1.zip')
이 백업의 아카이브는 다음과 같은 구조입니다: 
├── .backup
└── metadata
    └── test_db
        └── test_table.sql
zip 외의 포맷도 사용할 수 있습니다. 자세한 내용은 아래의 “tar 아카이브 형식의 백업”을 참조하십시오.

​
디스크로의 증분 백업

ClickHouse에서 기준 백업은 이후의 증분 백업을 생성하는 기준이 되는 최초의 전체 백업입니다. 증분 백업은 기준 백업 이후의 변경 사항만 저장하므로, 어떤 증분 백업에서든 복원할 수 있도록 기준 백업을 계속 사용할 수 있는 상태로 유지해야 합니다. 기준 백업 대상은 setting base_backup으로 설정할 수 있습니다.
증분 백업은 기준 백업에 의존합니다. 증분 백업에서 복원할 수 있으려면 기준 백업을 계속 사용할 수 있는 상태로 유지해야 합니다.
테이블의 증분 백업을 만들려면 먼저 기준 백업을 만드십시오: 
BACKUP TABLE test_db.test_table TO Disk('backups', 'd.zip')

BACKUP TABLE test_db.test_table TO Disk('backups', 'incremental-a.zip')
SETTINGS base_backup = Disk('backups', 'd.zip')
증분 백업과 기준 백업의 모든 데이터는 다음 명령을 사용해 새 테이블 test_db.test_table2로 복원할 수 있습니다: 
RESTORE TABLE test_db.test_table AS test_db.test_table2
FROM Disk('backups', 'incremental-a.zip');

​
Backup 보안 설정

디스크에 기록되는 Backup 파일에는 비밀번호를 설정할 수 있습니다. 비밀번호는 password 설정을 사용하여 지정할 수 있습니다.
비밀번호 보호는 ZIP 아카이브(.zip, .zipx)에서만 지원됩니다. 비밀번호가 적용되려면 Backup 경로가 .zip 또는 .zipx로 끝나야 합니다. tar 아카이브 및 아카이브가 아닌 경로를 포함한 다른 포맷에서 비밀번호를 사용하면 BAD_ARGUMENTS 오류가 발생합니다: Password is not applicable, backup cannot be encrypted.
BACKUP TABLE test_db.test_table
TO Disk('backups', 'password-protected.zip')
SETTINGS password='qwerty'
비밀번호로 보호된 백업을 복원하려면 비밀번호를 다시 password 설정으로 지정해야 합니다: 
RESTORE TABLE test_db.test_table
FROM Disk('backups', 'password-protected.zip')
SETTINGS password='qwerty'

​
tar 아카이브 형식의 백업

백업은 zip 아카이브뿐만 아니라 tar 아카이브로도 저장할 수 있습니다. 기능은 zip과 동일하지만, tar 아카이브에서는 비밀번호 보호가 지원되지 않습니다. 또한 tar 아카이브는 다양한 압축 방식을 지원합니다. 테이블을 tar 형식으로 백업하려면: 
BACKUP TABLE test_db.test_table TO Disk('backups', '1.tar')
tar 아카이브에서 복원하려면: 
RESTORE TABLE test_db.test_table FROM Disk('backups', '1.tar')
압축 방법을 변경하려면 올바른 파일 접미사를 백업 이름 뒤에 추가해야 합니다. 예를 들어 tar 아카이브를 gzip으로 압축하려면 다음을 실행하세요: 
BACKUP TABLE test_db.test_table TO Disk('backups', '1.tar.gz')
지원되는 압축 파일 확장자는 다음과 같습니다:
  • tar.gz
  • .tgz
  • tar.bz2
  • tar.lzma
  • .tar.zst
  • .tzst
  • .tar.xz

​
압축 설정

압축 메서드와 압축 수준은 각각 compression_method 및 compression_level 설정을 사용해 지정할 수 있습니다. 
BACKUP TABLE test_db.test_table
TO Disk('backups', 'filename.zip')
SETTINGS compression_method='lzma', compression_level=3

​
특정 파티션 복원

테이블에 속한 특정 파티션만 복원해야 하는 경우 해당 파티션을 지정할 수 있습니다. 4개의 파티션으로 이루어진 간단한 테이블을 만들고 데이터를 삽입한 다음, 첫 번째와 네 번째 파티션만 백업해 보겠습니다: 
CREATE IF NOT EXISTS test_db;
       
-- 파티션된 테이블 생성
CREATE TABLE test_db.partitioned (
    id UInt32,
    data String,
    partition_key UInt8
) ENGINE = MergeTree()
PARTITION BY partition_key
ORDER BY id;

INSERT INTO test_db.partitioned VALUES
(1, 'data1', 1),
(2, 'data2', 2),
(3, 'data3', 3),
(4, 'data4', 4);

SELECT count() FROM test_db.partitioned;

SELECT partition_key, count() 
FROM test_db.partitioned
GROUP BY partition_key
ORDER BY partition_key;

   ┌─count()─┐
1. │       4 │
   └─────────┘
   ┌─partition_key─┬─count()─┐
1. │             1 │       1 │
2. │             2 │       1 │
3. │             3 │       1 │
4. │             4 │       1 │
   └───────────────┴─────────┘
다음 명령을 실행하여 파티션 1과 4를 백업합니다: 
BACKUP TABLE test_db.partitioned PARTITIONS '1', '4'
TO Disk('backups', 'partitioned.zip')
다음 명령을 실행하여 1번과 4번 파티션을 복원하세요: 
RESTORE TABLE test_db.partitioned PARTITIONS '1', '4'
FROM Disk('backups', 'partitioned.zip')
SETTINGS allow_non_empty_tables=true
마지막 수정일 2026년 6월 10일