排查迁移问题

本文档可帮助您排查将数据仓库（例如 Teradata、Amazon Redshift、Oracle 或 Apache Hive）迁移到 BigQuery 时遇到的常见问题，包括迁移评估、交互式和批量 SQL 转换以及使用 dwh-migration-dumper 命令行提取工具生成元数据时遇到的问题。

如需检查已迁移 查询和作业的作业执行详情、错误代码和槽位使用情况，您还可以查询 INFORMATION_SCHEMA.JOBS视图。

迁移评估

以下部分介绍了将数据仓库迁移到 BigQuery 时的一些常见问题和问题排查方法。

dwh-migration-dumper 工具错误

如需排查元数据或查询日志提取期间发生的 dwh-migration-dumper 工具终端输出中的错误和警告，请参阅生成元数据问题排查。

Hive 迁移错误

以下部分介绍了在您计划将数据仓库从 Hive 迁移到 BigQuery 时可能会遇到的常见问题。

hadoop-migration-assessment 查询日志提取日志记录钩子会在 hive-server2 日志中写入调试日志消息。如果您遇到任何问题，请查看包含 MigrationAssessmentLoggingHook 字符串的日志记录钩子调试日志。

处理 ClassNotFoundException 错误

当 hive-server2 进程在查询编译期间找不到 com.google.cloud.bigquery.dwhassessment.hooks.MigrationAssessmentLoggingHook 时，会发生此错误。

确保您已将 日志记录钩子 JAR 文件添加到 Hive 集群上的 auxlib 文件夹，或者您已在 hive.aux.jars.path 属性中指定 JAR 文件的完整路径，例如 file://AUXLIB_PATH/HiveMigrationAssessmentQueryLogsHooks_deploy.jar。

如果错误仍然存在，请执行以下操作：

  • 验证 Cloudera（CDP 或 CDH）上的 JAR 位置： 在 Cloudera 环境中，辅助 JAR 属性 (hive.aux.jars.path) 可能无法可靠地加载到根查询编译类加载器中。如需解决此问题，请将日志记录钩子 JAR 文件直接复制到所有 HiveServer2 主机上的核心 Hive 库目录中，例如 /opt/cloudera/parcels/CDH/lib/hive/lib/。

  • 验证配置范围： 如果您使用 Cloudera Manager，请确保将日志记录钩子配置属性（例如 hive.exec.pre.hooks、hive.exec.post.hooks、hive.exec.failure.hooks 和 dwhassessment.hook.base-directory）放在活跃的执行引擎配置代码段中。例如，如果您的集群使用 Tez 执行，请将 XML 属性添加到 hive-site.xml 的 Hive on Tez 高级配置代码段（安全阀）字段中，或添加到服务范围的 Hive 安全阀中，而不是添加到独立的 HiveServer2 配置代码段中。保存更改后，请重启 Hive 服务，包括 HiveServer2 和 Hive Metastore 角色。

子文件夹不显示在已配置的文件夹中

此问题可能是由日志记录钩子初始化期间配置错误或出现问题引起的。

在您的 hive-server2 调试日志中搜索以下日志记录钩子消息：

Unable to initialize logger, logging disabled

Log dir configuration key 'dwhassessment.hook.base-directory' is not set,
logging disabled.

Error while trying to set permission

请查看问题详情，看看是否需要进行更正，以修复相关问题。

文件不显示在文件夹中

此问题可能是由事件处理期间或向文件写入时遇到问题导致的。

在您的 hive-server2 调试日志中搜索以下日志记录钩子消息：

Failed to close writer for file

Got exception while processing event

Error writing record for query

请查看问题详情，看看是否需要进行更正，以修复相关问题。

缺少某些查询事件

此问题可能是由日志记录钩子线程队列溢出引起的。

在您的 hive-server2 调试日志中搜索以下日志记录钩子消息：

Writer queue is full. Ignoring event

如果您找到此消息，请考虑增加 dwhassessment.hook.queue.capacity 参数。

交互式 SQL 转换器

以下部分介绍了使用交互式 SQL 转换器时遇到的常见错误。

RelationNotFound 或 AttributeNotFound 转换问题

使用 交互式 SQL 转换器转换查询后，您可能会遇到转换失败，并显示 RelationNotFound 或 AttributeNotFound 错误。

您可以在 Cloud de Confiance 控制台中前往 BigQuery 中的转换详情 页面 ，然后打开 日志消息 标签页，找到转换失败的查询。

