Загрузка из NFS
Команда import nfs запускает на стороне сервера процесс загрузки из сетевой файловой системы (Network File System, NFS) хостов кластера YDB данных и информации об объектах схемы, в описанном в статье Файловая структура формате:
ydb [connection options] import nfs [options]
, где [connection options] — опции соединения с БД
В отличие от команды tools restore, команда import nfs всегда создает объекты целиком, поэтому для её успешного выполнения ни один из загружаемых объектов (ни директорий, ни таблиц) не должен существовать.
При необходимости догрузки данных в существующие таблицы воспользуйтесь командой tools restore непосредственно на смонтированной NFS-директории.
Параметры командной строки
[options] - параметры команды:
Параметры NFS
Команда загрузки из NFS требует указания монтированной директории (или поддиректории) общей для всех объектов, участвующих в загрузке. Так как загрузка производится в асинхронном режиме на всех хостах YDB, указанная директория должна быть на каждом хосте YDB и смонтирована в NFS.
--fs-path PATH: путь до монтированной директории (или поддиректории).
Загружаемые объекты схемы базы данных
--destination-path PATH: Целевая директория для загружаемых объектов; значением по умолчанию является корень базы данных.
--include PATH: Объекты схемы данных для включения в импорт. Директории обходятся рекурсивно. Для включения нескольких объектов допускается указание параметра несколько раз. Если не указан, выполняется загрузка всех объектов выгрузки.
--exclude STRING: Шаблон (PCRE) для исключения путей из импорта. Данный параметр может быть указан несколько раз для разных шаблонов.
Альтернативный способ
В целях обратной совместимости поддерживается альтернативный способ указания перечня объектов:
--item STRING: Описание объекта загрузки. Параметр --item может быть указан несколько раз, если необходимо выполнить загрузку нескольких объектов. Если параметры --item или --include не указаны, будут загружены все объекты, присутствующие в указанной выгрузке. STRING задаётся в формате <свойство>=<значение>,... со следующими обязательными свойствами:
source,srcилиs— путь в NFS (относительноfs-path) с загружаемой директорией или таблицей.destination,dst, илиd— путь в базе данных для размещения загружаемой директории или таблицы. Конечный элемент пути не должен существовать. Все директории на пути будут созданы, если не существуют.
Некоторые возможности могут быть недоступны при использовании альтернативного синтаксиса (в частности, шифрованные резервные копии или перечисление объектов выгрузки).
Дополнительные параметры
-
--description STRING: Текстовое описание операции, сохраняемое в истории операций. -
--retries NUM: Количество повторных попыток загрузки, которые будет предпринимать сервер. Значение по умолчанию:10. -
--skip-checksum-validation: Пропустить этап валидации контрольных сумм загружаемых объектов. -
--index-population-mode STRING: Режим наполнения индексов при импорте. Допустимые значения:build— построить индексы с нуля (значение по умолчанию);import— загрузить данные индексных таблиц (если выгрузка была выполнена с опцией--include-index-data);auto— попытаться загрузить данные индексных таблиц, при отсутствии данных построить индексы.
-
--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.
Примечание
Использование режима --index-population-mode=import позволяет максимально задействовать ресурсы и быстро восстановить индексы, либо наоборот — ограничить ресурсы и скопировать индексные таблицы с минимальным влиянием на пользовательскую нагрузку. Для ограничения ресурсов импорта используется очередь queue_restore брокера ресурсов.
Выполнение загрузки
Ход серверной операции загрузки
- Создаётся серверная асинхронная операция импорта.
- Сервер считывает метаданные объектов из файлов (
scheme.pb,metadata.jsonи т.д.) из хранилища. - Для каждого объекта создаётся новая таблица в базе данных. Целевые пути не должны существовать — импорт не может перезаписать существующие таблицы.
- Данные загружаются из файлов параллельно на всех узлах кластера.
Результат запуска
При успешном исполнении команда import nfs выводит сводную информацию о поставленной в очередь операции загрузки из NFS, в заданном опцией --format формате. Фактическая загрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией:
- В режиме вывода
pretty(по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id:
┌───────────────────────────────────────────┬───────┬─────...
| id | ready | stat...
├───────────────────────────────────────────┼───────┼─────...
| ydb://import/8?id=281474976788395&kind=fs | true | SUCC...
├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴...
| Items:
...
- В режиме вывода
proto-json-base64идентификатор находится в атрибуте "id":
{"id":"ydb://import/8?id=281474976788395&kind=fs","ready":true, ... }
Статус загрузки
Загрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе загрузки можно вызовом команды operation get, параметром которой должен быть передан заключенный в кавычки идентификатор операции, например:
ydb -p quickstart operation get "ydb://import/8?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://import/8?id=281474976788395&kind=fs"
Список операций загрузки
Для получения списка операций загрузки воспользуйтесь командой operation list import/nfs:
ydb -p quickstart operation list import/nfs
Формат вывода operation list также устанавливается опцией --format.
Примеры
Примечание
В примерах используется профиль quickstart, подробнее смотрите в Создание профиля для соединения с тестовой БД.
Загрузка в корень базы данных
Загрузка в корень базы данных содержимого директории /mnt/nfs/backups/export1 на файловой системе:
ydb -p quickstart import nfs \
--fs-path /mnt/nfs/backups/export1
Загрузка нескольких директорий
Загрузка объектов из директорий dir1 и dir2 выгрузки, расположенной в /mnt/nfs/backups/export1 на файловой системе, в одноименные директории базы данных:
ydb -p quickstart import nfs \
--fs-path /mnt/nfs/backups/export1 \
--include dir1 --include dir2
Загрузка зашифрованной выгрузки
Загрузка одной таблицы, которая была выгружена по пути dir/my_table, в путь dir1/dir/my_table из зашифрованной выгрузки, расположенной в /mnt/nfs/backups/export1 на файловой системе, с использованием секретного ключа из файла ~/my_secret_key.
ydb -p quickstart import nfs \
--fs-path /mnt/nfs/backups/export1 --destination-path dir1 \
--include dir/my_table \
--encryption-key-file ~/my_secret_key
Получение идентификаторов операций
Для получения перечня идентификаторов операций загрузки в удобном для обработки в скриптах bash формате вы можете применить утилиту jq:
ydb -p quickstart operation list import/nfs --format proto-json-base64 | jq -r ".operations[].id"
Вы получите вывод, где в каждой новой строке находится идентификатор операции, например:
ydb://import/8?id=281474976789577&kind=fs
ydb://import/8?id=281474976789526&kind=fs
ydb://import/8?id=281474976788779&kind=fs
По этим идентификаторам может быть, например, запущен цикл для завершения всех текущих операций:
ydb -p quickstart operation list import/nfs --format proto-json-base64 | jq -r ".operations[].id" | while read line; do ydb -p quickstart operation forget $line;done