MySQL :: MySQL Shell 9.0 :: 11.6 转储加载实用程序

版本 9.0

8.4 当前
8.0

8.0 日语

MySQL Shell 9.0 / MySQL Shell 实用程序 / 转储加载实用程序

11.6 转储加载实用程序

MySQL Shell 的转储加载实用程序 util.loadDump() 支持将使用 MySQL Shell 的第 11.5 节 “实例转储实用程序、模式转储实用程序和表转储实用程序”转储的模式或表导入到 HeatWave 服务数据库系统或 MySQL 服务器实例中。转储加载实用程序提供从远程存储流式传输数据、并行加载表或表块、进度状态跟踪、恢复和重置功能，以及在转储仍在进行时并发加载的选项。为了获得最佳功能，请始终使用 MySQL Shell 的转储和转储加载实用程序的最新可用版本。

关于实用程序

要导入到 HeatWave 服务数据库系统，必须在可以访问 HeatWave 服务数据库系统的 Oracle 云基础设施计算实例上安装 MySQL Shell。如果转储文件位于 Oracle 云基础设施对象存储桶中，则可以从计算实例访问该对象存储桶。如果转储文件位于您的本地系统上，则需要使用您选择的复制实用程序（具体取决于您为计算实例选择的操作系统）将它们传输到 Oracle 云基础设施计算实例。确保在 MySQL Shell 的实例转储实用程序或模式转储实用程序中创建转储时将 ocimds 选项设置为 true，以便与 HeatWave 服务兼容。MySQL Shell 的表转储实用程序不使用此选项。

对于实例转储实用程序或模式转储实用程序生成的输出，MySQL Shell 的转储加载实用程序使用 DDL 文件和制表符分隔的 .tsv 数据文件在目标 MySQL 实例中设置服务器实例或模式，然后加载数据。仅包含 DDL 文件或仅包含数据文件的转储可用于分别执行这些任务。转储加载实用程序还允许您分别应用来自包含两种类型文件的常规转储的 DDL 文件和数据文件。

您可以使用实用程序的选项来包含或排除要导入的指定模式和表、用户及其角色和授权、事件、例程和触发器。请注意，默认情况下，用户及其角色和授权将从加载中排除。如果您指定了冲突的包含和排除选项或指定了转储文件中未包含的对象，则会报告错误并停止加载，以便您更正选项。

对于 MySQL Shell 的表转储实用程序生成的输出，转储包含设置最初包含该表的模式所需的信息。默认情况下，从该版本开始，如果目标 MySQL 实例中不存在该模式，则会在其中重新创建该模式。或者，您可以在转储加载实用程序中指定 schema 选项，以将表加载到目标 MySQL 实例中的备用模式（该模式必须存在于目标 MySQL 实例中）。

您可以使用您选择的一组转储加载选项执行空运行，以显示在实际运行带有这些选项的实用程序时将执行的操作。

waitDumpTimeout 选项允许您应用仍在创建过程中的转储。表在可用时加载，并且实用程序在转储位置停止接收新数据后等待指定的秒数。当超时到期时，实用程序假定转储已完成并停止导入。

导入的进度状态存储在一个持久的进度状态文件中，该文件记录了已成功完成的步骤和已中断或失败的步骤。默认情况下，进度状态文件名为 load-progress.server_uuid.json 并在转储目录中创建，但您可以选择其他名称和位置。当您恢复或重试转储的导入时，转储加载实用程序会引用进度状态文件，并跳过已完成的步骤。对于部分加载的表，将自动管理重复数据删除。如果您使用 Ctrl + C 中断正在进行的转储，则在第一次使用该组合键时，实用程序不会启动任何新任务，但现有任务会继续。再次按下 Ctrl + C 将停止现有任务，从而导致错误消息。在任何一种情况下，实用程序仍然可以从停止的地方恢复导入。

您可以选择重置进度状态并从头开始重新开始转储的导入，但在这种情况下，实用程序不会跳过已创建的对象，也不会管理重复数据删除。如果您这样做，为了确保正确导入，您必须手动从目标 MySQL 实例中删除该转储中所有先前加载的对象，包括模式、表、用户、视图、触发器、例程和事件。否则，如果转储文件中的对象已存在于目标 MySQL 实例中，则导入将停止并显示错误。谨慎起见，您可以使用 ignoreExistingObjects 选项使实用程序报告重复的对象，但跳过它们并继续导入。请注意，实用程序不会检查目标 MySQL 实例和转储文件中对象的内容是否不同，因此最终的导入可能会包含不正确或无效的数据。

重要

不要在转储停止和转储恢复之间更改转储文件中的数据。在更改数据后恢复转储的行为未定义，并且可能导致数据不一致和数据丢失。如果您需要在部分加载转储后更改数据，请手动删除部分导入期间创建的所有对象（如进度状态文件中所列），然后使用 resetProgress 选项运行转储加载实用程序，以从头开始重新开始。

如果您需要在将转储的数据文件导入目标 MySQL 实例之前修改其中的任何数据，则可以通过将 MySQL Shell 的并行表导入实用程序 util.importTable() 与转储加载实用程序组合在一起来实现。为此，首先使用转储加载实用程序仅加载所选表的 DDL，以便在目标服务器上创建该表。然后使用并行表导入实用程序捕获并转换来自该表输出文件的数据，并将其导入到目标表中。对您要修改数据的任何其他表，请根据需要重复该过程。最后，使用转储加载实用程序加载您不想修改的任何剩余表的 DDL 和数据，但不包括您修改过的表。有关该过程的说明，请参阅修改转储数据。

转储中的表由您使用 threads 选项指定的线程数并行加载，默认值为 4。如果在创建转储时对表数据进行了分块，则可以为一个表使用多个线程，否则每个线程一次加载一个表。转储加载实用程序跨线程调度数据导入，以最大限度地提高并行度。使用后台线程池来获取文件的内容。如果转储文件是由 MySQL Shell 的转储实用程序压缩的，则转储加载实用程序会为它们处理解压缩。

默认情况下，仅在表完全加载后才会创建表的全文索引，这会加快导入速度。您可以选择将所有索引创建（主键索引除外）推迟到每个表完全加载之后。您还可以选择在表导入期间创建所有索引。您还可以选择在导入期间禁用索引创建，并在之后创建索引，例如，如果您想在加载后更改表结构。

