诊断问题

概览

数据流在运行时可能会出错。

  • 某些错误（例如源数据库上的密码错误）可以恢复，这意味着它们可以得到修复，并且数据流会自动恢复。
  • 一些错误可能会影响单个对象，例如包含不受支持的数据类型的事件。其他错误可能会影响多个对象或整个数据流，例如当 Datastream 无法连接到源数据库时。
  • 根据错误情况，Datastream 界面的数据流或数据流详情页面中提供了相关信息。您还可以使用 Datastream 的 API 来检索错误的相关信息。

如需排查错误，请导航到数据流以查看错误，然后按照错误消息中列出的步骤操作。

此页面包含有关配置、连接、Oracle 和 MySQL 错误的信息，以及排查错误的步骤。

配置和连接错误

错误 问题排查步骤
未能连接到源数据库（常规）。

造成这种情况的原因有很多。如需排查此错误，请执行以下操作：

  1. 确保源数据库已启动且可以访问。
  2. 从数据流或连接配置文件页面导航到来源连接配置文件。
  3. 验证连接配置文件连接信息是否正确。
  4. 验证用户名和密码是否匹配。
  5. 验证数据库上是否存在该用户名且是否具有所需权限。
  6. 保存您在连接配置文件页面上所做的任何更改。

数据流会自动恢复。
未能连接到源数据库（IP 许可名单）。 如果所选连接方法为 IP 许可名单，但 Datastream 的一个或多个传出 IP 地址未正确添加到源数据库，则可能会发生此问题。请确保在网络防火墙上配置 Datastream 连接配置文件中显示的传出 IP 地址，以便源数据库服务器可以接受来自这些 IP 地址的连接。解决此问题后，数据流会自动恢复。
未能连接到源数据库（转发 SSH 隧道）。 如果转发 SSH 隧道存在问题，则可能会发生此问题。检查隧道的状态。如果隧道停止，则需要启动它。解决此问题后，数据流会自动恢复。
Datastream 无法通过转发 SSH 隧道连接到堡垒主机。 请验证来源连接配置文件中的转发 SSH 隧道是否配置正确，以及该端口在 SSH 隧道服务器中是否处于开启状态。
由于证书错误，无法连接到源数据库。 如果在定义来源连接配置文件时提供的证书存在问题，则可能会发生此错误。导航到连接配置文件页面，然后选择给定的连接配置文件。验证证书是否已正确设置。进行更改后，保存连接配置文件，随后数据流会自动恢复。
未能使用专用连接来连接到源数据库。
  1. 确保您已满足准备工作中的所有前提条件。

  2. 创建专用连接配置后，验证包含数据库内部 IP 地址的路由是否显示在 VPC 网络对等互连页面的导出的路由标签页中。

    为此，请前往 VPC 网络对等互连页面，然后搜索添加的对等互连（名称为 peering-[UUID]）。您可以在导出的路由标签页中找到该路由。如果此路由不存在，请手动添加它。

  3. Datastream 不会检查与动态对等互连路由重叠的情况。提供与动态路由重叠的子网可能会导致连接问题。因此，我们不建议使用动态路由中的子网。
  4. 请确保正确通告 Datastream IP 地址范围的自定义路由。如果缺少自定义路由，请参阅自定义路由通告指南。
  5. 如果您在连接到源数据库时仍然遇到问题，请参阅设置反向代理。
组织政策 constraints/datastream.disablePublicConnectivity 开启时，不允许使用连接类型 STATIC_SERVICE_IP_CONNECTIVITY。

您为要创建的连接配置文件选择了公共 IP 许可名单或转发 SSH 隧道网络连接方法。但是，Datastream 的禁止使用公共连接方法组织政策已启用。因此，您无法为连接配置文件选择公共连接方法。

如需解决此问题，请选择专用 VPC 对等互连网络连接方法或停用组织政策。

