诊断从 PostgreSQL 迁移到 AlloyDB for PostgreSQL 期间出现的问题

迁移作业过程在运行时可能会发生错误。

• 某些错误（例如源数据库上的密码错误）是可恢复的，这意味着这些错误可以修复，并且迁移作业会自动恢复。
• 有些错误是不可恢复的，例如数据损坏或架构不兼容，这意味着需要从头开始重启迁移作业。

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

如需排查错误，请前往失败的迁移作业查看错误，并按照错误消息中所述的步骤操作。

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

下表列出了常见问题及其解决方案：

针对此问题…	可能的原因…	请尝试以下操作…
当您迁移到现有目标集群时，会收到以下出错提示： The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job.	您的 AlloyDB for PostgreSQL 目标集群包含额外用户数据。您只能迁移到空的现有集群。请参阅 已知限制。	请从目标集群中清除冲突或多余的数据，然后重试迁移作业。请参阅从现有目标集群中清除多余数据。
无法连接到源数据库实例。	源数据库实例与目标 AlloyDB for PostgreSQL 集群之间存在连接问题。	按照调试连接中的步骤操作。
由于源数据库版本和目标数据库版本不兼容，迁移作业运行失败。	来源数据库版本和目标数据库版本不是受支持的组合。具体而言，提供的源数据库版本与目标数据库版本不兼容。	确保目标数据库版本与源数据库版本相同，或为受支持的更高主要版本。然后，创建新的迁移作业。
源数据库上屏蔽了数据定义语言 (DDL) 或数据操纵语言 (DML)。	在完整转储阶段运行且需要 ACCESS EXCLUSIVE 锁的 DDL 会被屏蔽。	在初始同步过程（完整转储）中，应避免在表上执行需要 ACCESS EXCLUSIVE 锁的 DDL 或程序，例如 ALTER TABLE 或 DROP TABLE。否则，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。请参阅 WAL 级别配置。
出错提示：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 RDS，使用独立根证书（而非证书包）可能会导致此问题。	创建一个组合源 CA 证书，其中包含根证书和所有必需的中间证书。 对于 Amazon RDS 来源，请使用包含中间证书和根证书的证书捆绑包。如需了解详情，请参阅 Amazon RDS 文档中的下载证书包。
出错提示：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 软件包未在源实例上正确安装。	如需详细了解如何正确安装此软件包，请参阅配置源数据库。
出错提示：Cannot assign TransactionIds during recovery.	配置的来源处于恢复模式。	请配置一个不处于恢复模式的来源。
完全转储速度缓慢。	AlloyDB for PostgreSQL 目标集群主实例从源数据库导入大量数据的速度可能较慢。	为目标 AlloyDB for PostgreSQL 主实例选择更高的机器层级，以获得最大可用网络带宽和 CPU 容量。 调整目标的 max_wal_size 标志。通常，将此标志设置为 32 GB 或 64 GB 是一个不错的值。更新此标志不需要重启数据库服务器。
出错提示：subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again	迁移作业在完全转储阶段失败，且无法恢复。源数据库实例已重启或处于恢复模式，或者由于为 wal_sender_timeout 参数设置的值不足，复制连接已结束。 如需找出问题的根本原因，请执行以下操作： 前往 Google Cloud 控制台中的 Logs Explorer 页面。 从资源列表中，选择您的 AlloyDB for PostgreSQL 实例。系统会显示该实例的最新日志列表。 从日志文件名中选择 postgres.log。 将日志的严重级别设置为 Warning 以上的所有级别。第一个错误日志可能是导致失败的根本原因。	确保在完整转储阶段，Database Migration Service 始终可以连接到源数据库实例。 检查源数据库实例上的 wal_sender_timeout 参数值是否设置为较大的数字（例如 0）。 重启迁移作业，然后重试。
出错提示：ERROR: unknown column name {column_name}	已向主节点上的复制表添加列，但未向副本节点上的复制表添加列。	在持续迁移期间，系统只会自动更新数据操纵语言 (DML) 更改。您必须管理数据定义语言 (DDL) 更改，以确保源数据库和目标数据库保持兼容。您可以通过以下两种方式实现此目的： 停止对源数据库执行写入操作，并在源数据库和目标数据库上运行 DDL 命令。在目标数据库上运行 DDL 命令之前，请向应用 DDL 更改的 AlloyDB for PostgreSQL 用户授予 alloydbexternalsync 角色。 使用 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 参数设置的值不足，复制连接已结束。此错误通常发生在初始转储成功后的复制阶段。	请考虑增加 wal_sender_timeout 参数值，或在源数据库实例上将其值设置为 0，以停用超时机制。
警告消息：migration job test configuration has returned the following warnings: Some table(s) have limited support.	来源包含支持有限的表，例如没有主键的表。	这是一条警告消息。您可以继续迁移，但请注意，在标准迁移中，没有主键的表在变更数据捕获 (CDC) 阶段仅复制初始快照和 INSERT 语句；UPDATE 和 DELETE 语句不会复制。如需了解详情，请参阅配置源数据库。
如果您迁移所选数据库，但迁移作业无法将数据复制到一个或多个数据库，则数据库列表中会显示失败状态。	各种迁移作业错误。	在错误列中，点击查看错误并修正错误。您还可以从迁移作业中移除失败的数据库。 如需详细了解如何从迁移作业中移除失败的数据库，请参阅管理迁移作业。

