诊断问题

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

  • 某些错误（例如源数据库上的密码错误）可以恢复，这意味着它们可以得到修复，并且数据流会自动恢复。
  • 一些错误可能会影响单个对象，例如包含不受支持的数据类型的事件。其他错误可能会影响多个对象或整个数据流，例如当 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 隧道服务器中是否处于开启状态。
由于证书错误，无法连接到源数据库。 如果在定义来源连接配置文件时提供的证书存在问题，则可能会发生此错误。导航到连接配置文件页面，然后选择给定的连接配置文件。验证证书是否已正确设置。进行更改后，保存连接配置文件，随后数据流会自动恢复。
未能使用专用连接来连接到源数据库。 此错误与 VPC 对等互连专用连接方法有关。
  1. 请确保您已满足所有前提条件VPC 对等互连前提条件。

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

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

  3. Datastream 不会检查是否与动态对等互连路由重叠。提供与动态路由重叠的子网可能会导致连接问题。因此，我们不建议使用属于动态路由一部分的子网。
  4. 确保正确通告 Datastream IP 地址范围的自定义路由。如果缺少自定义路由，请参阅自定义通告路由。
  5. 如果您在连接到源数据库时仍然遇到问题，请参阅设置反向代理。
未能使用 Private Service Connect 接口连接到源数据库。
  1. 请确保您已满足所有前提条件。
  2. 确保防火墙规则允许所提供网络连接的子网连接到源数据库。
  3. 确保正确通告 Datastream IP 地址范围的自定义路由。如果缺少自定义路由，请参阅自定义通告路由。
组织政策 constraints/datastream.disablePublicConnectivity 开启时，不允许使用连接类型 STATIC_SERVICE_IP_CONNECTIVITY。

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

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

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

  1. 前往 Google Cloud 控制台中的组织政策页面。
  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 事件时，才能实现此目的。
  • 如果舍弃的事件数量较少或舍弃的事件不重要，请忽略此问题。
尝试连接到数据源时超时。确保主机名和端口配置准确无误，并且数据源可供访问。 使用 VPC 对等互连时，由于 Datastream 网络无法与专用服务网络（例如 Cloud SQL 实例）直接对等互连，因此您需要使用网络地址转换 (NAT) 虚拟机来建立 Datastream 与资源之间的连接。如需详细了解如何设置 NAT 虚拟机，请参阅配置 VPC 对等互联。
对象 OBJECT_NAME 的架构过大，Datastream 无法处理。 Datastream 不支持复制相应源架构大于 2,621,440 个 Unicode 字符的事件。这些事件被舍弃，原因代码为：UNSUPPORTED_LARGE_SCHEMA。您可能需要排除或重命名某些列。或者，您也可以排除具有大型架构的对象。
数据流状态已更改。 虽然导致此错误的原因可能不止一个，但常见的根本问题是来源配置无效。如果您的数据流因出现此错误消息而无法启动，请检查您的来源配置是否存在重复的键或表名称、数据不一致或架构冲突。许多问题都可以通过直接在 Google Cloud 控制台中修改失败的数据流设置并调整包含和排除对象的条目来解决。如需了解详情，请参阅修改有关源数据库的配置信息。

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 源所做的更改不会反映在目标位置。 如果您使用 LogMiner 作为 CDC 方法，Datastream 会从归档的重做日志文件中读取数据。在这种情况下，您对来源所做的更改不会反映在目标中，直到日志被归档为止。如需查看目标中的更改，请将 CDC 方法更改为二进制日志读取器，更改日志归档政策，或手动强制执行日志切换。如需了解详情，请参阅使用 Oracle 数据库重做日志文件。
Oracle CDC 配置验证失败。 您选择的 CDC 方法未针对源数据库进行配置。选择其他方法，或完成 CDC 方法的配置。如需了解详情，请参阅配置源 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 编码证书。
从 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. 将副本身份更改为 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 作为数据源的概览。
该数据流无法读取 LSN“YOUR_LSN”中的事件，因为事务日志似乎已被截断。

