ClickHouse のバックアップとリストア

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

はじめに

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

多くの場合、このようなミスはすべてのレプリカに影響します。ClickHouse には一部の種類のミスを防ぐための 組み込みの安全機構があり、たとえば デフォルトでは、50 GB を超えるデータを含む MergeTree ファミリーエンジンのテーブルを安易に DROP することはできません。しかし、これらの安全機構は あらゆるケースを網羅しているわけではなく、問題が発生する可能性は依然としてあります。

起こりうる人的ミスを効果的に軽減するには、データのバックアップおよびリストア戦略を 事前に 慎重に準備しておく必要があります。

各社が利用できるリソースやビジネス要件は異なるため、あらゆる状況に適合するような ClickHouse のバックアップおよびリストアの万能な解決策は存在しません。1 ギガバイトのデータで有効な方法は、 数十ペタバイトのデータではまず機能しません。さまざまなアプローチが存在し、それぞれに長所と短所があり、 このセクションで解説します。1 つの方法だけに頼るのではなく、複数のアプローチを組み合わせて それぞれの欠点を補完することをお勧めします。

注記

バックアップを取得していても、一度もリストアを試したことがなければ、 いざ必要になったときに正しくリストアできない可能性があります（少なくとも、ビジネスが許容できる時間より 長くかかるかもしれません）。そのため、どのようなバックアップアプローチを選択する場合でも、 リストア手順も自動化し、予備の ClickHouse クラスター上で定期的にテストするようにしてください。

次のページでは、ClickHouse で利用可能なさまざまなバックアップおよび リストア方法の詳細を説明します。

Page	Description
Backup/restore using local disk or S3 disk	ローカルディスクまたは S3 ディスクへの／からのバックアップ／リストアの詳細
Backup/restore using S3 endpoint	S3 エンドポイントへの／からのバックアップ／リストアの詳細
Backup/restore using AzureBlobStorage	Azure blob storage への／からのバックアップ／リストアの詳細
Alternative methods	代替的なバックアップ手法についての説明

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

• フルまたは増分
• 同期または非同期
• 並行または非並行
• 圧縮ありまたは圧縮なし
• 名前付きコレクション を使用
• パスワード保護の有無
• system テーブル、log テーブル、アクセス管理テーブル のバックアップかどうか

バックアップの種類

バックアップにはフルバックアップと増分バックアップの 2 種類があります。フルバックアップは データの完全なコピーであり、増分バックアップは最後のフルバックアップからのデータの差分です。

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

要件に応じて、次のように使い分けることができます。

• 小規模なデータベースや重要なデータには フルバックアップ。
• 大規模なデータベース、または高頻度かつコスト効率良くバックアップを行う必要がある場合には 増分バックアップ。
• 例えば、週次のフルバックアップと日次の増分バックアップのように 両方 を併用。

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

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

名前付きコレクションの使用

名前付きコレクションを使用すると、バックアップ／リストア処理で再利用できるキーと値のペア（S3 の認証情報、エンドポイント、設定など）を保存できます。これにより、次のことが可能になります:

• 管理者権限を持たないユーザーから認証情報を隠す
• 複雑な設定を集中管理してコマンドを簡潔にする
• 処理間で一貫性を維持する
• クエリログ上で認証情報が露出することを防ぐ

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

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

システムテーブルもバックアップおよびリストアのワークフローに含めることができますが、 含めるかどうかは特定のユースケースに依存します。

query_log や part_log など、_log サフィックスを持つ履歴データを保存するシステムテーブルは、 他のテーブルと同様にバックアップおよびリストアできます。 ユースケースとして履歴データの分析（たとえば、query_log を使用してクエリのパフォーマンスを追跡したり、 問題をデバッグしたりすること）に依存している場合は、これらのテーブルをバックアップ戦略に 含めることが推奨されます。逆に、これらのテーブルの履歴データが不要な場合は、 バックアップストレージ容量を節約するために除外できます。

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

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

一般的な構文

-- コアコマンド
BACKUP | RESTORE [ASYNC]
--- バックアップ/復元の対象（または除外対象）
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 ...]

詳しくは、「コマンドの概要」を参照してください。

コマンド概要

上記の各コマンドの詳細は以下のとおりです。

