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

本文档介绍了如何使用 dwh-migration-dumper 命令行工具创建元数据和查询日志文件。元数据文件用于描述源系统中的 SQL 对象。

BigQuery Migration Service 可使用此信息改善 SQL 脚本从源系统方言到 GoogleSQL 的转换。

BigQuery 迁移评估使用元数据文件和查询日志文件来分析现有数据仓库，并帮助评估将数据仓库迁移到 BigQuery 的工作量。

概览

您可以使用 dwh-migration-dumper 工具从要迁移到 BigQuery 的数据库平台中提取元数据信息。虽然转换时不需要使用提取工具，但 BigQuery 迁移评估时需要用到，我们强烈建议将其用于所有迁移任务。

如需了解详情，请参阅创建元数据文件。

您可以使用 dwh-migration-dumper 工具从以下数据库平台中提取元数据：

TeraData
Amazon Redshift
Apache Hive
Apache Spark
Azure Synapse
Microsoft SQL Server
IBM Netezza
Oracle
Snowflake
Trino 或 PrestoSQL
Vertica

对于其中大多数数据库，您还可以提取查询日志。

dwh-migration-dumper 工具会查询系统表，以收集与用户和系统数据库相关的数据定义语言 (DDL) 语句。它不会查询用户数据库的内容。该工具会将系统表中的元数据信息保存为 CSV 文件，然后将这些文件压缩为一个软件包。然后，在上传要转换或评估的源文件时，将此 ZIP 文件上传到 Cloud Storage。

使用查询日志选项时，dwh-migration-dumper 工具会在系统表中查询与用户和系统数据库相关的 DDL 语句和查询日志。这些内容会以 CSV 或 yaml 格式保存到子目录中，然后打包为 zip 软件包。用户数据库本身的内容绝不会被查询。此时，BigQuery 迁移评估需要将单独的 CSV、YAML 和文本文件用于查询日志，因此您应该从查询日志 ZIP 文件中将这些文件全部解压缩，然后上传进行评估。

dwh-migration-dumper 工具可以在 Windows、macOS 和 Linux 上运行。

dwh-migration-dumper 工具可通过 Apache 2 许可获取。

如果选择不使用 dwh-migration-dumper 工具进行转换，则可以通过将源系统中 SQL 对象的数据定义语言 (DDL) 语句收集到单独的文本文件中来手动提供元数据文件。

使用 BigQuery 迁移评估进行迁移评估时，必须提供使用该工具提取的元数据和查询日志。

合规要求

为方便使用，我们提供已编译的 dwh-migration-dumper 工具二进制文件。如果您需要审核工具以确保它符合合规性要求，则可以查看 dwh-migration-dumper 工具 GitHub 代码库中的源代码，并编译您自己的二进制文件。

前提条件

安装 Java

您打算运行 dwh-migration-dumper 工具的服务器必须安装 Java 8 或更高版本。如果未安装，请从 Java 下载页面下载并安装 Java。

所需权限

您指定用于将 dwh-migration-dumper 工具连接到源系统的用户账号必须具有从该系统读取元数据的权限。确认此账号具有适当的角色成员资格，可以查询您的平台可用的元数据资源。例如，INFORMATION_SCHEMA 是在多个平台中常见的元数据资源。

安装 `dwh-migration-dumper` 工具

如需安装 dwh-migration-dumper 工具，请按以下步骤操作：

在要运行 dwh-migration-dumper 工具的机器上，从 dwh-migration-dumper 工具 GitHub 代码库下载 zip 文件。
下载 SHA256SUMS.txt 文件并运行以下命令：
```
sha256sum --check SHA256SUMS.txt
```
如果验证失败，请参阅问题排查。
提取该 zip 文件。提取工具二进制文件位于通过提取 ZIP 文件创建的文件夹的 /bin 子目录中。
更新 PATH 环境变量，以包含提取工具的安装路径。

运行 `dwh-migration-dumper` 工具

dwh-migration-dumper 工具使用以下格式：

dwh-migration-dumper [FLAGS]

如果运行 dwh-migration-dumper 工具，则系统会在工作目录中创建一个名为 dwh-migration-<source platform>-metadata.zip 的输出文件（例如 dwh-migration-teradata-metadata.zip）。

请按照以下说明了解如何为源平台运行 dwh-migration-dumper 工具。

TeraData

如需允许 dwh-migration-dumper 工具连接到 Teradata，请从 Teradata 的下载页面下载其 JDBC 驱动程序。

下表介绍了使用提取工具提取 Teradata 元数据和查询日志的常用标志。如需了解所有支持的标志，请参阅全局标志。

