ディスクへの BACKUP / RESTORE

ローカルディスクへの/からのバックアップと復元の詳細

​

構文

-- コアコマンド
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]

各コマンドの詳細については、“コマンド概要”を参照してください。

​

ディスク用のバックアップ保存先を設定する

​

ローカルディスクのバックアップ保存先を設定する

以下の例では、バックアップ保存先は Disk('backups', '1.zip') として指定されています。 Disk バックアップエンジンを使用するには、まず以下のパスに バックアップ保存先を指定するファイルを追加する必要があります。

/etc/clickhouse-server/config.d/backup_disk.xml

たとえば、以下の設定では backups という名前のディスクを定義し、そのディスクを backups の allowed_disk リストに追加しています。

<clickhouse>
    <storage_configuration>
        <disks>
            <backups>
                <type>local</type>
                <path>/backups/</path>
            </backups>
        </disks>
    </storage_configuration>
    <backups>
        <allowed_disk>backups</allowed_disk>
        <allowed_path>/backups/</allowed_path>
    </backups>
</clickhouse>

​

S3ディスクのバックアップ保存先を構成する

ClickHouseのストレージ構成でS3ディスクを設定することで、S3へのBACKUP/RESTOREも可能になります。 ローカルディスクで前述したように、/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 storage で、ディスクの種類が異なる場合、 パーツを宛先バケットにコピーする際に 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 が実行中の場合は、変更を反映するために再起動する必要があります。

テーブルをバックアップするには、次を実行します。

Query

BACKUP TABLE test_db.test_table TO Disk('backups', '1.zip')

Response

   ┌─id───────────────────────────────────┬─status─────────┐
1. │ 065a8baf-9db7-4393-9c3f-ba04d1e76bcd │ BACKUP_CREATED │
   └──────────────────────────────────────┴────────────────┘

テーブルが空の場合は、次のコマンドでバックアップから復元できます。

Query

RESTORE TABLE test_db.test_table FROM Disk('backups', '1.zip')

Response

   ┌─id───────────────────────────────────┬─status───┐
1. │ f29c753f-a7f2-4118-898e-0e4600cd2797 │ RESTORED │
   └──────────────────────────────────────┴──────────┘

上記の RESTORE は、table test.table にデータが含まれている場合は失敗します。 設定 allow_non_empty_tables=true を指定すると、RESTORE TABLE で空でない table にデータを挿入できます。 これにより、table 内の既存データとバックアップから復元されたデータが混在します。 そのため、この設定を使用すると table 内でデータが重複する可能性があるため、注意して使用してください。

すでにデータが入っている table を復元するには、次を実行します。

RESTORE TABLE test_db.test_table FROM Disk('backups', '1.zip')
SETTINGS allow_non_empty_tables=true

テーブルは、新しい名前を付けて復元またはバックアップできます：

RESTORE TABLE test_db.test_table AS test_db.test_table_renamed FROM Disk('backups', '1.zip')

このバックアップのバックアップアーカイブの構造は、次のとおりです。

├── .backup
└── metadata
    └── test_db
        └── test_table.sql

zip以外のフォーマットも使用できます。詳細は、以下の”tarアーカイブ形式のバックアップ”を参照してください。

​

ディスクへの増分バックアップ

ClickHouse におけるベースバックアップとは、後続の 増分バックアップを作成する基準となる最初のフルバックアップです。増分バックアップには、ベースバックアップ以降の 変更分のみが保存されるため、どの増分バックアップからでも 復元できるように、ベースバックアップを利用可能な状態にしておく必要があります。ベースバックアップの保存先は setting 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 設定で指定できます。

パスワード保護は ZIP アーカイブ (.zip、.zipx) でのみサポートされています。 パスワードを使用するには、バックアップパスの末尾が .zip または .zipx である必要があります。 tar アーカイブや非アーカイブパスを含む、それ以外のフォーマットでパスワードを使用すると、 BAD_ARGUMENTS エラー: Password is not applicable, backup cannot be encrypted が発生します。

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 アーカイブとして保存することもできます。 機能は 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
• .tgz
• tar.bz2
• tar.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 つのパーティションに分かれたシンプルなテーブルを作成し、データを insert してから、 1 番目と 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