为了进一步提高数据加载性能，您可以在导入期间禁用目标 MySQL 实例上的 InnoDB 重做日志。请注意，这只应在新 MySQL 服务器实例（而非生产系统）上执行，并且此功能在 MySQL 数据库系统上不可用。有关详细信息，请参阅禁用重做日志记录。

要求和限制

加载转储的目标 MySQL 实例需要 MySQL 5.7 或更高版本。
低于 8.0.27 版本的 MySQL Shell 的转储加载实用程序无法加载使用 MySQL Shell 8.0.27 或更高版本中的转储实用程序创建的转储。这是因为从 MySQL Shell 8.0.27 开始，转储元数据中包含有关创建转储时使用的功能的信息。此功能列表不向后兼容，但它支持在未来版本中添加新功能时的向后兼容性。为了获得最佳功能，请始终使用 MySQL Shell 的转储和转储加载实用程序的最新可用版本。
转储加载实用程序使用 LOAD DATA LOCAL INFILE 语句，因此在导入期间，目标 MySQL 实例上 local_infile 系统变量的全局设置必须为 ON。默认情况下，在标准 HeatWave 服务数据库系统配置中，此系统变量设置为 ON。
LOAD DATA LOCAL INFILE 语句使用非限制性数据解释，它会将错误转换为警告并继续加载操作。此过程可以包括为字段分配默认值和隐式默认值，以及将无效值转换为列数据类型的最接近有效值。有关语句行为的详细信息，请参见 LOAD DATA。
在目标 MySQL 实例上，转储加载实用程序会检查 sql_require_primary_key 系统变量是否设置为 ON，如果是，则如果转储文件中存在没有主键的表，则返回错误。默认情况下，在标准 HeatWave Service DB System 配置中，此系统变量设置为 OFF。
转储加载实用程序不会自动将源 MySQL 实例上的 gtid_executed GTID 集应用于目标 MySQL 实例。GTID 集包含在 MySQL Shell 的实例转储实用程序、模式转储实用程序或表转储实用程序的转储元数据中，作为 @.json 转储文件中的 gtidExecuted 字段。要在目标 MySQL 实例上应用这些 GTID 以用于复制，请使用 updateGtidSet 选项或手动导入它们，具体取决于目标 MySQL 实例的版本和 MySQL Shell 版本。这也得到 HeatWave Service DB System 实例的支持。有关详细信息，请参阅 updateGtidSet 选项的说明。

使用 PAR 加载转储文件

MySQL Shell 支持使用预先验证的请求 (PAR) 从对象存储桶加载转储文件。PAR 提供了一种让用户无需拥有自己的凭据即可访问存储桶或对象的方法。

重要

在使用此访问方法之前，请评估对存储桶或存储桶中对象的预先验证访问的业务需求和安全影响。PAR 允许拥有 PAR 的任何人访问请求中标识的目标。请谨慎管理 PAR 的分发。

MySQL Shell 支持对存储桶中的所有对象或具有特定前缀的存储桶中的对象使用读取访问 PAR（对象读取 PAR）。有关创建存储桶 PAR 和前缀 PAR 的信息，请参阅使用预先验证的请求。使用存储桶 PAR 或前缀 PAR 时，转储加载实用程序需要本地进度状态文件。文件内容采用 JSON 格式，因此扩展名为 .json 的文本文件是合适的（例如，progress.json）。以下示例显示了使用为存储桶中的所有对象创建的 PAR 加载转储文件的语法：

JS> util.loadDump("BucketPARURL", {progressFile: "progress.json"})

使用相同的语法来加载具有特定前缀的存储桶中的对象，但在这种情况下，PAR URL 包含前缀

shell-js> util.loadDump("PrefixPARURL", progressFile: "progress.json"})

运行实用程序

转储加载实用程序使用 MySQL Shell 全局会话获取要将转储导入到的目标 MySQL 实例的连接详细信息。必须先打开全局会话（可以具有 X 协议连接或经典 MySQL 协议连接），然后才能运行该实用程序。该实用程序会为每个线程打开自己的会话，从全局会话复制连接压缩和 SSL 选项等选项，并且不再使用全局会话。

在 MySQL Shell API 中，转储加载实用程序是 util 全局对象的一个函数，并具有以下签名：

util.loadDump(url[, options])

options 是一个选项字典，如果为空则可以省略。本主题的其余部分列出了这些选项。

如果要导入的转储位于运行实用程序的 Oracle Cloud Infrastructure Compute 实例的文件系统中，则 url 是一个字符串，指定包含转储文件的本地目录的路径。您可以在本地目录路径前面加上 file:// 模式。在 MySQL Shell 的 JavaScript 模式的此示例中，执行了一次空运行以检查从本地目录将转储文件加载到连接的 MySQL 实例时是否不会出现问题：

shell-js> util.loadDump("/mnt/data/worlddump", {dryRun: true})

如果要从 Oracle Cloud Infrastructure 对象存储桶导入转储，则 url 是转储文件在存储桶中的路径前缀，该前缀是在创建转储时使用 outputUrl 参数分配的。使用 osBucketName 选项提供对象存储桶的名称，并使用 osNamespace 选项标识存储桶的命名空间。在 MySQL Shell 的 JavaScript 模式的此示例中，使用 8 个线程将前缀为 worlddump 的转储从对象存储桶加载到连接的 HeatWave Service DB System：

shell-js> util.loadDump("worlddump", {
          threads: 8, osBucketName: "hanna-bucket", osNamespace: "idx28w1ckztq"})

对象存储桶的命名空间显示在 Oracle Cloud Infrastructure 控制台的存储桶详细信息页面的“存储桶信息”选项卡中，也可以使用 Oracle Cloud Infrastructure 命令行界面获取。使用默认 Oracle Cloud Infrastructure CLI 配置文件中的默认配置文件或您使用 ociConfigFile 和 ociProfile 选项指定的备用详细信息建立与对象存储桶的连接。有关设置 CLI 配置文件的说明，请参阅 SDK 和 CLI 配置文件。

负载控制选项

dryRun：[true | false]

显示有关在指定选项和转储文件的情况下将执行的操作的信息，包括根据转储内容将返回的任何错误，但不继续执行导入。默认值为 false。

