ALTER EXTRACT

使用 ALTER EXTRACT 可以实现以下目的：

• 更改使用 ADD EXTRACT 命令创建的提取组的属性。

• 将线索递增到序列中的下一个文件。

• 升级到集成捕获配置。

• 从集成捕获配置降级。

• 将任何给定 Db2 for i 日志定位到特定的日志序号处。

使用此命令之前，请先使用 STOP EXTRACT group_name 命令停止提取。

语法

ALTER EXTRACT group-name
         [, BEGIN {NOW | yyyy-mm-dd[ hh:mi:[ss[.cccccc]]]} |
|            [, EXTRBA archive-offset-number]
|            [, ADD_EXTRACT_attribute  | SCN value]
|            [, LSN
|            [, EOL
|            [, DESC
|            [ CRITICAL    [ YES | NO ]     ]
|            [ ENCRYPTIONPROFILE     encryption-profile-name]
|            [ 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

i 支持使用以下 Db2 选项定位给定日志的提取：ALTER EXTRACT

ALTER EXTRACT {BEGIN {NOW | yyyy-mm-ddT[ hh:mi:[ss[.cccccc]]Z]}
[JOURNAL journal_library/journal_name [JRNRCV receiver_library/
  receiver_name]] |
, EOL [JOURNAL journal_library/journal_name
  [JRNRCV receiver_library/receiver_name]] |
, SEQNO sequence_number [JOURNAL journal_library/journal_name
  [JRNRCV receiver_library/receiver_name]]}

BEGIN {NOW | yyyy-mm-ddT[ hh:mi:[ss[.cccccc]]]Z} [JOURNAL journal_library/journal_name [JRNRCV receiver_library/ receiver_name]] | , EOL [JOURNAL journal_library/journal_name [JRNRCV receiver_library/receiver_name]] | , SEQNO sequence_number [JOURNAL journal_library/journal_name [JRNRCV receiver_library/receiver_name]]

这些 IBM for i 选项允许在使用 ADD EXTRACT 发出全局起点后进行特定于日志的提取定位。使用 ALTER EXTRACT 设置的特定日志位不影响以前使用 ADD EXTRACT 或 ALTER EXTRACT 设置的任何全局位置；但是，使用 ALTER EXTRACT 设置的整体位置会覆盖以前在同一提取配置中设置的任何特定日志位。

注意：SEQNO 与 `ALTER' 中的日志一起使用时

          EXTRACT`, is the journal sequence number that is relative to that specific journal, not the system sequence number that is global across journals.
          {: .infoboxnote}

group-name

要变更的提取组的名称。

{BEGIN {NOW

Tyyyy-mm-dd[ hh:mi:[ss[.cccccc]]]Z}

NOW

对于除 Db2 LUW 以外的所有数据库，NOW 指定 ALTER EXTRACT 命令的发出时间。

NOW 指定 ALTER EXTRACT 命令的发出时间。

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

YYYY-MM-DDThh:mm:ssZ

给定形式的日期和时间（时间戳）。例如 2017-07-14T14:54:45Z。

yyyy-mm-dd[ hh:mi:[ss[.cccccc]]]

给定形式的日期和时间（时间戳）。对于集成模式下的 Oracle 提取，时间戳值必须大于在数据库中注册提取时的时间戳值。

按 SQL Server 事务处理日志中的时间戳定位受 SQL Server 的以下特征影响：

• SQL Server 事务处理日志中记录的时间戳使用 3.3333 微秒 (ms) 粒度。如果两个事务处理在相同的 3.3333 微秒时间间隔内开始，则此粒度级别可能不允许按时间在这两个事务处理之间定位。

• 时间戳并非记录在每个 SQL Server 日志记录中，而是只记录在开始和提交事务处理的记录中，以及其他一些不包含数据的记录中。

• SQL Server 时间戳并非来自系统时钟，而是来自特定于所使用的单个处理器的内部时钟。此时钟每秒更新几次，但是在更新之间，它可能与系统时钟不同步。这进一步降低了按时间定位的精度。

• 为日志备份文件记录的时间戳可能与备份中记录的时间不完全一致（但是这种不精确小于 1 秒）。

定位到 LSN 是精确的。

PostgreSQL 中的按时间戳定位包括以下场景：

• 场景 1

  如果 track_commit_timestamp 为 off，则无论使用哪种定位方法，提取进程启动时都会显示以下输出：

  2020-04-29 02:15:54 INFO OGG-01517 Position of first record processed LSN: 0/2222C20, Jan 1, 1970 12:00:00 PM.

• 场景 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.

• 如果复制插槽已移开，则无法指定过去的时间戳。

START

对 PostgreSQL 有效。

在不提及 BEGIN NOW 或 LSN 的的情况下添加提取。提取将从复制插槽重新启动位置自动启动。

ADD_EXTRACT_attribute

可以更改通过 ALTER EXTRACT 命令指定的任何属性，以下情况除外：

• 变更通过 EXTTRAILSOURCE 选项指定的提取。

• 变更通过 THREADS 选项指定的 RAC 线程数。

对于这些例外情况，请删除提取组，然后重新添加。

如果使用 BEGIN 选项，则不要在该语句中结合其他选项。请发出单独的语句，例如：

ALTER EXTRACT exte, BEGIN 2019-01-01
ALTER EXTRACT exte, ETROLLOVER
ALTER EXTRACT exte, SCN 789000

如果将 SCN 或 BEGIN 选项用于集成提取，则需要 DBLOGIN，并且指定的 SCN 或时间戳值不能小于出站服务器的第一个 SCN 或时间戳。要查找出站服务器的第一个 SCN，请发出以下命令：

INFO EXTRACT group_name, SHOWCH DETAIL

将列出第一个 SCN 值，如以下示例中所示：

Integrated Extract outbound server first scn: 0.665884 (665884)

EXTRBA 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 位置不准确。

TRANLOG LRI LRI_number

(Db2 LUW) 可以对 Db2 LUW 系统使用此选项以指定检查点事务处理日志的 LRI 记录值。

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

REPORT file_name

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

SCN value

对 Oracle 有效。

从具有指定 Oracle 系统更改号 (System Change Number, SCN) 的重做日志中的事务处理开始提取。对于提取，SCN 值必须大于在数据库中注册提取时的 SCN 值。对于 SCN 或 BEGIN 选项，需要使用 DBLOGIN，并且指定的 SCN 或时间戳值不能小于出站服务器的首个 SCN 或时间戳。

LSN value

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

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

对于 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：

ALTER EXTRACT extn TRANLOG, LSN 0xDEE40E4F27A3245400

示例 2：

ALTER EXTRACT extn TRANLOG, LSN 22216433159121980904448

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

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

LOGNUM

对 MySQL 有效。

这是日志文件编号。例如，如果所需的日志文件名为 test.000034，则 LOGNUM 值为 34。提取将搜索此日志文件。注：在微服务体系结构中，如果 LOGNUM 值有前导零，ALTER EXTRACT 将失败。例如，ALTER EXTRACT ext1, TRANLOG, LOGNUM 000001, LOGPOS 0 将会失败。而将 LOGNUM 设置为 1，此示例可成功。

LOGPOS

对 MySQL 有效。

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

ETROLLOVER

用于需要重新定位和重新生成主要提取的线索文件的手动恢复情况，以及从以前的版本升级 Oracle GoldenGate 时。

使提取创建线索文件的新原型，并在重新启动时递增到线索序列中的下一个文件，从而需要将泵或复制等读进程手动重新定位到新的线索序号。

使用 ETROLLOVER 时，提取将捕获指定 SCN（提取从中开始）之后的所有记录，而不管其是否已经被捕获并写入到线索。如果不使用 ETROLLOVER，提取将跳过对已经被捕获并写入到线索的任何记录的捕捉。

从 19c 开始，在分发服务处理期间：

• 如果使用目标线索文件 ETROLLOVER 升级源部署上的主要提取，则 theDistribution 服务将自动检测源线索文件 ETROLLOVER，并且从下一个输入线索文件开始读。这是与数据泵 ALTER EXTRACT groupname EXTSEQNO seqno+1 EXTRBA 0 相同的命令。

• 升级分发服务后，将会在重新启动时自动执行输出线索文件的 ETROLLOVER，并且正确写入下一个线索文件。这与数据泵 ALTER EXTRACT groupname ETROLLOVER 相同。

DESC ‘description’

指定组的说明，例如 'Extracts account_tab on Serv1'。用单引号括起说明。可以使用缩写关键字 DESC 或完整单词 DESCRIPTION。

ENCRYPTIONPROFILE

指定提取的加密概要文件的名称。此名称区分大小写，因此使用的名称必须与通过 ADD EXTRACT 输入的名称完全相同。

GTIDSET gtidset

对 MySQL 有效。

通过使用 GTID 集的位置类型选项指定提取的初始定位，以对 MySQL 进行基于 GTID 的捕获。GTID 集支持的 MySQL 源为 MySQL Server 8.0、MySQL Server 5.7、MySQL 数据库服务 (MySQL Database Service, MDS)。支持的最大 GTID 集大小为 64 KB。

语法：

ALTER EXTRACT extract_name, TRANLOG, GTIDSET gtidset

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

示例 1：

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

示例 2：

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

示例 3：

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

示例 4：

ALTER 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 集。

CRITICAL

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

PROFILE

自动启动概要文件的名称。此名称区分大小写，因此使用的名称必须与通过 ALTER EXTRACT 输入的名称完全相同。

AUTOSTART

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

RETRIES

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

WAITSECONDS

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

RESETSECONDS

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

DISABLEONFAILURE

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

INFO EXTRACT group-name, SHOWCH DETAIL

将列出第一个 SCN 值，如以下示例中所示：

Integrated Extract outbound server first scn: 0.665884 (665884)

示例

---

以下示例将提取变更为从 2019 年 1 月 1 日开始处理数据。

ALTER EXTRACT exte, BEGIN 2019-01-01

---

以下示例将提取变更为从线索中的特定位置开始处理。

ALTER EXTRACT exte, EXTSEQNO 26, EXTRBA 338

---

以下示例将 SQL Server 环境中的提取变更为从特定 LSN 开始。

ALTER EXTRACT exte, LSN 0Xd7e:36b:1

---

以下示例将提取变更为递增到线索序列中的下一个文件。

ALTER EXTRACT exte, ETROLLOVER

---

以下示例将提取变更为升级到集成捕获。

ALTER EXTRACT exte, UPGRADE INTEGRATED TRANLOG

---

以下命令使用 ETROLLOVER 通过向后 SCN 778899 防止筛选重复记录。

ALTER EXTRACT exte, SCN 778899
ALTER EXTRACT exte ETROLLOVER
START EXTRACT exte

不使用 ETROLLOVER 时，如果将提取变前一个 SCN 值，则将不处理重复记录。将提取变更为筛选重复记录的命令如下：

ALTER EXTRACT exte, SCN 778899
START EXTRACT exte

---

以下示例显示 IBM for i 日志起点的 ALTER EXTRACT。

ALTER EXTRACT exte, SEQNO 1234  JOURNAL accts/acctsjrn

---

以下示例显示 IBM for i 日志和接收方起点的 ALTER EXTRACT。

ALTER EXTRACT exte, SEQNO 1234 JOURNAL accts/acctsjrn JRNRCV accts/jrnrcv0005

---

以下示例变更 Db2 LUW 系统上的提取。

ALTER EXTRACT exte, TRANLOG LRI 8066.322711

---

以下示例显示用于 PostgreSQL 的 ALTER EXTRACT 选项：

ALTER EXTRACT exte, EOL
ALTER EXTRACT POSTEXT, LSN 0/156784
ALTER EXTRACT POSTEXT, BEGIN 2022-02-18T14:50:43.4230Z