ClickHouse のバックアップと復元

このセクションでは、ClickHouse におけるバックアップと復元の概要を説明します。各バックアップ方法のより詳細な説明については、サイドバーにある各方法のページを参照してください。

はじめに

レプリケーションはハードウェア障害に対する保護を提供しますが、人的ミスまでは防げません。たとえば、データの誤削除、誤ったテーブルの削除、誤ったクラスター上のテーブルの削除、さらに不正なデータ処理やデータ破損を引き起こすソフトウェアバグなどです。

多くの場合、このようなミスはすべてのレプリカに影響します。ClickHouse には一部の種類のミスを防ぐための組み込みの安全策があります。たとえば、デフォルトでは、50 Gb を超えるデータを含む MergeTree ファミリーのエンジンを使用するテーブルをそのまま削除することはできません。とはいえ、こうした安全策ですべてのケースをカバーできるわけではなく、問題が発生する可能性は残ります。

想定される人的ミスを効果的に軽減するには、データのバックアップと復元のための戦略をあらかじめ慎重に準備しておく必要があります。

利用できるリソースや業務要件は会社ごとに異なるため、あらゆる状況に適した ClickHouse のバックアップと復元の万能な解決策は存在しません。1 ギガバイトのデータに有効な方法が、数十 PB のデータには通用しない可能性があります。考えられるアプローチにはそれぞれ長所と短所があり、このドキュメントのこのセクションで紹介しています。さまざまな欠点を補うために、1 つだけでなく複数のアプローチを併用することをお勧めします。

以下のページでは、ClickHouse で利用可能なさまざまなバックアップおよび復元方法について詳しく説明しています。

Page	Description
ローカルディスクまたは S3 disk を使用したバックアップ/復元	ローカルディスクまたは S3 disk への、またはそれらからのバックアップ/復元について詳しく説明します
S3 エンドポイントを使用したバックアップ/復元	S3 エンドポイントへの、またはそこからのバックアップ/復元について詳しく説明します
AzureBlobStorage を使用したバックアップ/復元	Azure blob storage への、またはそこからのバックアップ/復元について詳しく説明します
代替手法	代替のバックアップ方法について説明します
スナップショットバックアップ	クラウドオブジェクトストレージを使用する SharedMergeTree テーブル向けの軽量スナップショット

バックアップは次のように分類できます。

フルまたは増分
同期または非同期
同時実行または非同時実行
圧縮または非圧縮
named collections を使用
パスワードで保護
システムテーブル、ログテーブル、またはアクセス管理テーブルのバックアップを取得

バックアップの種類

バックアップには、フルバックアップと増分バックアップがあります。フルバックアップはデータの完全なコピーであり、増分バックアップは直近のフルバックアップ以降に変更されたデータの差分です。

フルバックアップには、単純で独立性が高く (ほかのバックアップに依存せず) 、信頼性の高い復旧方法であるという利点があります。ただし、完了までに時間がかかる場合があり、多くの容量を消費することもあります。一方、増分バックアップは時間と容量の両面でより効率的ですが、データを復元するには、関連するバックアップがすべて利用可能である必要があります。

要件に応じて、次の方法を検討できます。

フルバックアップ: 小規模なデータベースや重要なデータ向け。
増分バックアップ: 大規模なデータベース向け、またはバックアップを高頻度かつコスト効率よく実行する必要がある場合。
両方: たとえば、毎週フルバックアップを実行し、毎日増分バックアップを実行します。

同期バックアップと非同期バックアップ

BACKUP コマンドと RESTORE コマンドには、ASYNC を指定することもできます。この場合、バックアップコマンドはすぐに制御を返し、バックアップ処理はバックグラウンドで実行されます。コマンドに ASYNC を指定しない場合、バックアップ処理は同期的に実行され、バックアップが完了するまでコマンドは待機します。

同時実行バックアップと非同時実行バックアップ

デフォルトでは、ClickHouse はバックアップと復元の同時実行を許可しています。つまり、複数のバックアップまたは復元操作を同時に開始できます。ただし、この動作を無効にできるサーバーレベルの設定もあります。これらの設定を false にすると、クラスター上で同時に実行できるバックアップまたは復元操作は 1 つだけになります。これにより、リソースの競合や、操作間で発生しうる競合を回避しやすくなります。

バックアップ/復元の同時実行を無効にするには、それぞれ次の設定を使用できます:

<clickhouse>
    <backups>
        <allow_concurrent_backups>false</allow_concurrent_backups>
        <allow_concurrent_restores>false</allow_concurrent_restores>
    </backups>
</clickhouse>

両方のデフォルト値は true であるため、デフォルトではバックアップ/復元の同時実行が許可されています。クラスターでこれらの設定が false の場合、そのクラスターでは一度に実行できるバックアップ/復元は 1 つだけです。