名称	默认值	说明	必需
`--assessment`		在生成数据库日志或提取元数据时启用评估模式。`dwh-migration-dumper` 工具在用于元数据提取时，会生成 BigQuery 迁移评估所需的元数据统计信息。在用于查询日志时，则会提取用于 BigQuery 迁移评估的一些其他列。	运行评估时必须使用该工具，但进行转换则不一定要使用该工具。
`--connector`		要使用的连接器的名称，在本例中为 teradata（用于元数据）或 teradata-logs（用于查询日志）。	是
`--database`		要提取的数据库列表，以英文逗号分隔。数据库名称可能区分大小写，具体取决于 Teradata 服务器配置。如果此标志与 `teradata` 连接器一起使用，则 `dwh-migration-dumper` 工具会按提供的数据库列表过滤元数据表和视图。但 `DatabasesV` 和 `RoleMembersV` 视图除外，`dwh-migration-dumper` 工具会从这些视图中提取数据库和用户，但不会按数据库名称过滤。此标志不能与 `teradata-logs` 连接器一起使用。系统始终会提取所有数据库的查询日志。	否
`--driver`		要用于此连接的驱动程序 JAR 文件的绝对或相对路径。您可以指定多个驱动程序 JAR 文件，并以逗号分隔。	是
`--host`	localhost	数据库服务器的主机名或 IP 地址。	否
`--password`		要用于数据库连接的密码。	如果未指定，则提取工具使用安全提示来请求它。
`--port`	1025	数据库服务器的端口。	否
`--user`		要用于数据库连接的用户名。	是
`--query-log-alternates`		仅适用于 `teradata-logs` 连接器。如需从其他位置提取查询日志，我们建议您改用 `-Dteradata-logs.query-logs-table` 和 `-Dteradata-logs.sql-logs-table` 标志。默认情况下，查询日志会从表 `dbc.DBQLogTbl` 和 `dbc.DBQLSQLTbl` 中提取。如果您使用 `--assessment` 标志，则查询日志会从视图 `dbc.QryLogV` 和表 `dbc.DBQLSQLTbl` 中提取。如果您需要从替代位置提取查询日志，则可以使用 `--query-log-alternates` 标志指定表或视图的完全限定名称。第一个参数引用 `dbc.DBQLogTbl` 表的替代位置，第二个参数引用 `dbc.DBQLSQLTbl` 表的替代位置。这两个参数都是必需的。当两个表都具有 `DATE` 类型的索引列时，`-Dteradata-logs.log-date-column` 标志可用于提高提取性能。示例：`--query-log-alternates historicdb.ArchivedQryLogV,historicdb.ArchivedDBQLSqlTbl`	否
`-Dteradata.tmode`		连接的事务模式。支持以下值： `ANSI`：ANSI 模式。这是默认模式（如果未指定标志） `TERA`：Teradata 事务模式 (BTET) `DEFAULT`：使用数据库服务器上配置的默认事务模式 `NONE`：没有为连接设置模式示例 (Bash)： `-Dteradata.tmode=TERA` 示例 (Windows PowerShell)： `"-Dteradata.tmode=TERA"`	否
`-Dteradata-logs.log-date-column`		仅适用于 `teradata-logs` 连接器。如需提高 `-Dteradata-logs.query-logs-table` 和 `-Dteradata-logs.sql-logs-table` 标志指定的联接表的性能，您可以在 `JOIN` 条件中额外添加一个类型为 `DATE` 的列。此列必须在两个表中定义，并且必须是分区主索引的一部分。示例 (Bash)： `-Dteradata-logs.log-date-column=ArchiveLogDate` 示例 (Windows PowerShell)： `"-Dteradata-logs.log-date-column=ArchiveLogDate"`	否
`-Dteradata-logs.query-logs-table`		仅适用于 `teradata-logs` 连接器。默认情况下，查询日志会从 `dbc.DBQLogTbl` 表中提取。如果您使用 `--assessment` 标志，则查询日志会从视图 `dbc.QryLogV` 中提取。如果您需要从其他位置提取查询日志，则可以使用此标志指定相应表或视图的完全限定名称。请参阅 `-Dteradata-logs.log-date-column` 标志，了解如何提高提取性能。示例 (Bash)： `-Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV` 示例 (Windows PowerShell)： `"-Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV"`	否
`-Dteradata-logs.sql-logs-table`		仅适用于 `teradata-logs` 连接器。默认情况下，包含 SQL 文本的查询日志会从 `dbc.DBQLSqlTbl` 表中提取。如果您需要从其他位置提取这些日志，则可以使用此标志指定相应表或视图的完全限定名称。请参阅 `-Dteradata-logs.log-date-column` 标志，了解如何提高提取性能。示例 (Bash)： `-Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl` 示例 (Windows PowerShell)： `"-Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl"`	否
`-Dteradata-logs.utility-logs-table`		仅适用于 `teradata-logs` 连接器。默认情况下，实用程序日志是从表 `dbc.DBQLUtilityTbl` 中提取的。如果需要从备用位置提取实用程序日志，您可以使用 `-Dteradata-logs.utility-logs-table` 标志指定表的完全限定名称。示例 (Bash)： `-Dteradata-logs.utility-logs-table=historicdb.ArchivedUtilityLogs` 示例 (Windows PowerShell)： `"-Dteradata-logs.utility-logs-table=historicdb.ArchivedUtilityLogs"`	否
`-Dteradata-logs.res-usage-scpu-table`		仅适用于 `teradata-logs` 连接器。默认情况下，SCPU 资源使用情况日志是从表 `dbc.ResUsageScpu` 中提取的。如果需要从备用位置提取这些表，可以使用 `-Dteradata-logs.res-usage-scpu-table` 标志指定表的完全限定名称。示例 (Bash)： `-Dteradata-logs.res-usage-scpu-table=historicdb.ArchivedResUsageScpu` 示例 (Windows PowerShell)： `"-Dteradata-logs.res-usage-scpu-table=historicdb.ArchivedResUsageScpu"`	否
`-Dteradata-logs.res-usage-spma-table`		仅适用于 `teradata-logs` 连接器。默认情况下，SPMA 资源使用情况日志会从表 `dbc.ResUsageSpma` 中提取。如果需要从备用位置提取这些日志，可以使用 `-Dteradata-logs.res-usage-spma-table` 标志指定表的完全限定名称。示例 (Bash)： `-Dteradata-logs.res-usage-spma-table=historicdb.ArchivedResUsageSpma` 示例 (Windows PowerShell)： `"-Dteradata-logs.res-usage-spma-table=historicdb.ArchivedResUsageSpma"`	否
`--query-log-start`		要提取的查询日志的开始时间（含边界值）。该值会被截断至小时。此标志仅适用于 teradata-logs 连接器。示例：`--query-log-start "2023-01-01 14:00:00"`	否
`--query-log-end`		要提取的查询日志的结束时间（不含边界值）。该值会被截断至小时。此标志仅适用于 teradata-logs 连接器。示例：`--query-log-end "2023-01-15 22:00:00"`	否
`-Dteradata.metadata.tablesizev.max-rows`		仅适用于 `teradata` 连接器。限制从视图 `TableSizeV` 中提取的行数。行按列 `DatabaseName`、`AccountName` 和 `TableName` 分组，再按永久空间的大小（表达式 `SUM(CurrentPerm)`）降序排序。然后，系统会提取指定的行数。示例 (Bash)： `-Dteradata.metadata.tablesizev.max-rows=100000` 示例 (Windows PowerShell)： `"-Dteradata.metadata.tablesizev.max-rows=100000"`	否
`-Dteradata.metadata.diskspacev.max-rows`		仅适用于 `teradata` 连接器。限制从视图 `DiskSpaceV` 中提取的行数。行按永久空间的大小（列 `CurrentPerm`）降序排序，然后系统会提取指定的行数。示例 (Bash)： `-Dteradata.metadata.diskspacev.max-rows=100000` 示例 (Windows PowerShell)： `"-Dteradata.metadata.diskspacev.max-rows=100000"`	否
`-Dteradata.metadata.databasesv.users.max-rows`		仅适用于 `teradata` 连接器。限制表示从视图 `DatabasesV` 中提取的用户 (`DBKind='U'`) 的行数。行按 `PermSpace` 列降序排序，然后系统会提取指定的行数。示例 (Bash)： `-Dteradata.metadata.databasesv.users.max-rows=100000` 示例 (Windows PowerShell)： `"-Dteradata.metadata.databasesv.users.max-rows=100000"`	否
`-Dteradata.metadata.databasesv.dbs.max-rows`		仅适用于 `teradata` 连接器。限制表示从视图 `DatabasesV` 中提取的数据库 (`DBKind='D'`) 的行数。行按 `PermSpace` 列降序排序，然后系统会提取指定的行数。示例 (Bash)： `-Dteradata.metadata.databasesv.dbs.max-rows=100000` 示例 (Windows PowerShell)： `"-Dteradata.metadata.databasesv.dbs.max-rows=100000"`	否
`-Dteradata.metadata.max-text-length`		仅适用于 `teradata` 连接器。从 `TableTextV` 视图中提取数据时的文本列长度上限。长度超过定义的限制的文本将被拆分为多行。允许的范围：5000 到 32000（含）之间。示例 (Bash)： `-Dteradata.metadata.max-text-length=10000` 示例 (Windows PowerShell)： `"-Dteradata.metadata.max-text-length=10000"`	否
`-Dteradata-logs.max-sql-length`		仅适用于 `teradata-logs` 连接器。 `DBQLSqlTbl.SqlTextInfo` 列的长度上限。超过定义的限制的查询文本将被拆分为多行。允许的范围：5000 到 31000（含）。示例 (Bash)： `-Dteradata-logs.max-sql-length=10000` 示例 (Windows PowerShell)： `"-Dteradata-logs.max-sql-length=10000"`	否

