诊断问题

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

  • 某些错误（例如源数据库上的密码错误）可以恢复，这意味着它们可以得到修复，并且数据流会自动恢复。
  • 一些错误可能会影响单个对象，例如包含不受支持的数据类型的事件。其他错误可能会影响多个对象或整个数据流，例如当 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. 在创建专用连接配置后，请验证 VPC 网络对等互连页面的导出的路由标签页中是否显示了包含数据库的内部 IP 地址的路由。

    为此，请前往 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 拉取的架构和表。
我使用要包含的对象菜单向数据流添加了多个表。不过，当我查看数据流详情中的对象标签页时，发现其中缺少一些表格。 确保每个表至少有 1 次 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 错误

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

如果源数据库上的二进制日志配置不正确，则连续 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 编码证书。
从 MySQL 源流式传输时存在较高的延迟时间。

提高 Datastream 从源数据库读取数据的能力：
MySQL CDC 配置验证失败。 您的源数据库未针对您选择的 CDC 方法进行配置。请选择其他方法，或完成 CDC 方法的配置。如需了解详情，请参阅配置源 MySQL 数据库。
出现意外的内部错误。 如需了解详情，请与 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. 将副本 ID 更改为 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 标准版。如需详细了解支持的 SQL Server 版本，请参阅将 SQL Server 用作来源的概览。
SQL Server CDC 配置：失败。 您选择的 CDC 方法不符合您的数据库配置。请更改 CDC 方法，然后重试。

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 目标位置。
目标 BigQuery 表中的记录数比源表中的记录数多得多。 如果来源表没有主键，就可能会出现这种情况。在这种情况下，Datastream 会以只附加写入模式处理表，并且给定行的每个事件都会在 BigQuery 中显示为单独的行。
在仅附加写入模式下执行回填时，数据会被复制。

为数据流选择仅附加写入模式后，系统会将您的数据作为 INSERT、UPDATE-INSERT、UPDATE-DELETE 和 DELETE 事件的流附加到 BigQuery 中，而不会进行任何合并。这可能会导致在您执行回填时，或在出现问题且 BigQuery 写入程序重试写入操作时，将重复行写入 BigQuery。为解决此问题，我们建议您定期运行类似于以下内容的重复数据删除查询：

SELECT * FROM (SELECT *, row_number() OVER (PARTITION BY datastream_metadata.uuid) AS num FROM TABLE_NAME) WHERE num=1
Datastream 配置为合并写入模式，但更改未在 BigQuery 中合并。

验证源表中是否存在主键。BigQuery 需要它才能将更改合并到目标表中。

如果没有主键，请考虑在源表或目标表中添加主键。如需在目标 BigQuery 表中添加主键，请按以下步骤操作：

  1. 暂停数据流。
  2. 在 BigQuery 中截断表。
  3. 向表定义添加主键。
  4. 恢复数据流。
  5. 为表触发回填。
无法为已复制到 BigQuery 的表添加主键、移除主键或更改主键定义。

默认情况下，Datastream 不支持向已复制到 BigQuery 但不含主键的表添加主键，也不支持从已复制到 BigQuery 且含主键的表中移除主键。不过，您可以更改已复制到 BigQuery 且已具有主键的源表的主键定义：

  1. 检查数据流的总延迟时间指标，并至少等待当前延迟时间，以确保所有正在处理的事件都写入到目标位置。这样，系统就可以成功流式传输具有原始主键的所有事件。
  2. 暂停数据流。
  3. 复制 BigQuery 中相应表的 CREATE TABLE 数据定义语言 (DDL) 命令： 
        SELECT ddl FROM PROJECT_ID.DATASET.INFORMATION_SCHEMA.TABLES
      WHERE table_name='TABLE_NAME';

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目的标识符。
    • DATASET_ID：BigQuery 中数据集的标识符。
    • TABLE_NAME：您要为其复制 DDL 命令的表的名称。
  4. 在 BigQuery 中删除表。
  5. 使用新主键调整 CREATE TABLE DDL 命令。添加分区和集群键以及 max_staleness OPTION： 
        CREATE TABLE `[PROJECT_ID].[DATASET_ID].[TABLE_NAME]`
    (
      product_id INT64 NOT NULL,
      product_name STRING,
      datastream_metadata STRUCT,
      PRIMARY KEY (product_id) NOT ENFORCED
    )
    CLUSTER BY dept_no
    OPTIONS(
      max_staleness=INTERVAL '0-0 0 0:MINS:0' YEAR TO SECOND
    );
    ;

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目的标识符。
    • DATASET_ID：BigQuery 中数据集的标识符。
    • TABLE_NAME：您复制 DDL 命令的表的名称。
    • MINS：您要为 max_staleness 选项设置的分钟数，例如 15。
  6. 运行经过调整的查询，以便在 BigQuery 中重新创建表。
  7. 恢复数据流。
  8. 为表启动回填。

后续步骤

  • 如需了解如何查找数据流的潜在问题，请参阅排查数据流问题。
  • 如需了解如何配置源数据库，请参阅来源。
  • 如需了解如何配置 BigQuery 或 Cloud Storage 目标位置，请参阅目标位置。