Выгрузка в NFS

Команда export nfs запускает на стороне сервера процесс выгрузки в сетевую файловую систему (Network File System, NFS) хостов кластера YDB данных и информации об объектах схемы, в описанном в статье Файловая структура формате:

ydb [connection options] export nfs [options]

, где [connection options] — опции соединения с БД

Важно

Выгрузка доступна только для объектов следующих типов:

Параметры командной строки

[options] - параметры команды:

Параметры NFS

Команда выгрузки в NFS требует указания монтированной директории (или поддиректории) общей для всех объектов, участвующих в выгрузке. Так как выгрузка производится в асинхронном режиме на всех хостах YDB, указанная директория должна быть на каждом хосте YDB и смонтирована в NFS.

--fs-path PATH: путь до монтированной директории (или поддиректории).

Перечень выгружаемых объектов

--root-path PATH: Корневая директория для выгружаемых объектов. Если не указана, используется корневая директория базы данных.

--include PATH: Объекты схемы данных для включения в экспорт. Директории обходятся рекурсивно. Пути указываются относительно root-path. Данный параметр может быть указан несколько раз для включения нескольких объектов. Если не указан, выполняется выгрузка всех несистемных объектов в root-path.

--exclude STRING: Шаблон (PCRE) для исключения путей из выгрузки. Пути указываются относительно root-path. Данный параметр может быть указан несколько раз для разных шаблонов.

Альтернативный способ

Поддерживается альтернативный способ указания перечня объектов:

--item STRING: Описание объекта выгрузки. Параметр --item может быть указан несколько раз, если необходимо выполнить выгрузку нескольких объектов. STRING задается в формате <свойство>=<значение>,..., со следующими обязательными свойствами:

source, src, или s — путь до выгружаемой директории или таблицы, . указывает на корневую директорию базы данных. При указании директории выгружаются все несистемные объекты в ней, а также рекурсивно все несистемные поддиректории.
destination, dst, или d — путь в NFS (относительно --fs-path).

--exclude STRING: Шаблон (PCRE) для исключения путей из выгрузки. Данный параметр может быть указан несколько раз для разных шаблонов.

Важно

Экспорты, сделанные с использованием альтернативного синтаксиса, не будут содержать списка объектов в составе резервной копии, поэтому некоторые возможности могут быть для них недоступны (в частности, шифрованные резервные копии), а импорт возможен только с использованием соответствующего альтернативного синтаксиса импорта.

Дополнительные параметры

--description STRING: Текстовое описание операции, сохраняемое в истории операций.
--retries NUM: Количество повторных попыток выгрузки, которые будет предпринимать сервер. Значение по умолчанию: 10.
--compression STRING: Сжимать выгружаемые данные. При уровне сжатия по умолчанию для алгоритма Zstandard данные могут быть сжаты в 5-10 раз. Сжатие данных использует ресурс CPU и может повлиять на скорость выполнения других операций с БД. Допустимые значения:
- zstd — сжатие алгоритмом Zstandard c уровнем сжатия по умолчанию (3);
- zstd-N — сжатие алгоритмом Zstandard, N — уровень сжатия (1 — 22).
--include-index-data BOOL: Выгружать данные индексных таблиц. По умолчанию выгружаются только метаданные индексов, а сами индексы строятся при импорте — это экономит место и сокращает время выгрузки, но может увеличить время импорта. При включении данной опции данные индексных таблиц выгружаются в полном объёме, что позволяет при импорте загрузить их вместо построения. Значение по умолчанию: false.
--encryption-algorithm ALGORITHM: Шифровать выгружаемые данные используя указанный алгоритм. Поддерживаемые значения: AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305.
--encryption-key-file PATH: Путь к файлу, содержащему ключ шифрования (только для зашифрованных выгрузок). Данный файл является бинарным и должен содержать точное количество байт, соответствующее длине ключа в выбранном алгоритме шифрования (16 байт для AES-128-GCM, 32 байта для AES-256-GCM и ChaCha20-Poly1305). Ключ также может быть передан через переменную окружения YDB_ENCRYPTION_KEY, в шестнадцатеричном строковом представлении.
--format STRING: Формат вывода результата. Допустимые значения:
- pretty — человекочитаемый формат (по умолчанию);
- proto-json-base64 — Protocol Buffers в формате JSON, бинарные строки закодированы в Base64.

Выполнение выгрузки

Ход серверной операции выгрузки

Создаётся серверная асинхронная операция экспорта.
В корневой директории базы данных создаётся служебная директория export-{id}, где {id} — числовой идентификатор операции.
В эту директорию создаётся согласованная копия таблиц с помощью механизма CopyTables.
Данные каждой таблицы записываются из копии в хранилище в формате файловой структуры выгрузки с параллельной записью из разных узлов кластера.
После успешного завершения служебная директория export-{id} и копии таблиц удаляются.

Результат запуска

При успешном исполнении команда export nfs выводит сводную информацию о поставленной в очередь операции выгрузки в NFS, в заданном опцией --format формате. Фактическая выгрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией:

