1. Oracle GoldenGateコマンドライン・インタフェース・リファレンス
  2. 管理クライアント・コマンドライン・インタフェース・コマンド
  3. ADD EXTRACT

ADD EXTRACT

サポートされているDb2、HP NonStop、MySQL、Oracle、PostgreSQL、SQL Serverに対して有効です。

ADD EXTRACTを使用して、ソース・データベース取得プロセス(Extractと呼ばれます)を作成します。Extractは変更データExtractとして作成することができ、これにより現在のトランザクションが、データベース・ログから、またはデータベース・ベンダーに応じた他の方法で取得されます。あるいは、初期ロードExtractとして作成することができ、これによりデータベース表に存在するレコードが取得されます。

ソース・データベースごとに1つの変更データExtractまたは1つの初期ロードExtractのみを作成することをお薦めしますが、まれな状況では、データベースごとに複数のExtractを使用することで取得スループットが向上する場合があります。

Oracle GoldenGateでは、オペレーティング・システムで使用可能なリソースに応じて、デプロイメントごとに多数の同時ExtractおよびReplicatプロセスをサポートできます。ただし、ExtractまたはReplicatプロセスが追加されるたびにシステム・リソースを監視し、デプロイメントごとのプロセスの合計数を300以下に維持することをお薦めします。

ノート:

  • このコマンドでは、DESCオプションに入力するテキストを含む、すべてのキーワードおよび入力のサイズは、500バイトを超えることはできません。

  • Db2 for iの場合、このコマンドはすべてのジャーナルのグローバル開始位置を設定するもので、必須の最初のステップです。ADD EXTRACTコマンドの発行後、オプションで適切なジャーナル・オプションを指定したALTER EXTRACTコマンドを使用して特定のジャーナル・シーケンス番号に特定のジャーナルを配置できます。

  • OracleおよびPostgreSQLデータベースの場合、Extractを追加する前に、DBLOGIN USERIDALIASを使用してソース・データベースへの接続を確立してからREGISTER EXTRACTコマンドを発行します。詳細は、REGISTER EXTRACTコマンドを参照してください。

  • SQL Serverの場合、Extractを追加する前に、DBLOGIN USERIDALIASを使用してソース・データベースへの接続を確立します。これは、管理サービスが資格証明情報をExtractプロセスにバインドするために必要です。

Admin Client構文

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

Extractの名前。最大8文字まで使用できます。「プロセスおよびファイルの名前の選択」を参照してください。

SOURCEISTABLE

Oracle GoldenGateを使用した初期ロードのために、指定された表からレコード全体を抽出するExtractタスクを作成します。SOURCEISTABLEを使用するときは、サービス・オプションを指定しないでください。

タスク・パラメータはパラメータ・ファイルで指定する必要があります。Oracle GoldenGate Microservicesドキュメントの管理クライアントを使用した初期ロード抽出の追加を参照してください。

TRANLOG [bsds_name]

このオプションは、すべてのデータベースで使用します。TRANLOGを指定するときは、BEGINオプションを指定する必要があります。

(z/OS上のDb2) z/OSシステム上のDb2では、bsds_nameオプションを使用してトランザクション・ログのブートストラップ・データ・セット・ファイル名を指定できますが、これは必須ではなく、使用されません。既存のTRANLOGパラメータを変更する必要はありません。

(Oracle) ExtractはOracle REDOログを直接読み取ります。代替構成については、INTEGRATED TRANLOGも参照してください。

INTEGRATED TRANLOG

Oracleに有効です。

統合取得モードでExtractを追加します。このモードでは、Extractは、論理変更レコード(LCR)をExtractに直接渡すデータベース・ログマイニング・サーバーと統合します。INTEGRATED TRANLOGを使用する前に、REGISTER EXTRACTコマンドを使用します。

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

データ・ソース内の処理開始位置のタイムスタンプを指定します。

  • NOW

    NOWは、ADD EXTRACTコマンドが発行される時刻を指定し、Extractの起動時に、その特定の時刻以降にトランザクション境界に位置指定しようとします。NOWよるExtractの位置指定は、LSN、SCNまたはLRIによる位置指定などの他の方法ほど正確ではありません。

    Db2 LUWの場合、コミットおよび終了トランザクション・レコードにのみタイムスタンプが含まれるため、Extractの開始位置はそれらのタイムスタンプを基準としてのみ計算できます。これは、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およびPostgreSQLのExtractの場合、タイムスタンプ値はExtractがデータベースに登録された時点のタイムスタンプよりも大きい必要があります。

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

    • シナリオ1

      track_commit_timestampがoffの場合、Extractプロセスが開始されると、使用する位置指定方法に関係なく、次の出力が表示されます。
      2020-04-29T02:15:54Z

    • シナリオ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.

    • レプリケーション・スロットが移動していない場合、過去のタイムスタンプは指定できません。

