BACKUP / RESTORE em disco | ClickHouse Docs

Sintaxe

-- comandos principais
BACKUP | RESTORE 
--- o que incluir no backup/restaurar (ou excluir)
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']
--- destino ou origem do backup ou restauração
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>')
--- configurações adicionais
[SETTINGS ...]
[ASYNC]

Consulte "resumo dos comandos" para obter mais detalhes sobre cada comando.

Configurar destinos de backup em disco

Configurar um destino de backup em disco local

Nos exemplos abaixo, você verá o destino de backup especificado como Disk('backups', '1.zip'). Para usar o mecanismo de backup Disk, primeiro é necessário adicionar um arquivo que especifique o destino de backup no caminho abaixo:

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

Por exemplo, a configuração abaixo define um disco chamado backups e depois adiciona esse disco à lista 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>

Configure um destino de backup para disco S3

Também é possível fazer BACKUP/RESTORE no S3 configurando um disco S3 na configuração de armazenamento do ClickHouse. Configure o disco assim, adicionando um arquivo a /etc/clickhouse-server/config.d, como foi feito acima para o disco 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 em disco S3 é feito da mesma forma que em disco local:

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

Exemplos de uso de backup/restauração em disco local

Fazer backup e restaurar uma tabela

Execute os comandos abaixo para criar o banco de dados e a tabela de teste dos quais faremos um backup e uma restauração neste exemplo:

Comandos de configuração

Crie o banco de dados e a tabela:

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é-processe e insira mil linhas de dados aleatórios:

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

Em seguida, você precisará criar um arquivo especificando o destino do backup no caminho abaixo:

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

<clickhouse>
    <storage_configuration>
        <disks>
            <backups>
                <type>local</type>
                <path>/backups/</path> -- para MacOS, escolha: /Users/backups/
            </backups>
        </disks>
    </storage_configuration>
    <backups>
        <allowed_disk>backups</allowed_disk>
        <allowed_path>/backups/</allowed_path> -- para MacOS, escolha: /Users/backups/
    </backups>
</clickhouse>

Para fazer backup da tabela, você pode executar:

Querysql

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

Responseresponse

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

A tabela pode ser restaurada a partir do backup com o seguinte comando, se estiver vazia:

Querysql

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

Responseresponse

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

Para restaurar a tabela com dados já existentes, execute:

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

Tabelas podem ser restauradas ou salvas em backup com novos nomes:

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

O arquivo desse backup tem a seguinte estrutura:

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

É possível usar formatos diferentes de zip. Veja "Backups como arquivos tar" abaixo para mais detalhes.

Backups incrementais em disco

Um backup de base no ClickHouse é o backup inicial e completo a partir do qual os backups incrementais subsequentes são criados. Os backups incrementais armazenam apenas as alterações feitas desde o backup de base, portanto ele deve ser mantido disponível para permitir a restauração a partir de qualquer backup incremental. O destino do backup de base pode ser definido com o setting base_backup.

Para fazer um backup incremental de uma tabela, primeiro faça um backup 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')

Todos os dados do backup incremental e do backup de base podem ser restaurados para uma nova tabela test_db.test_table2 com o comando:

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

Protegendo um backup

Backups gravados em disco podem ter uma senha aplicada ao arquivo. A senha pode ser especificada usando a configuração password.

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

Para restaurar um backup protegido por senha, a senha deve ser novamente especificada usando a configuração password:

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

Backups como arquivos tar

Os backups podem ser armazenados não apenas como arquivos zip, mas também como arquivos tar. A funcionalidade é a mesma dos arquivos zip, exceto que a proteção por senha não é compatível com arquivos tar. Além disso, os arquivos tar oferecem suporte a vários métodos de compressão.

Para fazer backup de uma tabela como tar:

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

para restaurar a partir de um arquivo tar:

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

Para alterar o método de compressão, o sufixo de arquivo correto deve ser adicionado ao nome do backup. Por exemplo, para compactar o arquivo tar usando gzip, execute:

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

Os sufixos de arquivos compactados compatíveis são:

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

Configurações de compressão

O método e o nível de compressão podem ser especificados por meio das configurações compression_method e compression_level, respectivamente.

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

Restaurar partições específicas

Se for necessário restaurar partições específicas associadas a uma tabela, elas podem ser especificadas.

Vamos criar uma tabela simples particionada em quatro partições, inserir alguns dados nela e depois fazer backup apenas da primeira e da quarta partições:

Configuração

CREATE IF NOT EXISTS test_db;
       
-- Cria uma tabela particionada
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 │
   └───────────────┴─────────┘

Execute o comando a seguir para fazer backup das partições 1 e 4:

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

Execute o comando a seguir para restaurar as partições 1 e 4:

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