为了确保最准确的转换，您可以在查询之前输入查询中使用的任何表的数据定义语言 (DDL) 语句。例如，如果要转换 Amazon Redshift 查询 select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;，请将以下 SQL 语句输入到交互式 SQL 转换器中：

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

使用 Gemini 解决转换问题

如需修复因 RelationNotFound 或 AttributeNotFound 错误而失败的转换作业，您还可以使用 Gemini 解决这些问题：

  1. 在 BigQuery 的 Cloud de Confiance 控制台中，前往 转换详情页面，然后打开日志消息标签页。
  2. 在类别 列中，点击包含 RelationNotFound 或 AttributeNotFound 消息的查询。
  3. 点击建议的修复方案 。
  4. 点击应用 。
  5. 如需重新转换查询，请点击转换 。

批量 SQL 转换器

以下部分介绍了使用批量 SQL 转换器时遇到的常见错误。

RelationNotFound 或 AttributeNotFound 转换问题

使用 批量 SQL 转换器转换查询后， 您可能会遇到转换失败，并显示 RelationNotFound 或 AttributeNotFound 错误。

您可以在控制台中前往 BigQuery 中的转换详情 页面 ，然后打开 Cloud de Confiance 日志消息 标签页，找到转换失败的查询。

Translation 最适合元数据 DDL。如果找不到 SQL 对象定义，则转换引擎会引发 RelationNotFound 或 AttributeNotFound 问题。我们建议您使用元数据提取器生成元数据包，以确保所有对象定义都存在。添加元数据是解决大多数转换错误的建议第一步，因为此步骤通常可以修复许多其他间接由缺少元数据引起的错误。

如需了解详情，请参阅 生成元数据以进行转换和评估。

使用 Gemini 解决转换问题

如需修复因 RelationNotFound 或 AttributeNotFound 错误而失败的转换作业，您还可以使用 Gemini 解决这些问题：

  1. 前往转换详情 页面，然后打开日志消息 标签页。
  2. 在类别 列中，点击包含 RelationNotFound 或 AttributeNotFound 消息的查询。

  3. 如需前往代码标签页中包含错误的文件和行，请点击

    出错提示。

  4. 在操作 列中，点击建议的修复方案 。

  5. 选择以下某个选项：应用 或应用并重新运行：

    • 如需将生成的架构文件从输出目录复制到输入目录，请点击应用 。
    • 如需将生成的架构文件从输出目录复制到输入目录并打开重新运行窗口，请点击应用并重新运行 。

生成元数据以进行转换和评估

以下部分介绍了 dwh-migration-dumper 工具的一些常见问题和问题排查方法。

内存不足错误

dwh-migration-dumper 工具终端输出中的 java.lang.OutOfMemoryError 错误通常与内存不足以处理检索的数据有关。如需解决此问题，请增加可用内存或减少处理线程数。

您可以通过导出 JAVA_OPTS 环境变量来增加最大内存：

Linux 

export JAVA_OPTS="-Xmx4G"

Windows 

set JAVA_OPTS="-Xmx4G"

您可以通过添加 --thread-pool-size 标志值来减少处理线程数（默认值为 32）。此选项仅适用于 hiveql 和 redshift* 连接器：

dwh-migration-dumper --thread-pool-size=1

处理 WARN...Task failed 错误

您有时可能会在 dwh-migration-dumper 工具终端输出中看到 WARN [main] o.c.a.d.MetadataDumper [MetadataDumper.java:107] Task failed: … 错误。提取工具会将多个查询提交到源系统，并且每个查询的输出会写入其各自的文件中。出现此问题意味着其中一个查询失败。不过，一个查询的失败不会阻止其他查询的执行。如果您看到多个 WARN 错误，请查看问题详情，看看是否需要进行更正，以使查询能够正常运行。例如，如果您在运行提取工具时指定的数据库用户缺少读取所有元数据的权限，请使用具有正确权限的用户重试。

ZIP 文件损坏

如需验证 dwh-migration-dumper 工具 ZIP 文件，请下载 SHA256SUMS.txt 文件 并运行以下命令：

Bash 

sha256sum --check SHA256SUMS.txt

OK 结果表示校验和验证成功。任何其他消息都表示验证错误：

  • FAILED: computed checksum did NOT match：ZIP 文件已损坏，必须重新下载。
  • FAILED: listed file could not be read：无法找到 ZIP 文件版本。请从同一版本下载校验和文件和 ZIP 文件，并将它们放在同一目录中。

