ALTER EXTRACT

ALTER EXTRACTは、次の目的で使用します。

ADD EXTRACTコマンドで作成したExtractグループの属性を変更する
次の順序のトレイル・ファイルに切り替える
統合キャプチャの構成にアップグレードする
統合キャプチャの構成からダウングレードする
特定のDb2 for iジャーナルを特定のジャーナル順序番号に配置します。

このコマンドを使用する前に、STOP EXTRACT group_nameコマンドを使用してExtractを停止します。

Admin Client構文

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

次のALTER EXTRACTオプションは、特定のジャーナルに対してExtractを配置するためにDb2 for iでサポートされています:

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オプションでは、グローバル開始位置より後のジャーナル固有のExtract位置がADD EXTRACTで発行されます。ALTER EXTRACTで設定された特定のジャーナル位置は、ADD EXTRACTまたはALTER EXTRACTで前に設定されたグローバル位置に影響しません。ただし、ALTER EXTRACTで設定されたグローバル位置は、同じExtract構成で前に設定された特定の仕訳位置を上書きします。

ノート:
SEQNOは、ALTER EXTRACTのジャーナルで使用する場合に、ジャーナル全体でグローバルであるシステム順序番号ではなく、特定のジャーナルに相対的なジャーナル順序番号です。

group-name

変更するExtractグループの名前。