Command	Description
BACKUP	指定したオブジェクトのバックアップを作成する
RESTORE	バックアップからオブジェクトを復元する
[ASYNC]	操作を非同期で実行する（即時に制御を返し、監視できる ID を返す）
TABLE [db.]table_name [AS [db.]table_name_in_backup]	特定のテーブルをバックアップ／復元する（名前を変更可能）
[PARTITION[S] partition_expr [,...]]	テーブルの特定パーティションのみバックアップ／復元する
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	すべて（すべてのデータベース、テーブルなど）をバックアップ／復元する。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 互換ストレージに保存／そこから復元する
[SETTINGS ...]	設定の全一覧は以下を参照

設定

汎用バックアップ／復元設定

設定	概要	デフォルト値
id	バックアップまたはリストア操作の ID。指定されていない場合は、ランダムに生成された UUID が使用されます。同じ ID の操作がすでに実行中の場合は、例外がスローされます。
compression_method	バックアップに使用する圧縮方式を指定します。セクション 「column compression codecs」 を参照してください。
compression_level	バックアップの圧縮レベルを指定します
password	ディスク上のファイルのパスワード。
base_backup	増分バックアップで使用するベースバックアップの格納先。例: Disk('backups', '1.zip')
use_same_password_for_base_backup	ベースバックアップのアーカイブがクエリのパスワードを継承するかどうか。
structure_only	有効にすると、実際のテーブルデータではなく CREATE 文だけをバックアップ／リストアします。
storage_policy	復元するテーブルに対するストレージポリシーです。詳細は「複数のブロックデバイスを使用したデータストレージ」を参照してください。RESTORE コマンドにのみ適用され、MergeTree ファミリーのエンジンを使用するテーブルに対してのみ有効です。
allow_non_empty_tables	RESTORE TABLE が、すでにデータが入っているテーブルに対してもデータを挿入できるようにします。これにより、テーブル内の既存データとバックアップから復元されたデータが混在します。その結果、テーブル内でデータの重複が発生する可能性があるため、注意して使用してください。	0
backup_restore_keeper_max_retries	BACKUP または RESTORE 処理の途中で実行される [Zoo]Keeper 操作の最大再試行回数。一時的な [Zoo]Keeper 障害が原因で BACKUP/RESTORE 処理全体が失敗しないよう、十分大きな値にする必要があります。	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 に再接続するのに要ると考えられるどのような妥当な時間よりも長く設定する必要があります。0 は無制限を意味します。	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	イニシエータが、他のホストが 'error' ノードに反応して現在の BACKUP ON CLUSTER または RESTORE ON CLUSTER 操作での処理を停止するまで待つべき時間。	180
backup_restore_keeper_value_max_size	バックアップ時における [Zoo]Keeper ノードデータの最大サイズ	1048576
backup_restore_batch_size_for_keeper_multi	バックアップまたはリストア時に [Zoo]Keeper へ送信される multi リクエストのバッチ最大サイズ	1000
backup_restore_batch_size_for_keeper_multiread	バックアップまたはリストア中に [Zoo]Keeper に対して行う multiread リクエストのバッチの最大サイズ	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	サーバー上の特定のバックアップにおける最大読み取り速度（バイト/秒）。0 の場合は無制限です。	0
max_backups_io_thread_pool_size	ClickHouse は Backups IO Thread プールのスレッドを使用して、S3 バックアップの IO 処理を実行します。max_backups_io_thread_pool_size は、このプール内のスレッド数の最大値を制限します。	1000
max_backups_io_thread_pool_free_size	Backups IO Thread プール内のアイドル状態のスレッド数が max_backup_io_thread_pool_free_size を超えると、ClickHouse はアイドル状態のスレッドが占有しているリソースを解放し、プールサイズを縮小します。必要に応じてスレッドは再作成されます。	0
backups_io_thread_pool_queue_size	Backups IO スレッドプールでスケジュール可能なジョブの最大数です。現在の 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 固有の設定

Setting	説明	既定値
azure_attempt_to_create_container	Azure Blob Storage を使用する場合に、指定されたコンテナが存在しない場合、そのコンテナを作成することを試みるかどうか。	true

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

バックアップコマンドは 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行が返されました。経過時間: 0.001秒

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')
#highlight-next-line
status:            BACKUP_FAILED
num_files:         0
uncompressed_size: 0
compressed_size:   0
#highlight-next-line
error:             コード: 598. DB::Exception: バックアップ Disk('backups', '1.zip') は既に存在します。(BACKUP_ALREADY_EXISTS) (バージョン 22.8.2.11 (公式ビルド))
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

行 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

行 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
#highlight-next-line
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行のセット。経過時間: 0.075秒