---

从现有目标集群中清除多余数据

当您迁移到现有目标集群时，会收到以下出错提示： The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job.

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

可以尝试的操作

请执行以下步骤，清除目标集群中的冲突数据或额外数据，然后重新启动迁移作业：

1. 停止迁移作业。
2. 使用 psql 或 AlloyDB Studio 连接到 AlloyDB for PostgreSQL 目标集群主实例。
3. 从目标集群数据库中移除额外数据。目标只能包含系统配置数据。目标数据库不能包含用户数据（例如用户定义的表或例程）。您可以在数据库上运行不同的 SQL 语句来查找非系统数据：

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

   SELECT datname FROM pg_catalog.pg_database
   WHERE datname NOT IN ('alloydbadmin', '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 NOT IN ('plpgsql', 'alloydb_utility');
       

4. 删除上一步中确定的所有非系统数据库、用户表和用户定义的函数。
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.

可能的原因

提升 AlloyDB for PostgreSQL 目标集群时，如果无法从 AlloyDB for PostgreSQL 集群访问源实例（例如，源实例未运行，或者您从源实例的许可清单中移除了 AlloyDB for PostgreSQL 集群），则在提升迁移作业期间无法清理复制所需的设置。您必须手动清理复制槽。

可以尝试的操作

对于每个数据库，以具有 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 '%alloydb%' AND active = 'f';

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

   SELECT pglogical.drop_node(node_name) FROM pglogical.node WHERE node_name LIKE '%alloydb%';

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

   DROP EXTENSION IF EXISTS pglogical;

---

出错提示：Cannot connect to invalid database

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

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

可能的原因

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

可以尝试的操作

使用新的目标集群再次执行迁移作业

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

1. 删除失败的迁移作业。 请参阅审核迁移作业。
2. 删除您遇到问题的目标集群。 请参阅 AlloyDB 集群管理。
3. 重新创建迁移作业。 请参阅创建迁移作业。

迁移到中间版本

请考虑迁移到更早的 PostgreSQL 版本，例如 PostgreSQL 14。成功迁移后，您可以升级到所需的 PostgreSQL 15 实例。请参阅 AlloyDB for PostgreSQL 文档中的升级数据库主要版本。

---

删除处于引导模式的孤立 AlloyDB for PostgreSQL 集群

在极少数极端情况下，您可能会发现迁移作业已被删除，但关联的 AlloyDB for PostgreSQL 集群未被删除，并且仍处于引导模式。您可以使用 gcloud alloydb clusters delete 命令和 --force 选项删除集群：

gcloud alloydb clusters delete CLUSTER_ID \
    --region=REGION_ID \
    --force

请注意，在活跃迁移作业使用引导集群时删除该集群会导致未定义的行为。

---

管理用户和角色

迁移现有用户

目前，Database Migration Service 不支持将现有用户和角色从源实例自动迁移到目标 AlloyDB for PostgreSQL 集群。您可以通过在 AlloyDB for PostgreSQL 中手动创建用户来管理此迁移。

关于 alloydbexternalsync 用户

在标准迁移期间，AlloyDB for PostgreSQL 副本上的所有数据库对象都归 alloydbexternalsync 用户所有（快速启动迁移使用 postgres 用户）。数据迁移完毕且迁移作业提升后，您可以完成以下步骤，将对象的所有权修改为其他应用用户：

• 运行 GRANT alloydbexternalsync TO USER; 命令。
• 在每个数据库上，运行 REASSIGN OWNED BY alloydbexternalsync TO USER; 命令。
• 如需移除 alloydbexternalsync 用户，请运行 DROP ROLE alloydbexternalsync; 命令。