1. Oracle GoldenGateコマンドライン・インタフェース・リファレンス
  2. GGSCIコマンドライン・インタフェースのコマンド
  3. ALTER EXTRACT

ALTER EXTRACT

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

  • ADD EXTRACTコマンドで作成したExtractグループの属性を変更する

  • 次の順序のトレイル・ファイルに切り替える

  • 統合キャプチャの構成にアップグレードする

  • 統合キャプチャの構成からダウングレードする

  • 特定のDb2 for iジャーナルを特定のジャーナル順序番号に配置します。

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

GGSCI構文

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

次の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]] |
, 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-ddT[ hh:mi:[ss[.cccccc]]]Z
[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-ddT[ hh:mi:[ss[.cccccc]]]Z}
NOW

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

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

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

データ・ポンプ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_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)
EXTSEQNO sequence_number

Oracleのクラシック・キャプチャ・モードのプライマリExtract、およびデータ・ポンプExtractに有効です。統合モードの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

Db2 for i、Db2 LUW、MySQL、PostgreSQLおよびSQL Serverの場合に有効です。

ログ・ファイル(またはジャーナル)の末尾(次のレコードの書込み位置)から処理を開始するように構成します。アクティブなトランザクションは取得されません。

Db2 LUWの場合、ログ・ファイル内のアクティブなLRI値から開始するように処理を構成します。アクティブLRIは、ログ・ファイルの末尾位置(次のレコードの書込み位置)です。アクティブなトランザクションは取得されません。

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

MySQLの場合は、ファイルの末尾に対応する位置が検出され、そこからトランザクションの読取りが開始されます。データがバイナリ・ログに継続的に書き込まれている場合は、EOFの位置が正確ではありません。

TRANLOG LRI LRI_number

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

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

REPORT file_name

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

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
管理サービスの起動時に、管理対象のプロセスを自動的に開始する必要があるかどうかを指定します。デフォルト値は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 exte, BEGIN 2019-01-01

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

ALTER EXTRACT exte, EXTSEQNO 26, EXTRBA 338

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

ALTER EXTRACT exte, LSN 3454:875:445

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

ALTER EXTRACT exte, ETROLLOVER

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

ALTER EXTRACT exte, UPGRADE INTEGRATED TRANLOG

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

ALTER EXTRACT exte, SCN 778899

次の例は、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, EOF
ALTER EXTRACT POSTEXT, LSN 0/156784
ALTER EXTRACT POSTEXT, BEGIN 2020-02-18T14:50:43.4230Z