BACKUP / RESTORE vers un disque

-- core commands
BACKUP | RESTORE 
--- what to backup/restore (or exclude)
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']
--- where to backup or restore to or from
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>')
--- additional settings
[SETTINGS ...]
[ASYNC]

Consultez "résumé des commandes" pour obtenir plus de détails sur chaque commande.

Dans les exemples ci-dessous, la destination de sauvegarde est indiquée sous la forme Disk('backups', '1.zip'). Pour utiliser le moteur de sauvegarde Disk, vous devez d’abord ajouter un fichier spécifiant la destination de sauvegarde au chemin ci-dessous :

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

Par exemple, la configuration ci-dessous définit un disque nommé backups, puis ajoute ce disque à la liste allowed_disk de backups :

<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>

Il est également possible d’effectuer BACKUP/RESTORE vers S3 en configurant un disque S3 dans la configuration de stockage de ClickHouse. Configurez le disque comme suit en ajoutant un fichier dans /etc/clickhouse-server/config.d, comme cela a été fait ci-dessus pour le disque local.

<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>

BACKUP/RESTORE pour un disque S3 s’effectue de la même manière que pour un disque local :

BACKUP TABLE data TO Disk('s3_plain', 'cloud_backup');
RESTORE TABLE data AS data_restored FROM Disk('s3_plain', 'cloud_backup');

Exécutez les commandes suivantes pour créer la base de données et la table de test dont nous allons effectuer la sauvegarde et la restauration dans cet exemple :

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;

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> -- pour MacOS, choisissez : /Users/backups/
            </backups>
        </disks>
    </storage_configuration>
    <backups>
        <allowed_disk>backups</allowed_disk>
        <allowed_path>/backups/</allowed_path> -- pour MacOS, choisissez : /Users/backups/
    </backups>
</clickhouse>

Pour sauvegarder la table, vous pouvez exécuter :

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

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

La table peut être restaurée depuis la sauvegarde à l’aide de la commande suivante si elle est vide :

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

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

Pour restaurer la table alors qu'elle contient déjà des données, exécutez :

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

Les tables peuvent être restaurées ou sauvegardées en leur donnant de nouveaux noms :

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

L’archive de cette sauvegarde a la structure suivante :

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

D'autres formats que zip peuvent également être utilisés. Voir "Sauvegardes sous forme d'archives tar" ci-dessous pour plus d'informations.

Dans ClickHouse, une sauvegarde de base est la sauvegarde complète initiale à partir de laquelle sont créées les sauvegardes incrémentielles suivantes. Les sauvegardes incrémentielles ne stockent que les modifications effectuées depuis la sauvegarde de base. Cette dernière doit donc rester disponible pour pouvoir restaurer depuis n’importe quelle sauvegarde incrémentielle. La destination de la sauvegarde de base peut être définie avec le paramètre base_backup.

Pour effectuer une sauvegarde incrémentielle d’une table, commencez par créer une sauvegarde de base :

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')

Toutes les données de la sauvegarde incrémentielle et de la sauvegarde de base peuvent être restaurées dans une nouvelle table test_db.test_table2 à l'aide de la commande :

RESTORE TABLE test_db.test_table AS test_db.test_table2
FROM Disk('backups', 'incremental-a.zip');

Les sauvegardes écrites sur disque peuvent être protégées par un mot de passe appliqué au fichier. Le mot de passe peut être défini à l'aide du paramètre password.

BACKUP TABLE test_db.test_table
TO Disk('backups', 'password-protected.zip')
SETTINGS password='qwerty'

Pour restaurer une sauvegarde protégée par un mot de passe, il faut à nouveau indiquer le paramètre password :

RESTORE TABLE test_db.test_table
FROM Disk('backups', 'password-protected.zip')
SETTINGS password='qwerty'

Les sauvegardes peuvent être stockées non seulement sous forme d’archives zip, mais aussi d’archives tar. Le fonctionnement est identique à celui des archives zip, à ceci près que la protection par mot de passe n'est pas prise en charge pour les archives tar. En outre, les archives tar prennent en charge différentes méthodes de compression.

Pour sauvegarder une table au format tar :

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

pour restaurer depuis une archive tar :

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

Pour modifier la méthode de compression, le suffixe de fichier approprié doit être ajouté au nom de la sauvegarde. Par exemple, pour compresser l’archive tar avec gzip, exécutez :

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

Les suffixes de fichiers de compression pris en charge sont :

• tar.gz
• .tgz
• tar.bz2
• tar.lzma
• .tar.zst
• .tzst
• .tar.xz

La méthode et le niveau de compression peuvent être spécifiés à l’aide des paramètres compression_method et compression_level, respectivement.

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

S'il faut restaurer des partitions spécifiques associées à une table, il est possible de les préciser.

Créons une table partitionnée simple en quatre partitions, insérons-y des données, puis effectuons une sauvegarde des première et quatrième partitions uniquement :

CREATE IF NOT EXISTS test_db;
       
-- Créer une table partitionnée
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 │
   └───────────────┴─────────┘

Exécutez la commande suivante pour sauvegarder les partitions 1 et 4 :

BACKUP TABLE test_db.partitioned PARTITIONS '1', '4'
TO Disk('backups', 'partitioned.zip')

Exécutez la commande suivante pour restaurer les partitions 1 et 4 :

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