BACKUP / RESTORE em disco

Detalha backup/restauração para um disco local ou a partir dele

​

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

• Este disco não deve ser usado para o próprio MergeTree, apenas para BACKUP/RESTORE
• Se suas tabelas usam armazenamento S3 e os tipos de disco são diferentes, não são usadas chamadas CopyObject para copiar as partes para o bucket de destino; em vez disso, elas são baixadas e reenviadas, o que é muito ineficiente. Nesse caso, prefira usar a sintaxe BACKUP ... TO S3(<endpoint>) para esse caso de uso.

​

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>

Se o clickhouse-server estiver em execução, você precisará reiniciá-lo para que as alterações entrem em vigor.

Para fazer backup da tabela, você pode executar:

Query

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

Response

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

Query

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

Response

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

O RESTORE acima falharia se a tabela test.table contiver dados. A configuração allow_non_empty_tables=true permite que RESTORE TABLE insira dados em tabelas que não estão vazias. Isso misturará os dados já existentes na tabela com os dados extraídos do backup. Portanto, essa configuração pode causar duplicação de dados na tabela e deve ser usada com cautela.

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.

Os backups incrementais dependem do backup de base. O backup de base deve ser mantido disponível para que seja possível restaurar a partir de um backup incremental.

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.

A proteção por senha é compatível apenas com arquivos ZIP (.zip, .zipx). O caminho do backup deve terminar com .zip ou .zipx para que a senha seja aceita. Usar uma senha com qualquer outro formato — incluindo arquivos tar e caminhos que não sejam de arquivo compactado — resultará no erro 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'

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