-- コアコマンド
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 ...]
詳しくは、「コマンドの概要」を参照してください。
以下の例では、バックアップ先は Disk('backups', '1.zip') として指定されています。
Disk バックアップエンジンを使用するには、まず以下のパスにバックアップ先を指定するファイルを追加する必要があります。
/etc/clickhouse-server/config.d/backup_disk.xml
例えば、以下の構成では backups という名前のディスクを定義し、次にそのディスクを backups の allowed_disk リストに追加します。
<clickhouse>
<storage_configuration>
<disks>
<!--highlight-next-line -->
<backups>
<type>local</type>
<path>/backups/</path>
</backups>
</disks>
</storage_configuration>
<!--highlight-start -->
<backups>
<allowed_disk>backups</allowed_disk>
<allowed_path>/backups/</allowed_path>
</backups>
<!--highlight-end -->
</clickhouse>
S3 ディスク用のバックアップ先を設定する
ClickHouse のストレージ設定で S3 ディスクを構成することで、BACKUP/RESTORE の実行先として S3 を利用することも可能です。ローカルディスクの場合と同様に、/etc/clickhouse-server/config.d にファイルを追加して、このディスクを次のように設定します。
<clickhouse>
<storage_configuration>
<disks>
<s3_plain>
<type>s3_plain</type>
<endpoint></endpoint>
<access_key_id></access_key_id>
<secret_access_key></secret_access_key>
</s3_plain>
</disks>
<policies>
<s3>
<volumes>
<main>
<disk>s3_plain</disk>
</main>
</volumes>
</s3>
</policies>
</storage_configuration>
<backups>
<allowed_disk>s3_plain</allowed_disk>
</backups>
</clickhouse>
S3 ディスクに対する BACKUP／RESTORE は、ローカル ディスクの場合と同様に実行できます。
BACKUP TABLE data TO Disk('s3_plain', 'cloud_backup');
RESTORE TABLE data AS data_restored FROM Disk('s3_plain', 'cloud_backup');
注記
- このディスクは
MergeTree 自体には使用せず、BACKUP/RESTORE 用にのみ使用してください。
- もしテーブルが S3 ストレージをバックエンドとしており、ディスクの種類が異なる場合、
パーツを宛先バケットにコピーする際に
CopyObject 呼び出しは使用されず、
代わりに一度ダウンロードしてからアップロードするため、非常に非効率です。このようなケースでは、
この用途には BACKUP ... TO S3(<endpoint>) 構文の使用を推奨します。
ローカルディスクへのバックアップ／リストアの使用例
テーブルのバックアップとリストア
この例でバックアップおよびリストアを行うテスト用データベースとテーブルを作成するため、次のコマンドを実行します:
セットアップ用コマンド
テスト用のデータベースとテーブルを作成します:
CREATE DATABASE test_db;
CREATE TABLE test_db.test_table (
id UUID,
name String,
email String,
age UInt8,
salary UInt32,
created_at DateTime,
is_active UInt8,
department String,
score Float32,
country String
) ENGINE = MergeTree()
ORDER BY id;
事前準備として、ランダムなデータを 1,000 行挿入します:
INSERT INTO test_table (id, name, email, age, salary, created_at, is_active, department, score, country)
SELECT
generateUUIDv4() as id,
concat('User_', toString(rand() % 10000)) as name,
concat('user', toString(rand() % 10000), '@example.com') as email,
18 + (rand() % 65) as age,
30000 + (rand() % 100000) as salary,
now() - toIntervalSecond(rand() % 31536000) as created_at,
rand() % 2 as is_active,
arrayElement(['Engineering', 'Marketing', 'Sales', 'HR', 'Finance', 'Operations'], (rand() % 6) + 1) as department,
rand() / 4294967295.0 * 100 as score,
arrayElement(['USA', 'UK', 'Germany', 'France', 'Canada', 'Australia', 'Japan', 'Brazil'], (rand() % 8) + 1) as country
FROM numbers(1000);
次に、以下のパスにバックアップ先を指定するファイルを作成します:
/etc/clickhouse-server/config.d/backup_disk.xml
<clickhouse>
<storage_configuration>
<disks>
<backups>
<type>local</type>
<path>/backups/</path> -- macOS の場合は /Users/backups/ を指定してください
</backups>
</disks>
</storage_configuration>
<backups>
<allowed_disk>backups</allowed_disk>
<allowed_path>/backups/</allowed_path> -- macOS の場合は /Users/backups/ を指定してください
</backups>
</clickhouse>
注記
clickhouse-server が起動中の場合は、変更を反映させるために再起動する必要があります。
テーブルをバックアップするには、次のコマンドを実行します：
BACKUP TABLE test_db.test_table TO Disk('backups', '1.zip')
┌─id───────────────────────────────────┬─status─────────┐
1. │ 065a8baf-9db7-4393-9c3f-ba04d1e76bcd │ BACKUP_CREATED │
└──────────────────────────────────────┴────────────────┘
テーブルが空の場合は、次のコマンドでバックアップからテーブルを復元できます。
RESTORE TABLE test_db.test_table FROM Disk('backups', '1.zip')
┌─id───────────────────────────────────┬─status───┐
1. │ f29c753f-a7f2-4118-898e-0e4600cd2797 │ RESTORED │
└──────────────────────────────────────┴──────────┘
注記
上記の RESTORE は、テーブル test.table にデータが含まれている場合は失敗します。
設定 allow_non_empty_tables=true を有効にすると、RESTORE TABLE がデータを
空ではないテーブルに挿入できるようになります。これにより、テーブル内の既存データと、バックアップから復元されるデータが混在します。
そのため、この設定はテーブル内のデータが重複する可能性があるため、注意して使用する必要があります。
既にデータが入っているテーブルを復元するには、次を実行します。
RESTORE TABLE test_db.table_table FROM Disk('backups', '1.zip')
SETTINGS allow_non_empty_tables=true
テーブルは新しい名前を付けてリストアまたはバックアップできます。
RESTORE TABLE test_db.table_table AS test_db.test_table_renamed FROM Disk('backups', '1.zip')
このバックアップのアーカイブは、次の構造になっています。
├── .backup
└── metadata
└── test_db
└── test_table.sql
zip 以外の形式も使用できます。詳細については、以下の "Backups as tar archives"
を参照してください。
ディスクへの増分バックアップ
ClickHouse におけるベースバックアップは、その後に作成される
増分バックアップの基準となる最初のフルバックアップです。増分バックアップには、
ベースバックアップ以降に行われた変更のみが保存されるため、任意の増分バックアップから
リストアできるように、ベースバックアップを利用可能な状態で保持しておく必要があります。
ベースバックアップの保存先は、設定 base_backup で指定できます。
注記
増分バックアップはベースバックアップに依存します。増分バックアップから
リストアできるようにするには、ベースバックアップを利用可能な状態で保持しておく必要があります。
テーブルの増分バックアップを作成するには、まずベースバックアップを作成してください。
BACKUP TABLE test_db.test_table TO Disk('backups', 'd.zip')
BACKUP TABLE test_db.test_table TO Disk('backups', 'incremental-a.zip')
SETTINGS base_backup = Disk('backups', 'd.zip')
増分バックアップとベースバックアップのすべてのデータは、次のコマンドで新しいテーブル test_db.test_table2 に復元できます。
RESTORE TABLE test_db.test_table AS test_db.test_table2
FROM Disk('backups', 'incremental-a.zip');
バックアップの保護
ディスクに出力されるバックアップファイルには、パスワードを設定できます。
パスワードは password 設定を使用して指定します。
BACKUP TABLE test_db.test_table
TO Disk('backups', 'password-protected.zip')
SETTINGS password='qwerty'
パスワードで保護されたバックアップを復元するには、password 設定でパスワードを再度指定する必要があります。
RESTORE TABLE test_db.test_table
FROM Disk('backups', 'password-protected.zip')
SETTINGS password='qwerty'
tar アーカイブとしてのバックアップ
バックアップは zip アーカイブだけでなく、tar アーカイブとしても保存できます。
tar アーカイブに対する機能は zip アーカイブの場合と同様ですが、tar アーカイブではパスワード保護はサポートされていません。さらに、tar アーカイブではさまざまな圧縮方式がサポートされています。
テーブルを tar アーカイブとしてバックアップするには、次のようにします。
BACKUP TABLE test_db.test_table TO Disk('backups', '1.tar')
tar アーカイブから復元するには:
RESTORE TABLE test_db.test_table FROM Disk('backups', '1.tar')
圧縮方式を変更するには、バックアップ名に正しいファイル拡張子を付ける必要があります。例えば、tar アーカイブを gzip で圧縮するには、次を実行します。
BACKUP TABLE test_db.test_table TO Disk('backups', '1.tar.gz')
サポートされている圧縮ファイルの拡張子は次のとおりです。
tar.gz.tgztar.bz2tar.lzma.tar.zst.tzst.tar.xz
圧縮設定
圧縮方式と圧縮レベルは、それぞれ設定 compression_method と compression_level を使用して指定できます。
BACKUP TABLE test_db.test_table
TO Disk('backups', 'filename.zip')
SETTINGS compression_method='lzma', compression_level=3
特定のパーティションを復元する
テーブルに関連付けられた特定のパーティションのみを復元する必要がある場合、それらを個別に指定できます。
4つのパーティションを持つ単純なパーティション分割テーブルを作成し、いくつかのデータを挿入してから、
最初と4番目のパーティションのみのバックアップを取得してみます。
セットアップ
CREATE IF NOT EXISTS test_db;
-- パーティション分割テーブルを作成
CREATE TABLE test_db.partitioned (
id UInt32,
data String,
partition_key UInt8
) ENGINE = MergeTree()
PARTITION BY partition_key
ORDER BY id;
INSERT INTO test_db.partitioned VALUES
(1, 'data1', 1),
(2, 'data2', 2),
(3, 'data3', 3),
(4, 'data4', 4);
SELECT count() FROM test_db.partitioned;
SELECT partition_key, count()
FROM test_db.partitioned
GROUP BY partition_key
ORDER BY partition_key;
┌─count()─┐
1. │ 4 │
└─────────┘
┌─partition_key─┬─count()─┐
1. │ 1 │ 1 │
2. │ 2 │ 1 │
3. │ 3 │ 1 │
4. │ 4 │ 1 │
└───────────────┴─────────┘
次のコマンドを実行して、パーティション 1 と 4 のバックアップを作成します。
BACKUP TABLE test_db.partitioned PARTITIONS '1', '4'
TO Disk('backups', 'partitioned.zip')
パーティション 1 と 4 を復元するには、以下のコマンドを実行します。
RESTORE TABLE test_db.partitioned PARTITIONS '1', '4'
FROM Disk('backups', 'partitioned.zip')
SETTINGS allow_non_empty_tables=true