示例

以下示例展示了如何提取本地主机上两个 Teradata 数据库的元数据：

dwh-migration-dumper \
  --connector teradata \
  --user user \
  --password password \
  --database database1,database2 \
  --driver path/terajdbc4.jar

以下示例展示了如何提取本地主机上评估的查询日志以用于身份验证：

dwh-migration-dumper \
  --connector teradata-logs \
  --assessment \
  --user user \
  --password password \
  --driver path/terajdbc4.jar

由 `dwh-migration-dumper` 工具提取的表和视图

使用 teradata 连接器时，系统会提取以下表和视图：

DBC.ColumnsV
DBC.DatabasesV
DBC.DBCInfo
DBC.FunctionsV
DBC.IndicesV
DBC.PartitioningConstraintsV
DBC.TablesV
DBC.TableTextV

当您使用带有 --assessment 标志的 teradata 连接器时，系统会提取以下额外的表和视图：

DBC.All_RI_ChildrenV
DBC.All_RI_ParentsV
DBC.AllTempTablesVX
DBC.DiskSpaceV
DBC.RoleMembersV
DBC.StatsV
DBC.TableSizeV

当您使用 teradata-logs 连接器时，系统会提取以下表和视图：

DBC.DBQLogTbl（如果使用 --assessment 标志，则更改为 DBC.QryLogV）
DBC.DBQLSqlTbl