圧縮バックアップと非圧縮バックアップ

ClickHouse のバックアップでは、compression_method および compression_level 設定により圧縮を利用できます。

バックアップの作成時には、以下を指定できます。

BACKUP TABLE test.table
  TO Disk('backups', 'filename.zip')
  SETTINGS compression_method='lzma', compression_level=3

named collections の使用

named collections を使用すると、バックアップ/復元操作で再利用できるキー・バリューの組 (S3 の認証情報、エンドポイント、設定など) を保存できます。これにより、次のことが可能になります。

管理者アクセス権のないユーザーに認証情報を見せない
複雑な構成を一元管理して、コマンドを簡素化する
操作間の一貫性を保つ
クエリログに認証情報が露出するのを防ぐ

詳細については、"named collections" を参照してください。

システム、ログ、またはアクセス管理テーブルのバックアップ

システムテーブルもバックアップおよび復元のワークフローに含めることができますが、含めるかどうかは、具体的なユースケースによって異なります。

_log 接尾辞を持つもの (たとえば query_log、part_log) など、履歴データを格納するシステムテーブルは、他のテーブルと同様にバックアップおよび復元できます。ユースケース上、履歴データの分析が必要な場合、たとえば query_log を使ってクエリのパフォーマンスを追跡したり問題をデバッグしたりする場合は、これらのテーブルをバックアップ戦略に含めることを推奨します。ただし、これらのテーブルの履歴データが不要であれば、バックアップの保存容量を節約するために除外できます。

users、ロール、row_policies、 settings_profiles、quotas などのアクセス管理に関連するシステムテーブルは、バックアップおよび復元操作時に特別な扱いを受けます。これらのテーブルがバックアップに含まれると、その内容は特別な accessXX.txt ファイルにエクスポートされ、このファイルにはアクセスエンティティの作成と設定に対応する SQL ステートメントがまとめられます。復元時には、復元処理がこれらのファイルを解釈し、SQL コマンドを再適用して users、ロール、その他の設定を再作成します。この機能により、 ClickHouse クラスターのアクセス制御設定を、クラスター全体の構成の一部としてバックアップおよび復元できます。

この機能は、SQL コマンドで管理される構成に対してのみ動作します ("SQL-driven Access Control and Account Management" と呼ばれます) 。 ClickHouse server の設定ファイル (例: users.xml) で定義されたアクセス設定はバックアップに含まれず、この方法では復元できません。

基本構文

-- コアコマンド
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	Description
`BACKUP`	指定したオブジェクトのバックアップを作成します
`RESTORE`	バックアップからオブジェクトを復元します
`TABLE [db.]table_name [AS [db.]table_name_in_backup]`	特定のテーブルをバックアップまたは復元します (名前の変更可)
`[PARTITION[S] partition_expr [,...]]`	テーブルの特定のパーティションのみをバックアップまたは復元します
`DICTIONARY [db.]dictionary_name [AS [db.]name_in_backup]`	Dictionaryオブジェクトをバックアップまたは復元します
`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`	すべて (すべてのデータベース、テーブルなど) をバックアップまたは復元します。ClickHouse バージョン 23.4 より前では、`ALL` は `RESTORE` コマンドでのみ使用可能でした。
`[EXCEPT {TABLES\|DATABASES}...]`	`ALL` 使用時に特定のテーブルまたはデータベースを除外します
`[ON CLUSTER 'cluster_name']`	ClickHouse クラスター全体でバックアップまたは復元を実行します
`TO\|FROM`	方向：バックアップの宛先には `TO`、復元元には `FROM` を使用します
`File('<path>/<filename>')`	ローカルファイルシステムに保存、またはローカルファイルシステムから復元します
`Disk('<disk_name>', '<path>/')`	設定済みディスクに保存、または設定済みディスクから復元します
`S3('<S3 endpoint>/<path>', '<Access key ID>', '<Secret access key>')`	Amazon S3 または S3-compatible ストレージに保存、またはそこから復元します
`[SETTINGS ...]`	Settings の完全な一覧は以下を参照してください
`[ASYNC]`	操作を非同期で実行します (すぐに制御が返り、監視可能な ID が返されます)

設定

共通のバックアップ／復元設定

