2.15 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]]]} |
   EXTSEQNO sequence-number   
   [, EXTRBA archive-offset-number] [, ADD_EXTRACT_attribute]  | 
   SCN value]
[, DESC
[, UPGRADE INTEGRATED TRANLOG]
[, DOWNGRADE INTEGRATED TRANLOG [THREADS number]]
[, THREAD number]

[, ETROLLOVER]
[, ENCRYPTIONPROFILE encryption-profile-name ]
         [CRITICAL    [ YES | NO ]
         [PROFILE     profile-name             
   |  [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]

GGSCI構文

ALTER EXTRACT group-name
[, BEGIN {NOW | yyyy-mm-dd[ hh:mi:[ss[.cccccc]]]}]
[, START]
[, EXTSEQNO sequence-number]
[, EXTRBA offset-number]
[, TRANLOG LRI LRI_number]
[, UPGRADE INTEGRATED TRANLOG]
[, DOWNGRADE INTEGRATED TRANLOG [THREADS number]]
[, THREAD number]
[, LSN value]
[, SCN value]
[, ETROLLOVER]
[, INFO EXTRACT group-name]

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

ALTER EXTRACT {BEGIN {NOW | yyyy-mm-dd[ hh:mi:[ss[.cccccc]]]}
[JOURNAL journal_library/journal_name [JRNRCV receiver_library/
  receiver_name]] |
, EOF [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-dd[ hh:mi:[ss[.cccccc]]]}
[JOURNAL journal_library/journal_name
[JRNRCV receiver_library/ receiver_name]] |
, EOF [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 | yyyy-mm-dd[ hh:mi:[ss[.cccccc]]]}
NOW

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

DB2 LUWの場合、NOWではSTART EXTRACTを有効にする時刻を指定します。この日時にほぼ一致する最初のレコードが開始位置になります。この理由は、タイムスタンプを含むログ・レコードのみがコミットおよび終了(中断)トランザクション・レコードであり、開始位置はそれらのタイムスタンプを基準としてのみ計算できるためです。これは、Oracle GoldenGateが使用するAPIの制限によるものです。

データ・ポンプExtractでは、ADD EXTRACT文より前にトレイルに取得されたデータをバイパスするときを除き、NOWを使用しないでください。

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_timestampoffの場合、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 finance, BEGIN 2011-01-01
ALTER EXTRACT finance, ETROLLOVER
ALTER EXTRACT finance, 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)
EXTSEQNO sequence_number

Oracleのクラシック・キャプチャ・モードのプライマリExtract、およびデータ・ポンプExtractに有効です。統合モードのOracle Extractではサポートされません。次のいずれかを指定します。

  • Oracle REDOログの順序番号と、そのログ内のデータ取得開始位置のRBA。

  • データ取得を開始するファイル内の相対バイト・アドレス。この2つの要素によって、TMFマスター監査証跡(MAT)の位置を指定します。

  • (データ・ポンプの場合)トレイル内のデータ取得開始ファイル。順序番号を指定しますが、埋込みのために0を使用しないでください。たとえば、証跡ファイルが\aa000026の場合は、EXTSEQNO 26と指定します。このオプションを使用しない場合、処理はデフォルトで証跡の最初から開始されます。

このオプションを使用する前に、Oracleサポートに連絡してください。詳細は、http://support.oracle.com.にアクセスしてください

EXTRBA offset_number

Oracle Databaseに有効です。トランザクション・ログ内のデータ取得開始位置の相対バイト・アドレスを指定します。

必要な書式は0Xnnnで、nnnは1 - 20桁の16進数(最初の文字は桁を表すゼロで、2番目の文字は大文字または小文字x)です。

EOF

(PostgreSQL) PostgreSQLでは、このオプションを使用してEOFの値を指定できます。DBLOGINは必須です。

TRANLOG LRI LRI_number

(DB2 LUW)このオプションをDB2 LUWシステムに使用して、LRIレコード値をチェックポイント・トランザクション・ログに指定できます。

PostgreSQLの場合、EOFによる位置にはDBLOGINが必要です。

UPGRADE INTEGRATED TRANLOG

Extractグループをクラシック・キャプチャから統合キャプチャにアップグレードします。アップグレードをサポートするには、オープンしている最も古いトランザクションの開始を含むトランザクション・ログが、ソースまたはダウンストリーム・マイニング・システムで使用可能である必要があります。

DOWNGRADE INTEGRATED TRANLOG [THREADS number]

Extractグループを統合キャプチャからクラシック・キャプチャにダウングレードします。RACシステムでダウングレードする場合、THREADSオプションを使用してRACスレッド数を指定する必要があります。RAC以外のシステムの場合は、RAC以外のシステムでTHREADS 1を指定してADD EXTRACTを実行するのと同様に、オプションでTHREADS 1を指定して、1つのスレッドがあるスレッド・モードでダウングレードされたクラシックExtractを実行できます。

ダウングレードをサポートするには、オープンしている最も古いトランザクションの開始を含むトランザクション・ログが、ソースまたはダウンストリーム・マイニング・システムで使用可能であることが必要です。

REPORT file_name

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

THREAD number

クラシック・キャプチャ・モードに有効です。Oracle RAC構成で、指定したREDOスレッドに対してのみExtractを変更します。指定できるスレッド番号は1つのみです。

SCN value

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

LSN value
SQL Server、DB2 z/OSおよびPostgreSQLに有効です。
データ取得を開始するトランザクション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)

  • 0000003454:0000000875:00001のように、先行ゼロを付けたコロン区切り10進数文字列(10:10:5)

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

  • 3454:875:1のように、先行ゼロなしのコロン区切り10進数文字列

  • 3454000000087500001のような10進数文字列

次をものを問い合せることで、使用可能な最小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などのリーダーをその新しい証跡順序番号に手動で再配置する必要があります。

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で入力した名前と完全に一致するものを使用する必要があります。
CRITICAL

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

PROFILE
自動開始プロファイルの名前。この名前は大/小文字が区別されるため、ADD EXTRACTで入力した名前と完全に一致するものを使用する必要があります。
AUTOSTART
Administration Serverの起動時に、管理対象のプロセスを自動的に開始する必要があるかどうかを指定します。デフォルト値はYES
RETRIES

再試行を中止するまでにタスクを再開する最大試行数。これはオプションです。

WAITSECONDS

再試行をカウントする期間(秒単位)。

RESETSECONDS
再試行をカウントする期間をリセットします。
DISABLEONFAILURE

TRUEに設定すると、再試行回数の上限に達した時点でタスクは無効になります。

INFO EXTRACT group-name, SHOWCH DETAIL

次の例に示すように、最初のSCN値がリストされます。

Integrated Extract outbound server first scn: 0.665884 (665884)

次の例では、2011年1月1日からのデータの処理を開始するようにExtractの設定を変更します。

ALTER EXTRACT finance, BEGIN 2011-01-01

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

ALTER EXTRACT finance, EXTSEQNO 26, EXTRBA 338

次の例では、Oracle RAC環境のExtractを変更し、REDOスレッド4のみに新しい開始位置を適用します。

ALTER EXTRACT accounts, THREAD 4, BEGIN 2011-01-01

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

ALTER EXTRACT sales, LSN 3454:875:445

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

ALTER EXTRACT finance, ETROLLOVER

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

ALTER EXTRACT finance, UPGRADE INTEGRATED TRANLOG

次の例では、RAC環境でクラシック・キャプチャにダウングレードするようにExtractの設定を変更します。

ALTER EXTRACT finance, DOWNGRADE INTEGRATED TRANLOG THREADS 3

次の例では、ソース・データベースSCN 778899からデータ処理を開始するようにOracle環境のExtractの設定を変更します。

ALTER EXTRACT finance, SCN 778899

次の例は、IBM for iジャーナル開始位置のALTER EXTRACTを示します。

ALTER EXTRACT finance, SEQNO 1234  JOURNAL accts/acctsjrn

次の例は、IBM for iジャーナルおよび受信者開始位置のALTER EXTRACTを示します。

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

次の例では、DB2 LUWシステム上のExtractを変更します。

ALTER EXTRACT extcust, TRANLOG LRI 8066.322711

次の例は、PostgreSQLで使用されるALTER EXTRACTオプションを示しています。
GGSCI> ALTER EXTRACT Extract1, EOF
GGSCI> ALTER EXTRACT <POSTEXT>, LSN 0/156784
GGSCI> ALTER EXTRACT <POSTEXT>, begin 2020-02-18 14:50:43.4230