诊断迁移到 Cloud SQL for PostgreSQL 的单一数据库迁移问题

迁移作业流程在运行时可能会出错。

  • 某些错误（例如源数据库上的密码错误）可以恢复，这意味着它们可以得到修复，并且迁移作业会自动恢复。
  • 某些错误无法恢复，例如数据复制错误，这意味着需要从头开始重启迁移作业。

发生错误时，迁移作业状态会更改为 Failed，并且子状态会反映失败前的最后状态。

如需排查错误，请前往失败的迁移作业以查看错误，然后按照错误消息中列出的步骤操作。

如需查看有关该错误的更多详细信息，请使用迁移作业中的链接前往 Cloud Monitoring。日志会过滤到特定的迁移作业。

在下表中，您可以查看一些问题示例以及解决方法：

针对此问题… 可能的原因… 请尝试以下操作…
迁移到 现有目标实例时，您收到以下错误消息： The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job. 目标 Cloud SQL 实例包含额外的数据。您只能迁移到空的现有实例。请参阅 已知限制。 将目标实例升级为读写实例，移除多余的数据，然后重试迁移作业。请参阅 清除现有目标实例中的额外数据。
未能连接到源数据库实例。 源数据库实例和目标实例之间存在连接问题。 请按照调试连接性中的步骤操作。
由于源数据库和目标数据库版本不兼容，迁移作业运行失败。 源数据库版本和目标数据库版本不受支持。具体而言，提供的源数据库版本与目标数据库版本不兼容。 确保目标数据库版本与源数据库版本相同或比源数据库版本高一个主要版本。然后，创建新的迁移作业。
源端阻止了数据定义语言 (DDL) 或数据操纵语言 (DML)。 需要 ACCESS EXCLUSIVE 锁定且在完整转储阶段运行的 DDL 会被阻止。

在初始同步过程（完全转储）期间，应避免对表执行需要 ACCESS EXCLUSIVE 锁（例如 ALTER TABLE 或 DROP TABLE）的 DDL 或程序。否则，DDL 或程序将等待初始同步完成。

例如，如果某个表仍处于初始同步过程中，并且对同一表执行了 ALTER TABLE 命令，则该命令将不会运行，并且在初始同步完成之前，后续的 DDL 和 DML 命令将被阻止。
错误消息：No pglogical extension installed on databases (X) 一个或多个源数据库未安装 pglogical。 请按照这些准则在源实例的数据库上安装 pglogical。
迁移到 PostgreSQL 版本 15 后，在多次后续连接重试后，会出现以下某种症状：
  • 您收到 Cannot connect to invalid database 错误消息。
  • 在迁移作业执行数据库完整转储时，存储用量迁移作业指标在很长一段时间后仍未显示任何进度。
此问题通常归因于 pglogical 扩展程序中的死锁问题。如需了解详情，请参阅 GitHub 中的 pglogical 问题跟踪器。 请重试迁移作业，或先迁移到中间 PostgreSQL 版本。如需了解更多详情，请参阅 错误消息：Cannot connect to invalid database。
错误消息：Replication user 'x' doesn't have sufficient privileges. 使用 Database Migration Service 的用户没有执行指定操作所需的权限。 请遵循这些准则，确保此用户拥有所需的权限。
错误消息：Unable to connect to source database server. Database Migration Service 无法与源数据库服务器建立连接。 确保源数据库实例和目标数据库实例可以相互通信，并且您已完成为迁移作业定义设置时显示的所有必要前提条件。
错误消息：The source database 'wal_level' configuration must be equal to 'logical'. 源数据库的 wal_level 设置为 logical 以外的值。 将 wal_level 设置为 logical。
错误消息：The source database 'max_replication_slots' configuration is not sufficient. max_replication_slots 参数未正确配置。 请遵循这些准则正确设置此参数。
错误消息：The source database 'max_wal_senders' configuration is not sufficient. max_wal_senders 参数未正确配置。 请遵循这些准则正确设置此参数。
错误消息：The source database 'max_worker_processes' configuration is not sufficient. max_worker_processes 参数未正确配置。 请遵循这些准则正确设置此参数。

错误消息：Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.

或

错误消息：Error promoting EM replica: finished drop replication with errors.

在迁移作业升级期间，无法清理复制所需的设置。

对于每个数据库，请以具有 superuser 权限的用户身份运行命令。

如需详细了解要运行哪些命令，请参阅清理复制槽。

错误消息：x509 certificate signed by unknown authority.

提供给 Database Migration Service 的源 CA 证书可能仅包含根证书。不过，来源证书需要同时提供根证书和任何中间证书。

例如，对于 Amazon Relational Database Service，使用 rds-ca-2019-root.pem 证书可能会导致此问题。

创建一个包含根证书和所有所需中间证书的组合来源 CA 证书。