設定	説明	デフォルト値
`id`	バックアップまたは復元操作の ID です。指定しない場合は、ランダムに生成された UUID が使用されます。すでに同じ ID の操作が実行中の場合は、例外がスローされます。
`compression_method`	バックアップの圧縮方式を指定します。"カラム圧縮コーデック"のセクションを参照してください
`compression_level`	バックアップの圧縮レベルを指定します
`password`	バックアップアーカイブのパスワード。ZIPアーカイブ (`.zip`、`.zipx`) でのみ使用できます。
`base_backup`	増分バックアップに使用するベースバックアップの宛先。例: `Disk('backups', '1.zip')`
`use_same_password_for_base_backup`	base backup アーカイブがクエリのパスワードを引き継ぐかどうかを指定します。
`structure_only`	有効にすると、実際のテーブルデータは含めず、CREATE ステートメントのみをバックアップまたは復元します。
`restore_table_data`	テーブルのデータを復元するかどうかを指定します。`RESTORE`コマンドでのみ使用できます。未設定の場合、デフォルトは `NOT structure_only` になります。明示的に設定すると `structure_only` をオーバーライドします。"復元設定"を参照してください。
`restore_access_entities`	アクセスエンティティ (ユーザー、ロール、設定プロファイル、行ポリシー、クォータ) を復元するかどうかを指定します。`RESTORE`コマンドでのみ使用できます。未設定の場合、デフォルトは `NOT structure_only` になります。明示的に設定すると `structure_only` をオーバーライドします。"復元設定"を参照してください。
`restore_functions`	ユーザー定義関数を復元するかどうかを指定します。`RESTORE`コマンドでのみ使用できます。未設定の場合、デフォルトは `NOT structure_only` になります。明示的に設定すると `structure_only` をオーバーライドします。"復元設定"を参照してください。
`storage_policy`	復元対象のテーブルのストレージポリシー。"データストレージに複数のブロックデバイスを使用するを参照してください。`RESTORE`コマンドでのみ使用できます。`MergeTree`ファミリーのエンジンを使用するテーブルにのみ適用されます。
`allow_non_empty_tables`	`RESTORE TABLE` で空でないテーブルにデータを挿入できるようにします。これにより、テーブル内の既存データとバックアップから抽出されたデータが混在します。そのため、この設定はテーブル内でデータの重複を引き起こす可能性があるため、注意して使用してください。	`0`
`backup_restore_keeper_max_retries`	BACKUP または RESTORE の処理中における [Zoo]Keeper 操作の最大再試行回数。一時的な [Zoo]Keeper 障害によって処理全体が失敗しないよう、十分に大きな値にする必要があります。	`1000`
`backup_restore_keeper_retry_initial_backoff_ms`	バックアップまたは復元中の [Zoo]Keeper 操作に対する初期バックオフタイムアウト	`100`
`backup_restore_keeper_retry_max_backoff_ms`	バックアップまたは復元中の [Zoo]Keeper 操作に対する最大バックオフタイムアウト	`5000`
`backup_restore_failure_after_host_disconnected_for_seconds`	`BACKUP ON CLUSTER` または `RESTORE ON CLUSTER` の実行中に、あるホストがこの時間内に ZooKeeper 上の一時的な 'alive' ノードを再作成できない場合、バックアップまたはリストア全体は失敗と見なされます。この値は、障害発生後にホストが ZooKeeper に再接続するのにかかり得る妥当な時間よりも長く設定する必要があります。ゼロは無制限を意味します。	`3600`
`backup_restore_keeper_max_retries_while_initializing`	`BACKUP ON CLUSTER` または `RESTORE ON CLUSTER` 操作の初期化中における [Zoo]Keeper 操作の最大再試行回数。	`20`
`backup_restore_keeper_max_retries_while_handling_error`	`BACKUP ON CLUSTER` または `RESTORE ON CLUSTER` のエラー処理中における [Zoo]Keeper 操作の最大再試行回数。	`20`
`backup_restore_finish_timeout_after_error_sec`	現在の `BACKUP ON CLUSTER` または `RESTORE ON CLUSTER` 操作で、他のホストが 'error' ノードを検知して処理を停止するまで、イニシエーターが待機する時間。	`180`
`backup_restore_keeper_value_max_size`	バックアップ中の [Zoo]Keeper ノードのデータの最大サイズ	`1048576`
`backup_restore_batch_size_for_keeper_multi`	バックアップまたは復元時に [Zoo]Keeper へのマルチリクエストで使用するバッチの最大サイズ	`1000`
`backup_restore_batch_size_for_keeper_multiread`	バックアップまたは復元時に [Zoo]Keeper へのマルチリードリクエストで使用するバッチの最大サイズ	`10000`
`backup_restore_keeper_fault_injection_probability`	バックアップまたは復元中に Keeper リクエストが失敗するおおよその確率です。有効な値は区間 `[0.0f, 1.0f]` です	`0`
`backup_restore_keeper_fault_injection_seed`	`0` はランダムシード、それ以外は設定された値	`0`
`backup_restore_s3_retry_attempts`	Aws::Client::RetryStrategy の設定です。Aws::Client 自体が再試行を行い、0 は再試行しないことを意味します。バックアップ／復元時にのみ適用されます。	`1000`
`max_backup_bandwidth`	サーバー上の特定のバックアップに対する、1 秒あたりの最大読み取り速度 (バイト数) です。0 は無制限を意味します。	`0`
`max_backups_io_thread_pool_size`	ClickHouse は、S3 バックアップの IO 処理に Backups IO Thread pool のスレッドを使用します。`max_backups_io_thread_pool_size` は、このプール内のスレッド数の上限を設定します。	`1000`
`max_backups_io_thread_pool_free_size`	Backups IO Thread pool 内のアイドル状態のスレッド数が `max_backup_io_thread_pool_free_size` を超えると、ClickHouse はアイドル状態のスレッドが使用しているリソースを解放し、プールサイズを縮小します。必要に応じて、スレッドは再び作成されます。	`0`
`backups_io_thread_pool_queue_size`	Backups IO Thread pool にスケジュールできるジョブの最大数。現在の S3 バックアップのロジック上、このキューは無制限のままにしておくことを推奨します。注: 値 `0` (デフォルト) は無制限を意味します。	`0`
`backup_threads`	`BACKUP` リクエストの実行に使用するスレッドの最大数。
`max_backup_bandwidth_for_server`	サーバー上のすべてのバックアップに対する1秒あたりの最大読み取り速度 (バイト単位) です。0 は無制限を意味します。	`0`
`shutdown_wait_backups_and_restores`	true に設定すると、ClickHouse はシャットダウン前に、実行中のバックアップおよび復元が完了するまで待機します。	`1`