waitDumpTimeout：number

将此选项设置为大于 0 的值将在仍在生成转储时激活并发加载转储。该值是在处理转储位置中的所有已上传数据块后，实用程序等待更多数据的超时时间（以秒为单位）。这允许实用程序在仍在创建转储时导入转储。数据将在可用时进行处理，并且当超过超时时间且转储位置中没有出现更多数据时，导入将停止。默认设置 0 表示实用程序在处理完所有已上传的数据块后将转储标记为完成，并且不会等待更多数据。使用默认设置时，将禁用并发加载。

schema：“string”

必须将 MySQL Shell 的转储实用程序生成的转储加载到的目标模式。

如果模式不存在，则会创建该模式，并将转储加载到该新模式。如果新模式名称与转储中的模式名称不同，则会将转储加载到新模式，但不会对已加载的数据进行任何更改。也就是说，对旧模式名称的任何引用都保留在数据中。所有存储过程、视图等都引用原始模式，而不是新模式。

单个模式转储或导致单个模式的过滤选项支持此加载选项。

threads：number

用于将数据块并行上传到目标 MySQL 实例的线程数。每个线程都与 MySQL 实例建立自己的连接。默认值为 4。如果在创建转储时启用了分块（默认情况下），则该实用程序可以使用多个线程来加载表的数据；否则，一个线程仅用于一个表。

backgroundThreads：number

用于获取文件内容的后台线程池中的线程数。默认值为从本地服务器加载的转储的 threads 选项的值，或者是从非本地服务器加载的转储的 threads 选项的值的四倍。

progressFile：“string”

指定本地进度状态文件的路径，用于跟踪加载进度。根据加载操作的类型，允许使用其他值：

从本地存储加载转储时：

可以省略 progressFile 选项。在这种情况下，会在转储目录中自动创建一个名为 load-progress-server-uuid.json 的进度状态文件。
可以将 progressFile 选项设置为空字符串以禁用进度状态跟踪，这意味着转储加载实用程序无法恢复部分完成的导入。

使用预先验证的请求 (PAR) 从 OCI 对象存储加载转储时，progressFile 选项是必需的。

如果使用存储桶或前缀 PAR 执行加载操作，请将 progressFile 选项设置为本地进度状态文件的路径。
如果使用清单文件 PAR 执行加载操作，请将 progressFile 选项设置为本地进度状态文件的路径，或为驻留在与清单文件相同位置的进度状态文件指定写入 PAR。

如果指定了本地进度状态文件或有效的写入 PAR，但进度状态文件不存在，则会创建该文件。

showProgress：[true | false]

显示 (true) 或隐藏 (false) 导入的进度信息。如果 stdout 是终端 (tty)，例如当 MySQL Shell 处于交互模式时，则默认值为 true，否则为 false。进度信息包括活动线程的数量及其操作、到目前为止已加载的数据量、完成百分比和吞吐率。未显示进度信息时，进度状态仍会记录在转储加载实用程序的进度状态文件中。

resetProgress：[true | false]

将此选项设置为 true 会重置进度状态并从头开始重新启动导入。默认值为 false。请注意，使用此选项时，转储加载实用程序不会跳过已创建的对象，也不会管理重复数据删除。如果要使用此选项，为了确保正确导入，必须先从目标 MySQL 实例中手动删除所有先前加载的对象，包括该转储中的模式、表、用户、视图、触发器、例程和事件。否则，如果转储文件中的对象已存在于目标 MySQL 实例中，则导入将停止并报错。谨慎起见，可以使用 ignoreExistingObjects 选项使实用程序报告重复的对象，但跳过它们并继续导入。

skipBinlog：[true | false]

通过发出 SET sql_log_bin=0 语句，为实用程序在导入过程中使用的会话跳过目标 MySQL 实例上的二进制日志记录。默认值为 false，因此默认情况下二进制日志记录处于活动状态。对于 HeatWave Service DB System，不使用此选项，并且如果尝试将其设置为 true，则导入将停止并报错。对于其他 MySQL 实例，如果要将源 MySQL 实例上的 gtid_executed GTID 集应用于目标 MySQL 实例，无论是使用 updateGtidSet 选项还是手动应用，请始终将 skipBinlog 设置为 true。当目标 MySQL 实例上正在使用 GTID (gtid_mode=ON) 时，将此选项设置为 true 可以防止在执行导入时生成和分配新的 GTID，以便可以使用源服务器的原始 GTID 集。用户帐户必须具有设置 sql_log_bin 系统变量所需的权限。

ignoreVersion：[true | false]

即使从中转储数据的 MySQL 实例的主版本号与要将数据上传到的 MySQL 实例的主版本号不连续，也要导入转储。默认值为 false，这意味着如果主版本号不连续，则会发出错误并且导入不会继续。如果此选项设置为 true，则会发出警告并继续导入。请注意，仅当转储文件中的模式与新的主版本没有兼容性问题时，导入才会成功。

注意

在连续的主要版本（例如从 8.0 到 8.1）之间复制时，不需要 ignoreVersion。

在尝试使用 ignoreVersion 选项进行导入之前，请使用 MySQL Shell 的升级检查器实用程序 checkForServerUpgrade() 检查源 MySQL 实例上的模式。在转储模式并将它们导入目标 MySQL 实例之前，请修复该实用程序标识的任何兼容性问题。

ignoreExistingObjects: [ true | false ]

即使转储包含 MySQL 实例中目标模式中已存在的对象，也要导入转储。默认值为 false，这意味着当发现重复对象时会发出错误并且导入停止，除非使用进度状态文件从之前的尝试恢复导入，在这种情况下，将跳过检查。如果此选项设置为 true，则会报告重复对象，但不会生成错误并且导入会继续。应谨慎使用此选项，因为该实用程序不会检查目标 MySQL 实例和转储文件中对象的内容是否不同，因此最终的导入可能包含不正确或无效的数据。另一种策略是使用 excludeTables 选项排除您已加载的表，在这些表中您已验证转储文件中的对象与目标 MySQL 实例中导入的对象相同。最安全的选择是在重新启动转储之前从目标 MySQL 实例中删除重复对象。

此选项还允许将没有使用 ocimds 选项创建的转储导入 HeatWave 服务实例。