对于 Amazon Relational Database Service 用例，请使用 rds-combined-ca-bundle.pem 证书，而不是 rds-ca-2019-root.pem 证书。

错误消息：ERROR: Out of shared memory HINT: You might need to increase max_locks_per_transaction.

为 max_locks_per_transaction 参数设置的值不足。 将此参数的值设置为至少为 {max_number_of_tables_per_database}/(max_connections + max_prepared_transactions)。

错误消息：ERROR: no data left in message.

pglogical 软件包未在源实例上正确安装。 如需详细了解如何正确安装此软件包，请参阅在源实例上安装 pglogical 软件包。

错误消息：Cannot assign TransactionIds during recovery.

已配置的来源处于恢复模式。 配置未处于恢复模式的来源。
完整转储速度缓慢。 Cloud SQL 目标数据库从源数据库导入大量数据的速度可能会很慢。
  • 创建目标位置时，请将数据磁盘大小设置为接近最终大小。完整转储阶段使用的是 I/O 写入密集型工作负载，磁盘越大，I/O 性能就越好。如需了解详情，请参阅块存储性能。
  • 为 Cloud SQL 目标位置选择更高层级，以获得最大可用网络和磁盘带宽。
  • 调整 Cloud SQL 目标的 max_wal_size 标志。通常，32 GB 或 64 GB 是适合为此标志设置的值。更新此标志不需要重启服务器。
错误消息：subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

迁移作业在完全转储阶段失败，且无法恢复。源数据库实例已重启或处于恢复模式，或者由于为 wal_sender_timeout 参数设置的值不足，复制连接已结束。

如需查找问题的根本原因，请执行以下操作：

  1. 前往 Google Cloud 控制台中的日志浏览器页面。
  2. 从资源列表中选择您的 Cloud SQL 副本。系统会显示副本的最新日志列表。
  3. 从日志文件名称中，选择 postgres.log。
  4. 将日志的严重级别设置为高于 Warning 的所有级别。第一个错误日志可能是失败的根本原因。
  • 确保 Database Migration Service 在完整转储阶段始终可以连接到源数据库实例。
  • 检查 wal_sender_timeout 参数的值是否在来源数据库实例上设置为较大的数字（例如 0）。
  • 请重启迁移作业，然后重试。
错误消息：ERROR: unknown column name {column_name}

在主节点上的已复制表中添加了列，但在副本节点上未添加。

在持续迁移期间，只有数据操纵语言 (DML) 更改会自动更新。管理数据定义语言 (DDL) 更改，以确保源数据库和目标数据库保持兼容，是用户的责任，可通过两种方式来实现：

  • 停止写入源数据库，并在源数据库和目标数据库中运行 DDL 命令。在目标数据库上运行 DDL 命令之前，向进行 DDL 更改的 Cloud SQL 用户授予 cloudsqlexternalsync 角色。
  • 使用 pglogical.replicate_ddl_command，可允许 DDL 命令在源数据库和目标数据库上同时运行。运行这些命令的用户在源端和目标端必须使用相同的用户名，并且应是超级用户或要迁移的工件（例如表、序列、视图或数据库）的所有者。

    • 如需查看使用 pglogical.replicate_ddl_command. 的示例，请参阅持续迁移
错误消息：ERROR: cannot truncate a table referenced in a foreign key constraint

用户尝试截断具有外键约束条件的表。

请先移除外键约束条件，然后截断表。
错误消息：ERROR: connection to other side has died

由于为 wal_sender_timeout parameter 设置的值不足，复制连接已终止。此错误通常会在初始转储成功后复制阶段发生。

不妨考虑在源数据库实例上将 wal_sender_timeout 参数值设置为 0，以增加该参数值或停用超时机制。
警告消息：migration job test configuration has returned the following warnings: Some table(s) have limited support.

源数据库中存在受支持有限的表，例如没有主键的表。

这是一条警告消息。您可以继续进行迁移，但请注意，系统不会迁移不受支持的实体（例如没有主键的表）。如需了解详情，请参阅 配置源数据库。

从现有目标实例中清除额外数据

迁移到 现有目标实例时，您收到以下错误消息：The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job.

如果您的目标实例包含额外数据，就可能会出现此问题。您只能迁移到空的现有实例。请参阅 已知限制。

可以尝试的操作

请执行以下步骤，从目标实例中清除额外数据，然后重新启动迁移作业：

  1. 停止迁移作业。
  2. 此时，目标 Cloud SQL 实例处于“只读”模式。 提升目标实例以获得写入权限。
  3. 连接到目标 Cloud SQL 实例。
  4. 从目标实例数据库中移除多余数据。目标位置只能包含系统配置数据。目标数据库不得包含用户数据（例如表）。您可以在数据库上运行不同的 SQL 语句来查找非系统数据，例如：

    用于检索非系统数据库的 SQL 语句示例（点击展开）

    SELECT datname FROM pg_catalog.pg_database