В режиме вывода pretty (по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id:

┌───────────────────────────────────────────┬───────┬─────...
| id                                        | ready | stat...
├───────────────────────────────────────────┼───────┼─────...
| ydb://export/6?id=281474976788395&kind=fs | true  | SUCC...
├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴...
| Include index data: false
| Items:
...

В режиме вывода proto-json-base64 идентификатор находится в атрибуте "id":

{"id":"ydb://export/6?id=281474976788395&kind=fs","ready":true, ... }

Статус выгрузки

Выгрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе выгрузки можно вызовом команды operation get, параметром которой должен быть передан заключенный в кавычки идентификатор операции, например:

ydb -p quickstart operation get "ydb://export/6?id=281474976788395&kind=fs"

Формат вывода operation get также устанавливается опцией --format.

Несмотря на то, что идентификатор операции имеет формат URL, не гарантируется, что он будет сохранен в дальнейшем. Его нужно интерпретировать только как строку.

Завершение выгрузки отслеживается по изменению атрибута "progress":

В режиме вывода pretty (по умолчанию) успешно завершенная операция отражается значением "Done" в выделенном псевдографикой поле progress:

┌───── ... ──┬───────┬─────────┬──────────┬─...
| id         | ready | status  | progress | ...
├──────... ──┼───────┼─────────┼──────────┼─...
| ydb://...   | true  | SUCCESS | Done     | ...
├╴╴╴╴╴ ... ╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴╴┴╴...
...

В режиме вывода proto-json-base64 завершенная операция отражается значением PROGRESS_DONE атрибута progress:
```
{"id":"ydb://...", ...,"progress":"PROGRESS_DONE",... }
```

Завершение операции выгрузки

После выполнения выгрузки воспользуйтесь командой operation forget для того, чтобы выгрузка считалась завершённой (была удалена из перечня операций):

ydb -p quickstart operation forget "ydb://export/6?id=281474976788395&kind=fs"

Список операций выгрузки

Для получения списка операций выгрузки воспользуйтесь командой operation list export/nfs:

ydb -p quickstart operation list export/nfs

Формат вывода operation list также устанавливается опцией --format.

Примеры

Примечание

В примерах используется профиль quickstart, подробнее смотрите в Создание профиля для соединения с тестовой БД.

Выгрузка базы данных

Выгрузка всех несистемных объектов базы данных в директорию /mnt/nfs/backups/export1 на файловой системе:

ydb -p quickstart export nfs \
  --fs-path /mnt/nfs/backups/export1

Выгрузка нескольких директорий

Выгрузка объектов из директорий dir1 и dir2 базы данных в директорию /mnt/nfs/backups/export1 на файловой системе:

ydb -p quickstart export nfs \
  --fs-path /mnt/nfs/backups/export1 \
  --include dir1 --include dir2

Либо с использованием альтернативного способа:

ydb -p quickstart export nfs \
  --fs-path /mnt/nfs/backups \
  --item src=dir1,dst=export1/dir1 --item src=dir2,dst=export1/dir2

Выгрузка с шифрованием

Выгрузка всей базы данных с шифрованием:

С использованием алгоритма шифрования AES-128-GCM
С генерацией случайного ключа утилитой openssl в файл ~/my_secret_key
С чтением сгенерированного ключа из файла ~/my_secret_key
В директорию /mnt/nfs/backups/export1 на файловой системе

openssl rand -out ~/my_secret_key 16
ydb -p quickstart export nfs \
  --fs-path /mnt/nfs/backups/export1 \
  --encryption-algorithm AES-128-GCM --encryption-key-file ~/my_secret_key

Выгрузка директории dir1 базы данных с шифрованием:

С использованием алгоритма шифрования AES-256-GCM
С генерацией случайного ключа утилитой openssl в переменную окружения YDB_ENCRYPTION_KEY
С чтением сгенерированного ключа из переменной окружения YDB_ENCRYPTION_KEY
В директорию /mnt/nfs/backups/export1 на файловой системе

export YDB_ENCRYPTION_KEY=$(openssl rand -hex 32)
ydb -p quickstart export nfs \
  --root-path dir1 \
  --fs-path /mnt/nfs/backups/export1 \
  --encryption-algorithm AES-256-GCM

Получение идентификаторов операций

Для получения перечня идентификаторов операций выгрузки в удобном для обработки в скриптах bash формате вы можете применить утилиту jq:

ydb -p quickstart operation list export/nfs --format proto-json-base64 | jq -r ".operations[].id"

Вы получите вывод, где в каждой новой строке находится идентификатор операции, например:

ydb://export/6?id=281474976789577&kind=fs
ydb://export/6?id=281474976789526&kind=fs
ydb://export/6?id=281474976788779&kind=fs

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

ydb -p quickstart operation list export/nfs --format proto-json-base64 | jq -r ".operations[].id" | while read line; do ydb -p quickstart operation forget $line;done

Была ли статья полезна?

Загрузка из S3

Загрузка из NFS