diff options
| author | stanislav_shchetinin <[email protected]> | 2026-06-29 07:58:56 +0300 |
|---|---|---|
| committer | GitHub <[email protected]> | 2026-06-29 07:58:56 +0300 |
| commit | 7241e954bfa17d8b0c62c1917f0cedf2e2489ec7 (patch) | |
| tree | 40705155c1df2f83a41d7a1f98148fe21154469b | |
| parent | e0a46902292e7fafd03dec4ec492a65ebb2fee07 (diff) | |
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
Co-authored-by: Ilnaz Nizametdinov <[email protected]>
Co-authored-by: sintjuri <[email protected]>
Co-authored-by: Stepan Beloyarov <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Cursor <[email protected]>
32 files changed, 871 insertions, 101 deletions
diff --git a/ydb/docs/ru/core/concepts/backup.md b/ydb/docs/ru/core/concepts/backup.md index 22738b28755..f6198fc8698 100644 --- a/ydb/docs/ru/core/concepts/backup.md +++ b/ydb/docs/ru/core/concepts/backup.md @@ -41,6 +41,18 @@ - миграции данных между кластерами; - долгосрочного архивирования. +### Экспорт в NFS {#nfs} + +Команды [`{{ ydb-cli }} export nfs`](../reference/ydb-cli/export-import/export-nfs.md) и [`{{ ydb-cli }} import nfs`](../reference/ydb-cli/export-import/import-nfs.md) позволяют выгружать и загружать данные в сетевую файловую систему (NFS), смонтированную на всех хостах кластера {{ ydb-short-name }}. В отличие от [дампа в файловую систему](#dump), выгрузка выполняется на стороне сервера и не требует передачи данных через CLI. + +Подходит для: + +- аварийного восстановления (данные хранятся вне кластера); +- миграции данных между кластерами; +- долгосрочного архивирования. + +Подробнее про настройку NFS для резервного копирования и восстановления см. рецепт [Резервное копирование и восстановление через NFS](../recipes/nfs-backup/nfs-backup.md). + ## Инкрементальное резервное копирование {#incremental-backup} При работе с большими таблицами повторное создание полных резервных копий может быть слишком затратным. Инкрементальное резервное копирование решает эту задачу: после начальной полной копии каждый последующий инкремент захватывает только изменения (вставки, обновления, удаления), произошедшие с момента предыдущей резервной копии. @@ -111,6 +123,7 @@ || [Копирование таблиц внутри кластера](#copy-table) | В кластере | Нет | Быстрая копия перед опасной операцией || || [Дамп в файловую систему](#dump) | Файловая система | Нет | Разработка, тестирование, небольшие БД || || [Экспорт в S3-совместимое хранилище](#s3) | S3-совместимое хранилище | Нет | Аварийное восстановление, миграция, архивирование || +|| [Экспорт в NFS](#nfs) | Сетевая файловая система (NFS) | Нет | Аварийное восстановление, миграция, архивирование || || [Инкрементальное резервное копирование](#incremental-backup) | В кластере ([экспортируются](datamodel/backup-collection.md#external-storage) в S3 или файловую систему) | Да | Регулярные бэкапы больших производственных БД || || [Резервное копирование системных таблеток](#system-tablet-backup) | Локальная ФС хостов кластера | Да | Восстановление метаданных кластера в аварийных ситуациях || |# diff --git a/ydb/docs/ru/core/concepts/datamodel/backup-collection.md b/ydb/docs/ru/core/concepts/datamodel/backup-collection.md index baca872fd5b..196616b62b9 100644 --- a/ydb/docs/ru/core/concepts/datamodel/backup-collection.md +++ b/ydb/docs/ru/core/concepts/datamodel/backup-collection.md @@ -135,7 +135,8 @@ block-beta Для экспорта резервных копий во внешнее хранилище используйте {{ ydb-short-name }} CLI: - [`ydb export s3`](../../reference/ydb-cli/export-import/export-s3.md) для S3-совместимого хранилища. -- [`ydb tools dump`](../../reference/ydb-cli/export-import/tools-dump.md) для файловой системы. +- [`ydb export nfs`](../../reference/ydb-cli/export-import/export-nfs.md) для NFS на хостах кластера. +- [`ydb tools dump`](../../reference/ydb-cli/export-import/tools-dump.md) для файловой системы на локальном компьютере. Каждую резервную копию в цепочке необходимо экспортировать отдельно. Сохраняйте порядок цепочки при экспорте/импорте для успешного восстановления. diff --git a/ydb/docs/ru/core/devops/backup-and-recovery/index.md b/ydb/docs/ru/core/devops/backup-and-recovery/index.md index f791106f739..94367c07eae 100644 --- a/ydb/docs/ru/core/devops/backup-and-recovery/index.md +++ b/ydb/docs/ru/core/devops/backup-and-recovery/index.md @@ -36,9 +36,17 @@ Для выполнения восстановления из резервной копии, созданной в S3-совместимом хранилище, применяется команда `{{ ydb-cli }} import s3`. Перейдите [по ссылке](../../reference/ydb-cli/export-import/import-s3.md) в справочник по {{ ydb-short-name }} CLI для получения информации о данной команде. +### NFS {#nfs} + +Для выполнения резервного копирования в [NFS](https://ru.wikipedia.org/wiki/Network_File_System) на хостах, где запущена {{ ydb-short-name }}, применяется команда `{{ ydb-cli }} export nfs`. Перейдите [по ссылке](../../reference/ydb-cli/export-import/export-nfs.md) в справочник по {{ ydb-short-name }} CLI для получения информации о данной команде. + +Для выполнения восстановления из резервной копии, созданной в [NFS](https://ru.wikipedia.org/wiki/Network_File_System) на хостах, где запущена {{ ydb-short-name }}, применяется команда `{{ ydb-cli }} import nfs`. Перейдите [по ссылке](../../reference/ydb-cli/export-import/import-nfs.md) в справочник по {{ ydb-short-name }} CLI для получения информации о данной команде. + +Подробнее про настройку NFS для резервного копирования и восстановления см. рецепт [Резервное копирование и восстановление через NFS](../../recipes/nfs-backup/nfs-backup.md). + {% note info %} -Скорость операций резервного копирования и восстановления в/из S3-совместимого хранилища подобрана таким образом, чтобы минимизировать влияние на пользовательскую нагрузку. Для управления скоростью операций настройте лимиты для соответствующей очереди [брокера ресурсов](../../reference/configuration/resource_broker_config.md#resource-broker-config). +Скорость операций резервного копирования и восстановления в/из S3-совместимого хранилища или NFS подобрана таким образом, чтобы минимизировать влияние на пользовательскую нагрузку. Для управления скоростью операций настройте лимиты для соответствующей очереди [брокера ресурсов](../../reference/configuration/resource_broker_config.md#resource-broker-config). {% endnote %} diff --git a/ydb/docs/ru/core/recipes/nfs-backup/nfs-backup.md b/ydb/docs/ru/core/recipes/nfs-backup/nfs-backup.md new file mode 100644 index 00000000000..e2ad20b709c --- /dev/null +++ b/ydb/docs/ru/core/recipes/nfs-backup/nfs-backup.md @@ -0,0 +1,352 @@ +# Резервное копирование и восстановление через NFS + +Рецепт описывает подготовку NFS для серверных команд **`export nfs`** и **`import nfs`**: требования к кластеру, права доступа, пошаговую настройку NFS-сервера и клиентов, feature flags, производительность и диагностику. Синтаксис команд см. в справочнике: [выгрузка в NFS](../../reference/ydb-cli/export-import/export-nfs.md), [загрузка из NFS](../../reference/ydb-cli/export-import/import-nfs.md). + +## Предварительные требования {#nfs-prerequisites} + +Операции `export nfs` / `import nfs` выполняются **серверными процессами** {{ ydb-short-name }}, а не CLI-клиентом. Это означает, что файловая система должна быть доступна с каждого узла кластера: + +- NFS-директория должна быть смонтирована на **всех узлах** кластера {{ ydb-short-name }} по одному и тому же абсолютному пути. +- Процесс {{ ydb-short-name }} должен иметь права на **запись** при экспорте и на **чтение** при импорте в эту директорию. +- Путь `--fs-path` должен быть абсолютным. Относительные пути, пути содержащие `..` или `.`, а также пути с нулевыми байтами будут отклонены сервером. +- Функциональность должна быть включена с помощью [feature flag](#nfs-feature-flags) `enable_fs_backups`. + +{% note warning %} + +Данная функциональность совместима с протоколом сетевой файловой системы NFSv4. + +{% endnote %} + +## Права доступа {#nfs-permissions} + +Файловые операции выполняются серверными процессами {{ ydb-short-name }}, а не CLI-клиентом. Поэтому права на NFS-директорию должны быть предоставлены пользователю ОС, от имени которого запущен процесс `ydbd`. + +**POSIX-права:** + +- Для **экспорта** (запись файлов): `rwx` на директорию (чтение для обхода, запись для создания файлов и поддиректорий, выполнение для навигации) и `rw` на файлы. +- Для **импорта** (чтение файлов): `rx` на директорию (чтение для обхода, выполнение для навигации) и `r` на файлы. + +**NFSv4 ACL:** + +NFSv4 использует расширенную модель прав вместо POSIX `rwx`. Одна и та же буква в NFSv4 ACE имеет разное значение для файлов и директорий: + +#| +|| **Буква** | **Для файлов** | **Для директорий** || +|| `r` | `read-data` — чтение содержимого | `list-directory` — просмотр содержимого || +|| `w` | `write-data` — запись данных | `create-file` — создание файлов || +|| `a` | `append-data` — дополнение данных | `create-subdirectory` — создание поддиректорий || +|| `x` | `execute` — выполнение | `change-directory` — навигация || +|| `D` | — | `delete-child` — удаление вложенных объектов || +|| `t` | `read-attributes` | `read-attributes` || +|# + +Права на NFS-директорию для **экспорта** (создание файлов и поддиректорий): + +- На саму директорию: `w` (create-file), `a` (create-subdirectory), `x` (change-directory), `t` (read-attributes), `D` (delete-child). +- На создаваемые файлы: `w` (write-data), `a` (append-data), `t` (read-attributes). + +Права на NFS-директорию для **импорта** (чтение файлов): + +- На саму директорию: `r` (list-directory), `x` (change-directory), `t` (read-attributes). +- На файлы: `r` (read-data), `t` (read-attributes). + +Поскольку файлы создаются процессом `ydbd` в ходе экспорта, права на них нельзя задать заранее. В NFSv4 для этого используется **наследование ACE** — флаги `f` (file-inherit) и `d` (directory-inherit) на ACE родительской директории. При создании нового файла или поддиректории ACE с этими флагами автоматически копируются на новый объект. + +{% cut "Пошаговая настройка NFS-сервера и клиентов" %} + +Ниже приведены инструкции по настройке NFS-сервера и клиентских узлов {{ ydb-short-name }} для двух вариантов управления правами: стандартные POSIX-права и расширенные NFSv4 ACL. + +### Вариант 1: POSIX-права + +#### Настройка NFS-сервера + +1. Установите пакет NFS-сервера: + + ```bash + sudo apt install nfs-kernel-server + ``` + +2. Создайте директорию для экспорта и назначьте владельца: + + ```bash + sudo mkdir -p /mnt/ydb-backup + sudo chown ydb:ydb /mnt/ydb-backup + sudo chmod 755 /mnt/ydb-backup + ``` + + Опции команды `chmod`: + - `7` (rwx) — владелец (`ydb`) может читать, писать и переходить в директорию. + - `5` (r-x) — группа и остальные могут читать и переходить, но не писать. + +3. Добавьте директорию в `/etc/exports`: + + ```text + /mnt/ydb-backup ydb-node-*.example.com(rw,sync,root_squash) + ``` + + Опции экспорта: + - `rw` — разрешить чтение и запись. + - `sync` — синхронная запись (данные записываются на диск до подтверждения клиенту). + - `root_squash` — преобразовать `root` на клиенте в анонимного пользователя. + +4. Примените изменения и запустите NFS-сервер: + + ```bash + sudo exportfs -arv + sudo systemctl enable --now nfs-server + ``` + + Опции `exportfs`: + - `-a` — экспортировать все директории из `/etc/exports`. + - `-r` — переэкспортировать все директории (синхронизация с `/etc/exports`). + - `-v` — подробный вывод. + +#### Настройка клиентов (узлов {{ ydb-short-name }}) + +1. Установите пакет NFS-клиента: + + ```bash + sudo apt install nfs-common + ``` + +2. Создайте точку монтирования: + + ```bash + sudo mkdir -p /mnt/ydb-backup + ``` + +3. Смонтируйте NFS-директорию: + + ```bash + sudo mount -t nfs4 -o rw nfs-server.example.com:/mnt/ydb-backup /mnt/ydb-backup + ``` + + Опции монтирования: + - `-t nfs4` — тип файловой системы NFSv4. + - `-o rw` — монтировать с правом чтения и записи. + + В данном примере хост сервер не принадлежит кластеру {{ ydb-short-name }}, при этом резервное копирование и восстановление будут корректно работать в случае, если один из хостов кластера назначен NFS-сервером. + +4. Для автоматического монтирования при загрузке добавьте строку в `/etc/fstab`: + + ```text + nfs-server.example.com:/mnt/ydb-backup /mnt/ydb-backup nfs4 rw,hard,timeo=600,retrans=2,_netdev 0 0 + ``` + + Опции `fstab`: + - `rw` — чтение и запись. + - `hard` — при недоступности сервера повторять запросы бесконечно (не терять данные). + - `timeo=600` — таймаут запроса в десятых долях секунды (60 секунд). + - `retrans=2` — количество повторных попыток перед сообщением об ошибке. + - `_netdev` — монтировать только после инициализации сети. + +#### Проверка работоспособности + +На сервере (или любом клиенте) создайте тестовый файл от имени пользователя `ydb`: + +```bash +sudo -u ydb touch /mnt/ydb-backup/test-file +``` + +На всех клиентских узлах проверьте, что файл виден: + +```bash +sudo -u ydb ls /mnt/ydb-backup/test-file +``` + +После проверки удалите тестовый файл: + +```bash +sudo -u ydb rm /mnt/ydb-backup/test-file +``` + +### Вариант 2: NFSv4 ACL + +NFSv4 ACL позволяют задать более гранулярные права доступа, а также настроить наследование прав для вновь создаваемых файлов и директорий. + +#### Настройка NFS-сервера + +1. Установите пакет NFS-сервера и утилиты для работы с NFSv4 ACL: + + ```bash + sudo apt install nfs-kernel-server nfs4-acl-tools + ``` + +2. Создайте директорию для экспорта: + + ```bash + sudo mkdir -p /mnt/ydb-backup-server + ``` + +3. Добавьте директорию в `/etc/exports`: + + ```text + /mnt/ydb-backup-server ydb-node-*.example.com(rw,sync,no_subtree_check,root_squash) + ``` + +4. Примените изменения: + + ```bash + sudo exportfs -arv + sudo systemctl enable --now nfs-server + ``` + +#### Настройка клиентов (узлов {{ ydb-short-name }}) + +В отличие от POSIX-прав, которые задаются на NFS-сервере, NFSv4 ACL настраиваются на каждом клиенте после монтирования директории. Если NFS-сервер одновременно является узлом кластера {{ ydb-short-name }}, на нём необходимо выполнить все описанные ниже шаги. + +1. Установите пакеты NFS-клиента и утилиты для работы с NFSv4 ACL: + + ```bash + sudo apt install nfs-common nfs4-acl-tools + ``` + +2. Создайте точку монтирования: + + ```bash + sudo mkdir -p /mnt/ydb-backup + ``` + +3. Смонтируйте NFS-директорию по протоколу NFSv4: + + ```bash + sudo mount -t nfs4 -o rw nfs-server.example.com:/mnt/ydb-backup /mnt/ydb-backup + ``` + + Опции: + - `-t nfs4` — явно указать протокол NFSv4 (необходимо для корректной работы ACL). + - `-o rw` — монтировать с правом чтения и записи. + +4. Для автоматического монтирования добавьте строку в `/etc/fstab`: + + ```text + nfs-server.example.com:/mnt/ydb-backup-server /mnt/ydb-backup nfs4 rw,hard,timeo=600,retrans=2,_netdev 0 0 + ``` + +5. Определите UID пользователя `ydb`: + + ```bash + id -u ydb + ``` + + Пример вывода: `1871` + +6. Настройте NFSv4 ACL на директории: + + ```bash + sudo nfs4_setfacl -s A::<uid>:rwaxtD,A:fi:OWNER@:rwat,A:di:OWNER@:rwaxtD /mnt/ydb-backup + ``` + + Структура ACE (`A:flags:who:permissions`): + - `A` — тип ACE: Allow (разрешить). + - Флаги наследования: + - `f` (file-inherit) — наследовать на создаваемые файлы. + - `d` (directory-inherit) — наследовать на создаваемые поддиректории. + - `i` (inherit-only) — применять только к потомкам, не к самой директории. + - `who` — кому предоставляются права: + - `1871` — UID пользователя `ydb`. + - `OWNER@` — владелец объекта. + - Разрешения: + - `r` — read-data / list-directory. + - `w` — write-data / create-file. + - `a` — append-data / create-subdirectory. + - `t` — read-attributes. + - `D` - delete-child. + + Данная команда устанавливает: + - Права для пользователя `ydb` на саму директорию. + - Наследуемые права для файлов и поддиректорий (`fi`, `di`), которые будут применяться только к потомкам. + - Права владельца (`OWNER@`) с наследованием на файлы и директории. + +#### Проверка работоспособности + +Проверьте установленные ACL: + +```bash +nfs4_getfacl /mnt/ydb-backup +``` + +Создайте тестовый файл от имени пользователя `ydb`: + +```bash +sudo -u ydb touch /mnt/ydb-backup/test-file +``` + +Проверьте, что файл унаследовал ACL: + +```bash +nfs4_getfacl /mnt/ydb-backup/test-file +``` + +На всех клиентских узлах проверьте доступ: + +```bash +sudo -u ydb ls /mnt/ydb-backup/test-file +``` + +После проверки удалите тестовый файл: + +```bash +sudo -u ydb rm /mnt/ydb-backup/test-file +``` + +{% endcut %} + +## Feature flags {#nfs-feature-flags} + +Для использования экспорта и импорта через NFS необходимо включить feature flag `enable_fs_backups` в [конфигурации](../../reference/configuration/feature_flags.md) кластера. По умолчанию этот флаг **выключен**. + +## Конфигурация производительности {#nfs-performance} + +На производительность операций экспорта и импорта через NFS влияют два механизма: **брокер ресурсов** (управляет параллельностью задач сканирования и загрузки данных) и **IO-пул акторной системы** (обслуживает файловые операции записи и чтения). + +### Брокер ресурсов + +Экспорт и импорт через NFS используют те же очереди [брокера ресурсов](../../reference/configuration/resource_broker_config.md), что и S3: `queue_backup` для экспорта и `queue_restore` для импорта. Увеличение лимитов ускоряет операции, но увеличивает нагрузку на CPU. Значения по умолчанию и способ настройки описаны в разделе [{#T}](../../reference/configuration/resource_broker_config.md). + +### IO-пул акторной системы + +Файловые операции (запись при экспорте, чтение при импорте) выполняются акторами в пуле `IO` [акторной системы](../../reference/configuration/actor_system_config.md#tuneconfig). По умолчанию этот пул содержит `1` поток. Поскольку операции с файловой системой являются блокирующими, при интенсивном экспорте или импорте IO-пул может стать узким местом. + +Для увеличения количества потоков в IO-пуле измените параметр `threads` в [конфигурации акторной системы](../../reference/configuration/actor_system_config.md#tuneconfig): + +```yaml +actor_system_config: + executor: + - name: IO + threads: 3 + time_per_mailbox_micro_secs: 100 + type: IO +``` + +{% note tip %} + +Рекомендации по выбору количества потоков IO-пула при использовании NFS-экспорта/импорта: + +- Начните с `2` потоков и наблюдайте за нагрузкой. +- Учитывайте, что IO-пул обслуживает не только NFS-операции, но и другие блокирующие задачи (например, запись логов). +- Мониторьте загрузку пула через [Embedded UI](../../reference/embedded-ui/ydb-monitoring.md#node_list_page). + +{% endnote %} + +## Логирование {#nfs-logging} + +Ход выполнения операций экспорта и импорта отражается в серверных логах {{ ydb-short-name }}. Основные компоненты логирования: + +- **`EXPORT`** — логирование процесса экспорта на SchemeShard: создание директорий, копирование таблиц, запуск задач резервного копирования, загрузка схемы. +- **`IMPORT`** — логирование процесса импорта на SchemeShard: чтение метаданных, создание таблиц, восстановление данных. +- **`FS_WRAPPER`** — логирование файловых операций на каждом узле. Этот компонент фиксирует ошибки ввода-вывода (недоступность файла, нехватка места, ошибки блокировки), что позволяет выявить проблемы с NFS-монтированием на конкретных узлах. + +При диагностике проблем рекомендуется: + +- Проверять статус операции через `{{ ydb-cli }} operation get`. +- Искать в серверных логах записи с компонентами `EXPORT` или `IMPORT` и идентификатором операции. +- При ошибках записи или чтения файлов искать в логах записи с компонентом `FS_WRAPPER` — они содержат путь к файлу и описание ошибки, что позволяет определить, на каком хосте и с каким файлом возникла проблема. +- Проверять, что NFS-директория доступна и имеет достаточно свободного места на **всех** узлах кластера. + +## Ограничения {#nfs-limitations} + +- Экспорт и импорт через NFS поддерживают те же типы объектов, что и экспорт в S3. Подробный перечень поддерживаемых объектов приведён в документации [команды экспорта](../../reference/ydb-cli/export-import/export-nfs.md). +- Импорт всегда создаёт объекты заново — нельзя импортировать в существующие таблицы. +- Параметр `--list` для перечисления объектов выгрузки в текущей версии доступен только для импорта из S3. +- Операция не поддерживается на Windows-платформе. diff --git a/ydb/docs/ru/core/recipes/toc_p.yaml b/ydb/docs/ru/core/recipes/toc_p.yaml index 3874041bed3..9162abf5b7a 100644 --- a/ydb/docs/ru/core/recipes/toc_p.yaml +++ b/ydb/docs/ru/core/recipes/toc_p.yaml @@ -42,6 +42,8 @@ items: include: mode: link path: transfer/toc_p.yaml +- name: Резервное копирование в NFS + href: nfs-backup/nfs-backup.md - name: Импорт и экспорт данных в колоночные таблицы href: import-export-column-tables.md - name: Потоковые запросы diff --git a/ydb/docs/ru/core/reference/configuration/feature_flags.md b/ydb/docs/ru/core/reference/configuration/feature_flags.md index cf4c7f1db53..04219ac7ad1 100644 --- a/ydb/docs/ru/core/reference/configuration/feature_flags.md +++ b/ydb/docs/ru/core/reference/configuration/feature_flags.md @@ -28,3 +28,4 @@ feature_flags: | `enable_kafka_transactions` | Включение транзакций в [YDB Topics Kafka API](../../reference/kafka-api/index.md)| | `enable_external_data_sources` | Включение [внешних источников данных](../../concepts/datamodel/external_data_source.md)| | `enable_grpc_audit` | Включение [аудита](../../security/audit-log.md#grpc-connection) изменений состояния gRPC-соединения | +| `enable_fs_backups` | Включение операций [резервного копирования и восстановления на сетевую файловую систему](../../concepts/backup.md#nfs) | diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-alternative-syntax-warning.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-alternative-syntax-warning.md new file mode 100644 index 00000000000..603748d3c60 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-alternative-syntax-warning.md @@ -0,0 +1,5 @@ +{% note warning %} + +Экспорты, сделанные с использованием альтернативного синтаксиса, не будут содержать списка объектов в составе резервной копии, поэтому некоторые возможности могут быть для них недоступны (в частности, шифрованные резервные копии), а импорт возможен только с использованием соответствующего альтернативного синтаксиса импорта. + +{% endnote %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-forget-intro.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-forget-intro.md new file mode 100644 index 00000000000..44737df1350 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-forget-intro.md @@ -0,0 +1 @@ +После выполнения выгрузки воспользуйтесь командой `operation forget` для того, чтобы выгрузка считалась завершённой (была удалена из перечня операций): diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-list-tail.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-list-tail.md new file mode 100644 index 00000000000..5e48bf22c25 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-list-tail.md @@ -0,0 +1 @@ +Формат вывода `operation list` также устанавливается опцией `--format`. diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-result-json-intro.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-result-json-intro.md new file mode 100644 index 00000000000..6f31201dfc4 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-result-json-intro.md @@ -0,0 +1 @@ +- В режиме вывода `proto-json-base64` идентификатор находится в атрибуте "id": diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-result-pretty-intro.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-result-pretty-intro.md new file mode 100644 index 00000000000..5436f80d8ed --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-result-pretty-intro.md @@ -0,0 +1 @@ +- В режиме вывода `pretty` (по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id: diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-status-after-get.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-status-after-get.md new file mode 100644 index 00000000000..e459daab741 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-status-after-get.md @@ -0,0 +1,22 @@ +Формат вывода `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",... } + ``` diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-status-intro.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-status-intro.md new file mode 100644 index 00000000000..8f764bc74fa --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-operation-status-intro.md @@ -0,0 +1 @@ +Выгрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе выгрузки можно вызовом команды `operation get`, параметром которой должен быть передан **заключенный в кавычки** идентификатор операции, например: diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-root-include-exclude-params.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-root-include-exclude-params.md new file mode 100644 index 00000000000..08264415af7 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-root-include-exclude-params.md @@ -0,0 +1,5 @@ +`--root-path PATH`: Корневая директория для выгружаемых объектов. Если не указана, используется корневая директория базы данных. + +`--include PATH`: Объекты схемы данных для включения в экспорт. Директории обходятся рекурсивно. Пути указываются относительно `root-path`. Данный параметр может быть указан несколько раз для включения нескольких объектов. Если не указан, выполняется выгрузка всех несистемных объектов в `root-path`. + +`--exclude STRING`: Шаблон ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) для исключения путей из выгрузки. Пути указываются относительно `root-path`. Данный параметр может быть указан несколько раз для разных шаблонов. diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-s3.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-s3.md index 73c2d6b005b..37c2f901aaa 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-s3.md +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-s3.md @@ -10,20 +10,7 @@ {% note warning %} -Выгрузка доступна только для объектов следующих типов: - -- [директория](../../../../concepts/datamodel/dir.md); -- [строковая таблица](../../../../concepts/datamodel/table.md#row-oriented-tables); -- [вторичный индекс](../../../../concepts/glossary.md#secondary-index); -- [векторный индекс](../../../../concepts/glossary.md#vector-index); -- [полнотекстовый индекс](../../../../concepts/glossary.md#fulltext-index); -- [локальный Блум-индекс](../../../../concepts/glossary.md#local-bloom-skip-index); -- [топик](../../../../concepts/datamodel/topic.md) (только схема); -- [представление (view)](../../../../concepts/datamodel/view.md); -- [асинхронная репликация](../../../../concepts/async-replication.md); -- [трансфер](../../../../concepts/transfer.md); -- [внешний источник данных](../../../../concepts/datamodel/external_data_source.md); -- [внешняя таблица](../../../../concepts/datamodel/external_table.md). +{% include [export-supported-object-types.md](export-supported-object-types.md) %} Для более простого экспорта одиночных строковых и колоночных таблиц в S3-совместимое хранилище данных можно использовать [внешние источники данных](../../../../concepts/datamodel/external_data_source.md). Подробнее см. в статье [{#T}](../../../../concepts/query_execution/federated_query/s3/write_data.md#export-to-s3). @@ -41,11 +28,7 @@ ### Перечень выгружаемых объектов {#items} -`--root-path PATH`: Корневая директория для выгружаемых объектов. Если не указана, используется корневая директория базы данных. - -`--include PATH`: Объекты схемы данных для включения в экспорт. Директории обходятся рекурсивно. Пути указываются относительно `root-path`. Данный параметр может быть указан несколько раз для включения нескольких объектов. Если не указан, выполняется выгрузка всех несистемных объектов в `root-path`. - -`--exclude STRING`: Шаблон ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) для исключения путей из выгрузки. Пути указываются относительно `root-path`. Данный параметр может быть указан несколько раз для разных шаблонов. +{% include [export-root-include-exclude-params.md](export-root-include-exclude-params.md) %} {% cut "Альтернативный способ" %} @@ -58,32 +41,30 @@ `--exclude STRING`: Шаблон ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) для исключения путей из выгрузки. Данный параметр может быть указан несколько раз для разных шаблонов. -{% note warning %} - -Экспорты, сделанные с использованием альтернативного синтаксиса, не будут содержать списка объектов в составе резервной копии, поэтому некоторые возможности могут быть для них недоступны (в частности, шифрованные резервные копии), а импорт возможен только с использованием соответствующего альтернативного синтаксиса импорта. - -{% endnote %} +{% include [export-alternative-syntax-warning.md](export-alternative-syntax-warning.md) %} {% endcut %} ### Дополнительные параметры {#aux} -Параметр | Описание ---- | --- -`--description STRING` | Текстовое описание операции, сохраняемое в истории операций. -`--retries NUM` | Количество повторных попыток выгрузки, которые будет предпринимать сервер.<br/>Значение по умолчанию: `10`. -`--compression STRING` | Сжимать выгружаемые данные.<br/>При уровне сжатия по умолчанию для алгоритма [Zstandard](https://ru.wikipedia.org/wiki/Zstandard) данные могут быть сжаты в 5-10 раз. Сжатие данных использует ресурс CPU и может повлиять на скорость выполнения других операций с БД.<br/>Допустимые значения:<br/><ul><li>`zstd` — сжатие алгоритмом Zstandard c уровнем сжатия по умолчанию (`3`);</li><li>`zstd-N` — сжатие алгоритмом Zstandard, `N` — уровень сжатия (`1` — `22`).</li></ul> -`--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` | Формат вывода результата.<br/>Допустимые значения:<br/><ul><li>`pretty` — человекочитаемый формат (по умолчанию);</li><li>`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).</li></ul> +| Параметр | Описание | +| --- | --- | +| `--description STRING` | Текстовое описание операции, сохраняемое в истории операций. | +| `--retries NUM` | Количество повторных попыток выгрузки, которые будет предпринимать сервер.<br/>Значение по умолчанию: `10`. | +| `--compression STRING` | Сжимать выгружаемые данные.<br/>При уровне сжатия по умолчанию для алгоритма [Zstandard](https://ru.wikipedia.org/wiki/Zstandard) данные могут быть сжаты в 5-10 раз. Сжатие данных использует ресурс CPU и может повлиять на скорость выполнения других операций с БД.<br/>Допустимые значения:<br/><ul><li>`zstd` — сжатие алгоритмом Zstandard c уровнем сжатия по умолчанию (`3`);</li><li>`zstd-N` — сжатие алгоритмом Zstandard, `N` — уровень сжатия (`1` — `22`).</li></ul> | +| `--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` | Формат вывода результата.<br/>Допустимые значения:<br/><ul><li>`pretty` — человекочитаемый формат (по умолчанию);</li><li>`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).</li></ul> | ## Выполнение выгрузки {#exec} +{% include [server-export-workflow.md](server-export-workflow.md) %} + ### Результат запуска {#result} При успешном исполнении команда `export s3` выводит сводную информацию о поставленной в очередь операции выгрузки в S3, в заданном опцией `--format` формате. Фактическая выгрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией: -- В режиме вывода `pretty` (по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id: +{% include [export-operation-result-pretty-intro.md](export-operation-result-pretty-intro.md) %} ```text ┌───────────────────────────────────────────┬───────┬─────... @@ -96,7 +77,7 @@ ... ``` -- В режиме вывода `proto-json-base64` идентификатор находится в атрибуте "id": +{% include [export-operation-result-json-intro.md](export-operation-result-json-intro.md) %} ```json {"id":"ydb://export/6?id=281474976788395&kind=s3","ready":true, ... } @@ -104,38 +85,17 @@ ### Статус выгрузки {#status} -Выгрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе выгрузки можно вызовом команды `operation get`, параметром которой должен быть передан **заключенный в кавычки** идентификатор операции, например: +{% include [export-operation-status-intro.md](export-operation-status-intro.md) %} ```bash {{ ydb-cli }} -p quickstart operation get "ydb://export/6?id=281474976788395&kind=s3" ``` -Формат вывода `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",... } - ``` +{% include [export-operation-status-after-get.md](export-operation-status-after-get.md) %} ### Завершение операции выгрузки {#forget} -После выполнения выгрузки воспользуйтесь командой `operation forget` для того, чтобы выгрузка считалась завершённой (была удалена из перечня операций): +{% include [export-operation-forget-intro.md](export-operation-forget-intro.md) %} ```bash {{ ydb-cli }} -p quickstart operation forget "ydb://export/6?id=281474976788395&kind=s3" @@ -149,7 +109,7 @@ {{ ydb-cli }} -p quickstart operation list export/s3 ``` -Формат вывода `operation list` также устанавливается опцией `--format`. +{% include [export-operation-list-tail.md](export-operation-list-tail.md) %} ## Примеры {#examples} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-supported-object-types.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-supported-object-types.md new file mode 100644 index 00000000000..9a0b00935a2 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/export-supported-object-types.md @@ -0,0 +1,13 @@ +Выгрузка доступна только для объектов следующих типов: + +- [директория](../../../../concepts/datamodel/dir.md); +- [строковая таблица](../../../../concepts/datamodel/table.md#row-oriented-tables); +- [вторичный индекс](../../../../concepts/glossary.md#secondary-index); +- [векторный индекс](../../../../concepts/glossary.md#vector-index); +- [полнотекстовый индекс](../../../../concepts/glossary.md#fulltext-index); +- [топик](../../../../concepts/datamodel/topic.md) (только схема); +- [представление (view)](../../../../concepts/datamodel/view.md); +- [асинхронная репликация](../../../../concepts/async-replication.md); +- [трансфер](../../../../concepts/transfer.md); +- [внешний источник данных](../../../../concepts/datamodel/external_data_source.md); +- [внешняя таблица](../../../../concepts/datamodel/external_table.md). diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-alternative-syntax-warning.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-alternative-syntax-warning.md new file mode 100644 index 00000000000..2aedb6cb074 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-alternative-syntax-warning.md @@ -0,0 +1 @@ +Некоторые возможности могут быть недоступны при использовании альтернативного синтаксиса (в частности, шифрованные резервные копии или перечисление объектов выгрузки). diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-alternative-syntax.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-alternative-syntax.md new file mode 100644 index 00000000000..652fe14b3d2 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-alternative-syntax.md @@ -0,0 +1,3 @@ +В целях обратной совместимости поддерживается альтернативный способ указания перечня объектов: + +`--item STRING`: Описание объекта загрузки. Параметр `--item` может быть указан несколько раз, если необходимо выполнить загрузку нескольких объектов. Если параметры `--item` или `--include` не указаны, будут загружены все объекты, присутствующие в указанной выгрузке. `STRING` задаётся в формате `<свойство>=<значение>,...` со следующими обязательными свойствами: diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-objects-params.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-objects-params.md new file mode 100644 index 00000000000..77214e0c6a3 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-objects-params.md @@ -0,0 +1,5 @@ +`--destination-path PATH`: Целевая директория для загружаемых объектов; значением по умолчанию является корень базы данных. + +`--include PATH`: Объекты схемы данных для включения в импорт. Директории обходятся рекурсивно. Для включения нескольких объектов допускается указание параметра несколько раз. Если не указан, выполняется загрузка всех объектов выгрузки. + +`--exclude STRING`: Шаблон ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) для исключения путей из импорта. Данный параметр может быть указан несколько раз для разных шаблонов. diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-forget-intro.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-forget-intro.md new file mode 100644 index 00000000000..671b09b8acd --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-forget-intro.md @@ -0,0 +1 @@ +После выполнения загрузки воспользуйтесь командой `operation forget` для того, чтобы загрузка была удалена из перечня операций: diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-list-tail.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-list-tail.md new file mode 100644 index 00000000000..5e48bf22c25 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-list-tail.md @@ -0,0 +1 @@ +Формат вывода `operation list` также устанавливается опцией `--format`. diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-result-json-intro.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-result-json-intro.md new file mode 100644 index 00000000000..6f31201dfc4 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-result-json-intro.md @@ -0,0 +1 @@ +- В режиме вывода `proto-json-base64` идентификатор находится в атрибуте "id": diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-result-pretty-intro.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-result-pretty-intro.md new file mode 100644 index 00000000000..5436f80d8ed --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-result-pretty-intro.md @@ -0,0 +1 @@ +- В режиме вывода `pretty` (по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id: diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-status-after-get.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-status-after-get.md new file mode 100644 index 00000000000..10f1608f52d --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-status-after-get.md @@ -0,0 +1,22 @@ +Формат вывода `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",... } + ``` diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-status-intro.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-status-intro.md new file mode 100644 index 00000000000..2a5c6d86f3d --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-operation-status-intro.md @@ -0,0 +1 @@ +Загрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе загрузки можно вызовом команды `operation get`, параметром которой должен быть передан **заключенный в кавычки** идентификатор операции, например: diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-s3.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-s3.md index ff1ed66fc78..ed45acd4040 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-s3.md +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/import-s3.md @@ -30,43 +30,39 @@ ### Загружаемые объекты схемы базы данных {#objects} -`--destination-path PATH`: Целевая директория для загружаемых объектов; значением по умолчанию является корень базы данных. - -`--include PATH`: Объекты схемы данных для включения в импорт. Директории обходятся рекурсивно. Для включения нескольких объектов допускается указание параметра несколько раз. Если не указан, выполняется загрузка всех объектов выгрузки. - -`--exclude STRING`: Шаблон ([PCRE](https://www.pcre.org/original/doc/html/pcrepattern.html)) для исключения путей из импорта. Пути указываются относительно `root-path`. Данный параметр может быть указан несколько раз для разных шаблонов. +{% include [import-objects-params.md](./import-objects-params.md) %} {% cut "Альтернативный способ" %} -В целях обратной совместимости поддерживается альтернативный способ указания перечня объектов: - -`--item STRING`: Описание объекта загрузки. Параметр `--item` может быть указан несколько раз, если необходимо выполнить загрузку нескольких объектов. Если параметры `--item` или `--include` не указаны, будут загружены все объекты, присутствующие по указанному префиксу загрузки. `STRING` задаётся в формате `<свойство>=<значение>,...` со следующими обязательными свойствами: +{% include [import-alternative-syntax.md](./import-alternative-syntax.md) %} - `source`, `src` или `s` — префикс ключа в S3 с загружаемой директорией или таблицей. - `destination`, `dst`, или `d` — путь в базе данных для размещения загружаемой директории или таблицы. Конечный элемент пути не должен существовать. Все директории на пути будут созданы, если не существуют. -Некоторые возможности могут быть недоступны при использовании альтернативного синтаксиса (в частности, шифрованные резервные копии или перечисление объектов выгрузки). +{% include [import-alternative-syntax-warning.md](./import-alternative-syntax-warning.md) %} {% endcut %} ### Дополнительные параметры {#aux} | Параметр | Описание | ---- | --- +| --- | --- | | `--description STRING` | Текстовое описание операции, сохраняемое в истории операций. | | `--retries NUM` | Количество повторных попыток загрузки, которые будет предпринимать сервер.<br/>Значение по умолчанию: `10`. | | `--skip-checksum-validation` | Пропустить этап валидации [контрольных сумм](../file-structure.md#checksums) загружаемых объектов. | -| `--encryption-key-file PATH` | Путь к файлу, содержащему ключ шифрования (только для зашифрованных выгрузок). Данный файл является бинарным и должен содержать точное количество байт, соответствующее длине ключа в выбранном алгоритме шифрования (16 байт для `AES-128-GCM`, 32 байта для `AES-256-GCM` и `ChaCha20-Poly1305`). Ключ также может быть передан через переменную окружения `YDB_ENCRYPTION_KEY`, в шестнадцатеричном строковом представлении. +| `--encryption-key-file PATH` | Путь к файлу, содержащему ключ шифрования (только для зашифрованных выгрузок). Данный файл является бинарным и должен содержать точное количество байт, соответствующее длине ключа в выбранном алгоритме шифрования (16 байт для `AES-128-GCM`, 32 байта для `AES-256-GCM` и `ChaCha20-Poly1305`). Ключ также может быть передан через переменную окружения `YDB_ENCRYPTION_KEY`, в шестнадцатеричном строковом представлении. | | `--list` | Перечислить объекты в существующей выгрузке. | | `--format STRING` | Формат вывода результата.<br/>Допустимые значения:<br/><ul><li>`pretty` — человекочитаемый формат (по умолчанию);</li><li>`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).</li></ul> | ## Выполнение загрузки {#exec} +{% include [server-import-workflow.md](server-import-workflow.md) %} + ### Результат запуска {#result} При успешном исполнении команда `import s3` выводит сводную информацию о поставленной в очередь операции загрузки из S3, в заданном опцией `--format` формате. Фактическая загрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией: -- В режиме вывода `pretty` (по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id: +{% include [import-operation-result-pretty-intro.md](import-operation-result-pretty-intro.md) %} ```text ┌───────────────────────────────────────────┬───────┬─────... @@ -78,46 +74,25 @@ ... ``` -- В режиме вывода `proto-json-base64` идентификатор находится в атрибуте "id": +{% include [import-operation-result-json-intro.md](import-operation-result-json-intro.md) %} ```json - {"id":"ydb://export/8?id=281474976788395&kind=s3","ready":true, ... } + {"id":"ydb://import/8?id=281474976788395&kind=s3","ready":true, ... } ``` ### Статус загрузки {#status} -Загрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе загрузки можно вызовом команды `operation get`, параметром которой должен быть передан **заключенный в кавычки** идентификатор операции, например: +{% include [import-operation-status-intro.md](import-operation-status-intro.md) %} -``` bash +```bash {{ ydb-cli }} -p quickstart operation get "ydb://import/8?id=281474976788395&kind=s3" ``` -Формат вывода `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",... } - ``` +{% include [import-operation-status-after-get.md](import-operation-status-after-get.md) %} ### Завершение операции загрузки {#forget} -После выполнения загрузки воспользуйтесь командой `operation forget` для того, чтобы загрузка была удалена из перечня операций: +{% include [import-operation-forget-intro.md](import-operation-forget-intro.md) %} ```bash {{ ydb-cli }} -p quickstart operation forget "ydb://import/8?id=281474976788395&kind=s3" @@ -131,7 +106,7 @@ {{ ydb-cli }} -p quickstart operation list import/s3 ``` -Формат вывода `operation list` также устанавливается опцией `--format`. +{% include [import-operation-list-tail.md](import-operation-list-tail.md) %} ## Примеры {#examples} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/index.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/index.md index bc4059c8912..202c786c2d0 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/index.md +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/index.md @@ -12,5 +12,8 @@ - [Соединение и аутентификация при работе с S3-совместимым объектным хранилищем](../auth-s3.md) - [Выгрузка в S3-совместимое объектное хранилище `export s3`](../export-s3.md) - [Загрузка из S3-совместимого объектного хранилища `import s3`](../import-s3.md) +- [Настройка NFS для выполнения резервного копирования](../../../../recipes/nfs-backup/nfs-backup.md) +- [Выгрузка в NFS `export nfs`](../export-nfs.md) +- [Загрузка из NFS `import nfs`](../import-nfs.md) {% include [_includes/options_overlay.md](options_overlay.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/server-export-workflow.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/server-export-workflow.md new file mode 100644 index 00000000000..ca889aedffd --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/server-export-workflow.md @@ -0,0 +1,7 @@ +### Ход серверной операции выгрузки {#server-export-workflow} + +1. Создаётся серверная асинхронная операция экспорта. +2. В корневой директории базы данных создаётся служебная директория `export-{id}`, где `{id}` — числовой идентификатор операции. +3. В эту директорию создаётся согласованная копия таблиц с помощью механизма `CopyTables`. +4. Данные каждой таблицы записываются из копии в хранилище в формате [файловой структуры выгрузки](../file-structure.md) с параллельной записью из разных узлов кластера. +5. После успешного завершения служебная директория `export-{id}` и копии таблиц удаляются. diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/server-import-workflow.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/server-import-workflow.md new file mode 100644 index 00000000000..0667f4b2c87 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/server-import-workflow.md @@ -0,0 +1,6 @@ +### Ход серверной операции загрузки {#server-import-workflow} + +1. Создаётся серверная асинхронная операция импорта. +2. Сервер считывает метаданные объектов из файлов (`scheme.pb`, `metadata.json` и т.д.) из хранилища. +3. Для каждого объекта создаётся новая таблица в базе данных. Целевые пути **не должны существовать** — импорт не может перезаписать существующие таблицы. +4. Данные загружаются из файлов параллельно на всех узлах кластера. diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/export-nfs.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/export-nfs.md new file mode 100644 index 00000000000..446eb272cfe --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/export-nfs.md @@ -0,0 +1,194 @@ +# Выгрузка в NFS + +Команда `export nfs` запускает на стороне сервера процесс выгрузки в сетевую файловую систему ([Network File System](https://ru.wikipedia.org/wiki/Network_File_System), NFS) хостов кластера {{ ydb-short-name }} данных и информации об объектах схемы, в описанном в статье [Файловая структура](./file-structure.md) формате: + +```bash +{{ ydb-cli }} [connection options] export nfs [options] +``` + +{% include [conn_options_ref.md](../commands/_includes/conn_options_ref.md) %} + +{% note warning %} + +{% include [export-supported-object-types.md](_includes/export-supported-object-types.md) %} + +{% endnote %} + +## Параметры командной строки {#pars} + +`[options]` - параметры команды: + +### Параметры NFS {#nfs-params} + +Команда выгрузки в NFS требует указания монтированной директории (или поддиректории) общей для всех объектов, участвующих в выгрузке. Так как выгрузка производится в асинхронном режиме на всех хостах {{ ydb-short-name }}, указанная директория должна быть на каждом хосте {{ ydb-short-name }} и смонтирована в NFS. + +`--fs-path PATH`: путь до монтированной директории (или поддиректории). + +### Перечень выгружаемых объектов {#items} + +{% include [export-root-include-exclude-params.md](_includes/export-root-include-exclude-params.md) %} + +{% 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)) для исключения путей из выгрузки. Данный параметр может быть указан несколько раз для разных шаблонов. + +{% include [export-alternative-syntax-warning.md](_includes/export-alternative-syntax-warning.md) %} + +{% endcut %} + +### Дополнительные параметры {#aux} + +| Параметр | Описание | +| --- | --- | +| `--description STRING` | Текстовое описание операции, сохраняемое в истории операций. | +| `--retries NUM` | Количество повторных попыток выгрузки, которые будет предпринимать сервер.<br/>Значение по умолчанию: `10`. | +| `--compression STRING` | Сжимать выгружаемые данные.<br/>При уровне сжатия по умолчанию для алгоритма [Zstandard](https://ru.wikipedia.org/wiki/Zstandard) данные могут быть сжаты в 5-10 раз. Сжатие данных использует ресурс CPU и может повлиять на скорость выполнения других операций с БД.<br/>Допустимые значения:<br/><ul><li>`zstd` — сжатие алгоритмом Zstandard c уровнем сжатия по умолчанию (`3`);</li><li>`zstd-N` — сжатие алгоритмом Zstandard, `N` — уровень сжатия (`1` — `22`).</li></ul> | +| `--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` | Формат вывода результата.<br/>Допустимые значения:<br/><ul><li>`pretty` — человекочитаемый формат (по умолчанию);</li><li>`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).</li></ul> | + +## Выполнение выгрузки {#exec} + +{% include [server-export-workflow.md](_includes/server-export-workflow.md) %} + +### Результат запуска {#result} + +При успешном исполнении команда `export nfs` выводит сводную информацию о поставленной в очередь операции выгрузки в NFS, в заданном опцией `--format` формате. Фактическая выгрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией: + +{% include [export-operation-result-pretty-intro.md](_includes/export-operation-result-pretty-intro.md) %} + + ```text + ┌───────────────────────────────────────────┬───────┬─────... + | id | ready | stat... + ├───────────────────────────────────────────┼───────┼─────... + | ydb://export/6?id=281474976788395&kind=fs | true | SUCC... + ├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴... + | Include index data: false + | Items: + ... + ``` + +{% include [export-operation-result-json-intro.md](_includes/export-operation-result-json-intro.md) %} + + ```json + {"id":"ydb://export/6?id=281474976788395&kind=fs","ready":true, ... } + ``` + +### Статус выгрузки {#status} + +{% include [export-operation-status-intro.md](_includes/export-operation-status-intro.md) %} + +```bash +{{ ydb-cli }} -p quickstart operation get "ydb://export/6?id=281474976788395&kind=fs" +``` + +{% include [export-operation-status-after-get.md](_includes/export-operation-status-after-get.md) %} + +### Завершение операции выгрузки {#forget} + +{% include [export-operation-forget-intro.md](_includes/export-operation-forget-intro.md) %} + +```bash +{{ ydb-cli }} -p quickstart operation forget "ydb://export/6?id=281474976788395&kind=fs" +``` + +### Список операций выгрузки {#list} + +Для получения списка операций выгрузки воспользуйтесь командой `operation list export/nfs`: + +```bash +{{ ydb-cli }} -p quickstart operation list export/nfs +``` + +{% include [export-operation-list-tail.md](_includes/export-operation-list-tail.md) %} + +## Примеры {#examples} + +{% include [ydb-cli-profile.md](../../../_includes/ydb-cli-profile.md) %} + +### Выгрузка базы данных {#example-full-db} + +Выгрузка всех несистемных объектов базы данных в директорию `/mnt/nfs/backups/export1` на файловой системе: + +```bash +{{ ydb-cli }} -p quickstart export nfs \ + --fs-path /mnt/nfs/backups/export1 +``` + +### Выгрузка нескольких директорий {#example-specific-dirs} + +Выгрузка объектов из директорий `dir1` и `dir2` базы данных в директорию `/mnt/nfs/backups/export1` на файловой системе: + +```bash +{{ ydb-cli }} -p quickstart export nfs \ + --fs-path /mnt/nfs/backups/export1 \ + --include dir1 --include dir2 +``` + +Либо с использованием альтернативного способа: + +```bash +{{ ydb-cli }} -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-cli }} -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-cli }} -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-cli }} -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-cli }} -p quickstart operation list export/nfs --format proto-json-base64 | jq -r ".operations[].id" | while read line; do {{ ydb-cli }} -p quickstart operation forget $line;done +``` diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/import-nfs.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/import-nfs.md new file mode 100644 index 00000000000..a1b6bdabf3b --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/import-nfs.md @@ -0,0 +1,158 @@ +# Загрузка из NFS + +Команда `import nfs` запускает на стороне сервера процесс загрузки из сетевой файловой системы ([Network File System](https://ru.wikipedia.org/wiki/Network_File_System), NFS) хостов кластера {{ ydb-short-name }} данных и информации об объектах схемы, в описанном в статье [Файловая структура](./file-structure.md) формате: + +```bash +{{ ydb-cli }} [connection options] import nfs [options] +``` + +{% include [conn_options_ref.md](../commands/_includes/conn_options_ref.md) %} + +В отличие от [команды `tools restore`](./tools-restore.md), команда `import nfs` всегда создает объекты целиком, поэтому для её успешного выполнения ни один из загружаемых объектов (ни директорий, ни таблиц) не должен существовать. + +При необходимости догрузки данных в существующие таблицы воспользуйтесь [командой `tools restore`](./tools-restore.md) непосредственно на смонтированной NFS-директории. + +## Параметры командной строки {#pars} + +`[options]` - параметры команды: + +### Параметры NFS {#nfs-params} + +Команда загрузки из NFS требует указания монтированной директории (или поддиректории) общей для всех объектов, участвующих в загрузке. Так как загрузка производится в асинхронном режиме на всех хостах {{ ydb-short-name }}, указанная директория должна быть на каждом хосте {{ ydb-short-name }} и смонтирована в NFS. + +`--fs-path PATH`: путь до монтированной директории (или поддиректории). + +### Загружаемые объекты схемы базы данных {#objects} + +{% include [import-objects-params.md](_includes/import-objects-params.md) %} + +{% cut "Альтернативный способ" %} + +{% include [import-alternative-syntax.md](_includes/import-alternative-syntax.md) %} + +- `source`, `src` или `s` — путь в NFS (относительно `fs-path`) с загружаемой директорией или таблицей. +- `destination`, `dst`, или `d` — путь в базе данных для размещения загружаемой директории или таблицы. Конечный элемент пути не должен существовать. Все директории на пути будут созданы, если не существуют. + +{% include [import-alternative-syntax-warning.md](_includes/import-alternative-syntax-warning.md) %} + +{% endcut %} + +### Дополнительные параметры {#aux} + +| Параметр | Описание | +| --- | --- | +| `--description STRING` | Текстовое описание операции, сохраняемое в истории операций. | +| `--retries NUM` | Количество повторных попыток загрузки, которые будет предпринимать сервер.<br/>Значение по умолчанию: `10`. | +| `--skip-checksum-validation` | Пропустить этап валидации [контрольных сумм](./file-structure.md#checksums) загружаемых объектов. | +| `--encryption-key-file PATH` | Путь к файлу, содержащему ключ шифрования (только для зашифрованных выгрузок). Данный файл является бинарным и должен содержать точное количество байт, соответствующее длине ключа в выбранном алгоритме шифрования (16 байт для `AES-128-GCM`, 32 байта для `AES-256-GCM` и `ChaCha20-Poly1305`). Ключ также может быть передан через переменную окружения `YDB_ENCRYPTION_KEY`, в шестнадцатеричном строковом представлении. | +| `--format STRING` | Формат вывода результата.<br/>Допустимые значения:<br/><ul><li>`pretty` — человекочитаемый формат (по умолчанию);</li><li>`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).</li></ul> | + +## Выполнение загрузки {#exec} + +{% include [server-import-workflow.md](_includes/server-import-workflow.md) %} + +### Результат запуска {#result} + +При успешном исполнении команда `import nfs` выводит сводную информацию о поставленной в очередь операции загрузки из NFS, в заданном опцией `--format` формате. Фактическая загрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией: + +{% include [import-operation-result-pretty-intro.md](_includes/import-operation-result-pretty-intro.md) %} + + ```text + ┌───────────────────────────────────────────┬───────┬─────... + | id | ready | stat... + ├───────────────────────────────────────────┼───────┼─────... + | ydb://import/8?id=281474976788395&kind=fs | true | SUCC... + ├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴... + | Items: + ... + ``` + +{% include [import-operation-result-json-intro.md](_includes/import-operation-result-json-intro.md) %} + + ```json + {"id":"ydb://import/8?id=281474976788395&kind=fs","ready":true, ... } + ``` + +### Статус загрузки {#status} + +{% include [import-operation-status-intro.md](_includes/import-operation-status-intro.md) %} + +```bash +{{ ydb-cli }} -p quickstart operation get "ydb://import/8?id=281474976788395&kind=fs" +``` + +{% include [import-operation-status-after-get.md](_includes/import-operation-status-after-get.md) %} + +### Завершение операции загрузки {#forget} + +{% include [import-operation-forget-intro.md](_includes/import-operation-forget-intro.md) %} + +```bash +{{ ydb-cli }} -p quickstart operation forget "ydb://import/8?id=281474976788395&kind=fs" +``` + +### Список операций загрузки {#list} + +Для получения списка операций загрузки воспользуйтесь командой `operation list import/nfs`: + +```bash +{{ ydb-cli }} -p quickstart operation list import/nfs +``` + +{% include [import-operation-list-tail.md](_includes/import-operation-list-tail.md) %} + +## Примеры {#examples} + +{% include [ydb-cli-profile.md](../../../_includes/ydb-cli-profile.md) %} + +### Загрузка в корень базы данных {#example-full-db} + +Загрузка в корень базы данных содержимого директории `/mnt/nfs/backups/export1` на файловой системе: + +```bash +{{ ydb-cli }} -p quickstart import nfs \ + --fs-path /mnt/nfs/backups/export1 +``` + +### Загрузка нескольких директорий {#example-specific-dirs} + +Загрузка объектов из директорий `dir1` и `dir2` выгрузки, расположенной в `/mnt/nfs/backups/export1` на файловой системе, в одноименные директории базы данных: + +```bash +{{ ydb-cli }} -p quickstart import nfs \ + --fs-path /mnt/nfs/backups/export1 \ + --include dir1 --include dir2 +``` + +### Загрузка зашифрованной выгрузки {#example-encryption} + +Загрузка одной таблицы, которая была выгружена по пути `dir/my_table`, в путь `dir1/dir/my_table` из зашифрованной выгрузки, расположенной в `/mnt/nfs/backups/export1` на файловой системе, с использованием секретного ключа из файла `~/my_secret_key`. + +```bash +{{ ydb-cli }} -p quickstart import nfs \ + --fs-path /mnt/nfs/backups/export1 --destination-path dir1 \ + --include dir/my_table \ + --encryption-key-file ~/my_secret_key +``` + +### Получение идентификаторов операций {#example-list-oneline} + +Для получения перечня идентификаторов операций загрузки в удобном для обработки в скриптах bash формате вы можете применить утилиту [jq](https://stedolan.github.io/jq/download/): + +```bash +{{ ydb-cli }} -p quickstart operation list import/nfs --format proto-json-base64 | jq -r ".operations[].id" +``` + +Вы получите вывод, где в каждой новой строке находится идентификатор операции, например: + +```text +ydb://import/8?id=281474976789577&kind=fs +ydb://import/8?id=281474976789526&kind=fs +ydb://import/8?id=281474976788779&kind=fs +``` + +По этим идентификаторам может быть, например, запущен цикл для завершения всех текущих операций: + +```bash +{{ ydb-cli }} -p quickstart operation list import/nfs --format proto-json-base64 | jq -r ".operations[].id" | while read line; do {{ ydb-cli }} -p quickstart operation forget $line;done +``` diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/export-import/toc_i.yaml index 5390d8d317d..04c6283d04f 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/export-import/toc_i.yaml +++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/toc_i.yaml @@ -11,5 +11,9 @@ items: href: export-s3.md - name: Загрузка из S3 href: import-s3.md +- name: Выгрузка в NFS + href: export-nfs.md +- name: Загрузка из NFS + href: import-nfs.md - name: Импорт данных из файла в существующую таблицу href: import-file.md |
