ADD EXTRACT

对支持的 Db2、HP NonStop、MySQL、Oracle、PostgreSQL、SQL Server、Sybase ASE 和 Yugabyte 数据库有效。

使用 ADD EXTRACT 可以创建源数据库捕获进程，称为提取。提取可以创建为更改数据提取（这将从数据库日志或通过其他方式（取决于数据库供应商）捕获当前事务处理），也可以创建为初始加载提取（这将捕获数据库表中存在的记录）。

建议每个源数据库仅创建一个更改数据或一个初始加载提取，但在极少情况下，可以通过每个数据库使用多个提取来提高捕获吞吐量。

Oracle GoldenGate 可以支持每个部署有大量并发提取和复制进程，具体取决于操作系统可用的资源。但是，建议在添加更多提取或复制进程时监视系统资源，并且使每个部署的进程总数不超过 300。

注意：

如果要创建与旧提取同名的提取，请确保已完全删除旧提取。您可以使用 DELETE EXTRACT 删除提取及其所有组件。
对于所有关键字和输入（包括您为 DESC 选项输入的任何文本），此命令大小不能超过 500 字节。
对于 Db2 for i，此命令会为所有日志建立一个全局起点，并且是必须执行的第一步。在发出 ADD EXTRACT 命令之后，您可以根据需要使用带有相应日志选项的 ALTER EXTRACT 命令来将给定日记放在特定的日志序号处。
对于 Oracle 和 PostgreSQL 数据库，使用 DBLOGIN USERIDALIAS 建立与源数据库的连接，然后在添加提取之前发出 REGISTER EXTRACT 命令。有关详细信息，请参见 REGISTER EXTRACT 命令。
对于 SQL Server，在添加提取之前，使用 DBLOGIN USERIDALIAS 建立与源数据库的连接。管理服务将身份证明信息与提取进程绑定时，需要此连接。

语法