handleGrantErrors: abort|drop_account|ignore

如果发生与 GRANT 或 REVOKE 错误相关的错误，则采取的操作。

abort: （默认）停止加载过程并显示错误。
drop_account: 删除帐户并继续加载过程。
ignore: 忽略错误并继续加载过程。

characterSet: "字符串"

用于导入到目标 MySQL 实例的字符集，例如在 LOAD DATA 语句的 CHARACTER SET 选项中。默认值为转储元数据中给定的字符集，该字符集是在 MySQL Shell 的实例转储实用程序、模式转储实用程序或表转储实用程序创建转储时使用的，默认使用 utf8mb4。字符集必须由 character_set_client 系统变量允许并且受 MySQL 实例支持。

maxBytesPerTransaction: 数字

在单个 LOAD DATA 语句中可以从数据文件加载的最大字节数。如果数据文件超过 maxBytesPerTransaction 值，则多个 LOAD DATA 语句将以小于或等于 maxBytesPerTransaction 值的块加载文件中的数据。

可以使用单位后缀 k 表示千字节，M 表示兆字节，G 表示千兆字节。最小值为 4096 字节。如果指定了较小的值，则隐式使用 4096 字节的最小值。如果未设置 maxBytesPerTransaction 选项，则用于转储数据的 bytesPerChunk 值将用作大于 1.5 * bytesPerChunk 值的文件的默认设置。如果未设置 maxBytesPerTransaction 选项并且数据文件小于 1.5 * bytesPerChunk 值，则会在单个 LOAD DATA 语句中请求数据。

如果数据文件包含大于 maxBytesPerTransaction 设置的行，则会在单个 LOAD DATA 语句中请求该行的数据。对于遇到的第一个超过 maxBytesPerTransaction 设置的行，将发出警告。

如果具有已配置的 maxBytesPerTransaction 设置的加载操作被中断并恢复执行，则已加载的块将被跳过。恢复的加载操作使用当前的 maxBytesPerTransaction 设置。操作中断之前使用的设置不会保存到进度状态文件。

此选项的一个预期用途是在数据文件对于目标服务器的限制（例如由服务器的 group_replication_transaction_size_limit 或 max_binlog_cache_size 设置定义的限制）太大时以较小的块加载数据。例如，如果在加载数据时收到错误 "MySQL 错误 1197 (HY000): 多语句事务需要的存储空间超过“max_binlog_cache_size”字节"，请将 maxBytesPerTransaction 设置为小于或等于服务器实例的 max_binlog_cache_size 设置的值。

sessionInitSql: 字符串列表

要在用于将数据加载到目标 MySQL 实例的每个客户端会话开始时运行的 SQL 语句列表。您可以使用此选项来更改会话变量。例如，以下语句在导入过程中跳过目标 MySQL 实例上用于该实用程序的会话的二进制日志记录，并增加可用于索引创建的线程数

sessionInitSQL: ["SET SESSION sql_log_bin=0;", "SET SESSION innodb_ddl_threads=8,"]

如果在运行 SQL 语句时发生错误，则导入将停止并返回错误消息。

加载内容的选项

loadIndexes: [ true | false ]

为表创建 (true) 或不创建 (false) 辅助索引。默认值为 true。如果此选项设置为 false，则在导入期间不会创建辅助索引，您必须在之后创建它们。如果您分别加载 DDL 文件和数据文件，并且希望在加载 DDL 文件后更改表结构，这将非常有用。之后，您可以通过再次运行转储加载实用程序来创建辅助索引，并将 loadIndexes 设置为 true，将 deferTableIndexes 设置为 all。

MySQL Shell 利用 MySQL Server 的并行索引创建。以前，转储加载实用程序会依次添加索引，一次添加一个。从本版本开始，表中的所有索引将同时添加。

有关限制和配置，请参阅为在线 DDL 操作配置并行线程。

deferTableIndexes: [ off | fulltext | all ]

延迟辅助索引的创建，直到加载表数据之后。这可以减少加载时间。off 表示所有索引都是在表加载期间创建的。默认设置 fulltext 仅延迟全文索引。all 延迟所有辅助索引，并且仅在表加载期间创建主键索引，以及在包含自动递增值的列上定义的索引。

analyzeTables: [ off | on | histogram ]

在加载表后对表执行 ANALYZE TABLE。on 分析所有表，histogram 仅分析在转储中存储了直方图信息的表。默认值为 off。即使数据已加载，您也可以使用此选项运行转储加载实用程序来分析表。

checksum: [true|false]

如果启用，则 loadDump 实用程序会在加载相应数据后检查转储实用程序生成的校验和数据。验证仅限于已转储的数据，忽略生成的数据，例如由 loadDump 实用程序添加的不可见主键。

如果校验和不匹配或缺少表且无法验证，则会返回错误。

如果 checksum: true 但由于 loadData: false 或没有转储数据而没有加载任何数据，则该实用程序会根据受影响表的当前内容验证转储的校验和信息。

如果表不存在，则会为每个缺少的表显示错误。
如果 checksum: true 且 dryRun: true，则不会验证校验和。将显示一条消息，说明未进行验证。

showMetadata: [ true | false ]

打印源实例的 gtid_executed GTID 集以及二进制日志文件名和位置，这些信息取自 MySQL Shell 的实例转储实用程序、模式转储实用程序或表转储实用程序生成的转储随附的转储元数据。元数据以 YAML 格式打印。

gtid_executed GTID 集始终作为 @.json 转储文件中的 gtidExecuted 字段包含在转储中。转储加载实用程序不会自动将源 MySQL 实例上的 gtid_executed GTID 集应用于目标 MySQL 实例。要在目标 MySQL 实例上应用这些 GTID 以用于复制，请使用 updateGtidSet 选项或手动导入它们，具体取决于目标 MySQL 实例的版本。HeatWave 服务数据库系统实例也支持此功能。有关详细信息，请参阅 updateGtidSet 选项的描述。

如果用于运行转储实用程序的用户帐户具有 REPLICATION CLIENT 权限，则将包含二进制日志文件名和位置。二进制日志文件名和位置可用于使用 CHANGE REPLICATION SOURCE TO 语句（从 MySQL Server 8.0.23 开始可用）的 ASSIGN_GTIDS_TO_ANONYMOUS_TRANSACTIONS 选项，从未启用 GTID 且未使用基于 GTID 的复制的源服务器设置到已启用 GTID 的副本的复制。