当您使用带有 --assessment 标志的 teradata-logs 连接器时，系统会提取以下额外的表和视图：

DBC.DBQLUtilityTbl
DBC.ResUsageScpu
DBC.ResUsageSpma

Redshift

您可以将以下任意 Amazon Redshift 身份验证和授权机制与提取工具结合使用：

用户名和密码。
AWS Identity and Access Management (IAM) 访问密钥 ID 和密码。
AWS IAM 配置文件名称。

如需使用用户名和密码进行身份验证，请使用 Amazon Redshift 默认的 PostgreSQL JDBC 驱动程序。如需向 AWS IAM 进行身份验证，请使用 Amazon Redshift JDBC 驱动程序，该驱动程序可以通过其下载页面进行下载。

下表展示了使用 dwh-migration-dumper 工具提取 Amazon Redshift 元数据和查询日志时常用的一些标志。如需了解所有支持的标志，请参阅全局标志。

名称	默认值	说明	必需
`--assessment`		在生成数据库日志或提取元数据时启用评估模式。用于元数据提取时，它会生成 BigQuery 迁移评估所需的元数据统计信息。用于查询日志提取时，它会生成用于 BigQuery 迁移评估的查询指标统计信息。	在评估模式下运行时是必需的，在转换时不需要。
`--connector`		要使用的连接器的名称，在本例中为 redshift（用于元数据）或 redshift-raw-logs（用于查询日志）。	是
`--database`	如果未指定，则 Amazon Redshift 使用 `--user` 值作为默认数据库名称。	要连接的数据库名称。	否
`--driver`	如果未指定，则 Amazon Redshift 使用默认 PostgreSQL JDBC 驱动程序。	要用于此连接的驱动程序 JAR 文件的绝对或相对路径。您可以指定多个驱动程序 JAR 文件，并以逗号分隔。	否
`--host`	localhost	数据库服务器的主机名或 IP 地址。	否
`--iam-accesskeyid`		要用于身份验证的 AWS IAM 访问密钥 ID。访问密钥是一串字符，类似于 `AKIAIOSFODNN7EXAMPLE`。与 `--iam-secretaccesskey` 标志结合使用。在指定 `--iam-profile` 或 `--password` 标志时，请勿使用此标志。	未明确说明，但您必须通过以下方法之一提供身份验证信息：将此标志与 `--iam-secretaccesskey` 标志结合使用。使用 `--iam-profile` 标志。将 `--password` 标志与 `--user` 标志结合使用。
`--iam-profile`		要用于身份验证的 AWS IAM 配置文件。您可以通过检查 `$HOME/.aws/credentials` 文件或运行 `aws configure list-profiles` 来检索要使用的配置文件值。请勿将此标志与 `--iam-accesskeyid`、`--iam-secretaccesskey` 或 `--password` 标志结合使用。	未明确说明，但您必须通过以下方法之一提供身份验证信息：使用此标志。将 `--iam-accesskeyid` 标志与 `--iam-secretaccesskey` 标志结合使用。将 `--password` 标志与 `--user` 标志结合使用。
`--iam-secretaccesskey`		用于身份验证的 AWS IAM 访问密钥。访问密钥是一串字符，类似于 `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`。与 `--iam-accesskeyid` 标志结合使用。请勿将此标志与 `--iam-profile` 或 `--password` 标志结合使用。	未明确说明，但您必须通过以下方法之一提供身份验证信息：将此标志与 `--iam-accesskeyid` 标志结合使用。使用 `--iam-profile` 标志。将 `--password` 标志与 `--user` 标志结合使用。
`--password`		要用于数据库连接的密码。请勿将此标志与 `--iam-accesskeyid`、`--iam-secretaccesskey` 或 `--iam-profile` 标志结合使用。	未明确说明，但您必须通过以下方法之一提供身份验证信息：将此标志与 `--user` 标志结合使用。将 `--iam-accesskeyid` 标志与 `--iam-secretaccesskey` 标志结合使用。使用 `--password` 标志。
`--port`	5439	数据库服务器的端口。	否
`--user`		要用于数据库连接的用户名。	是
`--query-log-start`		要提取的查询日志的开始时间（含边界值）。该值会被截断至小时。此标志仅适用于 redshift-raw-logs 连接器。示例：`--query-log-start "2023-01-01 14:00:00"`	否
`--query-log-end`		要提取的查询日志的结束时间（不含边界值）。该值会被截断至小时。此标志仅适用于 redshift-raw-logs 连接器。示例：`--query-log-end "2023-01-15 22:00:00"`	否