Windows PowerShell 

(Get-FileHash RELEASE_ZIP_FILENAME).Hash -eq ((Get-Content SHA256SUMS.txt) -Split " ")[0]

将 RELEASE_ZIP_FILENAME 替换为 dwh-migration-dumper 命令行提取工具版本的下载 ZIP 文件名，例如 dwh-migration-tools-v1.0.52.zip。

True 结果表示校验和验证成功。

False 结果表示验证错误。请从同一发布版本下载校验和文件和 ZIP 文件，并将它们放在同一目录中。

Teradata 查询日志提取速度缓慢

如需提高 -Dteradata-logs.query-logs-table 和 -Dteradata-logs.sql-logs-table 标志指定的联接表的性能，您可以在 JOIN 条件中额外添加一个类型为 DATE 的列。 此列必须在两个表中定义，并且必须是分区主索引的一部分。如需添加此列，请使用 -Dteradata-logs.log-date-column 标志。

以下示例展示了如何使用 -Dteradata-logs.log-date-column 标志：

Bash

dwh-migration-dumper \
  -Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV \
  -Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl \
  -Dteradata-logs.log-date-column=ArchiveLogDate

Windows PowerShell

dwh-migration-dumper `
  "-Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV" `
  "-Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl" `
  "-Dteradata-logs.log-date-column=ArchiveLogDate"

已超出 Teradata 行大小限制

Teradata 版本 15 的行大小上限为 64 KB。如果超出限制，提取工具将失败并显示以下消息：

[Error 9804] [SQLState HY000] Response Row size or Constant Row size overflow

如需解决此错误，请将行限制扩展到 1 MB 或将行拆分为多行：

  • 安装并启用 1 MB 永久性和响应行功能以及当前 TTU 软件。如需了解详情，请参阅 Teradata 数据库消息 9804。
  • 使用 -Dteradata.metadata.max-text-length 和 -Dteradata-logs.max-sql-length 标志将长查询文本拆分为多行。

以下命令展示了如何使用 -Dteradata.metadata.max-text-length 标志将长查询文本拆分为多行，每行最多包含 10,000 个字符：

Bash

dwh-migration-dumper \
  --connector teradata \
  -Dteradata.metadata.max-text-length=10000

Windows PowerShell

dwh-migration-dumper `
  --connector teradata `
  "-Dteradata.metadata.max-text-length=10000"

以下命令展示了如何使用 -Dteradata-logs.max-sql-length 标志将长查询文本拆分为多行，每行最多包含 10,000 个字符：

Bash

dwh-migration-dumper \
  --connector teradata-logs \
  -Dteradata-logs.max-sql-length=10000

Windows PowerShell

dwh-migration-dumper `
  --connector teradata-logs `
  "-Dteradata-logs.max-sql-length=10000"

Oracle 连接问题

在密码或主机名无效等常见情况下，dwh-migration-dumper 工具会输出一条有意义的出错提示，其中描述了根本问题。不过，在某些情况下，Oracle 服务器返回的出错提示可能是通用的，并且难以调查。

其中一个问题是 IO Error: Got minus one from a read call。此错误表示已与 Oracle 服务器建立连接，但服务器未接受客户端并关闭了连接。 此问题通常发生在服务器仅接受 TCPS 连接时。默认情况下，dwh-migration-dumper 工具使用 TCP 协议。如需解决此问题，您必须替换 Oracle JDBC 连接网址。

您可以通过提供以下格式的 url 标志来解决此问题，而不是提供 oracle-service、host 和 port 标志：jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE。通常，Oracle 服务器使用的 TCPS 端口号为 2484。

以下示例展示了如何在命令中指定连接网址：

dwh-migration-dumper \
  --connector oracle-stats \
  --url "jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE" \
  --assessment \
  --driver "JDBC_DRIVER_PATH" \
  --user "USER" \
  --password

除了将连接协议更改为 TCPS 之外，您可能还需要提供验证 Oracle 服务器证书所需的信任库 SSL 配置。如果缺少 SSL 配置，系统会显示 Unable to find valid certification path 出错提示。如需解决此问题，请设置 JAVA_OPTS 环境变量：

set JAVA_OPTS=-Djavax.net.ssl.trustStore="JKS_FILE_LOCATION" -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStorePassword="PASSWORD"

根据您的 Oracle 服务器配置，您可能还需要提供密钥库配置。如需详细了解 配置选项，请参阅 使用 Oracle JDBC 驱动程序的 SSL。

后续步骤