updateGtidSet: [ off | append | replace ]

将转储元数据中记录的源 MySQL 实例上的 gtid_executed GTID 集应用于目标 MySQL 实例上的 gtid_purged GTID 集。gtid_purged GTID 集包含已应用于服务器但服务器上的任何二进制日志文件中都不存在的所有事务的 GTID。默认值为 off，这意味着不应用 GTID 集。

不要将此选项用于由 MySQL Shell 的表转储实用程序生成的转储，仅用于由 MySQL Shell 的实例转储实用程序或模式转储实用程序生成的转储。此外，当组复制在目标 MySQL 实例上运行时，请勿使用此选项。

对于非 HeatWave Service DB System 实例的 MySQL 实例，当您设置 append 或 replace 来更新 GTID 集时，还要将 skipBinlog 选项设置为 true。这可确保源服务器上的 GTID 与目标服务器上的 GTID 匹配。对于 HeatWave Service DB System 实例，不使用此选项。

对于 MySQL 8.0 的目标 MySQL 实例，您可以将选项设置为 append，这会将源 MySQL 实例的 gtid_executed GTID 集追加到目标 MySQL 实例的 gtid_purged GTID 集。要应用的 gtid_executed GTID 集（在 @.json 转出文件的 gtidExecuted 字段中显示）不得与目标 MySQL 实例上已有的 gtid_executed 集相交。例如，将架构从不同的源 MySQL 实例导入到已包含来自其他源服务器的架构的目标 MySQL 实例时，可以使用此选项。

您还可以对 MySQL 8.0 的目标 MySQL 实例使用 replace，以将目标 MySQL 实例上的 gtid_purged GTID 集替换为源 MySQL 实例的 gtid_executed GTID 集。为此，源 MySQL 实例的 gtid_executed GTID 集必须是目标 MySQL 实例上的 gtid_purged GTID 集的超集，并且不得与目标的 gtid_executed GTID 集中不在其 gtid_purged GTID 集中的事务集相交。

对于 MySQL 5.7 的目标 MySQL 实例，请将选项设置为 replace，这会将目标 MySQL 实例上的 gtid_purged GTID 集替换为源 MySQL 实例的 gtid_executed GTID 集。在 MySQL 5.7 中，为此，目标 MySQL 实例上的 gtid_executed 和 gtid_purged GTID 集必须为空，因此实例必须未使用，并且没有以前导入的 GTID 集。

对于 HeatWave Service DB System，不支持此方法。要应用 GTID 集，请在导入后使用 MySQL Shell 的 \sql 命令（或进入 SQL 模式）在连接的 MySQL 实例上发出以下语句，并从转储元数据的 @.json 转出文件中的 gtidExecuted 字段复制 gtid_executed GTID 集

shell-js> \sql SET @@GLOBAL.gtid_purged= "+gtidExecuted_set";

此语句从 MySQL 8.0 开始有效，它将源 MySQL Server 实例的 gtid_executed GTID 集添加到目标 MySQL 实例的 gtid_purged GTID 集。对于 MySQL 5.7，必须省略加号 (+)，并且目标 MySQL 实例上的 gtid_executed 和 gtid_purged GTID 集必须为空。有关更多详细信息，请参阅目标 MySQL 实例版本中 gtid_purged 系统变量的说明。

createInvisiblePKs: [ true | false ]

在转储中不包含主键的每个表的不可见列中添加主键。如果转储是使用 MySQL Shell 的实例转储实用程序 util.dumpInstance()、架构转储实用程序 util.dumpSchemas() 或表转储实用程序 util.dumpTables() 的 create_invisible_pks 选项创建的，则会自动应用 true 设置。仅当加载了转储的 DDL (loadDdl: true) 时，才会添加主键。不可见列（名为“my_row_id”）对使用上传表的应用程序没有影响。

当 createInvisiblePKs 设置为 true 时，目标 MySQL 实例必须为 MySQL Server 8.0.24 或更高版本，否则加载将失败。不可见列从 MySQL Server 8.0.23 开始可用，但该版本中对它们施加的限制会阻止使用此函数。

以这种方式添加主键尚不能实现将修改后的表入站复制到 HeatWave Service 高可用性数据库系统，因为该功能当前要求源服务器和副本服务器中都存在主键。如果可能，请考虑在源服务器上的表中创建主键，然后再转储它们，而不是使用此选项。从 MySQL 8.0.23 开始，您可以使用不可见列来保存主键，而不会对应用程序造成任何影响。这是提高性能和易用性的最佳实践，并且有助于转储的数据库与 HeatWave Service 无缝协作。

HeatWave Service 和 Oracle Cloud Infrastructure 的选项

osBucketName: "string"

转储文件所在的 Oracle Cloud Infrastructure 对象存储桶的名称。默认情况下，使用位于 ~/.oci/config 的 Oracle Cloud Infrastructure CLI 配置文件中的 [DEFAULT] 配置文件来建立与存储桶的连接。您可以替换用于连接的备用配置文件，方法是使用 ociConfigFile 和 ociProfile 选项。有关设置 CLI 配置文件的说明，请参阅SDK 和 CLI 配置文件。

osNamespace: "string"

osBucketName 命名的对象存储桶所在的 Oracle Cloud Infrastructure 命名空间。对象存储桶的命名空间显示在 Oracle Cloud Infrastructure 控制台中存储桶详细信息页面的“存储桶信息”选项卡中，也可以使用 Oracle Cloud Infrastructure 命令行界面获取。

ociConfigFile: "string"

包含用于连接的配置文件的 Oracle Cloud Infrastructure CLI 配置文件，而不是默认位置 ~/.oci/config 中的配置文件。

ociProfile: "string"

用于连接的 Oracle Cloud Infrastructure 配置文件的配置文件名称，而不是用于连接的 Oracle Cloud Infrastructure CLI 配置文件中的 [DEFAULT] 配置文件。

ociAuth: "string"

连接到 Oracle Cloud Infrastructure 时使用的身份验证方法。此选项要求使用有效值配置 osBucketName 。

以下选项可用