要停用组织政策，请执行以下操作：

  1. 转到 Google Cloud Console 中的组织政策页面。
  2. 选择 Datastream - 禁止使用公共连接方法组织政策。

  3. 点击修改。

  4. 在页面的应用对象部分中，选择自定义。

  5. 在强制执行部分中，选择关闭。

  6. 点击保存。
  7. 返回到要创建的 Oracle 连接配置文件，然后点击创建。
为数据流配置源数据库时，我在要包含的对象列表中找不到要转移的表和架构。

如果您的数据库包含数千个表和架构，则可能会发生这种情况。在 Google Cloud 控制台中配置数据流的来源时，部分数据流可能未包含在要拉取的对象列表中。在选择要包含的对象部分中选择自定义，而不是选择特定架构和表。在对象匹配条件字段中，输入您希望 Datastream 拉取的架构和表。
我使用要包含的对象菜单向数据流中添加了多个表。但是，当我查看数据流详情中的对象标签页时，发现缺少一些表。 请确保其中每个表至少有一个 CDC 更新，以便 Datastream 能够识别更改并自动将这些表添加到数据流中。
使用 Google Cloud 控制台中的要包含的对象菜单时，无法加载对象列表。 如果数据库的架构和表超过 5,000 个，就可能发生这种情况。请使用其他方法指定要包含的对象，或使用 Datastream API。如需了解详情，请参阅配置源数据库。
在流式传输期间被丢弃且未复制到目标位置的事件。

在流式传输期间，Datastream 可能会丢弃不受支持的事件。您可以执行以下操作来解决此问题：

  • 手动触发对整个表的回填。如果舍弃的事件仅是 UPSERT 事件，此方法会正常运行。如果丢弃的事件包含 DELETE 事件，则您需要先在 BigQuery 中截断该表，然后才能执行回填。

    如需了解如何执行回填，请参阅启动回填。

  • 请与 Google 支持团队联系，让他们执行部分回填。仅当您可以使用 SQL WHERE 子句标识丢弃的事件，并且所有事件都不是 DELETE 事件时，才可以这么做。
  • 如果舍弃的事件数量较少或被舍弃事件不重要，则忽略问题。

Oracle 错误

错误 问题排查步骤
补充日志记录在源数据库上配置有误。

如果源数据库上的补充日志记录配置不正确，则提取正在进行的变更数据捕获 (CDC) 数据时可能会出错。验证补充日志记录是否已正确配置。具体来说，确认正在从来源流式传输到目标位置的数据库表已启用补充日志记录功能。数据流会自动恢复。
由于日志位置丢失，无法恢复复制。 当复制过程长时间暂停时，可能会发生此错误，从而导致日志位置丢失。数据流暂停的时长不得接近日志保留期限。重新创建数据流。
日志文件缺失（部分或全部）。

日志文件可能已被删除。Oracle 会尽快完全清除日志文件，除非您指定了最短轮换周期来保留它们。在 Oracle 服务器中，设置日志文件的保留时间。例如，使用 CONFIGURE RETENTION POLICY TO RECOVERY WINDOW OF 4 DAYS; 将日志文件保留至少 4 天。

对于 RDS 部署，请使用 exec rdsadmin.rdsadmin_util.set_configuration('archivelog retention hours',96);
排除列表中有包含列表。 包含列表完全包含在排除列表中，因此 Datastream 从来源拉取的对象列表为空。请修改所选对象，然后重试。
Oracle 数据库的日志记录模式未设置为 ARCHIVELOG。 请更改日志记录模式，然后重试。
Datastream 返回 ORA-00942: table or view does not exist 错误消息，但一切配置正确无误。 这可能是由于 Oracle 服务器上的缓存所致。重新创建数据库用户应该可以解决缓存问题。
当数据流已在运行时，对 Oracle 来源所做的更改不会反映在目标中。 由于 Datastream 会从归档的重做日志文件中读取数据，因此在日志归档之前，对来源所做的更改不会反映在目标位置。如需查看目标位置中的更改，请更改日志归档政策或手动强制切换日志。如需了解详情，请参阅使用 Oracle 数据库重做日志文件。
出现意外的内部错误。 如需了解详情，请与 Google 支持团队联系。

