백업과 복원, 업그레이드 (BACKUP TO S3, LTS 주기, 호환성 설정)

백업이 필요한 이유 (복제가 있어도)

복제본은 하드웨어 장애를 막지만 DROP TABLE 과 잘못된 뮤테이션은 모든 복제본에 그대로 퍼집니다. 백업은 사람의 실수와 논리적 손상에서 돌아오는 유일한 길입니다. TTL 로 지운 데이터도 백업에서만 돌아옵니다 (TTL, 디스크 티어링).

ClickHouse 백업 방법은 세 가지가 있었고, 지금은 내장 BACKUP 문이 표준입니다.

BACKUP 문 쓰기

먼저 백업 대상 저장소를 허용합니다. S3 는 설정 없이 URL 과 키로 바로 쓸 수 있고, 로컬 디스크는 allowed_disk 또는 allowed_path 에 적어야 합니다.

<clickhouse>
    <backups>
        <allowed_disk>backups</allowed_disk>
        <allowed_path>/backups/</allowed_path>
    </backups>
</clickhouse>

-- 테이블 하나를 S3 로
BACKUP TABLE logs.events
    TO S3('https://my-bucket.s3.ap-northeast-2.amazonaws.com/ch-backups/events-20261021/',
          'AKIA...', 'secret...');

-- 데이터베이스 전체, 비동기
BACKUP DATABASE logs TO S3('https://.../ch-backups/logs-20261021/') ASYNC;

-- 서버 전체 (system 테이블은 빠짐)
BACKUP ALL EXCEPT DATABASE tmp TO Disk('backups', 'all-20261021.zip');

자격 증명은 쿼리에 박지 말고 네임드 컬렉션에 둡니다.

CREATE NAMED COLLECTION backup_s3 AS
    url = 'https://my-bucket.s3.ap-northeast-2.amazonaws.com/ch-backups/',
    access_key_id = 'AKIA...', secret_access_key = 'secret...';

BACKUP TABLE logs.events TO S3(backup_s3, 'events-20261021/');

증분 백업

base_backup 을 주면 그 백업 이후에 생긴 파트만 올립니다. 복원은 증분 백업만 지정해도 베이스를 따라가 전체를 되살립니다.

BACKUP TABLE logs.events TO S3(backup_s3, 'events-20261022/')
    SETTINGS base_backup = S3(backup_s3, 'events-20261021/');

매일 증분, 매주 전체로 두면 S3 비용과 복원 시간이 균형을 잡습니다. 증분 사슬이 길어지면 복원이 느려지므로 주 1 회는 베이스를 새로 잡습니다.

상태 확인

SELECT id, name, status, error, start_time, end_time,
       formatReadableSize(total_size) AS size, num_files, uncompressed_size, compressed_size
FROM system.backups
ORDER BY start_time DESC
LIMIT 10;

status 는 CREATING_BACKUP, BACKUP_CREATED, BACKUP_FAILED, RESTORING, RESTORED, RESTORE_FAILED 중 하나입니다. 실패하면 error 에 이유가 있습니다. 복제 테이블을 ON CLUSTER 로 백업하면 샤드별로 한 복제본만 파트를 올립니다.

RESTORE

-- 같은 이름으로 (대상 테이블이 없어야 함)
RESTORE TABLE logs.events FROM S3(backup_s3, 'events-20261022/');

-- 다른 이름으로 복원해 비교
RESTORE TABLE logs.events AS logs.events_restored FROM S3(backup_s3, 'events-20261022/');

-- 구조만, 또는 이미 있는 테이블에 덧붙이기
RESTORE TABLE logs.events FROM ... SETTINGS structure_only = 1;
RESTORE TABLE logs.events FROM ... SETTINGS allow_non_empty_tables = 1;

• 복제 테이블을 복원하면 한 복제본에만 파트가 들어가고 나머지는 복제로 받아 옵니다. 복제본 수만큼 네트워크가 움직입니다.
• 복원 뒤 SELECT count(), sum(cityHash64(*)) 로 원본과 비교하는 습관을 둡니다.
• 복원 테스트를 분기마다 해 봅니다. "백업은 있는데 복원이 안 되는" 경우의 대부분은 권한과 네임드 컬렉션 접근입니다.

팁 백업 전에 SYSTEM SYNC REPLICA 로 큐를 비우고, 적재가 멈춘 시간대를 고르면 "어느 시점의 스냅숏" 인지 분명해집니다. 백업은 테이블 단위로 일관되지만 테이블 사이의 일관성은 보장하지 않습니다.

Cloud 의 백업