S3固有の設定

設定	説明	デフォルト値
`use_same_s3_credentials_for_base_backup`	S3 へのベースバックアップで、クエリの認証情報を引き継ぐかどうかを指定します。`S3` でのみ有効です。
`s3_storage_class`	S3 バックアップで使用するストレージクラス。例: `STANDARD`

Azure固有の設定

設定	説明	デフォルト値
`azure_attempt_to_create_container`	Azure Blob Storage の使用時に、指定したコンテナーが存在しない場合は作成を試みるかどうか。	`true`

管理とトラブルシューティング

backup コマンドは id と status を返し、その id を使ってバックアップのステータスを取得できます。これは、長時間かかる ASYNC バックアップの進行状況を確認する際に非常に便利です。以下の例は、既存のバックアップファイルを上書きしようとしたときに発生したエラーを示しています。

BACKUP TABLE helloworld.my_first_table TO Disk('backups', '1.zip') ASYNC

┌─id───────────────────────────────────┬─status──────────┐
│ 7678b0b3-f519-4e6e-811f-5a0781a4eb52 │ CREATING_BACKUP │
└──────────────────────────────────────┴─────────────────┘

1 row in set. Elapsed: 0.001 sec.

SELECT
*
FROM system.backups
WHERE id='7678b0b3-f519-4e6e-811f-5a0781a4eb52'
FORMAT Vertical

Row 1:
──────
id:                7678b0b3-f519-4e6e-811f-5a0781a4eb52
name:              Disk('backups', '1.zip')
status:            BACKUP_FAILED
num_files:         0
uncompressed_size: 0
compressed_size:   0
error:             Code: 598. DB::Exception: Backup Disk('backups', '1.zip') already exists. (BACKUP_ALREADY_EXISTS) (version 22.8.2.11 (official build))
start_time:        2022-08-30 09:21:46
end_time:          2022-08-30 09:21:46

1 row in set. Elapsed: 0.002 sec.

system.backups テーブルに加え、すべてのバックアップおよび復元操作は、システムログテーブル system.backup_log にも記録されます:

SELECT *
FROM system.backup_log
WHERE id = '7678b0b3-f519-4e6e-811f-5a0781a4eb52'
ORDER BY event_time_microseconds ASC
FORMAT Vertical

Row 1:
──────
event_date:              2023-08-18
event_time_microseconds: 2023-08-18 11:13:43.097414
id:                      7678b0b3-f519-4e6e-811f-5a0781a4eb52
name:                    Disk('backups', '1.zip')
status:                  CREATING_BACKUP
error:
start_time:              2023-08-18 11:13:43
end_time:                1970-01-01 03:00:00
num_files:               0
total_size:              0
num_entries:             0
uncompressed_size:       0
compressed_size:         0
files_read:              0
bytes_read:              0

Row 2:
──────
event_date:              2023-08-18
event_time_microseconds: 2023-08-18 11:13:43.174782
id:                      7678b0b3-f519-4e6e-811f-5a0781a4eb52
name:                    Disk('backups', '1.zip')
status:                  BACKUP_FAILED
error:                   Code: 598. DB::Exception: Backup Disk('backups', '1.zip') already exists. (BACKUP_ALREADY_EXISTS) (version 23.8.1.1)
start_time:              2023-08-18 11:13:43
end_time:                2023-08-18 11:13:43
num_files:               0
total_size:              0
num_entries:             0
uncompressed_size:       0
compressed_size:         0
files_read:              0
bytes_read:              0

2 rows in set. Elapsed: 0.075 sec.