WHERE datname NOT IN ('cloudsqladmin', 'template1', 'template0', 'postgres');

    用于检索 postgres 数据库中非系统数据的 SQL 语句示例（点击可展开）

    postgres 数据库是系统数据库，但可以包含非系统数据。请务必在 postgres 数据库上运行这些语句。如果您使用 psql 客户端连接到目标实例，则可以使用 \connect {database_name_here} 命令切换到其他数据库，而无需重置连接。

    SELECT table_schema, table_name FROM information_schema.tables
WHERE table_schema != 'information_schema' AND table_schema not like 'pg\_%';

SELECT routine_schema, routine_name FROM information_schema.routines
WHERE routine_schema != 'information_schema' AND routine_schema not like 'pg\_%';

SELECT extname FROM pg_extension WHERE extname != 'plpgsql';
  5. 启动迁移作业。

清理复制槽

您会看到以下某条消息：

  • Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.
  • Error promoting EM replica: finished drop replication with errors.

可能的原因

在提升 Cloud SQL 实例的优先级时，如果 Cloud SQL 实例无法访问源实例（例如，源实例未运行，或者您已将 Cloud SQL 实例从源实例的许可名单中移除），则在提升迁移作业的优先级期间，系统无法清理复制所需的设置。您必须手动清理复制槽。

可以尝试的操作

对于每个数据库，请以具有 superuser 权限的用户身份运行以下命令：

  1. 从错误消息中获取复制槽名称，然后运行以下命令逐个删除槽：

    select pg_drop_replication_slot({slot_name});

  2. 如果错误消息中未显示复制槽名称，请运行以下命令查询现有复制槽：

    select pg_drop_replication_slot(slot_name) from pg_replication_slots where slot_name like '%cloudsql%' and active = 'f';

  3. 如果没有使用源实例的 Cloud SQL 副本，请运行以下命令来清理 pglogical 设置：

    select pglogical.drop_node(node_name) from pglogical.node where node_name like 'cloudsql';

  4. 如果不再需要 pglogical 扩展程序，请运行以下命令卸载该扩展程序：

    DROP EXTENSION IF EXISTS pglogical;

错误消息：Cannot connect to invalid database

迁移到 PostgreSQL 版本 15 后，在多次后续连接重试尝试后，会出现以下某种症状：

  • 您收到 Cannot connect to invalid database 错误消息。
  • 在迁移作业执行数据库完整转储时，存储用量迁移作业指标在很长一段时间后仍未显示任何进度。

可能的原因

此问题通常归因于 pglogical 扩展程序中的死锁问题。如需了解详情，请参阅 GitHub 中的 pglogical 问题跟踪器。

可以尝试的操作

使用新的目标实例再次执行迁移作业

请尝试删除出现问题的目标数据库，然后重新创建迁移作业。请按以下步骤操作：

  1. 删除您遇到问题的目标实例。 请参阅 Cloud SQL for PostgreSQL 文档中的删除实例。
  2. 删除失败的迁移作业。 请参阅 审核迁移作业。
  3. 重新创建迁移作业。 请参阅 创建迁移作业。

迁移到中间版本

考虑迁移到较低的 PostgreSQL 版本，例如 PostgreSQL 14。迁移成功后，您可以尝试升级到所需的 PostgreSQL 15 实例。请参阅 Cloud SQL for PostgreSQL 文档中的通过迁移数据升级数据库主要版本。

管理用户和角色

迁移现有用户

目前，Database Migration Service 不支持将现有用户从源实例迁移到目标 Cloud SQL 实例。您可以通过手动在 Cloud SQL 中创建用户来管理此迁移。

cloudsqlexternalsync 用户简介

在迁移期间，Cloud SQL 副本上的所有对象均归 cloudsqlexternalsync 用户所有。数据迁移完成后，您可以完成以下步骤，将对象的所有权修改为其他用户：

  • 运行 GRANT cloudsqlexternalsync to {USER} 命令。
  • 在每个数据库上，运行 reassign owned by cloudsqlexternalsync to {USER}; 命令。
  • 如需移除 cloudsqlexternalsync 用户，请运行 drop role cloudsqlexternalsync 命令。

将数据导入新的 Cloud SQL 实例

如果您先从 Database Migration Service 迁移到 Cloud Storage 的 Cloud SQL 实例中导出数据，然后再从 Cloud Storage 导入数据到独立 Cloud SQL 实例，导入操作可能会失败，因为目标实例中不存在 cloudsqlexternalsync 用户。

如需缓解此问题，请在目标实例上创建 cloudsqlexternalsync 用户，或从已迁移的实例中移除该用户。