MySQL 错误

错误 问题排查步骤
二进制日志在源数据库上配置错误。

如果源数据库上的 binlog 配置不正确，连续的 MySQL 数据流可能会发生这种情况。如需排查此错误，请执行以下操作：

  1. 验证二进制日志是否配置正确。
  2. 确认 MySQL 数据库的二进制日志格式已设置为 ROW。
  3. 重启数据流。
由于二进制日志位置丢失，无法恢复复制。 当复制过程长时间暂停时，可能会发生此错误，从而导致二进制日志位置丢失。数据流暂停的时长不得接近二进制日志保留期限。重新创建数据流。
由于源数据库和目标版本不兼容，无法运行数据流。

当源数据库未遵循版本支持矩阵时，就可能发生这种情况。如需排查此错误，请执行以下操作：

  1. 确保源数据库遵循矩阵。
  2. 使用更新后的源数据库重新创建数据流。
AWS RDS MySQL 源二进制日志缺失（部分或全部）。 二进制日志可能已被删除。AWS RDS 会尽快完全清除日志文件，除非您指定了最短轮换周期来保留它们。在源 AWS RDS MySQL 实例中，设置二进制日志的保留时间（以小时为单位）。例如，使用 mysql.rds_set_configuration('binlog retention hours', 168); 将二进制日志保留至少 7 天。
排除列表中有包含列表。 包含列表完全包含在排除列表中，因此 Datastream 从来源拉取的对象列表为空。请修改所选对象，然后重试。
Datastream 无法复制 MySQL 数据库。 确保 Datastream 有权复制数据库。
为 MySQL 来源创建连接配置文件时，加密类型菜单中不接受多个 PEM 编码的 SSL 证书。 Datastream 不支持 MySQL 连接配置文件中的 SSL 证书链。仅支持单个 x509 PEM 编码证书。
出现意外的内部错误。 如需了解详情，请与 Google 支持团队联系。

PostgreSQL 错误

错误 问题排查步骤
源数据库的逻辑解码配置不正确。

验证逻辑解码是否已正确配置。请参阅配置源 PostgreSQL 数据库。
复制槽不存在 如果数据库中不存在复制槽，则在提取正在进行的变更数据捕获 (CDC) 数据时可能会出错。验证复制槽是否已正确配置。请参阅配置源 PostgreSQL 数据库。
复制槽配置的插件有误 如果复制槽是使用 pgoutput 以外的插件配置的，则可能会出现此错误。验证复制槽是否已正确配置。如需了解详情，请参阅源 PostgreSQL 数据库。
复制槽在其他进程中处于活跃状态。 当复制槽正被其他进程使用时，可能会发生此错误。复制槽一次只能由一个进程使用。请确保您在除 Datastream 之外的任何其他进程中不使用同一复制槽。
发布内容配置不正确 如果发布内容未配置为公开数据流配置中包含的表，则可能会发生此错误。请验证发布内容配置是否正确。请参阅为数据流配置源数据库的相关信息。
发布内容不存在。 如果数据库中不存在相应发布内容，则可能会发生此错误。请验证发布内容配置是否正确。请参阅配置源 PostgreSQL 数据库。
由于 WAL 文件丢失，无法继续复制。 如果复制过程长时间暂停，从而导致 WAL 文件丢失，就可能会发生此错误。直播不应在接近 WAL 文件保留期限的时段暂停。重新创建数据流。
排除列表中有包含列表。 包含列表完全包含在排除列表中，因此 Datastream 从来源拉取的对象列表为空。请修改所选对象，然后重试。
Datastream 无法复制 PostgreSQL 架构。 请确保 Datastream 有权复制架构。
源数据库上的大型事务会导致数据复制和同步出现问题。 如果您在源数据库中插入、更新或删除大量记录，则复制槽可能会因相应的事件而过载。Datastream 需要时间来读取和处理这些事件。由于 PostgreSQL 复制槽是单线程的，因此系统会延迟处理复制槽中的其他更改（包括对其他表中的数据的更改），直到 Datastream 赶上复制槽中的所有更改为止。
源数据库上的大型事务会导致 CDC 吞吐量低。 Datastream 在 PostgreSQL 中不支持多线程 CDC。为了克服此限制并提高 CDC 吞吐量，您可以将来源拆分为多个数据流，每个数据流都有自己的发布和复制槽。例如，您可能想要为数据库中的最大表创建一个流，为所有其他表创建另一个流，或者为优先级最高的表创建一个流，为其余表创建另一个流。不同用例可能有所不同，因此您需要考虑在特定 CDC 场景中最合理的做法。如需了解如何创建发布内容，请参阅配置源 PostgreSQL 数据库。
丢弃了不受支持的事件数，原因代码为：BIGQUERY_TOO_MANY_PRIMARY_KEYS。 如果表的 PostgreSQL 副本身份设置为 FULL，则 Datastream 会将该表中的所有列视为主键。如果表中的列数超过 16，则违反了 BigQuery CDC 限制并导致错误。如需解决此问题，请完成以下步骤：
  1. 将副本身份更改为 DEFAULT：
    
