> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 클라우드 객체 스토리지를 사용하여 클라우드 네이티브 테이블의 경량 스냅샷을 생성하고 복원하는 방법을 설명합니다.

# 스냅샷 백업 및 복원

스냅샷 백업은 클라우드 네이티브 테이블 엔진을 위한 경량 백업 모드입니다. 데이터를 복사하는 대신 각 파트별 잠금 노드를 ClickHouse Keeper에 기록합니다. 이 잠금은 스냅샷이 유지되는 동안 서버가 참조된 객체 스토리지 파트를 삭제하지 못하게 합니다. 이후 백업은 데이터를 물리적으로 복사하는 대신 객체 스토리지 참조를 기록하므로, 테이블 크기와 관계없이 스냅샷을 빠르게 생성할 수 있습니다.

이 경량 방식은 [SharedMergeTree](/ko/products/cloud/features/infrastructure/shared-merge-tree), SharedSet, SharedJoin 테이블에 적용됩니다. Log 또는 Memory와 같은 다른 모든 엔진 유형에서는 백업이 자동으로 표준 복사 기반 백업으로 전환됩니다.

<div id="create-a-snapshot">
  ## 스냅샷 생성
</div>

스냅샷 백업은 `experimental_lightweight_snapshot = true`와 함께 표준 [`BACKUP`](/ko/concepts/features/backup-restore/overview#syntax) 명령을 사용합니다. `id` 설정은 필수이며, 스냅샷 이름을 지정하고 잠금 해제 및 관측성 명령에서 이를 참조하는 데 사용됩니다:

```sql theme={null}
BACKUP { TABLE [db.]table_name | DATABASE db_name | ALL [EXCEPT {TABLES | DATABASES} ...] }
TO { S3(...) | AzureBlobStorage(...) }
SETTINGS experimental_lightweight_snapshot = true, id = '<snapshot_id>'
```

이 명령은 `id`와 `status`를 반환하며, `id`를 사용해 [`system.backups`](/ko/reference/system-tables/backups)에서 작업을 추적할 수 있습니다.

단일 테이블을 S3로 백업합니다:

```sql theme={null}
BACKUP TABLE mydb.events
TO S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS experimental_lightweight_snapshot = true, id = 'events_snapshot_1'
```

전체 데이터베이스를 백업하세요:

```sql theme={null}
BACKUP DATABASE mydb
TO S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/mydb/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS experimental_lightweight_snapshot = true, id = 'mydb_snapshot_1'
```

테이블 하나를 제외하고 모두 백업합니다:

```sql theme={null}
BACKUP ALL
EXCEPT TABLES mydb.staging_table
TO S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/full/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS experimental_lightweight_snapshot = true, id = 'full_snapshot_1'
```

다음 명령은 Azure Blob Storage에서도 동일하게 사용할 수 있습니다:

```sql theme={null}
BACKUP TABLE mydb.events
TO AzureBlobStorage('DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=...', 'my-container', 'snapshots/events/')
SETTINGS experimental_lightweight_snapshot = true, id = 'events_snapshot_1'
```

<div id="restore-to-same-service">
  ## 동일한 서비스로 복원
</div>

스냅샷은 데이터 복사본이 아니라 객체 스토리지 파일에 대한 참조를 저장하므로, 새롭거나 다른 ClickHouse 서비스로 복원하려면 원본 객체 스토리지에 대한 액세스가 필요합니다. 따라서 서비스 간 복원은 SQL로는 지원되지 않으며 UI에서만 가능합니다. SQL에서는 `snapshot_from_current_service = 1`을 사용하여 외부 백업 버킷에서 동일한 서비스로 스냅샷을 복원할 수 있습니다. 이 경우 원격 스냅샷 리더를 거치지 않고 대상 디스크를 통해 객체를 직접 읽습니다:

```sql theme={null}
RESTORE TABLE mydb.events AS mydb.events_restored
FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS snapshot_from_current_service = 1
```

`AS` 절은 원본 테이블은 그대로 둔 채 새 테이블 이름으로 복원합니다. 원본 테이블을 덮어쓰려면 먼저 삭제하십시오:

```sql theme={null}
DROP TABLE mydb.events;

RESTORE TABLE mydb.events
FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS snapshot_from_current_service = 1
```

<div id="unlock-snapshot">
  ## 스냅샷 잠금 해제
</div>

각 스냅샷은 참조된 객체 스토리지 파일이 가비지 컬렉션되지 않도록 ClickHouse Keeper에 잠금을 유지합니다. 복원이 완료되었거나 스냅샷이 더 이상 필요하지 않으면 잠금을 해제하여 해당 잠금을 해제하십시오.

잠금 해제 방식은 두 가지입니다. 하나는 스냅샷의 모든 잠금을 한 번에 제거하는 시스템 수준 잠금 해제이고, 다른 하나는 나머지 스냅샷은 그대로 둔 채 단일 테이블의 잠금만 제거하는 테이블별 잠금 해제입니다.

**시스템 수준 잠금 해제** — 스냅샷의 모든 잠금을 제거합니다.

```sql theme={null}
SYSTEM UNLOCK SNAPSHOT '<snapshot_id>'
FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
```

**테이블별 잠금 해제** — 하나의 테이블에만 적용된 잠금을 해제합니다:

```sql theme={null}
ALTER TABLE mydb.events UNLOCK SNAPSHOT '<snapshot_id>'
FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
```

스냅샷 대상이 생성될 때 Keeper에 저장된 경우 `FROM` 절은 선택 사항입니다(`system.snapshot_locks`의 `info` 컬럼에서 확인할 수 있음):

```sql theme={null}
SYSTEM UNLOCK SNAPSHOT '<snapshot_id>'

-- 또는 테이블별:
ALTER TABLE mydb.events UNLOCK SNAPSHOT '<snapshot_id>'
```

잠금이 해제되면 해당 행은 `system.snapshot_locks`에서 사라지고, 다른 스냅샷에서 더 이상 참조되지 않는 파트는 `system.snapshot_parts`에서도 사라집니다.

<div id="observability">
  ## 관측성
</div>

<div id="system-backups">
  ### system.backups
</div>

모든 스냅샷 작업은 일반적인 백업 및 복원 작업과 함께 [`system.backups`](/ko/reference/system-tables/backups)에 표시됩니다. 설정한 `id`(또는 명령이 반환한 UUID)로 조회하십시오:

```sql theme={null}
SELECT id, name, status, error, start_time, end_time, num_files, uncompressed_size, compressed_size
FROM system.backups
WHERE id = 'events_snapshot_1'
FORMAT Vertical
```

```response theme={null}
Row 1:
──────
id:                events_snapshot_1
name:              S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', '[HIDDEN]')
status:            BACKUP_CREATED
error:
start_time:        2024-06-01 10:00:00
end_time:          2024-06-01 10:00:03
num_files:         42
uncompressed_size: 1073741824
compressed_size:   0
```

<div id="system-snapshot-locks">
  ### system.snapshot\_locks
</div>

`system.snapshot_locks`는 현재 Keeper에 등록된 커밋된 스냅샷을 보여줍니다. 스냅샷이 커밋되면 `/clickhouse/snapshot/committed/{snapshot_id}`에 Keeper 노드가 생성됩니다. 서버는 데이터 파트(data part)를 삭제하기 전에 커밋된 스냅샷이 해당 파트에 대한 잠금을 보유하고 있는지 확인합니다. 잠금이 있으면 삭제를 건너뜁니다. 잠금은 스냅샷을 명시적으로 잠금 해제할 때까지 유지됩니다.

```sql theme={null}
SELECT *
FROM system.snapshot_locks
```

| 컬럼          | 유형         | 설명                     |
| ----------- | ---------- | ---------------------- |
| `id`        | `String`   | 스냅샷 ID                 |
| `info`      | `String`   | 스냅샷 대상(예: `S3('...')`) |
| `ctime`     | `DateTime` | 이 잠금이 Keeper에 생성된 시점   |
| `lock_path` | `String`   | 이 잠금의 Keeper 경로        |

각 행은 커밋된 스냅샷 1개를 나타냅니다. 더 이상 유효한 backup destination이 없는 스냅샷 잠금이 보이면 `SYSTEM UNLOCK SNAPSHOT`을 실행하여 정리하십시오.

특정 스냅샷 잠금이 존재하는지 확인하려면:

```sql theme={null}
SELECT id, info, lock_path
FROM system.snapshot_locks
WHERE id = 'events_snapshot_1'
```

<div id="system-snapshot-parts">
  ### system.snapshot\_parts
</div>

`system.snapshot_parts`는 현재 하나 이상의 스냅샷 잠금에 의해 고정된 데이터 파트를 보여줍니다. 잠긴 각 파트마다 `/clickhouse/snapshot/{table_uuid}/{part_name}`에 해당 파트의 압축된 크기와 압축되지 않은 크기를 포함하는 Keeper 노드가 존재합니다. 이 테이블은 해당 노드를 읽어 현재 삭제되지 않도록 보호되고 있는 파트를 보여줍니다.

```sql theme={null}
SELECT *
FROM system.snapshot_parts
ORDER BY data_compressed_bytes DESC
LIMIT 20
```

| 컬럼                        | 유형       | 설명                       |
| ------------------------- | -------- | ------------------------ |
| `name`                    | `String` | 파트 이름                    |
| `table_id`                | `String` | 이 파트가 속한 테이블의 UUID       |
| `data_compressed_bytes`   | `UInt64` | 이 파트의 압축된 크기             |
| `data_uncompressed_bytes` | `UInt64` | 이 파트의 압축되지 않은 크기         |
| `snapshots_size`          | `UInt64` | 현재 이 파트에 잠금을 보유 중인 스냅샷 수 |

`snapshots_size > 1`인 파트는 여러 스냅샷에서 참조되며, 잠금을 보유한 모든 스냅샷이 잠금 해제될 때까지 객체 스토리지에서 제거되지 않습니다.

고정된 총 스토리지 사용량을 확인하려면:

```sql theme={null}
SELECT
    formatReadableSize(sum(data_compressed_bytes)) AS total_pinned_compressed,
    formatReadableSize(sum(data_uncompressed_bytes)) AS total_pinned_uncompressed,
    count() AS parts_count
FROM system.snapshot_parts
```

스냅샷으로 잠겨 있지만 이미 삭제되었거나 서버에서 더 이상 활성 상태가 아닌 파트, 즉 스냅샷 잠금 때문에만 객체 스토리지에 유지되는 데이터를 찾으려면:

```sql theme={null}
SELECT
    count(*),
    sum(data_uncompressed_bytes)
FROM system.snapshot_parts
WHERE (name, table_id) NOT IN (
    SELECT
        name,
        toString(tables.uuid)
    FROM system.parts
    INNER JOIN system.tables ON (parts.`table` = tables.name) AND parts.active
)
```

```response theme={null}
┌─count()─┬─sum(data_uncompressed_bytes)─┐
│    1000 │                        96037 │
└─────────┴──────────────────────────────┘
```

이는 원본 데이터가 변경되거나 삭제된 후에도 스냅샷을 유지할 때 발생하는 스토리지 오버헤드를 이해하는 데 유용합니다.

<div id="server-settings">
  ## 서버 설정
</div>

다음 서버 구성 매개변수는 스냅샷 동작을 제어합니다. 이 매개변수는 SQL이 아니라 서버 설정 파일에서 설정합니다.

| 설정                                                                                                                                       | 유형     | 기본값   | 재시작 없이 변경 가능 | 설명                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| [`max_held_snapshots`](/ko/reference/settings/server-settings/settings#max_held_snapshots)                                               | UInt64 | `0`   | 아니요          | 동시에 유지할 수 있는 경량 스냅샷의 최대 개수입니다. `0`은 무제한을 의미합니다. 한도에 도달하면 새 스냅샷을 생성할 때 예외가 발생합니다.                                     |
| [`max_snapshot_commit_thread_pool_size`](/ko/reference/settings/server-settings/settings#max_snapshot_commit_thread_pool_size)           | UInt64 | `64`  | 예            | 스냅샷 잠금 노드를 Keeper에 커밋하는 데 사용하는 스레드 수입니다. 파트가 많은 대규모 테이블에서 스냅샷 생성이 느리다면 이 값을 늘리십시오.                                   |
| [`max_snapshot_commit_thread_pool_free_size`](/ko/reference/settings/server-settings/settings#max_snapshot_commit_thread_pool_free_size) | UInt64 | `0`   | 예            | 스냅샷 커밋 풀의 유휴 스레드 수가 이 값을 초과하면 ClickHouse가 해당 스레드를 해제하고 풀 크기를 줄입니다. 필요할 때 스레드는 다시 생성됩니다. `0`은 유휴 스레드를 해제하지 않음을 의미합니다. |
| [`snapshot_cleaner_period`](/ko/reference/settings/server-settings/settings#snapshot_cleaner_period)                                     | UInt64 | `120` | 아니요          | 스냅샷 정리기가 어떤 스냅샷 잠금에서도 더 이상 참조되지 않는 파트를 제거하기 위해 실행되는 주기(초)입니다. ClickHouse Cloud에서만 사용할 수 있습니다.                        |
| [`snapshot_cleaner_pool_size`](/ko/reference/settings/server-settings/settings#snapshot_cleaner_pool_size)                               | UInt64 | `128` | 아니요          | 스냅샷 정리기 스레드 풀의 스레드 수입니다. ClickHouse Cloud에서만 사용할 수 있습니다.                                                             |