--- metadata: - name: generator content: Diplodoc Platform v5.59.0 alternate: - https://ydb.tech/docs/en/reference/ydb-cli/export-import/export-nfs.md - https://ydb.tech/docs/ru/reference/ydb-cli/export-import/export-nfs.md - href: https://ydb.tech/docs/ru/reference/ydb-cli/export-import/export-nfs.md type: text/markdown title: Markdown version - href: https://ydb.tech/docs/ru/llms.txt rel: describedby sourcePath: ru/core/reference/ydb-cli/export-import/export-nfs.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Выгрузка в NFS Команда `export nfs` запускает на стороне сервера процесс выгрузки в сетевую файловую систему ([Network File System](https://ru.wikipedia.org/wiki/Network_File_System), NFS) хостов кластера YDB данных и информации об объектах схемы, в описанном в статье [Файловая структура](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/file-structure.md) формате: ```bash ydb [connection options] export nfs [options] ``` , где `[connection options]` — опции [соединения с БД](https://ydb.tech/docs/ru/reference/ydb-cli/connect.md#command-line-pars) {% note warning %} Выгрузка доступна только для объектов следующих типов: - [директория](https://ydb.tech/docs/ru/concepts/datamodel/dir.md); - [строковая таблица](https://ydb.tech/docs/ru/concepts/datamodel/table.md#row-oriented-tables); - [вторичный индекс](https://ydb.tech/docs/ru/concepts/glossary.md#secondary-index); - [векторный индекс](https://ydb.tech/docs/ru/concepts/glossary.md#vector-index); - [полнотекстовый индекс](https://ydb.tech/docs/ru/concepts/glossary.md#fulltext-index); - [локальный Блум-индекс](https://ydb.tech/docs/ru/concepts/glossary.md#local-bloom-skip-index); - [топик](https://ydb.tech/docs/ru/concepts/datamodel/topic.md) (только схема); - [представление (view)](https://ydb.tech/docs/ru/concepts/datamodel/view.md); - [асинхронная репликация](https://ydb.tech/docs/ru/concepts/async-replication.md); - [трансфер](https://ydb.tech/docs/ru/concepts/transfer.md); - [внешний источник данных](https://ydb.tech/docs/ru/concepts/datamodel/external_data_source.md); - [внешняя таблица](https://ydb.tech/docs/ru/concepts/datamodel/external_table.md). {% endnote %} ## Параметры командной строки {#pars} `[options]` - параметры команды: ### Параметры NFS {#nfs-params} Команда выгрузки в NFS требует указания монтированной директории (или поддиректории) общей для всех объектов, участвующих в выгрузке. Так как выгрузка производится в асинхронном режиме на всех хостах YDB, указанная директория должна быть на каждом хосте YDB и смонтирована в NFS. `--fs-path PATH`: путь до монтированной директории (или поддиректории). ### Перечень выгружаемых объектов {#items} `--root-path PATH`: Корневая директория для выгружаемых объектов. Если не указана, используется корневая директория базы данных. `--include PATH`: Объекты схемы данных для включения в экспорт. Директории обходятся рекурсивно. Пути указываются относительно `root-path`. Данный параметр может быть указан несколько раз для включения нескольких объектов. Если не указан, выполняется выгрузка всех несистемных объектов в `root-path`. `--exclude STRING`: Шаблон ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) для исключения путей из выгрузки. Пути указываются относительно `root-path`. Данный параметр может быть указан несколько раз для разных шаблонов. {% cut "Альтернативный способ" %} Поддерживается альтернативный способ указания перечня объектов: `--item STRING`: Описание объекта выгрузки. Параметр `--item` может быть указан несколько раз, если необходимо выполнить выгрузку нескольких объектов. `STRING` задается в формате `<свойство>=<значение>,...`, со следующими обязательными свойствами: - `source`, `src`, или `s` — путь до выгружаемой директории или таблицы, `.` указывает на корневую директорию базы данных. При указании директории выгружаются все несистемные объекты в ней, а также рекурсивно все несистемные поддиректории. - `destination`, `dst`, или `d` — путь в NFS (относительно `--fs-path`). `--exclude STRING`: Шаблон ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) для исключения путей из выгрузки. Данный параметр может быть указан несколько раз для разных шаблонов. {% note warning %} Экспорты, сделанные с использованием альтернативного синтаксиса, не будут содержать списка объектов в составе резервной копии, поэтому некоторые возможности могут быть для них недоступны (в частности, шифрованные резервные копии), а импорт возможен только с использованием соответствующего альтернативного синтаксиса импорта. {% endnote %} {% endcut %} ### Дополнительные параметры {#aux} - `--description STRING`: Текстовое описание операции, сохраняемое в истории операций. - `--retries NUM`: Количество повторных попыток выгрузки, которые будет предпринимать сервер. Значение по умолчанию: `10`. - `--compression STRING`: Сжимать выгружаемые данные. При уровне сжатия по умолчанию для алгоритма [Zstandard](https://ru.wikipedia.org/wiki/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](https://ru.wikipedia.org/wiki/Protocol_Buffers) в формате [JSON](https://ru.wikipedia.org/wiki/JSON), бинарные строки закодированы в [Base64](https://ru.wikipedia.org/wiki/Base64). ## Выполнение выгрузки {#exec} ### Ход серверной операции выгрузки {#server-export-workflow} 1. Создаётся серверная асинхронная операция экспорта. 2. В корневой директории базы данных создаётся служебная директория `export-{id}`, где `{id}` — числовой идентификатор операции. 3. В эту директорию создаётся согласованная копия таблиц с помощью механизма `CopyTables`. 4. Данные каждой таблицы записываются из копии в хранилище в формате [файловой структуры выгрузки](https://ydb.tech/docs/ru/reference/ydb-cli/export-import/file-structure.md) с параллельной записью из разных узлов кластера. 5. После успешного завершения служебная директория `export-{id}` и копии таблиц удаляются. ### Результат запуска {#result} При успешном исполнении команда `export nfs` выводит сводную информацию о поставленной в очередь операции выгрузки в NFS, в заданном опцией `--format` формате. Фактическая выгрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией: - В режиме вывода `pretty` (по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id: ```text ┌───────────────────────────────────────────┬───────┬─────... | id | ready | stat... ├───────────────────────────────────────────┼───────┼─────... | ydb://export/6?id=281474976788395&kind=fs | true | SUCC... ├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴... | Include index data: false | Items: ... ``` - В режиме вывода `proto-json-base64` идентификатор находится в атрибуте "id": ```json {"id":"ydb://export/6?id=281474976788395&kind=fs","ready":true, ... } ``` ### Статус выгрузки {#status} Выгрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе выгрузки можно вызовом команды `operation get`, параметром которой должен быть передан **заключенный в кавычки** идентификатор операции, например: ```bash ydb -p quickstart operation get "ydb://export/6?id=281474976788395&kind=fs" ``` Формат вывода `operation get` также устанавливается опцией `--format`. Несмотря на то, что идентификатор операции имеет формат URL, не гарантируется, что он будет сохранен в дальнейшем. Его нужно интерпретировать только как строку. Завершение выгрузки отслеживается по изменению атрибута "progress": - В режиме вывода `pretty` (по умолчанию) успешно завершенная операция отражается значением "Done" в выделенном псевдографикой поле `progress`: ```text ┌───── ... ──┬───────┬─────────┬──────────┬─... | id | ready | status | progress | ... ├──────... ──┼───────┼─────────┼──────────┼─... | ydb://... | true | SUCCESS | Done | ... ├╴╴╴╴╴ ... ╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴╴╴╴┴╴... ... ``` - В режиме вывода `proto-json-base64` завершенная операция отражается значением `PROGRESS_DONE` атрибута `progress`: ```json {"id":"ydb://...", ...,"progress":"PROGRESS_DONE",... } ``` ### Завершение операции выгрузки {#forget} После выполнения выгрузки воспользуйтесь командой `operation forget` для того, чтобы выгрузка считалась завершённой (была удалена из перечня операций): ```bash ydb -p quickstart operation forget "ydb://export/6?id=281474976788395&kind=fs" ``` ### Список операций выгрузки {#list} Для получения списка операций выгрузки воспользуйтесь командой `operation list export/nfs`: ```bash ydb -p quickstart operation list export/nfs ``` Формат вывода `operation list` также устанавливается опцией `--format`. ## Примеры {#examples} {% note info %} В примерах используется профиль `quickstart`, подробнее смотрите в [Создание профиля для соединения с тестовой БД](https://ydb.tech/docs/ru/reference/ydb-cli/profile/create.md#quickstart). {% endnote %} ### Выгрузка базы данных {#example-full-db} Выгрузка всех несистемных объектов базы данных в директорию `/mnt/nfs/backups/export1` на файловой системе: ```bash ydb -p quickstart export nfs \ --fs-path /mnt/nfs/backups/export1 ``` ### Выгрузка нескольких директорий {#example-specific-dirs} Выгрузка объектов из директорий `dir1` и `dir2` базы данных в директорию `/mnt/nfs/backups/export1` на файловой системе: ```bash ydb -p quickstart export nfs \ --fs-path /mnt/nfs/backups/export1 \ --include dir1 --include dir2 ``` Либо с использованием альтернативного способа: ```bash ydb -p quickstart export nfs \ --fs-path /mnt/nfs/backups \ --item src=dir1,dst=export1/dir1 --item src=dir2,dst=export1/dir2 ``` ### Выгрузка с шифрованием {#example-encryption} Выгрузка всей базы данных с шифрованием: - С использованием алгоритма шифрования `AES-128-GCM` - С генерацией случайного ключа утилитой `openssl` в файл `~/my_secret_key` - С чтением сгенерированного ключа из файла `~/my_secret_key` - В директорию `/mnt/nfs/backups/export1` на файловой системе ```bash 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` на файловой системе ```bash 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 ``` ### Получение идентификаторов операций {#example-list-oneline} Для получения перечня идентификаторов операций выгрузки в удобном для обработки в скриптах bash формате вы можете применить утилиту [jq](https://stedolan.github.io/jq/download/): ```bash ydb -p quickstart operation list export/nfs --format proto-json-base64 | jq -r ".operations[].id" ``` Вы получите вывод, где в каждой новой строке находится идентификатор операции, например: ```text ydb://export/6?id=281474976789577&kind=fs ydb://export/6?id=281474976789526&kind=fs ydb://export/6?id=281474976788779&kind=fs ``` По этим идентификаторам может быть, например, запущен цикл для завершения всех текущих операций: ```bash 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 ```