1. clickhouse-backup 설치 및 환경 설정

ClickHouse의 물리적 백업 및 복구를 효율적으로 수행하기 위해 clickhouse-backup 도구를 설치하고 구성하는 방법입니다.

1.1 바이너리 다운로드 및 설치

cd /opt/downloads/
wget https://github.com/Altinity/clickhouse-backup/releases/download/v2.4.33/clickhouse-backup-linux-amd64.tar.gz

mkdir -pv /opt/clickhouse-backup
tar xvf clickhouse-backup-linux-amd64.tar.gz -C /opt/clickhouse-backup/

ln -sv /opt/clickhouse-backup/build/linux/amd64/clickhouse-backup /usr/local/bin

1.2 설치 확인

clickhouse-backup -v

1.3 구성 파일 작성

ClickHouse 서버의 데이터 저장 경로가 기본값(/var/lib/clickhouse)과 다를 경우, 구성 파일에서 data_path를 반드시 명시해야 합니다.

mkdir -p /etc/clickhouse-backup/
cd /etc/clickhouse-backup/
vim config.yml

config.yml에 다음 내용을 추가합니다.

general:
  remote_storage: none
  backups_to_keep_local: 14
  backups_to_keep_remote: 60
clickhouse:
  username: admin_user
  password: "SecurePass123!"
  host: localhost
  port: 9000
  data_path: "/mnt/data/clickhouse_storage"

2. 데이터 백업 수행

2.1 백업 가능한 테이블 조회

clickhouse-backup tables

2.2 단일 테이블 백업

특정 테이블만 백업할 수 있으며, 백업 이름은 직접 지정할 수 있습니다. 백업 파일은 $data_path/backup 디렉토리에 생성되며, metadata(DDL SQL)와 shadow(FREEZE된 데이터) 디렉토리로 구성됩니다.

clickhouse-backup create -t analytics_db.user_sessions user_sessions_bak_20241015

2.3 다중 테이블 백업

쉼표(,)로 구분하여 여러 테이블을 동시에 백업할 수 있습니다.

clickhouse-backup create -t analytics_db.user_sessions,analytics_db.page_views multi_tables_bak_20241015

2.4 전체 데이터베이스 백업

clickhouse-backup create full_db_backup_20241015

2.5 백업 목록 조회 및 관리

# 백업 목록 확인
clickhouse-backup list

# 로컬 백업 파일 삭제
clickhouse-backup delete local user_sessions_bak_20241015

# shadow 디렉토리의 임시 파일 정리
clickhouse-backup clean

3. 데이터 복구 및 문제 해결

3.1 단일 테이블 복구 및 UUID 충돌 해결

백업된 데이터를 복구할 때 기존 테이블의 UUID와 충돌이 발생할 수 있습니다.

clickhouse-backup restore user_sessions_bak_20241010

만약 다음과 같은 오류가 발생한다면:

error can't create table `analytics_db`.`user_sessions_bak_20241010`: code: 57, message: Directory for table data store/.../ already exists after 1 times, please check your schema dependencies

해결 방법: 백업 메타데이터 JSON 파일($data_path/backup/user_sessions_bak_20241010/metadata/analytics_db/user_sessions_bak_20241010.json)을 열어 충돌을 일으키는 UUID 관련 경로나 값을 제거한 후, 복구 명령어를 다시 실행합니다.

3.2 전체 데이터베이스 복구

전체 복구를 수행할 때는 기존 데이터베이스가 완전히 삭제된 상태여야 합니다. 그렇지 않으면 위와 유사한 디렉토리 충돌 오류가 발생할 수 있습니다.

clickhouse-backup restore full_db_backup_20241015

3.3 선택적 복구 (스키마 또는 데이터)

테이블 구조만 복구하거나 데이터만 복구할 수 있습니다. 단, --data 옵션은 ATTACH PARTITION을 사용하므로 중복 실행 시 데이터가 중복 추가될 수 있습니다.

# 스키마만 복구
clickhouse-backup restore full_db_backup_20241015 --table analytics_db.user_sessions --schema

# 데이터만 복구
clickhouse-backup restore full_db_backup_20241015 --table analytics_db.user_sessions --data

3.4 복구 시나리오 테스트

다음은 테스트용 데이터를 생성하고 삭제 후 복구하는 시나리오입니다.

CREATE DATABASE IF NOT EXISTS ecommerce_db;

CREATE TABLE IF NOT EXISTS ecommerce_db.order_history
(
  order_id Int64 COMMENT '주문 ID', 
  order_date DateTime COMMENT '주문 일시',
  product_name String COMMENT '상품명',
  amount Decimal32(2) COMMENT '결제 금액',
  customer_id Int64 COMMENT '고객 ID'
) ENGINE = MergeTree 
PARTITION BY toYYYYMM(order_date)
ORDER BY order_id;

INSERT INTO ecommerce_db.order_history VALUES 
(1, '2023-05-10 09:15:00', '무선 마우스', 25000, 1001),
(2, '2023-06-12 14:30:00', '기계식 키보드', 120000, 1002),
(3, '2023-07-20 18:45:00', '모니터', 350000, 1001);

-- 데이터 삭제 및 테이블 드롭 후 복구 테스트
ALTER TABLE ecommerce_db.order_history DELETE WHERE order_id = 2;
TRUNCATE TABLE ecommerce_db.order_history;
DROP TABLE ecommerce_db.order_history;
DROP DATABASE ecommerce_db;

4. 자동화 및 스케줄링

4.1 백업 스크립트 작성

mkdir -pv /opt/scripts/clickhouse/
vim /opt/scripts/clickhouse/daily_full_backup.sh

스크립트 내용은 다음과 같이 작성합니다.

#!/bin/bash
BACKUP_NAME="full_backup_$(date +%Y-%m-%d_%H-%M-%S)"
/usr/local/bin/clickhouse-backup create ${BACKUP_NAME}

실행 권한을 부여합니다.

chmod +x /opt/scripts/clickhouse/daily_full_backup.sh

4.2 크론탭(crontab) 등록

매일 새벽 2시에 백업 스크립트가 자동 실행되도록 스케줄링합니다.

crontab -e

0 2 * * * /opt/scripts/clickhouse/daily_full_backup.sh >> /var/log/clickhouse_backup.log 2>&1