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

11.6 转储加载实用程序

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

关于实用程序

要导入到 HeatWave Service DB System 中，必须在可以访问 HeatWave Service DB System 的 Oracle Cloud Infrastructure Compute 实例上安装 MySQL Shell。如果转储文件位于 Oracle Cloud Infrastructure 对象存储桶中，则可以从 Compute 实例访问该对象存储桶。如果转储文件位于本地系统上，则需要使用您选择的复制实用程序（具体取决于您为 Compute 实例选择的操作系统）将它们传输到 Oracle Cloud Infrastructure Compute 实例。确保转储是在 MySQL Shell 的实例转储实用程序或架构转储实用程序中设置了 ocimds 选项（设置为 true）的情况下创建的，以便与 HeatWave Service 兼容。MySQL Shell 的表转储实用程序不使用此选项。

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

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

对于 MySQL Shell 的表转储实用程序生成的输出，转储包含设置最初包含该表的架构所需的信息。默认情况下，从该版本开始，如果目标 MySQL 实例中尚不存在该架构，则会在其中重新创建该架构。或者，您可以在转储加载实用程序中指定 schema 选项，将表加载到目标 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 DB System 上不可用。有关更多信息，请参阅禁用重做日志记录。

要求和限制

  • 加载转储的目标 MySQL 实例需要 MySQL 5.7 或更高版本。

  • MySQL Shell 8.0.27 之前的版本的转储加载实用程序无法加载使用 MySQL Shell 8.0.27 或更高版本中的转储实用程序创建的转储。这是因为从 MySQL Shell 8.0.27 开始，转储元数据中包含有关创建转储时使用的功能的信息。此功能列表不向后兼容，但它支持将来版本中添加新功能时的向后兼容性。为了获得最佳功能，请始终使用最新版本的 MySQL Shell 转储和转储加载实用程序。

  • 转储加载实用程序使用 LOAD DATA LOCAL INFILE 语句，因此在导入期间，目标 MySQL 实例上 local_infile 系统变量的全局设置必须为 ON。默认情况下，在标准 HeatWave Service DB System 配置中，此系统变量设置为 ON。

  • LOAD DATA LOCAL INFILE 语句使用非限制性数据解释，它会将错误转换为警告并继续加载操作。此过程可以包括为字段分配默认值和隐式默认值，以及将无效值转换为列数据类型的最接近有效值。有关该语句行为的详细信息，请参阅 LOAD DATA。

  • 在目标 MySQL 实例上，转储加载实用程序会检查 sql_require_primary_key 系统变量是否设置为 ON，如果是，则在转储文件中存在没有主键的表时返回错误。默认情况下，此系统变量在标准 HeatWave Service DB 系统配置中设置为 OFF。

  • 转储加载实用程序不会自动将源 MySQL 实例上的 gtid_executed GTID 集应用于目标 MySQL 实例。GTID 集包含在 MySQL Shell 的实例转储实用程序、架构转储实用程序或表转储实用程序的转储元数据中，作为 @.json 转储文件中的 gtidExecuted 字段。要在目标 MySQL 实例上应用这些 GTID 以用于复制，请使用 updateGtidSet 选项或手动导入它们，具体取决于目标 MySQL 实例的版本和 MySQL Shell 版本。HeatWave Service DB 系统实例也支持此功能。有关详细信息，请参阅 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 计算实例的文件系统中，则 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 模式的此示例中，将前缀为 worlddump 的转储使用 8 个线程从对象存储桶加载到连接的 HeatWave Service DB 系统中：

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 系统，不使用此选项，如果您尝试将其设置为 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 Service 实例。

handleGrantErrors: abort|drop_account|ignore

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

  • abort：（默认）停止加载过程并显示错误。

  • drop_account：删除帐户并继续加载过程。

  • ignore：忽略错误并继续加载过程。

characterSet: "string"

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

maxBytesPerTransaction: number

在单个 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 服务器的并行索引创建功能。以前，转储加载实用程序会按顺序添加索引，一次添加一个。从此版本开始，表中的所有索引将同时添加。

有关限制和配置，请参阅 为联机 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 Service 数据库系统实例也支持此功能。有关详细信息，请参阅 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 高可用性 DB System，因为该功能目前要求主键同时存在于源服务器和副本服务器中。如果可能，请考虑在再次转储之前在源服务器上的表中创建主键，而不是使用此选项。从 MySQL 8.0.23 开始，您可以通过使用不可见列来保存主键来做到这一点，而不会对应用程序产生影响。这是提高性能和可用性的最佳实践，并且有助于转储的数据库与 HeatWave Service 无缝协作。

适用于 HeatWave Service 和 Oracle Cloud Infrastructure 的选项

osBucketName: "字符串"

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

osNamespace: "字符串"

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

ociConfigFile: "字符串"

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

ociProfile: "字符串"

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

适用于与 S3 兼容的服务的选项

MySQL Shell 支持加载存储在与 S3 兼容的存储桶中的转储，例如 Amazon Web Services (AWS) S3。

注意

MySQL Shell 支持在命令行选项、环境变量和配置文件中配置 AWS S3。命令行选项优先于环境变量、配置文件和默认选项。

有关配置要求的信息，请参阅 第 4.7 节“云服务配置”。

s3BucketName: "字符串"

转储文件所在的 S3 存储桶的名称。默认情况下，将使用位于 ~/.aws/ 的 Amazon Web Services (AWS) CLI config 和 credentials 文件中的 default 配置文件来建立与 S3 存储桶的连接。您可以使用 s3ConfigFile 和 s3CredentialsFile 选项替换用于连接的备用配置和凭据。有关安装和配置 AWS CLI 的说明，请参阅 AWS CLI 入门。

s3CredentialsFile: "字符串"

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

s3ConfigFile: "字符串"

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

s3Profile: "字符串"

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

s3Region: "字符串"

要用于连接的区域的名称。

s3EndpointOverride: "字符串"

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

连接到 Oracle Cloud Infrastructure S3 兼容性 API 时，端点的格式如下：https://命名空间.compat.objectstorage.区域.oraclecloud.com。将 命名空间 替换为对象存储命名空间，并将 区域 替换为您的区域标识符。例如，美国东部（阿什本）区域的区域标识符为 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: "字符串"

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

azureConfigFile: "字符串"

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

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

azureStorageAccount: "字符串"

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

azureStorageSasToken: "字符串"

可选。要用于操作身份验证的 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 System 的用户帐户，或者目标 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: 字符串数组

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

includeTriggers: 字符串数组

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

生成的不可见主键模式

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 实例之前修改分块输出文件中的数据。您可以使用此方法一次修改一个表的数据。

  1. 将转储加载实用程序与 loadDdl: true 和 loadData: false 选项一起使用，仅加载 DDL 文件，并在目标 MySQL 实例上创建所选表，不包含数据。

    shell-js> util.loadDump("/mnt/data/proddump", { 
        > includeTables: ["product.pricing"], 
        > loadDdl: true, 
        > loadData: false});

  2. 使用并行表导入实用程序捕获和转换表的数据，并将其导入到目标 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"}});

  3. 根据需要，对转储文件中需要修改数据的任何其他表重复步骤 1 和 2。

  4. 完成上传所有需要修改的表和数据后，使用转储加载实用程序加载不需要修改的任何剩余表的 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 错误名称]

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


上一页   首页   上一级   下一页
下载本手册
PDF (US Ltr) - 2.2Mb
PDF (A4) - 2.3Mb