api_key：OCI 连接使用 OCI 配置文件。请参阅第 4.7.1 节“Oracle Cloud Infrastructure 对象存储”。

如果使用有效值定义了 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 存储桶的名称。默认情况下，使用位于 ~/.aws/ 的 Amazon Web Services (AWS) CLI config 和 credentials 文件中的 default 配置文件来建立与 S3 存储桶的连接。您可以使用 s3ConfigFile 和 s3CredentialsFile 选项为连接替换备用配置和凭据。有关安装和配置 AWS CLI 的说明，请参阅AWS CLI 入门。

s3CredentialsFile: "string"

包含用于连接的用户凭据的凭据文件，而不是默认位置 ~/.aws/credentials 中的文件。通常，凭据文件包含用于连接的 aws_access_key_id 和 aws_secret_access_key。

s3ConfigFile: "string"

包含用于连接的配置文件的 AWS CLI 配置文件，而不是默认位置 ~/.aws/config 中的文件。通常，配置文件包含用于连接的区域和输出类型。

s3Profile: "string"

用于连接的 s3 CLI 配置文件的配置文件名称，而不是用于连接的 AWS CLI 配置文件中的 default 配置文件。

s3Region: "string"

用于连接的区域的名称。

s3EndpointOverride: "string"

要使用的端点的 URL，而不是默认端点。

连接到 Oracle Cloud Infrastructure S3 兼容性 API 时，端点采用以下格式：https://namespace.compat.objectstorage.region.oraclecloud.com。将 namespace 替换为对象存储命名空间，并将 region 替换为您的区域标识符。例如，美国东部（阿什本）区域的区域标识符为 us-ashburn-1。

对于美国东部（阿什本）区域中名为 axaxnpcrorw5 的命名空间

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

以下示例显示了如何从 AWS S3 存储桶 Bucket001 中的文件夹 test 加载 MySQL 转储，

      util.loadDump("test",{s3BucketName: "Bucket001", threads: 4})

以下示例显示了如何使用配置配置文件 oci 和 s3EndpointOverride 将连接定向到所需租户和区域的 OCI 端点，从对象存储桶 Bucket001 中的前缀 test 加载 MySQL 转储

      util.loadDump("test",{s3BucketName: "Bucket001", 
      s3EndpointOverride: "https://axaxnpcrorw5.compat.objectstorage.us-ashburn-1.oraclecloud.com", 
      s3Profile: "oci", threads: 4})

Microsoft Azure Blob 存储的选项

MySQL Shell 支持从 Microsoft Azure Blob 存储加载。

注意

MySQL Shell 支持在命令行选项、环境变量和配置文件中配置 Microsoft Azure Blob 存储。命令行选项优先于环境变量和配置文件。

有关配置要求和配置类型优先级的详细信息，请参见第 4.7 节“云服务配置”。

azureContainerName: "string"

必需。要从中加载转储的 Azure 容器的名称。该容器必须存在。

azureConfigFile: "string"

可选。包含存储连接参数的配置文件，而不是默认位置的配置文件，例如 ~/.azure/config。如果未定义，则使用默认配置文件。

azureContainerName 必须定义，并且不能为空。

azureStorageAccount: "string"

可选。用于操作的 Azure 存储帐户的名称。

azureStorageSasToken: "string"

可选。用于对操作进行身份验证的 Azure 共享访问签名 (SAS) 令牌，而不是密钥。

在以下示例中，配置对连接参数使用配置字符串，这意味着转储命令仅需要 azureContainerName。

示例 config 文件

        [cloud]
         name = AzureCloud

        [storage]
         connection_string=alphanumericConnectionString

示例 loadDump 命令，它将名为 prefix1 的文件夹的内容从名为 mysqlshellazure 的容器导入到连接的 MySQL 实例

        util.loadDump("prefix1", {azureContainerName: "mysqlshellazure", threads: 4})

过滤选项

loadDdl: [ true | false ]

将此选项设置为 false 会从加载中排除转储中的 DDL 文件。默认值为 true，这意味着将加载 DDL 文件。

loadData: [ true | false ]

将此选项设置为 false 会从加载中排除转储中的数据文件。默认值为 true，这意味着将加载数据文件。

loadUsers: [ true | false ]

将用户及其角色和权限导入 (true) 或不导入 (false) 到目标 MySQL 实例中。默认值为 false，因此默认情况下不会导入用户。将跳过当前用户的语句。如果目标 MySQL 实例中已存在某个用户，则会返回错误，并且不会应用来自转储文件的用户权限。您可以在转储加载实用程序中使用 excludeUsers 或 includeUsers 选项来指定要从导入中排除或包含的用户帐户。

MySQL Shell 的架构转储实用程序和表转储实用程序不包含转储中的用户、角色和权限，但实例转储实用程序可以包含，并且默认情况下会包含。在实例转储实用程序中，excludeUsers 和 includeUsers 选项也可用于从转储文件中排除或包含指定的帐户。

如果您指定了 true，但提供的转储文件不包含用户帐户，则该实用程序会返回警告并继续。

excludeUsers: 字符串数组

从导入中排除指定的帐户。您可以使用它来排除不接受导入到 HeatWave Service DB 系统的用户帐户，或者目标 MySQL 实例中已存在或不需要的用户帐户。对于使用用户名和主机名定义的帐户，请使用 "'用户名'@'主机名'" 格式指定每个用户帐户字符串；对于仅使用用户名定义的帐户，请使用 "'用户名'" 格式指定。如果您没有提供主机名，则排除具有该用户名的所有帐户。

includeUsers: 字符串数组

仅包含导入中指定的帐户。请像 excludeUsers 选项那样指定每个用户帐户字符串。如果目标 MySQL 实例中仅需要几个用户帐户，则可以使用它作为 excludeUsers 的替代方案。您还可以同时指定这两个选项以包含某些帐户并排除其他帐户。

excludeSchemas: 字符串数组

从导入中排除指定的架构。请注意，information_schema、mysql、ndbinfo、performance_schema 和 sys 架构始终从 MySQL Shell 的实例转储实用程序创建的转储中排除。

includeSchemas: 字符串数组

仅加载转储文件中指定的架构。您可以同时指定这两个选项以包含某些架构并排除其他架构。

excludeTables: 字符串数组

