12.3 Table Export Utility — MySQL Shell 9.2

12.3 Утилита экспорта таблиц

Утилита экспорта таблиц MySQL Shell util.exportTable() экспортирует MySQL реляционную таблицу в файл данных, как на локальном сервере, так и в ведро Oracle Cloud Infrastructure Object Storage. Данные затем можно загрузить в таблицу на целевом MySQL сервере с помощью утилиты параллельного импорта таблиц MySQL Shell util.importTable() (см. Раздел 12.4, «Утилита параллельного импорта таблиц»), которая использует параллельные соединения для быстрого импорта больших файлов данных. Файл данных также можно использовать для импорта данных в другое приложение или как лёгкую логическую резервную копию для одной таблицы данных.

О утилите

По умолчанию, утилита экспорта таблиц создаёт файл данных в формате по умолчанию для утилиты параллельного импорта таблиц MySQL Shell. Доступны предустановленные параметры для экспорта файлов CSV для систем DOS или UNIX, а также TSV-файлов. Утилита экспорта таблиц не может создавать данные в формате JSON. Вы также можете установить параметры обработки полей и строк, как и для оператора, для создания файлов данных в произвольных форматах.

util.exportTable() может быть использована с разнесёнными и подразнесёнными таблицами, но не выполняет никакой специальной обработки этих типов. Эта утилита всегда создаёт по одному файлу на таблицу, независимо от версии выпуска.

При выборе места назначения для файла экспорта таблицы обратите внимание, что для импорта в HeatWave Service DB System экземпляр MySQL Shell, где вы запускаете утилиту параллельного импорта таблиц, должен быть установлен на экземпляре Oracle Cloud Infrastructure Compute, который имеет доступ к HeatWave Service DB System. Если вы экспортируете таблицу в файл в ведро Object Storage, вы можете получить доступ к ведру Object Storage с экземпляра Compute. Если вы создаёте файл экспорта таблицы на локальной системе, вам нужно перенести его на экземпляр Oracle Cloud Infrastructure Compute с помощью утилиты копирования по вашему выбору, в зависимости от операционной системы вашего экземпляра Compute.

Требования и ограничения

Следующие требования применяются к экспортам с использованием утилиты экспорта таблиц:

Для исходного MySQL экземпляра и целевого MySQL экземпляра требуется MySQL 5.7 или более поздняя версия.
Метод загрузки, используемый для передачи файлов в ведро Oracle Cloud Infrastructure Object Storage, имеет ограничение по размеру файла в 1,2 ТБ.

Запуск утилиты

Утилита экспорта таблиц использует глобальную сессию MySQL Shell для получения данных подключения к целевому MySQL серверу, с которого выполняется экспорт. Вам необходимо открыть глобальную сессию (которая может иметь соединение X Protocol или классическое MySQL соединение) перед запуском утилиты. Утилита открывает свою собственную сессию для каждого потока, копируя такие параметры, как сжатие соединения и параметры SSL из глобальной сессии, и не делает дальнейшего использования глобальной сессии. Вы можете ограничить максимальную скорость передачи данных для балансировки нагрузки на сеть.

В API MySQL Shell, утилита экспорта таблиц является функцией глобального объекта util и имеет следующую сигнатуру:

util.exportTable(table, outputUrl[, options])

options — это имя реляционной таблицы данных, которая должна быть экспортирована в файл данных. Имя таблицы может быть квалифицировано именем схемы и, при необходимости, заключено в обратные кавычки. Если схема опущена, используется активная схема для глобальной сессии MySQL Shell.

options — это словарь параметров, который можно опустить, если он пуст. Эти параметры перечислены в последнем разделе этой темы.

Если вы экспортируете данные на локальный файловый сервер, outputUrl — это строка, определяющая путь к файлу экспортированных данных, включая само имя файла с соответствующим расширением. Вы можете указать абсолютный путь или путь относительно текущей рабочей директории. Вы можете префикс-определить локальный путь к директории с помощью схемы file://. В этом примере в режиме JavaScript MySQL Shell пользователь экспортирует таблицу employees из схемы hr, используя диалект по умолчанию. Файл записывается в директорию exports в домашней директории пользователя и получает соответствующее расширение .txt для файла в этом формате:

shell-js> util.exportTable("hr.employees", "file:///home/hanna/exports/employees.txt")

Целевая директория должна существовать до начала экспорта, но она не должна быть пустой. Если экспортируемый файл данных уже существует, он перезаписывается. При экспорте в локальную директорию файл данных создаётся с правами доступа rw-r----- (в операционных системах, где это поддерживается). Владельцем файла является учётная запись пользователя, запускающего MySQL Shell.

