BACKUP / RESTORE в конечную точку S3 или из неё

Эта статья посвящена резервному копированию в S3 бакет или восстановлению резервных копий из него через конечную точку S3.

Синтаксис

-- основные команды
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]

См. "сводку команд", где приведены более подробные сведения о каждой команде.

Пример использования

Инкрементное резервное копирование в конечную точку S3

В этом примере мы создадим резервную копию в конечную точку S3, а затем восстановим из неё данные.

Для использования этого метода вам потребуется следующая информация:

Параметр	Пример
Конечная точка S3	`https://backup-ch-docs.s3.us-east-1.amazonaws.com/backups/`
Идентификатор ключа доступа	`BKIOZLE2VYN3VXXTP9RC`
Секретный ключ доступа	`40bwYnbqN7xU8bVePaUCh3+YEyGXu8UOMV9ANpwL`

Пункт назначения резервной копии указывается следующим образом:

S3('<s3 endpoint>/<directory>', '<access key id>', '<secret access key>', '<extra_credentials>')

Настройка

Создайте следующую базу данных и таблицу и вставьте в неё немного случайных данных:

CREATE DATABASE IF NOT EXISTS test_db;
CREATE TABLE test_db.test_table
(
    `key` Int,
    `value` String,
    `array` Array(String)
)
ENGINE = MergeTree
ORDER BY tuple()

INSERT INTO test_db.test_table SELECT *
FROM generateRandom('key Int, value String, array Array(String)')
LIMIT 1000

Создайте базовую резервную копию

Для инкрементных резервных копий нужна базовая резервная копия, от которой они будут отсчитываться. Первый параметр пункта назначения S3 — это конечная точка S3, а затем указывается каталог в бакете, который будет использоваться для этой резервной копии. В этом примере каталог называется my_backup.

Выполните следующую команду, чтобы создать базовую резервную копию:

BACKUP TABLE test_db.test_table TO S3(
'https://backup-ch-docs.s3.us-east-1.amazonaws.com/backups/base_backup',
'<access key id>',
'<secret access key>'
)

┌─id───────────────────────────────────┬─status─────────┐
│ de442b75-a66c-4a3c-a193-f76f278c70f3 │ BACKUP_CREATED │
└──────────────────────────────────────┴────────────────┘

Добавьте больше данных

Инкрементные резервные копии формируются на основе различий между базовой резервной копией и текущим содержимым таблицы, для которой создаётся резервная копия. Перед созданием инкрементной резервной копии добавьте больше данных:

INSERT INTO test_db.test_table SELECT *
FROM generateRandom('key Int, value String, array Array(String)')
LIMIT 100

Создание инкрементной резервной копии

Эта команда резервного копирования похожа на команду создания базовой резервной копии, но дополнительно включает SETTINGS base_backup и расположение базовой резервной копии. Обратите внимание, что для инкрементной резервной копии используется не тот же каталог, что и для базовой, а та же конечная точка с другим целевым каталогом внутри бакета. Базовая резервная копия находится в my_backup, а инкрементная будет записана в my_incremental:

BACKUP TABLE test_db.test_table TO S3(
'https://backup-ch-docs.s3.us-east-1.amazonaws.com/backups/incremental_backup',
'<access key id>',
'<secret access key>'
)
SETTINGS base_backup = S3(
'https://backup-ch-docs.s3.us-east-1.amazonaws.com/backups/base_backup',
'<access key id>',
'<secret access key>'
)

┌─id───────────────────────────────────┬─status─────────┐
│ f6cd3900-850f-41c9-94f1-0c4df33ea528 │ BACKUP_CREATED │
└──────────────────────────────────────┴────────────────┘

Восстановление из инкрементной резервной копии

Эта команда восстанавливает инкрементную резервную копию в новую таблицу test_table_restored. Обратите внимание: при восстановлении инкрементной резервной копии также восстанавливается и базовая резервная копия. При восстановлении указывайте только инкрементную резервную копию:

RESTORE TABLE data AS test_db.test_table_restored FROM S3(
'https://backup-ch-docs.s3.us-east-1.amazonaws.com/backups/incremental_backup',
'<access key id>',
'<secret access key>'
)

┌─id───────────────────────────────────┬─status───┐
│ ff0c8c39-7dff-4324-a241-000796de11ca │ RESTORED │
└──────────────────────────────────────┴──────────┘

Проверьте число строк

В исходную таблицу data были выполнены две вставки: одна на 1 000 строк и одна на 100 строк, итого 1 100. Убедитесь, что в восстановленной таблице 1 100 строк:

SELECT count()
FROM test_db.test_table_restored

┌─count()─┐
│    1100 │
└─────────┘

Проверьте содержимое

Ниже сравнивается содержимое исходной таблицы test_table с восстановленной таблицей test_table_restored:

SELECT throwIf((
   SELECT groupArray(tuple(*))
   FROM test_db.test_table
   ) != (
   SELECT groupArray(tuple(*))
   FROM test_db.test_table_restored
), 'Data does not match after BACKUP/RESTORE')