Выгрузка в S3-совместимое хранилище
Команда export s3
запускает на стороне сервера процесс выгрузки в S3-совместимое хранилище данных и информации об объектах схемы данных, в описанном в статье Файловая структура формате:
ydb [connection options] export s3 [options]
Важно
Выгрузка доступна только для объектов следующих типов:
, где [connection options]
— опции соединения с БД
Параметры командной строки
[options]
- параметры команды:
Параметры соединения с S3
Команда выгрузки в S3 требует указания параметров соединения с S3. Так как выгрузка производится в асинхронном режиме сервером YDB, указанный эндпоинт должен быть доступен для установки соединения со стороны сервера.
Перечень выгружаемых объектов
--item STRING
: Описание объекта выгрузки. Параметр --item
может быть указан несколько раз, если необходимо выполнить выгрузку нескольких объектов. STRING
задается в формате <свойство>=<значение>,...
, со следующими обязательными свойствами:
source
,src
, илиs
— путь до выгружаемой директории или таблицы,.
указывает на корневую директорию базы данных. При указании директории выгружаются все объекты в ней, имена которых не начинаются с точки, а также рекурсивно все поддиректории, имена которых не начинаются с точки.destination
,dst
, илиd
— путь (префикс ключа) в S3 для размещения выгружаемых объектов
--exclude STRING
: Шаблон (PCRE) для исключения путей из выгрузки. Данный параметр может быть указан несколько раз, для разных шаблонов.
Дополнительные параметры
Параметр | Описание |
---|---|
--description STRING |
Текстовое описание операции, сохраняемое в истории операций. |
--retries NUM |
Количество повторных попыток выгрузки, которые будет предпринимать сервер. Значение по умолчанию: 10 . |
--compression STRING |
Сжимать выгружаемые данные. При уровне сжатия по умолчанию для алгоритма Zstandard данные могут быть сжаты в 5-10 раз. Сжатие данных использует ресурс CPU и может повлиять на скорость выполнения других операций с БД. Допустимые значения:
|
--format STRING |
Формат вывода результата. Допустимые значения:
|
Выполнение выгрузки
Результат запуска
При успешном исполнении команда export s3
выводит сводную информацию о поставленной в очередь операции выгрузки в S3, в заданном опцией --format
формате. Фактическая выгрузка производится сервером асинхронно. В сводной информации выводится ID операции, который может быть использован в дальнейшем для проверки статуса и действий с операцией:
-
В режиме вывода
pretty
(по умолчанию) идентификатор операции показывается в выделенном псевдографикой поле id:┌───────────────────────────────────────────┬───────┬─────... | id | ready | stat... ├───────────────────────────────────────────┼───────┼─────... | ydb://export/6?id=281474976788395&kind=s3 | true | SUCC... ├╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┴╴╴╴╴╴╴╴┴╴╴╴╴╴... | StorageClass: NOT_SET | Items: ...
-
В режиме вывода proto-json-base64 идентификатор находится в атрибуте "id":
{"id":"ydb://export/6?id=281474976788395&kind=s3","ready":true, ... }
Статус выгрузки
Выгрузка данных выполняется в фоновом режиме. Получить информацию о статусе и прогрессе выгрузки можно вызовом команды operation get
, параметром которой должен быть передан заключенный в кавычки идентификатор операции, например:
ydb -p quickstart operation get "ydb://export/6?id=281474976788395&kind=s3"
Формат вывода 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",... }
Завершение операции выгрузки
При выполнении выгрузки в корневом каталоге базы данных создается директория с именем export_*
, где *
— это числовая часть идентификатора выгрузки. В данной директории размещаются таблицы, содержащие консистентный снапшот выгружаемых данных на момент начала выгрузки.
После выполнения выгрузки воспользуйтесь командой operation forget
для того, чтобы выгрузка была завершена: удалена из перечня операций, а также были удалены все созданные для неё файлы:
ydb -p quickstart operation forget "ydb://export/6?id=281474976788395&kind=s3"
Список операций выгрузки
Для получения списка операций выгрузки воспользуйтесь командой operation list export/s3
:
ydb -p quickstart operation list export/s3
Формат вывода operation list
также устанавливается опцией --format
.
Примеры
Примечание
В примерах используется профиль quickstart
, подробнее смотрите в Создание профиля для соединения с тестовой БД.
Выгрузка базы данных
Выгрузка всех объектов базы данных, имена которых не начинаются с точки, и не размещенных внутри директорий, имена которых начинаются с точки, в директорию export1
в бакете mybucket
с использованием параметров аутентификации S3 из переменных окружения или файла ~/.aws/credentials
:
ydb -p quickstart export s3 \
--s3-endpoint storage.yandexcloud.net --bucket mybucket \
--item src=.,dst=export1
Выгрузка нескольких директорий
Выгрузка объектов из директорий dir1 и dir2 базы данных, в директорию export1
в бакете mybucket
, с использованием явно заданных параметров аутентификации в S3:
ydb -p quickstart export s3 \
--s3-endpoint storage.yandexcloud.net --bucket mybucket \
--access-key VJGSOScgs-5kDGeo2hO9 --secret-key fZ_VB1Wi5-fdKSqH6074a7w0J4X0 \
--item src=dir1,dst=export1/dir1 --item src=dir2,dst=export1/dir2
Получение идентификаторов операций
Для получения перечня идентификаторов операций выгрузки в удобном для обработки в скриптах bash формате вы можете применить утилиту jq:
ydb -p quickstart operation list export/s3 --format proto-json-base64 | jq -r ".operations[].id"
Вы получите вывод, где в каждой новой строке находится идентификатор операции, например:
ydb://export/6?id=281474976789577&kind=s3
ydb://export/6?id=281474976789526&kind=s3
ydb://export/6?id=281474976788779&kind=s3
По этим идентификаторам может быть, например, запущен цикл для завершения всех текущих операций:
ydb -p quickstart operation list export/s3 --format proto-json-base64 | jq -r ".operations[].id" | while read line; do ydb -p quickstart operation forget $line;done