EXTRBA archive-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の位置は正確ではありません。

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値は一連の16進数または一連の10進数にすることができます。16進形式の場合は、0Xまたは0xの後に1から20の16進数(0-9、a-gまたはA-G)が続く必要があります。10進数形式の場合は、接頭辞なしの1から25の10進数(0-9)です。

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

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

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

SQL Serverの有効な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

次の例は、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に有効です。Extract起動時のトランザクション・ログ内のデータ取得開始位置を指定します。

Db2 LUWシステムのLRIオプションを使用して、Extractがトランザクション・ログからのレコードの取得を開始できるLRIを指定できます。Db2ユーティリティdb2logsForRfwdを使用して、LRIを取得できます。このユーティリティは、Db2ログに存在するLRIの範囲を提示します。

Extractは指定したLRIに配置されますが、ExtractがそのLRIを最初に処理するとはかぎらないことに注意してください。これは、ログ・ファイル内に、Db2内部ログ・レコードなどExtractが無視する多数のタイプのレコードが存在するためです。Extractは、実際に最初に処理したLRIをExtractレポート・ファイルにレポートします。

LOGNUM lognum

MySQLに有効です。

これはログ・ファイル番号です。ADD EXTRACTは、LOGNUM値の前にゼロが含まれていると失敗します。たとえば、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システム変更番号(SCN)を持つREDOログ内のトランザクションからExtractを開始します。統合モードのExtractでは、SCN値はExtractがデータベースに登録された時点のSCNよりも大きい必要があります。詳細は、REGISTER EXTRACTを参照してください。

PARAMS file_name

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

REPORT file_name

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

DESC 'description'

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

ENCRYPTIONPROFILE

特定のクライアントに関連付けられたOracle GoldenGate暗号化プロファイルの名前を指定します。

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

CRITICAL

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

PROFILE

自動開始プロファイルの名前。

AUTOSTART

管理サービスの起動時に、管理対象のプロセスを自動的に開始する必要があるかどうかを指定します。デフォルト値はYES。

RETRIES

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

WAITSECONDS

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

RESETSECONDS

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

DISABLEONFAILURE

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

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

別名Extractに対して使用します。プロキシ・サーバーのDNSホスト名またはIPアドレスを指定します。DNSサーバーに接続できない場合は、IPアドレスを使用する必要がありますが、いずれか1つを使用してホストを定義できます。IPアドレスを使用している場合、宛先システムのスタックに応じて、IPv6またはIPv4のいずれかのマップ・アドレスを使用します。PROXYCSALIASを指定する必要があります。また、使用するポートと、資格証明ストアのドメインを指定できます。

例

次の例では、トランザクション・ログからデータベースの変更を取得する、exteという名前のExtractグループを作成します。抽出は、Extractグループが作成されADD EXTRACTによって開始したときに生成されたレコードから開始します。 

ADD EXTRACT extn, TRANLOG, BEGIN NOW
次の例では、Admin Clientから、Extractグループ名extwが作成されて、指定された時間以降のトランザクション・ログからデータベースの変更を取得します。
ADD EXTRACT extn, TRANLOG, BEGIN 2020-08-02T06:05:30.000Z

次の例では、統合Extractグループが作成されます。

ADD EXTRACT extn, INTEGRATED TRANLOG, BEGIN NOW

次の例では、exteiという名前の初期ロードExtractが作成されます。 

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セットに分割されます。

次の例は、REDOログ内の特定のOracleシステム変更番号(SCN)でExtractを作成および配置します。

ADD EXTRACT extn TRANLOG SCN 123456
ADD EXTRACT extn INTEGRATED TRANLOG SCN 123456

次の例では、Db2 LUWシステム上にExtractを作成します。

ADD EXTRACT extn, TRANLOG LRI 8066.322711
次の例では、Admin Clientを使用して、自動起動オプションを指定したExtractを作成します。
ADD EXTRACT extn, TRANLOG , BEGIN NOW , AUTOSTART yes