如果源数据库中不再存在事务日志，则可能会出现此问题。如果您使用事务日志 CDC 方法从 SQL Server 源复制数据，日志可能会在 Datastream 读取之前被截断。发生这种情况时，Datastream 无法可靠地将源数据库复制到目标位置。

如需解决此问题，请恢复您的数据流，或考虑改用变更表 CDC 方法。 如需详细了解这两种方法之间的差异，请参阅 SQL Server 作为来源的概览。
SQL Server CDC 配置：失败。 您选择的 CDC 方法与您的数据库配置不符。请更改 CDC 方法，然后重试。

Salesforce 错误

错误 问题排查步骤
权限不足。

您配置为对 Salesforce 组织与 Datastream 之间的连接进行身份验证的关联应用或外部客户端应用的用户没有足够的权限来访问您要复制的数据。确保您已正确配置 Salesforce 源。如需了解详情，请参阅配置 Salesforce 来源。
Bulk API 2.0 已停用。

对于专业版、无限版、企业版和开发者版，系统默认启用 Bulk API 2.0。此错误消息表示，您的版本中已停用相应 API，或者您使用的凭据没有足够的权限。确保您使用的用户个人资料已获授 API Enabled 权限。
超出上限。

您已超出 Salesforce API 查询限制。当您达到 API 配额上限的 90% 时，会看到此消息。在这种情况下，Datastream 会稍后重试该操作。您可能需要考虑增加 Salesforce API 配额。
超出删除限制。

查询已删除的记录时，Salesforce 会将响应限制为 60 万个记录标识符。Salesforce 中的最低查询粒度为 1 分钟，如果您在 1 分钟内删除超过 60 万条记录，Salesforce 会返回此错误。
身份验证错误。

Datastream 无法通过 Salesforce 进行身份验证。您可能使用了错误的凭据或域名。

MongoDB 错误

错误 问题排查步骤
身份验证失败。 请检查 Datastream 用户的 authSource 是否为 admin。Datastream 用户必须在 admin 数据库中创建。此数据库是一个特权数据库，可让用户运行某些管理命令。
数据库登录失败。 请检查您的用户名和密码，然后重试。另外，请确保已在 admin 数据库中创建用户账号。如果问题仍然存在，则可能是因为您的用户账号已被删除或创建不正确。
排除对象列表无效：{exclude_list}。 请使用以下格式（可以选择使用通配符）指定排除的对象：DATABASE_NAME.COLLECTION_NAME.FIELD_NAME.NESTED_FIELD_NAME。有效示例：db.*、database.collection.*、database.*.field.*。
我们缺少从来源读取数据所需的必要权限。 为您的用户分配 readAnyDatabase 角色，然后重试。
不支持 MongoDB 版本 VERSION_NAME。 请使用 5.0 或更高版本。
Datastream 无法执行 buildinfo 命令来确定 MongoDB 版本。 请确保用户拥有执行 buildinfo 命令的必要权限，然后重试。如需详细了解所需权限，请参阅配置 MongoDB 数据库。
与 MongoDB 集群的连接超时。 请确保您提供的主机名和凭据正确无误，然后重试。
由于权限不足，我们无法读取必要的数据。 请为用于连接到 MongoDB 集群的账号分配 readAnyDatabase 角色，然后重试。
用于连接到 MongoDB 集群的用户账号不存在。 请创建该用户账号，然后重试。
我们无法使用提供的信息进行连接。 请验证是否使用了正确的连接格式（SRV 或标准格式），并包含了所有必要的信息（例如副本集连接字符串的副本集名称）。如需了解详情，请参阅为 MongoDB 数据库创建连接配置文件。
我们遇到了 MongoDB 异常。来源错误消息：{source_error}。 如果来源错误消息不明确，请与 Google 支持团队联系。

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 目标位置，请参阅目标位置。