示例

以下示例展示了如何使用 AWS IAM 密钥进行身份验证，然后从指定主机上的 Amazon Redshift 数据库提取元数据：

dwh-migration-dumper \
  --connector redshift \
  --database database \
  --driver path/redshift-jdbc42-version.jar \
  --host host.region.redshift.amazonaws.com \
  --iam-accesskeyid access_key_ID \
  --iam-secretaccesskey secret_access-key \
  --user user

以下示例展示了如何使用用户名和密码进行身份验证，然后从默认主机上的 Amazon Redshift 数据库提取元数据：

dwh-migration-dumper \
  --connector redshift \
  --database database \
  --password password \
  --user user

以下示例展示了如何使用 AWS IAM 配置文件进行身份验证，然后从指定主机上的 Amazon Redshift 数据库提取元数据：

dwh-migration-dumper \
  --connector redshift \
  --database database \
  --driver path/redshift-jdbc42-version.jar \
  --host host.region.redshift.amazonaws.com \
  --iam-profile profile \
  --user user \
  --assessment

以下示例展示了如何使用 AWS IAM 配置文件进行身份验证，然后从指定主机上的 Amazon Redshift 数据库提取用于评估的查询日志：

dwh-migration-dumper \
  --connector redshift-raw-logs \
  --database database \
  --driver path/redshift-jdbc42-version.jar \
  --host 123.456.789.012 \
  --iam-profile profile \
  --user user \
  --assessment

由 `dwh-migration-dumper` 工具提取的表和视图

使用 redshift 连接器时，系统会提取以下表和视图：

SVV_COLUMNS
SVV_EXTERNAL_COLUMNS
SVV_EXTERNAL_DATABASES
SVV_EXTERNAL_PARTITIONS
SVV_EXTERNAL_SCHEMAS
SVV_EXTERNAL_TABLES
SVV_TABLES
SVV_TABLE_INFO
INFORMATION_SCHEMA.COLUMNS
PG_CAST
PG_DATABASE
PG_LANGUAGE
PG_LIBRARY
PG_NAMESPACE
PG_OPERATOR
PG_PROC
PG_TABLE_DEF
PG_TABLES
PG_TYPE
PG_VIEWS

当您使用带有 --assessment 标志的 redshift 连接器时，系统会提取以下额外的表和视图：

SVV_DISKUSAGE
STV_MV_INFO
STV_WLM_SERVICE_CLASS_CONFIG
STV_WLM_SERVICE_CLASS_STATE

使用 redshift-raw-logs 连接器时，系统会提取以下表和视图：

STL_DDLTEXT
STL_QUERY
STL_QUERYTEXT
PG_USER

当您使用带有 --assessment 标志的 redshift-raw-logs 连接器时，系统会提取以下额外的表和视图：

STL_QUERY_METRICS
SVL_QUERY_QUEUE_INFO
STL_WLM_QUERY

如需了解 Redshift 中的系统视图和表，请参阅 Redshift 系统视图和 Redshift 系统目录表。

Apache Hive/Spark 或 Trino/PrestoSQL

dwh-migration-dumper 工具仅支持通过 Kerberos 向 Apache Hive Metastore 进行身份验证。因此，不使用 --user 和 --password 标志，而是使用 --hive-kerberos-url 标志来提供 Kerberos 身份验证详细信息。

下表介绍了使用提取工具提取 Apache Hive、Spark、Presto 或 Trino 元数据的常用标志。如需了解所有支持的标志，请参阅全局标志。