Если вы экспортируете данные в ведро Oracle Cloud Infrastructure Object Storage или в совместимое с S3 хранилище, outputUrl — имя файла данных в ведре, включая подходящее расширение файла. Вы можете включать разделители директорий для имитации структуры директорий. Используйте параметр osBucketName для указания имени ведра Object Storage и параметр osNamespace для идентификации пространства имён ведра. В этом примере в Python режиме MySQL Shell пользователь экспортирует таблицу employees из схемы hr как файл в формате TSV в ведро Object Storage hanna-bucket:

shell-py> util.export_table("hr.employees", "dump/employees.tsv", {
        > dialect: "tsv", "osBucketName": "hanna-bucket", "osNamespace": "idx28w1ckztq" })

Пространство имён ведра Object Storage отображается на вкладке «Информация о ведре» страницы сведений о ведре в консоли Oracle Cloud Infrastructure, или может быть получено с помощью командной строки Oracle Cloud Infrastructure. Соединение с ведром Object Storage устанавливается с помощью профиля по умолчанию в файле конфигурации Oracle Cloud Infrastructure CLI по умолчанию или с альтернативными параметрами, которые вы указываете, используя параметры ociConfigFile и ociProfile. Инструкции по настройке файла конфигурации CLI см. в Файле конфигурации SDK и CLI.

Параметры

where: "string"

Действительное выражение SQL-условия, используемое для фильтрации экспортируемых данных.

Примечание

SQL-запрос валидируется только при его выполнении. Если вы экспортируете много таблиц, любые проблемы с синтаксисом SQL станут видны только на поздних этапах процесса. Поэтому рекомендуется протестировать ваше SQL-условие перед использованием в длительном процессе экспорта.

В следующем примере, where экспортирует только те строки таблицы sakila.actor, где значение actor_id больше 150, в файл с именем dump.csv:

              util.exportTable("sakila.actor", "dump.csv", {"where" : "actor_id > 150"})

partitions: ["string","string",..]

Список допустимых имён разделов, которые ограничивают экспорт указанными разделами.