{BEGIN {NOW | Tyyyy-mm-dd[ hh:mi:[ss[.cccccc]]]Z}

NOW

Db2 LUW以外のすべてのデータベースで、NOWはALTER EXTRACTコマンドが発行される時刻を指定します。

NOWは、ADD EXTRACTコマンドを発行する時刻を指定します。

Db2 LUWの場合、コミットおよび終了トランザクション・レコードにのみタイムスタンプが含まれるため、Extractの開始位置はそれらのタイムスタンプを基準としてのみ計算できます。これは、Oracle GoldenGateが使用するAPIの制限によるものです。タイムスタンプによる位置設定は正確ではなく、長い時間がかかる可能性があることに注意する必要があります。可能な場合には、LRIまたはEOLオプションを使用することをお薦めします。

YYYY-MM-DDThh:mm:ssZ

指定された形式の日付と時刻(タイムスタンプ)。たとえば、2017-07-14T14:54:45Zです。

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

指定された形式の日付と時刻(タイムスタンプ)。統合モードのOracle Extractでは、タイムスタンプ値はExtractがデータベースに登録された時点のタイムスタンプよりも大きい必要があります。

SQL Serverトランザクション・ログのタイムスタンプで位置を決定する場合、SQL Serverの次の特性によって影響を受けます。

SQL Serverトランザクション・ログに記録されているタイムスタンプは、3.3333マイクロ秒(ms)の粒度を使用します。このレベルの粒度では、2つのトランザクションが同じ3.3333ミリ秒の時間間隔で開始する場合、2つのトランザクションの時間差に基づいて開始位置を決定できないことがあります。
タイムスタンプは、すべてのSQL Serverログ・レコードではなく、トランザクションを開始してコミットしたレコード、およびデータが含まれないその他の一部のレコードのみに記録されます。
SQL Serverのタイムスタンプは、システム・クロックではなく、使用中の各プロセッサ固有の内部クロックに基づいています。このクロックは1秒間に数回更新されますが、更新から更新までの間にシステム・クロックとの同期が外れることがあります。その場合、時刻で決定する開始位置の正確さがさらに低下します。
ログ・バックアップ・ファイルに記録されるタイムスタンプは、バックアップ内に記録された時刻と正確に一致しない可能性があります(ただし、不正確さは1秒未満です)。

LSNを使用した位置決めのほうが正確です。

PostgreSQLのタイムスタンプによる位置指定には、次のシナリオがあります。

シナリオ1
track_commit_timestampがoffの場合、Extractプロセスが開始されると、使用する位置指定方法に関係なく、次の出力が表示されます。
```
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
Extractが登録される前にtrack_commit_timestampが有効になっている場合、次の例に示すように、レコードがソース・データベースでプッシュされると、正しいタイムスタンプが表示されます。
```
2020-04-29 02:19:07 INFO OGG-01515 Positioning to begin time Apr 29,2020 2:18:38 AM.
```
シナリオ3
Extractの登録後にtrack_commit_timestampが有効になっている場合、関連付けられたtransaction IDでコミット・タイムスタンプが構成されていないログに古いレコードが存在する可能性があります。その場合、Extractでタイムスタンプが取得されないと、シナリオ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を指定せずにExtractを追加します。Extractは、レプリケーション・スロットの再開位置から自動的に開始されます。

ADD_EXTRACT_attribute

次の例外を除き、ADD EXTRACTコマンドで指定した任意の属性を変更できます。

EXTTRAILSOURCEオプションで指定したExtractの変更。
THREADSオプションで指定したRACスレッド数の変更。

このような例外に該当する場合は、対象のExtractグループを削除し、このグループをもう一度追加してください。

BEGINオプションを使用している場合は、同じ文に他のオプションを指定しないでください。別の文を発行してください。たとえば:

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

統合Extractに対して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桁の16進数(最初の文字は桁を表すゼロで、2番目の文字は大文字または小文字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

Extractレポート・ファイルの保管場所の完全パス名を、Oracle GoldenGateディレクトリ内のデフォルトのdirrpt以外に指定します。

SCN value

Oracleに有効です。

指定されたOracleシステム変更番号(SCN)を持つREDOログ内のトランザクションからExtractを開始します。Extractでは、SCN値はExtractがデータベースに登録された時点のSCNよりも大きい必要があります。SCNまたはBEGINオプションの場合、DBLOGINが必要であり、指定されたSCNまたはタイムスタンプ値はアウトバウンド・サーバーの最初のSCNまたはタイムスタンプ未満にすることはできません。

LSN value

Db2 z/OS、PostgreSQLおよびSQL Serverに有効です。

データ取得を開始するトランザクションLSNを指定します。このオプションの別名はEXTLSNです。指定されたLSNは、cdc.lsn_time_mappingシステム表内に存在する有効なtran_begin_lsnとして存在する必要があります。存在しない場合、Extractは、指定されたLSN値の後に配置しようとします。

Db2 z/OSの場合、必要なフォーマットは0Xnnnで、nnnは1から20桁の16進数です(最初の文字は数字のゼロで、2番目の文字は大文字または小文字のxです)。

PostgreSQLの場合、LSN値はhiまたはloです。ログ・ファイルのエントリ・ポイントで値をhiに設定します。Loは、ログ・ファイル内のオフセットです。LSNの位置は、レプリケーション・スロットの再開位置と、ログ先行書込みの現在の位置の間にある必要があります。指定した位置自体が指定した範囲内に存在する場合は、Extractによってエラーがスローされます。

SQL Serverでは、データ取得を開始するトランザクションLSNを指定します。このオプションの別名はEXTLSNです。

指定されたLSNは、cdc.lsn_time_mappingシステム表内に存在する有効なtran_begin_lsnとして存在する必要があります。存在しない場合、Extractは、指定されたLSN値の後に配置しようとします。

有効なLSN指定には、次のものが含まれます。

0X00000d7e:0000036b:0001のように、先行ゼロと接頭辞0Xを付けたコロン区切り16進数文字列(8:8:4)
0Xd7e:36b:1のように、接頭辞0Xを付けた先行ゼロなしのコロン区切り16進数文字列

次をものを問い合せることで、使用可能な最小LSNを検索できます。

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

例:

ALTER EXTRACT extsql LSN 0X00000d7e:0000036b:0001

LOGNUM

MySQLに有効です。

これはログ・ファイル番号です。たとえば、必要なログ・ファイルの名前がtest.000034である場合、LOGNUM値は34です。Extractでは、このログ・ファイルが検索されます。

ノート:

Microservices Architectureでは、LOGNUM値の前にゼロが含まれる場合、ADD EXTRACTが失敗します。たとえば、ADD EXTRACT ext1, TRANLOG, LOGNUM 000001, LOGPOS 0は失敗します。かわりに、LOGNUMを1に設定すると、この例は成功します。

LOGPOS

MySQLに有効です。

これはログ・ファイル内のイベント・オフセット値で、特定のトランザクション・レコードを識別します。イベント・オフセット値は、ログ・レコードのヘッダー・セクションに格納されます。binlogファイルの先頭に配置するには、LOGPOSを0に設定します。

ETROLLOVER

手動リカバリでプライマリExtractの証跡ファイルの再配置および再生成が必要な場合、および以前のバージョンからOracle GoldenGateをアップグレードする場合に使用します。

Extractで証跡ファイルのインカネーションが新規作成され、再起動時に次の証跡順序のファイルに切り替えられます。ポンプまたはReplicatなどのリーダーをその新しい証跡順序番号に手動で再配置する必要があります。

ETROLLOVERを指定した場合、Extractは、Extractが開始された指定のSCNの後のすべてのレコードを、すでにキャプチャされて証跡に書き込まれたかどうかに関係なくキャプチャします。ETROLLOVERが指定されていない場合、Extractは、すでにキャプチャされて証跡に書き込まれたレコードのキャプチャをスキップします。

19c以降、分散サービスの処理中は次のようになります。

ソース・デプロイメントにあるプライマリExtractがターゲット証跡ファイルETROLLOVERでアップグレードされた場合は、分散サービスにより、ソース証跡ファイルETROLLOVERが自動的に検出され、次の入力証跡ファイルから読取りが開始されます。これは、データ・ポンプのALTER EXTRACT groupname EXTSEQNO seqno+1 EXTRBA 0と同じコマンドです。
分散サービスがアップグレードされると、再起動時に出力証跡ファイルのETROLLOVERが自動的に実行され、次の証跡ファイルに適切に書き込まれます。これは、データ・ポンプのALTER EXTRACT groupname ETROLLOVERと同じです。

DESC 'description'

グループの説明('Extracts account_tab on Serv1'など)を指定します。説明を一重引用符で囲みます。短縮キーワードDESCまたは完全なキーワードDESCRIPTIONを使用できます。

ENCRYPTIONPROFILE

Extractの暗号化プロファイルの名前を指定します。この名前は大/小文字が区別されるため、ADD EXTRACTで入力した名前と完全に一致するものを使用する必要があります。

GTIDSET gtidset

MySQLに有効です。

MySQLのGTIDベース取得のGTIDセット・オプションを設定する位置タイプを使用して、Extractの初期位置を指定します。GTIDセットでサポートされているMySQLソースは、MySQL Server 8.0、MySQL Server 5.7、MySQL Database Service (MDS)です。サポートされている最大GTIDセット・サイズは64 KBです。

構文:

ADD EXTRACT extract_name, TRANLOG, GTIDSET gtidset

次の例は、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セットに分割されます。

CRITICAL

プロセスがデプロイメントにとって重要かどうかを示します。

PROFILE

自動開始プロファイルの名前。この名前は大/小文字が区別されるため、ADD 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日からのデータの処理を開始するようにExtractの設定を変更します。

ALTER EXTRACT exte, BEGIN 2019-01-01

次の例では、トレイル内の特定の場所から処理を開始するようにExtractの設定を変更します。

ALTER EXTRACT exte, EXTSEQNO 26, EXTRBA 338

次の例では、特定のLSNから処理を開始するようにSQL Server環境のExtractの設定を変更します。

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

次の例では、Extractの設定を変更して、順序の次のトレイル・ファイルに切り替えさせます。

ALTER EXTRACT exte, ETROLLOVER

次の例では、統合キャプチャにアップグレードするようにExtractの設定を変更します。

ALTER EXTRACT exte, UPGRADE INTEGRATED TRANLOG

次のコマンドは、ETROLLOVERを使用して、過去のSCN 778899での重複レコードのフィルタリングを阻止します。

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

ETROLLOVERを使用しない場合、Extractを以前のSCN値に変更すると、重複レコードは処理されません。重複レコードをフィルタ処理するようにExtractを変更するコマンドは、次のとおりです。

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システム上のExtractを変更します。

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