从导入中排除指定的表，以便不会将它们上传到目标 MySQL 实例。表名必须使用有效的架构名进行限定，并在需要时用反引号字符引起来。请注意，mysql.apply_status、mysql.general_log、mysql.schema 和 mysql.slow_log 表 的数据始终从 MySQL Shell 的架构转储实用程序创建的转储中排除，尽管它们的 DDL 语句已包含在内。

includeTables: 字符串数组

仅加载转储文件中指定的表。表名必须使用有效的架构名进行限定，并在需要时用反引号字符引起来。您可以同时指定这两个选项以包含某些表并排除其他表。

excludeEvents: 字符串数组

从导入中排除指定的事件。事件名称必须使用有效的架构名进行限定，并在需要时用反引号字符引起来。

includeEvents: 字符串数组

仅加载转储文件中指定的事件。事件名称必须使用有效的架构名进行限定，并在需要时用反引号字符引起来。

excludeRoutines: 字符串数组

从导入中排除指定的函数和存储过程。例程名称必须使用有效的架构名进行限定，并在需要时用反引号字符引起来。

includeRoutines: 字符串数组

仅加载转储文件中指定的函数和存储过程。例程名称必须使用有效的架构名进行限定，并在需要时用反引号字符引起来。

excludeTriggers: 字符串数组

从导入中排除指定的触发器。触发器名称必须使用有效的架构名和表名 (schema.table.trigger) 进行限定，并在需要时用反引号字符引起来。您可以通过使用此选项指定架构名和表名 (schema.table) 来排除特定表的所有触发器。

includeTriggers: 字符串数组

仅加载转储文件中指定的触发器。触发器名称必须使用有效的架构名和表名 (schema.table.trigger) 进行限定，并在需要时用反引号字符引起来。您可以通过使用此选项指定架构名和表名 (schema.table) 来包含特定表的所有触发器。

生成的不可见主键模式

MySQL Server 8.0.30 引入了 GIPK 模式，生成的不可见主键。在此模式下运行时，对于任何未显式创建主键的 InnoDB 表，MySQL 服务器都会自动向该表添加一个生成的不可见主键 (GIPK)。通过将 sql_generate_invisible_primary_key 设置为 ON 来启用此模式。

MySQL Shell 的加载实用程序选项 createInvisiblePKs 使用服务器的 GIPK 模式为没有主键的表生成不可见主键。

在某些情况下，如果用户没有足够的权限使用 GIPK 模式，MySQL Shell 可以回退到以前的生成不可见主键的方法。

如果 createInvisiblePKs:false 且 sql_generate_invisible_primary_key=OFF，则不会为从转储加载的任何表生成主键。

如果 createInvisiblePKs:false 且 sql_generate_invisible_primary_key=ON，则 MySQL Shell 会尝试设置 sql_generate_invisible_primary_key=OFF。如果更改成功，则不会为从转储加载的任何表生成主键。

如果 createInvisiblePKs:true 且 sql_generate_invisible_primary_key=OFF，则 MySQL Shell 会尝试设置 sql_generate_invisible_primary_key=ON。如果更改成功，则会为从转储加载的每个没有主键的表生成主键。

如果 createInvisiblePKs:true 且 sql_generate_invisible_primary_key=ON，则会使用 MySQL Server GIPK 模式为加载的每个表生成主键。

如果运行 MySQL Shell 加载实用程序的用户没有所需的 MYSQL Server 权限，则尝试设置 sql_generate_invisible_primary_key 会失败。如果尝试失败且 createInvisiblePKs:true，则 MySQL Shell 会为任何没有主键的表生成不可见主键。

如果启用了 GIPK 服务器选项 sql_generate_invisible_primary_key 且禁用了 MySQL Shell 加载实用程序选项 createInvisiblePKs，并且用户没有更改 sql_generate_invisible_primary_key 所需的权限，则会生成错误并且加载失败。可以通过启用 MySQL Shell 环境变量 MYSQLSH_ALLOW_ALWAYS_GIPK 来覆盖此行为。如果启用了 sql_generate_invisible_primary_key，则此环境变量会覆盖 createInvisiblePKs:false，从而在所有加载的表上启用不可见私钥。

如果启用了 MySQL Shell 加载实用程序选项 createInvisiblePKs，但禁用了 GIPK 服务器选项 sql_generate_invisible_primary_key，则 MySQL Shell 会尝试启用 sql_generate_invisible_primary_key。如果用户对目标 MySQL 服务器具有适当的权限，则会启用 sql_generate_invisible_primary_key，并且加载实用程序会使用服务器的 GIPK 模式在加载的表上创建不可见主键。如果用户没有所需的权限（例如，在 HeatWave Service 上），则 MySQL Shell 会回退到以前的行为，并在不使用服务器的 GIPK 模式的情况下在表上创建主键。

修改转储的数据

MySQL Shell 的并行表导入实用程序 util.importTable() 可以与转储加载实用程序 util.loadDump() 结合使用，以便在将数据上传到目标 MySQL 实例之前修改分块输出文件中的数据。您可以使用此方法一次修改一个表的数据。

将转储加载实用程序与 loadDdl: true 和 loadData: false 选项一起使用，仅加载 DDL 文件，并在目标 MySQL 实例上创建所选表，但不加载数据。
```
shell-js> util.loadDump("/mnt/data/proddump", { 
        > includeTables: ["product.pricing"], 
        > loadDdl: true, 
        > loadData: false});
```
使用并行表导入实用程序捕获和转换表的数据，并将其导入到目标 MySQL 实例上的空表中。在本例中，pricing 表的数据位于多个压缩文件中，这些文件使用通配符模式匹配进行指定。转储文件中 id 和 prodname 列中的值将原封不动地分配给目标表中的相同列。转储文件中 price 列中的值将被捕获并分配给变量 @1。然后，使用 decodeColumns 选项按标准金额降低价格，并将降低后的价格放入目标表的 price 列中。
```
shell-js> util.importTable ("/mnt/data/proddump/product@pricing@*.zst", {   
        > schema: "product",  
        > table: "pricing",  
        > columns: ["id",  "prodname",  1],
        > decodeColumns: { "price": "0.8 * @1"}});
```
根据需要对转储文件中需要修改数据的任何其他表重复步骤 1 和 2。
上传完所有需要修改的表和数据后，使用转储加载实用程序加载任何不需要修改的剩余表的 DDL 和数据。请务必排除您在先前步骤中修改过的表。
```
shell-js> util.loadDump("/mnt/data/proddump", {excludeTables: ["product.pricing"]});
```

