11.3 Table Export Utility — MySQL Shell 8.4

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

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

Описание утилиты

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

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

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

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

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

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

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

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

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

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

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 или в хранилище, совместимое с S3, outputUrl — имя файла данных в ведре, включая подходящее расширение файла. Вы можете включить разделители каталогов, чтобы смоделировать структуру каталогов. Используйте параметр osBucketName для указания имени ведра хранилища объектов и параметр osNamespace для идентификации пространства имён ведра. В этом примере в режиме Python MySQL Shell пользователь экспортирует таблицу employees из схемы hr в формате TSV в ведро хранилища объектов hanna-bucket:

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

Пространство имён ведра хранилища объектов отображается на вкладке «Информация о ведре» на странице подробностей ведра в консоли Oracle Cloud Infrastructure или может быть получено с помощью командной строки Oracle Cloud Infrastructure. Подключение к ведру хранилища объектов устанавливается с помощью профиля по умолчанию в файле конфигурации 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).

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

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

Таблица 11.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, в котором расположено хранилище Object Storage, указанное параметром osBucketName. Пространство имен для хранилища Object Storage отображается на вкладке «Информация о хранилище» на странице сведений о хранилище в консоли Oracle Cloud Infrastructure или может быть получено с помощью командной строки Oracle Cloud Infrastructure.
ociConfigFile: "string": Файл конфигурации Oracle Cloud Infrastructure CLI, содержащий профиль для подключения вместо файла по умолчанию, расположенного по адресу ~/.oci/config.
ociProfile: "string": Имя профиля профиля Oracle Cloud Infrastructure, используемого для подключения, вместо профиля [DEFAULT] в файле конфигурации Oracle Cloud Infrastructure CLI, используемом для подключения.

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

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

Примечание

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

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

s3BucketName: "string"

Имя хранилища S3, в которое будет выполняться экспорт. По умолчанию используется профиль default из файлов config и credentials, расположенных по адресу ~/.aws/, для подключения к хранилищу S3. Можно использовать альтернативные конфигурации и учетные данные для подключения с помощью параметров 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 конечной точки, используемой вместо значения по умолчанию.

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

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

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

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

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

Примечание

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

Сведения о требованиях к конфигурации и порядке приоритета типов конфигурации см. в разделе 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"})