当数据流在 Datastream 中遇到运行时错误时,您可以在 Google Cloud 控制台的数据流或数据流详情页面上查看详细信息。您还可以使用 Datastream API 检索诊断信息。某些问题(例如密码无效)是可恢复的,在您解决这些问题后,复制会自动恢复。其他错误会影响单个对象(例如不受支持的数据类型),或者在 Datastream 无法连接到来源时停止数据流。
如需排查问题,请查看错误消息,并按照配置、连接、来源或 BigQuery 目标位置错误的步骤操作。
配置和连接错误
| 错误 | 问题排查步骤 |
|---|---|
| 未能连接到源数据库(常规)。 | 造成这种情况的原因有很多。如需排查此错误,请执行以下操作:
数据流会自动恢复。 |
| 未能连接到源数据库(IP 许可名单)。 | 如果所选连接方法为 IP 许可名单,但 Datastream 的一个或多个传出 IP 地址未正确添加到源数据库,则可能会发生此问题。请确保在网络防火墙上配置 Datastream 连接配置文件中显示的传出 IP 地址,以便源数据库服务器可以接受来自这些 IP 地址的连接。解决此问题后,数据流会自动恢复。 |
| 未能连接到源数据库(转发 SSH 隧道)。 | 如果转发 SSH 隧道存在问题,则可能会发生此问题。检查隧道的状态。如果隧道停止,则需要启动它。解决此问题后,数据流会自动恢复。 |
| Datastream 无法通过转发 SSH 隧道连接到堡垒主机。 | 请验证来源连接配置文件中的转发 SSH 隧道是否配置正确,以及该端口在 SSH 隧道服务器中是否处于开启状态。 |
| 由于证书错误,无法连接到源数据库。 | 如果在定义来源连接配置文件时提供的证书存在问题,则可能会发生此错误。导航到连接配置文件页面,然后选择给定的连接配置文件。验证证书是否已正确设置。进行更改后,保存连接配置文件,随后数据流会自动恢复。 |
| 未能使用专用连接来连接到源数据库。 | 此错误与 VPC 对等互连专用连接方法有关。
|
| 使用 Private Service Connect 接口连接到源数据库失败。 | |
| 组织政策 constraints/datastream.disablePublicConnectivity 开启时,不允许使用连接类型 STATIC_SERVICE_IP_CONNECTIVITY。 | 您为要创建的连接配置文件选择了公共 IP 许可名单或转发 SSH 隧道网络连接方法。但是,Datastream 的禁止使用公共连接方法组织政策已启用。因此,您无法为连接配置文件选择公共连接方法。 如需解决此问题,请选择专用 VPC 对等互连或 Private Service Connect 接口网络连接方法,或者停用组织政策。 要停用组织政策,请执行以下操作:
|
| 在为数据流配置源数据库时,我在要包含的对象列表中找不到要转移的表和架构。 | 如果您的数据库有数千个表和架构,就可能会发生这种情况。在 Google Cloud 控制台中为数据流配置来源时,其中一些对象可能未包含在要拉取的对象列表中。在选择要包含的对象部分中,选择自定义,而不是特定架构和表。在对象匹配条件字段中,输入您希望 Datastream 提取的架构和表。 |
| 我已使用要包含的对象菜单向数据流添加了多个表。但是,当我查看数据流详细信息中的对象标签页时,发现缺少一些表。 | 确保对每个表至少进行一次 CDC 更新,以便 Datastream 能够识别更改并自动将这些表包含在数据流中。 |
| 在 Google Cloud 控制台中使用要包含的对象菜单时,无法加载对象列表。 | 如果您的数据库包含超过 5,000 个架构和表,则可能会发生这种情况。请使用其他方法指定要包含的对象,或使用 Datastream API。如需了解详情,请参阅配置源数据库。 |
| 在流式传输期间丢弃且未在目标位置复制的事件。 | Datastream 可能会在流式传输期间丢弃不受支持的事件。您可以执行以下操作来解决此问题:
|
| 尝试连接到数据源时超时。请确保主机名和端口配置准确无误,并且数据源可访问。 | 由于在使用 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 服务器中,设置日志文件的保留时间。例如,使用 对于 RDS 部署,请使用 |
| 排除列表中有包含列表。 | 包含列表完全包含在排除列表中,因此 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 数据流可能会发生这种情况。如需排查此错误,请执行以下操作:
|
| 由于二进制日志位置丢失,无法恢复复制。 | 当复制过程长时间暂停时,可能会发生此错误,从而导致二进制日志位置丢失。数据流暂停的时长不得接近二进制日志保留期限。重新创建数据流。 |
| 由于源数据库和目标版本不兼容,无法运行数据流。 | 如果源数据库不符合版本支持矩阵,则可能会发生这种情况。如需排查此错误,请执行以下操作:
|
| 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 限制,并会导致错误。如需解决此问题,请完成以下步骤:
|
| 出现意外的内部错误。 | 如需了解详情,请与 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 默认在 Performance、Unlimited、Enterprise 和 Developer 版本中启用。此出错提示表示,您所用版本中的 API 已停用,或者您使用的凭证没有足够的权限。请确保您使用的用户个人资料已获得 |
| 超出限额。 | 您已超出 Salesforce API 查询限制。当您达到 API 限制配额的 90% 时,就会看到此消息。在这种情况下,Datastream 会稍后重新尝试执行此操作。您可能需要考虑增加 Salesforce API 配额。 |
| 已超出删除限制。 | 查询已删除的记录时,Salesforce 会将响应限制为 600,000 个记录标识符。Salesforce 中的最低查询粒度为 1 分钟,如果您在 1 分钟内删除超过 600,000 条记录,Salesforce 会返回此错误。 |
| 身份验证错误。 | Datastream 无法向 Salesforce 进行身份验证。您可能使用了错误的凭据或域名。 |
MongoDB 错误
| 错误 | 问题排查步骤 |
|---|---|
| 身份验证失败。 | 请检查 Datastream 用户的 authSource 是否为 admin。必须在 admin 数据库中创建 Datastream 用户。此数据库是一个特权数据库,可让用户运行某些管理命令。 |
| 数据库登录失败。 | 请检查您的用户名和密码,然后重试。另外,请确保已在 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 支持团队联系。 |
Spanner 错误
| 错误 | 问题排查步骤 |
|---|---|
| Spanner 读取错误。 | 如果您的 Spanner 数据库与 Datastream 运行的项目不同,请确保您已提供必要权限。此外,请确保您的 Spanner 数据库有足够的 CPU 资源,并且不会限制请求。 |
| 变更数据流超出保留期限。 | 您无法恢复遇到此错误的直播。此错误表示 Datastream 已滞后于 Spanner 变更数据流保留窗口,并丢失了数据。如果保留窗口较短(例如,持续几秒钟或几分钟),您可以尝试增加保留窗口并创建新数据流。 |
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 中显示为单独的行。 |
| 在仅附加写入模式下执行回填时,数据会重复。 | 如果您为数据流选择仅附加写入模式,则数据会以 SELECT * FROM (SELECT *, row_number() OVER (PARTITION BY datastream_metadata.uuid) AS num FROM TABLE_NAME) WHERE num=1
|
| Datastream 已配置为合并写入模式,但更改未在 BigQuery 中合并。 | 验证源表中是否存在主键。BigQuery 需要使用该列将更改合并到目标表中。 如果没有主键,请考虑在源表或目标表中添加一个主键。如需在目标 BigQuery 表中添加主键,请按以下步骤操作:
|
| 无法为已复制到 BigQuery 的表添加主键、移除主键或更改主键定义。 | 默认情况下,Datastream 不支持向已复制到 BigQuery 且没有主键的表添加主键,也不支持从已复制到 BigQuery 且具有主键的表中移除主键。不过,您可以更改已复制到 BigQuery 且已有主键的源表的主键定义:
|