名称	默认值	说明	必需
`--assessment`		在提取元数据时启用评估模式。 `dwh-migration-dumper` 工具在用于元数据提取时，会生成 BigQuery 迁移评估所需的元数据统计信息。	评估时需要。转换时不需要。
`--connector`		要使用的连接器的名称，在本例中为 hiveql。	是
`--hive-metastore-dump-partition-metadata`	true	让 `dwh-migration-dumper` 工具提取分区元数据。由于 Thrift 客户端性能影响，建议您针对具有大量分区的生产 Metastore 将此标志设置为 `false`。这会提高提取工具性能，但会对 BigQuery 端的分区优化造成一定的损失。请勿将此标志与 `--assessment` 标志结合使用，因为它会无效。	否
`--hive-metastore-version`	2.3.6	当您运行 `dwh-migration-dumper` 工具时，它会根据此标志的值选择要用于与 Apache Hive 服务器通信的适当 Thrift 规范。如果提取工具没有适当的 Thrift 规范，则使用 2.3.6 客户端并向 `stdout` 发出警告。如果发生这种情况，请与支持团队联系，并提供您请求的 Apache Hive 版本号。	否
`--host`	localhost	数据库服务器的主机名或 IP 地址。	否
`--port`	9083	数据库服务器的端口。	否
`--hive-kerberos-url`		用于身份验证的 Kerberos 主账号和主机。	启用了 Kerberos 身份验证的集群需要。
`-Dhiveql.rpc.protection`		RPC 保护配置级别。这决定了集群和 `dwh-migration-dumper` 工具之间的简单身份验证和安全层 (SASL) 连接的保护质量 (QOP)。必须等于集群上 `/etc/hadoop/conf/core-site.xml` 文件中的 `hadoop.rpc.protection` 参数的值，值为以下值之一： `authentication` `integrity` `privacy` 示例 (Bash)： `-Dhiveql.rpc.protection=privacy` 示例 (Windows PowerShell)： `"-Dhiveql.rpc.protection=privacy"`	启用了 Kerberos 身份验证的集群需要。

示例

以下示例展示了如何提取指定主机上的 Hive 2.3.7 数据库的元数据，而无需身份验证，并使用备用端口进行连接：

dwh-migration-dumper \
  --connector hiveql \
  --hive-metastore-version 2.3.7 \
  --host host \
  --port port

如需使用 Kerberos 身份验证，请以对 Hive Metastore 具有读取权限的用户身份登录并生成 Kerberos 票据。然后，使用以下命令生成元数据 ZIP 文件：

JAVA_OPTS="-Djavax.security.auth.useSubjectCredsOnly=false" \
  dwh-migration-dumper \
  --connector hiveql \
  --host host \
  --port port \
  --hive-kerberos-url principal/kerberos_host

Azure Synapse 或 Microsoft SQL Server

如需允许 dwh-migration-dumper 工具连接到 Azure Synapse 或 Microsoft SQL Server，请从 Microsoft 的下载页面下载其 JDBC 驱动程序。

下表介绍了使用提取工具提取 Azure Synapse 或 Microsoft SQL Server 元数据的常用标志。如需了解所有支持的标志，请参阅全局标志。

名称	默认值	说明	必需
`--connector`		要使用的连接器的名称，在本例中为 sqlserver。	是
`--database`		要连接的数据库名称。	是
`--driver`		要用于此连接的驱动程序 JAR 文件的绝对或相对路径。您可以指定多个驱动程序 JAR 文件，并以逗号分隔。	是
`--host`	localhost	数据库服务器的主机名或 IP 地址。	否
`--password`		要用于数据库连接的密码。	是
`--port`	1433	数据库服务器的端口。	否
`--user`		要用于数据库连接的用户名。	是

示例

以下示例展示了如何从指定主机上的 Azure Synapse 数据库提取元数据：

dwh-migration-dumper \
  --connector sqlserver \
  --database database \
  --driver path/mssql-jdbc.jar \
  --host server_name.sql.azuresynapse.net \
  --password password \
  --user user

Netezza

如需允许 dwh-migration-dumper 工具连接到 IBM Netezza，您必须获取其 JDBC 驱动程序。通常，您可以从 IBM Netezza 设备主机上的 /nz/kit/sbin 目录获取该驱动程序。如果您在其中找不到该驱动程序，请向您的系统管理员寻求帮助，或阅读 IBM Netezza 文档中的安装和配置 JDBC。

下表介绍了使用提取工具提取 IBM Netezza 元数据的常用标志。如需了解所有支持的标志，请参阅全局标志。

名称	默认值	说明	必需
`--connector`		要使用的连接器的名称，在本例中为 netezza。	是
`--database`		要提取的数据库列表，以英文逗号分隔。	是
`--driver`		要用于此连接的驱动程序 JAR 文件的绝对或相对路径。您可以指定多个驱动程序 JAR 文件，并以逗号分隔。	是
`--host`	localhost	数据库服务器的主机名或 IP 地址。	否
`--password`		要用于数据库连接的密码。	是
`--port`	5480	数据库服务器的端口。	否
`--user`		要用于数据库连接的用户名。	是

示例

以下示例展示了如何提取指定主机上两个 IBM Netezza 数据库的元数据：

dwh-migration-dumper \
  --connector netezza \
  --database database1,database2 \
  --driver path/nzjdbc.jar \
  --host host \
  --password password \
  --user user

Oracle

如需允许 dwh-migration-dumper 工具连接到 Oracle，请从 Oracle 的下载页面下载其 JDBC 驱动程序。