В следующем примере экспортируются разделы p1 и p2 из таблицы schema.table в файл с именем dump.csv:

              util.exportTable("schema.table", "dump.csv", {"partitions" : ["p1", "p2"]}

dialect: [default|csv|csv-unix|tsv]

Укажите набор параметров обработки полей и строк для формата экспортируемого файла данных. Вы можете использовать выбранный диалект в качестве основы для дальнейшей настройки, также указав один или несколько параметров linesTerminatedBy, fieldsTerminatedBy, fieldsEnclosedBy, fieldsOptionallyEnclosed и fieldsEscapedBy для изменения настроек.

По умолчанию диалект создаёт файл данных, соответствующий тому, что был бы создан с помощью оператора с настройками по умолчанию для этого оператора. .txt — подходящее расширение файла для этих выходных файлов. Доступны другие диалекты для экспорта CSV-файлов для систем DOS или UNIX (.csv) и TSV-файлов (.tsv).

Применяемые настройки для каждого диалекта приведены ниже:

Таблица 12.1 Настройки диалекта для утилиты экспорта таблиц

Таблица 12.1 Настройки диалекта для утилиты экспорта таблиц
`dialect`	`linesTerminatedBy`	`fieldsTerminatedBy`	`fieldsEnclosedBy`	`fieldsOptionallyEnclosed`	`fieldsEscapedBy`
`default`	[LF]	[TAB]	[пусто]	`false`	\
`csv`	[CR][LF]	,	''	`true`	\
`csv-unix`	[LF]	,	''	`false`	\
`tsv`	[CR][LF]	[TAB]	''	`true`	\

Примечание

Значения возврата каретки и перевода строки для диалектов независимы от операционной системы.
Если вы используете параметры linesTerminatedBy, fieldsTerminatedBy, fieldsEnclosedBy, fieldsOptionallyEnclosed и fieldsEscapedBy, в зависимости от соглашений об экранировании вашей командной оболочки, символ обратного слэша (\) может потребоваться удвоить, если вы используете его в значениях параметров.
Как и в MySQL-сервере с оператором , MySQL Shell не валидирует параметры обработки полей и строк, которые вы указываете. Неправильный выбор этих параметров может привести к частичному или неправильному экспорту данных. Всегда проверяйте свои настройки перед началом экспорта и проверяйте результаты после него.

linesTerminatedBy: "characters"

Один или несколько символов (или пустая строка), которыми утилита завершает каждую строку в экспортируемом файле данных. По умолчанию — как для указанного диалекта, или символ перевода строки (\n), если опция диалекта опущена. Эта опция эквивалентна параметру LINES TERMINATED BY для оператора . Обратите внимание, что утилита не предоставляет эквивалента параметра LINES STARTING BY для оператора , который имеет значение пустой строки.

fieldsTerminatedBy: "characters"

Один или несколько символов (или пустая строка), которыми утилита завершает каждое поле в экспортируемом файле данных. По умолчанию — как для указанного диалекта, или табуляция (\t), если опция диалекта опущена. Эта опция эквивалентна параметру FIELDS TERMINATED BY для оператора .

fieldsEnclosedBy: "character"

Один символ (или пустая строка), которым утилита обрамляет каждое поле в экспортируемом файле данных. По умолчанию — как для указанного диалекта, или пустая строка, если опция диалекта опущена. Эта опция эквивалентна параметру FIELDS ENCLOSED BY для оператора .

fieldsOptionallyEnclosed: [ true | false ]

Должен ли символ, заданный для fieldsEnclosedBy, обрамлять все поля в экспортируемом файле данных (false), или обрамлять поле только если у него тип данных строка, такой как CHAR, BINARY, TEXT или ENUM (true). По умолчанию — как для указанного диалекта, или false, если опция диалекта опущена. Этот параметр делает опцию fieldsEnclosedBy эквивалентной параметру FIELDS OPTIONALLY ENCLOSED BY для оператора .

fieldsEscapedBy: "character"

Символ, которым утилита начинает последовательности экранирования в экспортируемом файле данных. По умолчанию — как для указанного диалекта, или обратный слэш (\), если опция диалекта опущена. Этот параметр эквивалентен параметру FIELDS ESCAPED BY для оператора . Если вы установите этот параметр в пустую строку, символы не будут экранированы, что не рекомендуется, так как специальные символы, используемые оператором , должны экранироваться.

maxRate: "string"

Максимальное количество байт в секунду на поток для пропускной способности чтения данных во время экспорта. Можно использовать суффиксы единиц k для килобайт, M для мегабайт и G для гигабайт (например, установка 100M ограничивает пропускную способность до 100 мегабайт в секунду на поток). Установка 0 (значение по умолчанию) или установка параметра в пустую строку означает, что ограничение не установлено.

showProgress: [ true | false ]

Отображать (true) или скрывать (false) информацию о ходе экспорта. По умолчанию — true, если stdout является терминалом (tty), например, когда MySQL Shell находится в интерактивном режиме, и false в противном случае. Информация о ходе выполнения включает в себя приблизительное общее количество строк для экспорта, количество экспортированных строк, процент завершения и пропускную способность в строках и байтах в секунду.

compression: "string;level=n"

Тип сжатия и уровень сжатия для использования при записи экспортируемого файла данных. Доступны следующие параметры сжатия:

none: По умолчанию. Сжатие не применяется.
gzip: Использует библиотеку сжатия gzip. Уровень сжатия может быть установлен от 0 до 9. Уровень сжатия по умолчанию — 1. Например:
```
                  "compression": "gzip;level=4"
                
```
zstd: Использует библиотеку сжатия zstd. Уровень сжатия может быть установлен от 1 до 22. Уровень сжатия по умолчанию — 1. Например:
```
                  "compression": "zstd;level=15"
                
```

defaultCharacterSet: "string"

Кодировка символов, которая должна использоваться во время сеансовых подключений, открываемых MySQL Shell к серверу для экспорта. По умолчанию — utf8mb4. Сеансовое значение системных переменных , , и устанавливается в это значение для каждого подключения. Кодировка символов должна быть разрешена системной переменной и поддерживаться экземпляром MySQL.

Параметры для облачной инфраструктуры OCI

osBucketName: "string"

Имя ведра хранилища объектов Oracle Cloud Infrastructure, в которое будет записан экспортированный файл данных. По умолчанию используется профиль [DEFAULT] в файле конфигурации Oracle Cloud Infrastructure CLI, расположенном по адресу ~/.oci/config, для подключения к ведру. Вы можете использовать альтернативный профиль для подключения с помощью параметров ociConfigFile и ociProfile. Инструкции по настройке файла конфигурации CLI см. на странице Файл конфигурации SDK и CLI.

osNamespace: "string"

Пространство имён Oracle Cloud Infrastructure, в котором расположено хранилище объектов, указанное в параметре osBucketName. Пространство имён для ведра хранилища объектов отображается на вкладке «Информация о ведре» страницы сведений о ведре в консоли Oracle Cloud Infrastructure или может быть получено с помощью командной строки Oracle Cloud Infrastructure.

ociConfigFile: "string"

Файл конфигурации Oracle Cloud Infrastructure CLI, содержащий профиль, который необходимо использовать для подключения вместо профиля в стандартном расположении ~/.oci/config.

ociProfile: "string"

Имя профиля профиля Oracle Cloud Infrastructure, который необходимо использовать для подключения вместо профиля [DEFAULT] в файле конфигурации Oracle Cloud Infrastructure CLI, используемом для подключения.

ociAuth: "string"

Метод аутентификации, который нужно использовать при подключении к Oracle Cloud Infrastructure. Для этого параметра требуется, чтобы osBucketName был настроен со значением.

Доступны следующие параметры:

api_key: Подключения OCI используют файл конфигурации OCI. См. Раздел 4.7.1, «Oracle Cloud Infrastructure Object Storage».

Если osBucketName определён с допустимым значением, но ociAuth не определён, api_key используется по умолчанию.
instance_principal: Подключения OCI используют аутентификацию на основе принципала экземпляра. См. Аутентификация на основе принципала экземпляра.

Этот параметр нельзя использовать, если определены ociConfigFile или ociProfile.
resource_principal: Подключения OCI используют аутентификацию на основе принципала ресурса. См. Аутентификация на основе принципала ресурса.

Этот параметр нельзя использовать, если определены ociConfigFile или ociProfile.
security_token: Подключения OCI используют временный сгенерированный токен сеанса. См. Аутентификация на основе токена сеанса.

Параметры для совместимых с S3 служб

MySQL Shell поддерживает экспорт таблиц в совместимые с S3 ведра, такие как Amazon Web Services (AWS) S3.

Примечание

MySQL Shell поддерживает конфигурацию AWS S3 в параметрах командной строки, переменных среды и файлах конфигурации. Параметры командной строки имеют приоритет над переменными среды, файлами конфигурации и параметрами по умолчанию.

Сведения о требованиях к конфигурации см. в разделе 4.7, «Конфигурация облачной службы».

s3BucketName: "string"

Имя ведра S3, в которое будет производиться экспорт. По умолчанию для подключения к ведру S3 используется профиль default из файлов config и credentials, расположенных по адресу ~/.aws/. Вы можете использовать альтернативные конфигурации и учетные данные для подключения с помощью параметров s3ConfigFile и s3CredentialsFile. Инструкции по установке и настройке AWS CLI см. на странице Начало работы с AWS CLI.

s3CredentialsFile:"string"

Файл учетных данных, содержащий учетные данные пользователя для подключения вместо файла в стандартном расположении ~/.aws/credentials. Как правило, файл учетных данных содержит данные aws_access_key_id и aws_secret_access_key для подключения.

s3ConfigFile: "string"

Файл конфигурации, содержащий профиль для подключения вместо файла в стандартном расположении, таком как ~/.aws/config. Обычно файл конфигурации содержит регион и тип вывода для подключения.

s3Profile: "string"

Имя профиля профиля s3 CLI для подключения вместо профиля default.

s3Region: "string"

Название региона для подключения.

s3EndpointOverride: "string"

URL конечной точки для использования вместо значения по умолчанию.

При подключении к совместимому с S3 API Oracle Cloud Infrastructure конечная точка имеет следующий формат: https://namespace.compat.objectstorage.region.oraclecloud.com. Замените namespace на пространство имён хранилища объектов и region на ваш идентификатор региона. Например, идентификатор региона для региона США Восточный (Ашберн) — us-ashburn-1.

Для пространства имён с именем axaxnpcrorw5 в регионе США Восточный (Ашберн):

https://axaxnpcrorw5.compat.objectstorage.us-ashburn-1.oraclecloud.com.

Параметры для хранилища BLOB Microsoft Azure

MySQL Shell поддерживает экспорт в хранилище BLOB Microsoft Azure.

Примечание

MySQL Shell поддерживает конфигурацию хранилища BLOB Microsoft Azure в параметрах командной строки, переменных среды и файлах конфигурации. Параметры командной строки имеют приоритет над переменными среды и файлами конфигурации.

Сведения о требованиях к конфигурации и порядке применения типов конфигурации см. в разделе 4.7, «Конфигурация облачной службы».

azureContainerName: "string"

Обязательный параметр. Имя контейнера Azure, в который будет производиться экспорт. Контейнер должен существовать.

azureConfigFile: "string"

Необязательный параметр. Файл конфигурации, содержащий параметры подключения к хранилищу, вместо файла в стандартном расположении, таком как ~/.azure/config. Если этот параметр не определён, используется файл конфигурации по умолчанию.

azureContainerName должен быть определён и не пустым.

azureStorageAccount: "string"

Необязательный параметр. Имя учётной записи хранилища Azure, которое необходимо использовать для операции.

azureStorageSasToken: "string"

Необязательный параметр. Токен Azure Shared Access Signature (SAS) для аутентификации операции вместо ключа.

В следующем примере конфигурация использует строку конфигурации для параметров подключения, что означает, что команда exportTable требует только параметра azureContainerName.

Пример файла config:

        [cloud]
         name = AzureCloud

        [storage]
         connection_string=alphanumericConnectionString

Пример команды exportTable, которая экспортирует таблицу sakila.actor в формате TSV в контейнер с именем mysqlshellazure:

        util.exportTable("sakila.actor", "actor.tsv", {dialect: "tsv", azureContainerName: "mysqlshellazure"})