实用程序错误消息

53000-53999 范围内的错误号特定于 MySQL Shell 的转储加载实用程序 util.loadDump()。可能会返回以下错误

错误号：53000；符号：SHERR_LOAD_MANIFEST_EXPIRED_PARS

消息：清单文件中的 PAR 已过期，到期时间设置为：%s
错误号：53001；符号：SHERR_LOAD_MANIFEST_PAR_MISMATCH

消息：提供的 PAR 必须是转储位置上的文件：'%s'
错误号：53002；符号：SHERR_LOAD_SPLITTING_DDL_FAILED

消息：拆分表 %s 的 DDL 脚本时出错：%s
错误号：53003；符号：SHERR_LOAD_SECONDARY_ENGINE_ERROR

消息：表 %s 设置了辅助引擎，但并非所有索引都已重新创建
错误号：53004；符号：SHERR_LOAD_FAILED_TO_DISABLE_BINLOG

消息：'SET sql_log_bin=0' 失败，错误：%s
错误号：53005；符号：SHERR_LOAD_WORKER_THREAD_FATAL_ERROR

消息：加载转储时出错
错误号：53006；符号：SHERR_LOAD_UNSUPPORTED_DUMP_VERSION

消息：不支持的转储版本
错误号：53007；符号：SHERR_LOAD_UNSUPPORTED_DUMP_CAPABILITIES

消息：不支持的转储功能
错误号：53008；符号：SHERR_LOAD_INCOMPLETE_DUMP

消息：转储不完整
错误号：53009；符号：SHERR_LOAD_UNSUPPORTED_SERVER_VERSION

消息：仅 MySQL 5.7 或更高版本支持加载转储
错误号：53010；符号：SHERR_LOAD_DUMP_NOT_MDS_COMPATIBLE

消息：转储与 MDS 不兼容
错误号：53011；符号：SHERR_LOAD_SERVER_VERSION_MISMATCH

消息：MySQL 版本不匹配
错误号：53012；符号：SHERR_LOAD_UPDATE_GTID_GR_IS_RUNNING

消息：updateGtidSet 选项不能在运行组复制的服务器上使用。
错误号：53013；符号：SHERR_LOAD_UPDATE_GTID_APPEND_NOT_SUPPORTED

消息：目标 MySQL 服务器不支持 updateGtidSet:'append'。
错误号：53014；符号：SHERR_LOAD_UPDATE_GTID_REQUIRES_SKIP_BINLOG

消息：仅当启用了 skipBinlog 选项时，才能在 MySQL 5.7 目标服务器上使用 updateGtidSet 选项。
错误号：53015；符号：SHERR_LOAD_UPDATE_GTID_REPLACE_REQUIRES_EMPTY_VARIABLES

消息：仅当 GTID_PURGED 和 GTID_EXECUTED 为空时，才能在目标服务器版本上使用 updateGtidSet:'replace' 选项，但它们不是。
错误号：53016；符号：SHERR_LOAD_UPDATE_GTID_REPLACE_SETS_INTERSECT

消息：仅当目标服务器上的 gtid_subtract(gtid_executed,gtid_purged) 与转储的 GTID 集不相交时，才能使用 updateGtidSet:'replace' 选项。
错误号：53017；符号：SHERR_LOAD_UPDATE_GTID_REPLACE_REQUIRES_SUPERSET

消息：仅当转储的 GTID 集是目标服务器上 gtid_purged 当前值的超集时，才能使用 updateGtidSet:'replace' 选项。
错误号：53018；符号：SHERR_LOAD_UPDATE_GTID_APPEND_SETS_INTERSECT

消息：仅当目标服务器上的 gtid_executed 与转储的 GTID 集不相交时，才能使用 updateGtidSet:'append' 选项。
错误号：53019；符号：SHERR_LOAD_INVISIBLE_PKS_UNSUPPORTED_SERVER_VERSION

消息：'createInvisiblePKs' 选项需要服务器 8.0.24 或更高版本。
错误号：53020；符号：SHERR_LOAD_REQUIRE_PRIMARY_KEY_ENABLED

消息：在目标服务器上启用了 sql_require_primary_key
错误号：53021；符号：SHERR_LOAD_DUPLICATE_OBJECTS_FOUND

消息：在目标数据库中找到重复的对象
错误号：53022；符号：SHERR_LOAD_DUMP_WAIT_TIMEOUT

消息：转储超时
错误号：53023；符号：SHERR_LOAD_INVALID_METADATA_FILE

消息：无效的元数据文件 %s
错误号：53024；符号：SHERR_LOAD_PARSING_METADATA_FILE_FAILED

消息：无法解析元数据文件 %s：%s
错误号：53025；符号：SHERR_LOAD_LOCAL_INFILE_DISABLED

消息：服务器中禁用了 local_infile
错误号：53026；符号：SHERR_LOAD_PROGRESS_FILE_ERROR

消息：加载加载进度文件“%s”时出错：%s
错误号：53027；符号：SHERR_LOAD_PROGRESS_FILE_UUID_MISMATCH

消息：进度文件是为 UUID 为 %s 的服务器创建的，而目标服务器的 UUID 为：%s
错误号：53028；符号：SHERR_LOAD_MANIFEST_UNKNOWN_OBJECT

消息：清单中的未知对象：%s

54000-54999 范围内的错误号是针对 MySQL Shell 的转储加载实用程序 util.loadDump() 或 MySQL Shell 的实例转储实用程序 util.dumpInstance()、架构转储实用程序 util.dumpSchemas() 和表转储实用程序 util.dumpTables() 遇到的连接和网络错误。在大多数情况下，错误代码与所涉及的 HTTP 错误相匹配，例如，当找不到 URL 的目标时，会发生错误 54404（HTTP 404 未找到）。可能会返回以下错误

错误号：54000；符号：SHERR_DL_COMMON_CONNECTION_ERROR

消息：%s连接错误：%s。
错误号：54100 至 54511；符号：SHERR_NETWORK_[HTTP 错误名称]

消息：特定于上下文的错误消息