下表介绍了使用提取工具提取 Oracle 元数据的常用标志。如需了解所有支持的标志，请参阅全局标志。

名称	默认值	说明	必需
`--connector`		要使用的连接器的名称，在本例中为 oracle。	是
`--driver`		要用于此连接的驱动程序 JAR 文件的绝对或相对路径。您可以指定多个驱动程序 JAR 文件，并以逗号分隔。	是
`--host`	localhost	数据库服务器的主机名或 IP 地址。	否
`--oracle-service`		要用于连接的 Oracle 服务名称。	未明确说明，但您必须指定此标志或 `--oracle-sid` 标志。
`--oracle-sid`		要用于连接的 Oracle 系统标识符 (SID)。	未明确说明，但您必须指定此标志或 `--oracle-service` 标志。
`--password`		要用于数据库连接的密码。	如果未指定，则提取工具使用安全提示来请求它。
`--port`	1521	数据库服务器的端口。	否
`--user`		要用于数据库连接的用户名。您指定的用户必须具有 `SELECT_CATALOG_ROLE` 角色才能提取元数据。如需查看用户是否具有所需的角色，请针对 Oracle 数据库运行查询 `select granted_role from user_role_privs;`。	是

示例

以下示例展示了如何使用 Oracle 服务进行连接，然后提取指定主机上的 Oracle 数据库的元数据：

dwh-migration-dumper \
  --connector oracle \
  --driver path/ojdbc8.jar \
  --host host \
  --oracle-service service_name \
  --password password \
  --user user

Snowflake

下表介绍了使用 dwh-migration-dumper 工具提取 Snowflake 元数据的常用标志。如需了解所有支持的标志，请参阅全局标志。

名称	默认值	说明	必需
`--connector`		要使用的连接器的名称，在本例中为 snowflake。	是
`--database`		要连接的数据库名称。一次只能从一个 Snowflake 数据库提取。	是
`--host`	localhost	数据库服务器的主机名或 IP 地址。	否
`--password`		要用于数据库连接的密码。	如果未指定，则提取工具使用安全提示来请求它。
`--role`		要用于授权的 Snowflake 角色。您只需为大型安装指定此角色，在此安装中，您需要从 `SNOWFLAKE.ACCOUNT_USAGE` 架构而不是 `INFORMATION_SCHEMA` 获取元数据。如需了解详情，请参阅处理大型 Snowflake 实例。	否
`--user`		要用于数据库连接的用户名。	是
`--warehouse`		用于处理元数据查询的 Snowflake 仓库。	是

示例

以下示例展示了如何提取本地主机上典型大小的 Snowflake 数据库的元数据：

dwh-migration-dumper \
  --connector snowflake \
  --database database \
  --password password \
  --user user \
  --warehouse warehouse

以下示例展示了如何提取指定主机上大型 Snowflake 数据库的元数据：

dwh-migration-dumper \
  --connector snowflake \
  --database database \
  --host "account.snowflakecomputing.com" \
  --password password \
  --role role \
  --user user \
  --warehouse warehouse

处理大型 Snowflake 实例

dwh-migration-dumper 工具会从 Snowflake INFORMATION_SCHEMA 读取元数据。但是，您可以从 INFORMATION_SCHEMA 检索的数据量是有限制的。如果您运行提取工具并收到错误 SnowflakeSQLException: Information schema query returned too much data，则必须执行以下步骤，以便改为从 SNOWFLAKE.ACCOUNT_USAGE 架构读取元数据：

打开 Snowflake 网页界面中的共享选项。

从 SNOWFLAKE.ACCOUNT_USAGE 共享创建数据库：

-- CREATE DATABASE database FROM SHARE SNOWFLAKE.ACCOUNT_USAGE;

创建角色：
```
CREATE ROLE role;
```

向该角色授予新数据库的 IMPORTED 特权：

GRANT IMPORTED PRIVILEGES ON DATABASE database TO ROLE role;

向您要用于运行 dwh-migration-dumper 工具的用户授予该角色：
```
GRANT ROLE role TO USER user;
```

Vertica

如需允许 dwh-migration-dumper 工具连接到 Vertica，请从 Vertica 下载页面下载其 JDBC 驱动程序。

下表介绍了使用提取工具提取 Vertica 元数据的常用标志。如需了解所有支持的标志，请参阅全局标志。

名称	默认值	说明	必需
`--connector`		要使用的连接器的名称，在本例中为 vertica。	是
`--database`		要连接的数据库名称。	是
`--driver`		要用于此连接的驱动程序 JAR 文件的绝对或相对路径。您可以指定多个驱动程序 JAR 文件，并以逗号分隔。	是
`--host`	localhost	数据库服务器的主机名或 IP 地址。	否
`--password`		要用于数据库连接的密码。	是
`--port`	5433	数据库服务器的端口。	否
`--user`		要用于数据库连接的用户名。	是

示例

以下示例展示了如何提取本地主机上 Vertica 数据库的元数据：

