BACKUP / RESTORE vers un disque

Détails de la sauvegarde et de la restauration vers ou depuis un disque local

​

Syntaxe

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

​

Configurer les destinations de sauvegarde sur disque

​

Configurer une destination de sauvegarde sur un disque local

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>

​

Configurer une destination de sauvegarde pour un disque S3

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

• Ce disque ne doit pas être utilisé pour MergeTree lui-même, uniquement pour BACKUP/RESTORE.
• Si vos tables reposent sur un stockage S3 et que les types de disques sont différents, les appels CopyObject ne sont pas utilisés pour copier les parts vers le bucket de destination ; à la place, elles sont téléchargées puis téléversées, ce qui est très inefficace. Dans ce cas, il est préférable d’utiliser la syntaxe BACKUP ... TO S3(<endpoint>) pour ce cas d’usage.

​

Exemples d’utilisation de la sauvegarde/restauration sur disque local

​

Sauvegarder et restaurer une table

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 :

Commandes de configuration

Créez la base de données et la table :

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;

Prétraitez, puis insérez mille lignes de données aléatoires :

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

Ensuite, vous devrez créer un fichier indiquant la destination de sauvegarde à l’emplacement ci-dessous :

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

Si clickhouse-server est en cours d’exécution, vous devrez le redémarrer pour que les modifications prennent effet.

Pour sauvegarder la table, vous pouvez exécuter :

Query

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

Response

   ┌─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 :

Query

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

Response

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

Le RESTORE ci-dessus échouera si la table test.table contient des données. Le paramètre allow_non_empty_tables=true permet à RESTORE TABLE d’insérer des données dans des tables non vides. Cela mélangera les données déjà présentes dans la table avec celles extraites de la sauvegarde. Ce paramètre peut donc entraîner une duplication des données dans la table et doit être utilisé avec prudence.

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.

​

Sauvegardes incrémentielles sur disque

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.

Les sauvegardes incrémentielles dépendent de la sauvegarde de base. La sauvegarde de base doit rester disponible pour pouvoir restaurer depuis une sauvegarde incrémentielle.

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

​

Sécuriser une sauvegarde

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.

La protection par mot de passe n’est prise en charge que pour les archives ZIP (.zip, .zipx). Le chemin de la sauvegarde doit se terminer par .zip ou .zipx pour que le mot de passe soit accepté. L’utilisation d’un mot de passe avec tout autre format, y compris les archives tar et les chemins qui ne sont pas des archives, entraînera une erreur 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'

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'

​

Sauvegardes sous forme d’archives tar

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

​

Paramètres de compression

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

​

Restaurer des partitions spécifiques

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 :

Préparation

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