ClickHouse Cloud 는 서비스마다 자동 백업을 돕니다. 기본은 하루 한 번이고 보존 기간은 티어마다 다릅니다. Scale 과 Enterprise 티어는 콘솔이나 API 에서 주기와 보존 기간과 시작 시각을 바꿀 수 있고, 백업을 내 계정의 S3, GCS, Azure 버킷으로 내보내는 기능도 있습니다. 복원은 "같은 리전에 새 서비스로 복원" 방식입니다. 기존 서비스에 덧쓰지 않으므로 복원 뒤 테이블을 옮기거나 서비스를 바꿔 끼웁니다. 자세한 것은 BYOC, 백업, API, Terraform 문서에 있습니다.

릴리스 주기와 어느 버전을 쓸지

• 운영 클러스터는 LTS 를 따라가고, 두 LTS 사이에 한 번 업그레이드하는 흐름이 가장 단순합니다.
• .1 처럼 끝 숫자가 작은 첫 빌드보다 몇 주 지난 패치 버전을 고릅니다. 패치 릴리스는 버그 수정만 들어갑니다.
• 2026 년 릴리스마다 무엇이 바뀌었는지는 2026년 ClickHouse 주요 변화에 있습니다.

업그레이드 절차 (셀프 호스팅)

1. 변경 사항을 읽습니다. 특히 "Backward Incompatible Change" 절과 바뀐 기본 설정값. 업그레이드 뒤 system.settings_changes 로도 확인됩니다.
2. 스테이징에서 같은 버전으로 올려 보고, 핵심 쿼리의 결과와 실행 시간을 비교합니다.
3. 백업을 하나 더 만듭니다. 새 버전이 쓴 파트 포맷은 옛 버전이 못 읽을 수 있어 다운그레이드가 항상 되지는 않습니다.
4. 복제본을 하나씩 올립니다(롤링). 한 노드를 SYSTEM SHUTDOWN 또는 서비스 중지, 패키지 교체, 시작, system.replicas 에서 큐가 비고 absolute_delay 가 돌아오면 다음 노드. 중간 상태에서는 옛 버전과 새 버전이 섞여 있어도 복제가 됩니다.
5. 올린 뒤 며칠간 system.errors, 쿼리 p95, 머지 속도를 봅니다.

# Debian/Ubuntu 예
sudo apt-get update
sudo apt-get install clickhouse-server=26.8.5.12 clickhouse-client=26.8.5.12 \
    clickhouse-common-static=26.8.5.12
sudo systemctl restart clickhouse-server
clickhouse-client -q "SELECT version()"

• 두 버전의 차이가 1 년을 넘으면 중간 LTS 를 거쳐 단계적으로 올립니다. 그 안이면 한 번에 올려도 됩니다.
• 샤드가 여러 개면 샤드 안의 복제본부터, 그다음 샤드로 넘어갑니다. Keeper 는 ClickHouse 와 따로 올리되 호환 범위를 확인합니다.

compatibility 설정

새 버전의 기본값 변경이 쿼리 결과나 성능을 바꿀까 걱정되면 compatibility 를 옛 버전으로 두고 올립니다. 그 버전의 기본 설정값으로 동작하게 묶어 주는 설정입니다.

-- 사용자 프로필 또는 config 의 default profile 에
SET compatibility = '25.8';
SELECT name, value FROM system.settings WHERE changed AND name != 'compatibility';

업그레이드 뒤 안정되면 compatibility 를 걷어 내고 바뀐 기본값을 하나씩 받아들입니다. 어떤 설정이 어느 버전에서 바뀌었는지는 system.settings_changes 에 적혀 있습니다.

Cloud 의 업그레이드

Cloud 는 ClickHouse 가 자동으로 올립니다. 서비스마다 릴리스 채널(빠름, 보통, 느림)과 업그레이드가 일어날 시간 창을 고를 수 있고, 운영 서비스는 "느림" 채널과 야간 창이 보통의 선택입니다. 업그레이드 중에도 서비스는 복제본 단위로 돌아가며 올라가 쿼리가 끊기지 않습니다. 옵션은 ClickHouse Cloud 개요에 있습니다.

체크리스트

• 백업: 매일 증분, 매주 전체, 분기마다 복원 연습, 자격 증명은 네임드 컬렉션.
• system.backups 의 BACKUP_FAILED 에 경보 (모니터링).
• 운영은 LTS, 패치 버전은 몇 주 지난 것.
• 업그레이드 전 백업, 스테이징 검증, 롤링, compatibility 로 단계적 수용.
• 변경 사항 중 "Backward Incompatible" 은 티켓에 옮겨 적고 담당자를 둡니다.

공식 문서

• BACKUP and RESTORE
• system.backups
• Named collections
• ClickHouse release schedule (stable, LTS)
• Update ClickHouse (self-managed)
• compatibility 설정