ADD EXTRACT extract-name
|             { SOURCEISTABLE |
|              [ INTEGRATED ] TRANLOG
|               {, BEGIN     [ NOW | yyyy-mm-ddThh:mm.ssZ | LSN value | EOL | EOF | EXTRBA archive-offset-number |  SCN  scn }
|               [, DESC        description    ]
|               [, CRITICAL    [ YES | NO ]     ]
|               [, ENCRYPTIONPROFILE     encryption-profile-name]
|               [, GTIDSET gtidset
|               [, PROFILE
|                 [ AUTOSTART   [ YES | NO ]
|                       [ DELAY     delay-number   ] ]
|                 [ AUTORESTART [ YES | NO ]
|                       [ RETRIES          retries-number ]
|                       [ WAITSECONDS      wait-number    ]
|                       [ RESETSECONDS     reset-number   ]
|                       [ DISABLEONFAILURE [ YES | NO ] ] ] ]
|               [ LOGNUM lognum]
|               [ LOGPOS logpos]

extract_name

提取的名称。它最多可以包含八个字符，请参见 Choosing Names for Processes and Files 。

SOURCEISTABLE

创建一个提取任务，该任务使用 Oracle GoldenGate 从指定表中提取整个记录进行初始加载。在使用 SOURCEISTABLE 时，不指定任何服务选项。

必须要在参数文件中指定任务参数，请参见《 Oracle GoldenGate Microservices Documentation 》中的使用管理客户机添加初始加载提取。

TRANLOG [bsds_name]

可对所有数据库使用此选项。TRANLOG 需要 BEGIN 选项。

（z/OS 上的 Db2）对于 z/OS 系统上的 Db2，您可以使用 bsds_name 选项指定事务处理日志的引导数据集文件名，不过此文件不是必需的而且不会使用。您无需更改现有的 TRANLOG 参数。

(Oracle) 提取进程直接读取 Oracle 重做日志。有关替代配置，请参见 INTEGRATED TRANLOG。

INTEGRATED TRANLOG

对 Oracle 有效。

以集成捕获模式添加提取。在该模式下，提取进程与数据库日志挖掘服务器集成，该服务器将逻辑更改记录 (Logical Change Record, LCR) 直接传递到提取。使用 INTEGRATED TRANLOG 之前，请使用 REGISTER EXTRACT 命令。

BEGIN {NOW yyyy-mm-ddthh:mm.ssZ}

在数据源中指定开始处理的时间戳。

注：在将提取定位到特定时间戳之前，必须注册提取。

NOW

NOW 指定 ADD EXTRACT 命令的发出时间和提取的启动日期，这将尝试在该特定时间或之后定位到事务处理边界。通过 NOW 定位提取不如其他方法（例如通过 LSN、SCN 或 LRI 定位）准确，并且要求将数据库服务器和 Oracle GoldenGate 服务器设置为相同的时间和时区。

对于 Db2 LUW，仅提交和结束事务处理记录包含时间戳，因此只能相对于这些时间戳计算提取起始位置。这是 Oracle GoldenGate 使用的 API 的限制。请务必注意，通过时间戳进行定位是不准确的，且可能需要很长时间。建议尽可能使用 LRI 或 EOL 选项。
yyyy-mm-ddthh:mm.ssZ

给定形式的日期和时间（时间戳）。例如，2017-07-14T14:54:45Z。
yyyy-mm-ddT[ hh:mi:[ss[.cccccc]]]Z

给定形式的日期和时间（时间戳）。对于 Oracle 提取或 Extract for PostgreSQL，时间戳值必须大于在数据库中注册提取时的时间戳值。

PostgreSQL 中的按时间戳定位包括以下场景：
- 场景 1
  
  如果 track_commit_timestamp 为 off，则无论使用哪种定位方法，提取进程启动时都会显示以下输出：
```
2020-04-29T02:15:54Z
```
- 场景 2
  
  如果在注册提取之前启用 track_commit_timestamp，则在记录推送到源数据库中后，就会显示正确的时间戳，如下例中所提及：
```
2020-04-29 02:19:07 INFO OGG-01515 Positioning to begin time Apr 29,2020 2:18:38 AM.
```
- 场景 3
  
  如果在注册提取之后启用 track_commit_timestamp，则日志中存在的较早记录可能未使用关联的 transaction ID 构建提交时间戳。在这种情况下，如果提取未获取时间戳，则它将使用场景 1 中所提及的默认时间戳进行回退。输出将与以下内容类似：
```
020-04-29 01:55:07 INFO OGG-01517 Position of first record processed LSN: 0/221D028, Jan 1, 1970 12:00:00 PM.
```
- 如果复制插槽已移开，则无法指定过去的时间戳。

EXTRBA archive-offset_number

对 Db2 z/OS 有效。

指定事务处理日志中开始捕获数据的相对字节地址。

所需格式为 0Xnnn，其中 nnn 是 1 至 20 位十六进制数字（第一个字符为数字零，第二个字符可以为大写或小写字母，x）。

EOL

对 Db2 for i、Db2 LUW、MySQL、PostgreSQL 和 SQL Server 有效。

将处理的开始位置配置为将在其中写入下一条记录的日志文件（或日志）的末尾。不捕获任何处于活动状态的事务处理。

对于 Db2 LUW，它将处理的开始位置配置日志文件中的活动 LRI 值。活动 LRI 值是下一条记录将写入的日志文件的末尾位置。不捕获任何处于活动状态的事务处理。

对于 PostgreSQL，按 EOL 定位需要使用 DBLOGIN。

对于 MySQL，将查找与文件末尾对应的位置，并从此处开始读取事务处理。如果数据连续写入二进制日志，则 EOL 位置不准确。

EOF

对 MySQL、Db2 z/OS、Db2 LUW、SQL Server、PostgreSQL、Oracle GoldenGate for DAA 有效。

LSN value

对 Db2 z/OS、PostgreSQL 和 SQL Server 有效

指定从中开始捕获数据的事务处理 LSN。此选项的别名为 EXTLSN。定位到 LSN 是精确的。

对于 Db2 z/OS，LSN 值可以是一系列十六进制数字或一系列十进制数字。如果是十六字符格式，则必须以 0X 或 0x 为前缀，后跟 1 到 20 个十六字符数字：0-9、a-g 或 A-G。如果是十进制格式，则没有前缀，并且有 1-25 个十进制数字 0-9。

对于 PostgreSQL，LSN 值可以为 hi 或 lo。对于日志文件入口点，将该值设置为 hi。Lo 是日志文件中的偏移量。LSN 位置应该位于复制插槽重新启动位置和预写日志当前位置之间。如果指定的位置本身存在于所提及范围之间，则提取将引发错误。

对于 SQL Server，LSN 指定从中开始捕获数据的事务处理 LSN。此选项的别名为 EXTLSN。

指定的 LSN 应该作为在 cdc.lsn_time_mapping 系统表中找到的有效 tran_begin_lsn 存在，否则提取将尝试在提供的 LSN 的值之后定位。

SQL Server 的有效 LSN 规范包括以下内容：

冒号分隔的十六进制字符串 (8:8:4)，前面填充前导零和 0X 前缀，如下所示：0X00000d7e:0000036b:0001
冒号分隔的十六进制字符串，具有 0X 前缀、没有前导零，如下所示：0Xd7e:36b:1

可以通过查询以下内容来查找可用的最小 LSN：

SELECT min([tran_begin_lsn]) FROM [cdc].[lsn_time_mapping] with (nolock) where tran_id <> 0x00

以下示例显示了对 Db2 z/OS 使用 LSN 值：

示例 1：

ADD EXTRACT extn TRANLOG, LSN 0xDEE40E4F27A3245400

示例 2：

ADD EXTRACT extn TRANLOG, LSN 22216433159121980904448

以下示例显示了 SQL Server 的 LSN 值：

ADD EXTRACT extn TRANLOG, LSN 0X00000d7e:0000036b:0001

LRI value

对 Db2 LUW 有效。指定事务处理日志中开始提取的起始位置。

对于 Db2 LUW 系统，您可以使用 LRI 选项指定 LRI，提取流程将从事务处理日志中的此位置开始捕获记录。您可以使用 Db2 实用程序 db2logsForRfwd 获取 LRI。此实用程序提供 Db2 日志中存在的 LRI 范围。

请注意，尽管提取可以将位置定位到给定的 LRI，但是该 LRI 不一定是提取将处理的第一条记录。提取可能会忽略日志文件中的许多记录类型，例如 Db2 内部日志记录。提取会将实际的起始 LRI 报告给提取报告文件。

LOGNUM lognum

对 MySQL 有效。

这是日志文件编号。如果 LOGNUM 值有前导零，ADD EXTRACT 将失败。例如，ADD EXTRACT ext1, TRANLOG, LOGNUM 000001, LOGPOS 0 将会失败。而将 LOGNUM 设置为 1，此示例可成功。

LOGPOS logpos

这是日志文件中标识特定事务处理记录的事件偏移值。事件偏移值存储在日志记录的标头部分。要定位在 binlog 文件的开头，则将 LOGPOS 设置为 0。

SEQNO sequence_number

对 Db2 for i 有效。在系统序号处或紧挨其后开始捕获，系统序号是长达 20 位的十进制数字。

SCN value

对 Oracle 有效。

从具有指定 Oracle 系统更改号 (System Change Number, SCN) 的重做日志中的事务处理开始提取。对于集成模式下的提取，SCN 值必须大于在数据库中注册提取时的 SCN 值。有关更多信息，请参见 REGISTER EXTRACT 。

PARAMS file_name

指定提取参数文件在 Oracle GoldenGate 目录中的默认位置 dirprm 之外的位置的完整路径名。

REPORT file_name

指定提取报告文件在 Oracle GoldenGate 目录中的默认位置 dirrpt 之外的位置的完整路径名。

DESC ‘description’

指定组的说明，例如 'Extracts account_tab on Serv1'。用单引号括起说明。

ENCRYPTIONPROFILE

指定与特定客户端相关联的 Oracle GoldenGate 加密概要文件的名称。

GTIDSET gtidset

对 MySQL 有效。

通过使用位置类型作为 GTID 集，指定提取的初始定位，以对 MySQL 进行基于 GTID 的捕获。GTID 集支持的 MySQL 源为 MySQL Server 8.0 及更高版本。支持的最大 GTID 集大小为 64 KB。

语法：

ADD EXTRACT extract_name, TRANLOG, GTIDSET gtidset

CRITICAL

指示进程对于部署是否至关重要。

PROFILE

自动启动概要文件的名称。

AUTOSTART

指定当管理服务启动时是否必须自动启动托管进程。默认值为 YES。

DELAY

启动进程之前等待的时间，以秒为单位。

AUTORESTART

控制进程终止时将如何重新启动进程。

RETRIES

取消重试之前重新启动任务的最大尝试次数。此项是可选的。

WAITSECONDS

计算重试次数的持续时间（以秒为单位）。

RESETSECONDS

重置重试次数的计算持续时间。

DISABLEONFAILURE

如果设置为 TRUE，则在重试次数用尽时将禁用该任务。

SOCKSPROXY {host_name IP_address}[:port] [PROXYCSALIAS credential_store_alias [PROXYCSDOMAIN credential_store_domain]

用于别名提取。指定代理服务器的 DNS 主机名或 IP 地址。您可以使用 DNS 主机名或 IP 地址定义主机，但是当 DNS 服务器无法访问时，必须使用 IP 地址。如果您使用的是 IP 地址，则根据目标系统的堆栈使用 IPv6 或 IPv4 映射地址。必须指定 PROXYCSALIAS。另外，您可以指定要使用的端口和身份证明存储域。

示例

以下示例创建一个名为 exte 的提取组，该组从事务处理日志中捕获数据库更改。提取从使用 ADD EXTRACT 创建和启动提取组时生成的记录开始。

ADD EXTRACT extn, TRANLOG, BEGIN NOW

在以下示例中，创建一个名为 extw 的提取组，以通过将提取定位到特定时间戳，从事务处理日志中获取数据库更改：

ADD EXTRACT extn, TRANLOG, BEGIN NOW

REGISTER EXTRACT extn DATABASE

ALTER EXTRACT extn BEGIN 2020-08-02T06:05:30.000Z

以下示例创建一个集成的提取组。

ADD EXTRACT extn, INTEGRATED TRANLOG, BEGIN NOW

以下示例创建一个名为 extei 的初始加载提取。

ADD EXTRACT extn, SOURCEISTABLE

以下示例包括 GTID 集的有效格式的所有组合。

示例 1：

ADD EXTRACT exte, TRANLOG, GTIDSET "E11FA47-71CA-11E1-9E33-C80AA9429562:4"

示例 2：

ADD EXTRACT exts, TRANLOG, GTIDSET "3E11FA47-71CA-11E1-9E33-C80AA9429562:1-10"

示例 3：

ADD EXTRACT extn, TRANLOG, GTIDSET "3E11FA47-71CA-11E1-9E33-C80AA9429562:1-3:11:47-49"

示例 4：

ADD EXTRACT extw, TRANLOG, GTIDSET "2174B383-5441-11E8-B90A-C80AA9429562:1-3,24DA167-0C0C-11E8-8442-00059A3C7B00:1-19"

注：如示例 4 所示，当 GTID 集包含多个 uuid 时，要形成 REST API 请求，使用逗号分隔符将此 GTID 集拆分为多个 GTID 集。

以下几个示例创建提取，并将其定位到重做日志中的特定 Oracle 系统更改号 (System Change Number, SCN)。

ADD EXTRACT extn TRANLOG SCN 123456

ADD EXTRACT extn INTEGRATED TRANLOG SCN 123456

以下示例在 Db2 LUW 系统上创建提取。

ADD EXTRACT extn, TRANLOG LRI 8066.322711

以下示例使用管理客户端通过 autostart 选项创建提取。

ADD EXTRACT extn, TRANLOG , BEGIN NOW , AUTOSTART yes