dwh-migration-dumper \
  --driver path/vertica-jdbc.jar \
  --connector vertica \
  --database database
  --user user
  --password password

全局标志

下表介绍了可与任何受支持的源平台结合使用的标志。

名称	说明
`--connector`	源系统的连接器名称。
`--database`	用量因源系统而异。
`--driver`	连接到源系统时要使用的驱动程序 JAR 文件的绝对或相对路径。您可以指定多个驱动程序 JAR 文件，并以英文逗号分隔。
`--dry-run` 或 `-n`	显示提取工具将创建但不执行的操作。
`--help`	显示命令行帮助。
`--host`	要连接的数据库服务器的主机名或 IP 地址。
`--jdbcDriverClass`	（可选）替换供应商指定的 JDBC 驱动程序类名称。如果您有自定义 JDBC 客户端，请使用此标志。
`--output`	输出 ZIP 文件的路径。例如 `dir1/dir2/teradata-metadata.zip`。如果您未指定路径，则系统会在工作目录中创建输出文件。如果您指定了目录的路径，则系统会在指定目录中创建默认 ZIP 文件名。如果目录不存在，则系统会创建目录。如需使用 Cloud Storage，请使用以下格式： `gs://<BUCKET>/<PATH>` 如需使用 Google Cloud 凭据进行身份验证，请参阅使用客户端库时进行身份验证。
`--password`	要用于数据库连接的密码。
`--port`	数据库服务器的端口。
`--save-response-file`	将命令行标志保存在 JSON 文件中，以便重复使用。该文件名为 `dumper-response-file.json`，是在工作目录中创建的。如需使用响应文件，请在运行提取工具时提供该文件以 `@` 为前缀的路径，例如 `dwh-migration-dumper @path/to/dumper-response-file.json`。
`--schema`	要提取的架构列表，以英文逗号分隔。 Oracle 不会区分架构和创建架构的数据库用户，因此您可以将架构名称或用户名与 `--schema` 标志搭配使用，例如 `--schema schema1,user2,schema3`。
`--thread-pool-size`	设置线程池大小，这会影响连接池大小。线程池的默认大小是运行 `dwh-migration-dumper` 工具的服务器上的核心数。如果提取工具似乎很慢或需要更多资源，您可以增加使用的线程数。如果表明服务器上的其他进程需要更多带宽，则您可以减少使用的线程数。
`--url`	要用于数据库连接的网址，而不是由 JDBC 驱动程序生成的 URI。在大多数情况下，生成的 URI 应该足够。只有在需要使用特定于源平台且尚未由此表中列出的某个标志设置的 JDBC 连接设置时，才替换生成的 URI。
`--user`	要用于数据库连接的用户名。
`--version`	显示产品版本。

问题排查

本部分介绍了 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 文件并运行以下命令：

sha256sum --check SHA256SUMS.txt

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

FAILED: computed checksum did NOT match：ZIP 文件已损坏，需要重新下载。
FAILED: listed file could not be read：找不到 ZIP 文件版本。确保校验和以及 ZIP 文件从同一发布版本下载并放在同一目录中。

Teradata 查询日志提取速度缓慢

如需提高 -Dteradata-logs.query-logs-table 和 -Dteradata-logs.sql-logs-table 标志指定的联接表的性能，您可以在 JOIN 条件中额外添加一个类型为 DATE 的列。此列必须在两个表中定义，并且必须是分区主索引的一部分。如需添加此列，请使用 -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。如果超出限制，转储程序将失败并显示以下消息：none [Error 9804] [SQLState HY000] Response Row size or Constant Row size overflow

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

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

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

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 标志将长查询文本拆分为多行，每行最多 10000 个字符：

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"

后续步骤

运行 dwh-migration-dumper 工具后，将输出以及要转换的源文件一起上传到 Cloud Storage。

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

概览

合规要求

前提条件

安装 Java

所需权限

安装 dwh-migration-dumper 工具

运行 dwh-migration-dumper 工具

TeraData

示例

由 dwh-migration-dumper 工具提取的表和视图

Redshift

示例

由 dwh-migration-dumper 工具提取的表和视图

Apache Hive/Spark 或 Trino/PrestoSQL

示例

Azure Synapse 或 Microsoft SQL Server

示例

Netezza

示例

Oracle

示例

Snowflake

示例

处理大型 Snowflake 实例

Vertica

示例

全局标志

问题排查

内存不足错误

Linux

Windows

处理 WARN...Task failed 错误

ZIP 文件损坏

Teradata 查询日志提取速度缓慢

Bash

Windows PowerShell

已超出 Teradata 行大小限制

Bash

Windows PowerShell

Bash

Windows PowerShell

后续步骤

安装 `dwh-migration-dumper` 工具

运行 `dwh-migration-dumper` 工具

由 `dwh-migration-dumper` 工具提取的表和视图

由 `dwh-migration-dumper` 工具提取的表和视图

处理 `WARN...Task failed` 错误