ALTER TABLE TABLE_NAME REPLICA IDENTITY DEFAULT
    将 TABLE_NAME 替换为您要更改副本身份的表的名称。
  2. 从数据流的要包含的对象列表中移除该表。如需了解详情，请参阅修改有关源数据库的配置信息。
  3. 从 BigQuery 中删除该表。如需了解详情，请参阅删除表。
  4. 在 Datastream 中，通过修改来源配置再次将表添加到数据流中。
出现意外的内部错误。 如需了解详情，请与 Google 支持团队联系。

SQL Server 错误

错误 问题排查步骤
已为数据库“DATABASE_NAME”停用 CDC。

必须为数据库启用变更数据捕获 (CDC)。Datastream 需要对事务日志的直接读取访问权限，以便将实时更改复制到源数据库并获取完整的日志信息。请为数据库启用 CDC，然后重试。

如需了解如何为数据库启用 CDC，请参阅配置 SQL Server 源数据库。
已停用 CDC 的表。

必须为数据流中包含的所有表启用变更数据捕获 (CDC)。Datastream 需要对事务日志的直接读取访问权限，才能将实时更改复制到源表并获取完整日志信息。请为数据流中包含的表启用 CDC，然后重试。

如需了解如何为源表启用 CDC，请参阅配置源 SQL Server 数据库。
缺少权限。 Datastream 缺少从来源读取数据的必要权限。请向用于连接数据库的用户账号授予适当的权限，然后重试。
不支持 SQL Server EDITION_NAME 版本。 Datastream 不支持此 SQL Server 版本。如需详细了解受支持的 SQL Server 版本，请参阅 SQL Server （作为来源）概览。
不支持标准版的 SQL Server 版本 VERSION_NAME。 Datastream 不支持此版本的 SQL Server Standard。如需详细了解受支持的 SQL Server 版本，请参阅 SQL Server （作为来源）概览。

BigQuery 错误

错误 问题排查步骤
BIGQUERY_UNSUPPORTED_PRIMARY_KEY_CHANGE, details: Failed to write to BigQuery due to an unsupported primary key change: adding primary keys to existing tables is not supported. 如果来源中的主键发生更改，则必须在 BigQuery 中删除该表并再次启动回填。这是 BigQuery 的一个限制，因为如果主键不同，则无法保证新事件与现有行正确合并。如需了解详情，请参阅配置 BigQuery 目标位置。