ADD EXTRACT

2.3 ADD EXTRACT

ADD EXTRACTでは、Extractグループを作成します。SOURCEISTABLEタスクまたは別名Extractが指定されている場合を除き、ADD EXTRACTは実行間の処理の継続性を維持するためにチェックポイントを使用するオンライン・グループを作成します。

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

Extractを構成するためのソースとしてTRANLOGを指定する必要があります。異種データベースのためのOracle GoldenGateの使用のPostgreSQLのサプリメンタル・ロギングの有効化を参照してください。

Oracle GoldenGateは、Oracle GoldenGate Managerインスタンス当たり、最大で5,000の同時ExtractおよびReplicatグループをサポートします。サポートされているレベルで、INFO、STATUSなどのGGSCIコマンドですべてのグループを完全に制御および表示できます。Oracle GoldenGateは、環境を効果的に管理するためにExtractグループとReplicatグループを組み合せた数を300以下のデフォルト・レベルに維持します。

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

Admin Client構文

ADD EXTRACT group-name
|             ( SOURCEISTABLE |
|             ( [ INTEGRATED ] TRANLOG )
|               ( BEGIN     ( NOW | yyyy-mm-ddthh:mm.ssZ ) |
|                 EXTSEQNO  archive-sequence-number 
                [ EXTRBA archive-offset-number ] |
                SCN       scn
|               ) )
|             [ DESC        description    ]
|             [ THREADS     threads-number ]
|             [ 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

GGSCI構文

ADD EXTRACT group_name
{, SOURCEISTABLE |
    , TRANLOG [bsds_name | 
    , INTEGRATED TRANLOG |
    , EXTFILESOURCE file_name |
    , EXTTRAILSOURCE trail_name |
[, BEGIN {NOW | yyyy-mm-dd[ hh:mi:[ss[.cccccc]]]}]
[, START]
[, EXTSEQNO sequence_number
[, EXTRBA offset_number |
[, EOF 
[, LSN value |
[, EXTRBA relative_byte_address |
[, LRI value |
[, PAGE data_page, ROW row_ID |
[, SEQNO sequence_number
[, SCN value]
[, THREADS n]
[, PASSIVE]
[, PARAMS file_name]
[, REPORT file_name]
[, DESC 'description']
[, SOCKSPROXY {host_name | IP_address}[:port] [PROXYCSALIAS credential_store_alias [PROXYCSDOMAIN credential_store_domain]]]
[, RMTNAME passive_Extract_name]
[, LOGNUM lognum]
[, LOGPOS logpos

group_name

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

SOURCEISTABLE

Oracle GoldenGateダイレクト・ロード・メソッド、またはSQL*Loaderへのダイレクト・バルク・ロード方式を使用して、初期ロードのためにデータベースからレコード全体を抽出するExtractタスクを作成します。SOURCEISTABLEを指定しない場合、ADD EXTRACTはオンライン変更同期プロセスを作成します。この場合は、他のデータ・ソース・オプションを1つ指定する必要があります。SOURCEISTABLEを使用するときは、サービス・オプションを指定しないでください。タスクのパラメータはパラメータ・ファイルで指定する必要があります。「初期ロードによるOracle GoldenGateのインスタンス化」を参照してください。

TRANLOG [bsds_name]

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

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

(Oracle) Oracle StandardまたはEnterprise Edition 11.2.0.3以降では、このモードはクラシック・キャプチャ・モードと呼ばれます。ExtractはOracle REDOログを直接読み取ります。代替構成については、INTEGRATED TRANLOGも参照してください。

(PostgreSQL) GGSCIを使用して、ソースとしてTRANLOGを持つExtractを追加します。

INTEGRATED TRANLOG

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

EXTFILESOURCE file_name

データ・ソースとしてExtractファイルを指定します。このオプションは、プライマリExtractグループとターゲット・システム間の仲介の役割を果すセカンダリExtractグループ(データ・ポンプ)に使用します。

file_nameの場合は、ファイルの相対パス名または完全修飾パス名を指定します(例: \extfile)。

EXTTRAILSOURCE trail_name

データ・ソースとしてトレイルを指定します。このオプションは、プライマリExtractグループとターゲット・システム間の仲介役として機能するExtractポンプとともに使用します。

trail_nameの場合は、証跡の相対パス名または完全修飾パス名を指定します(例: \aa)。

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

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

NOW

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

DB2 LUWの場合、NOWではSTART 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は、レプリケーション・スロットの再開位置から自動的に開始されます。

EXTSEQNO sequence-number

Oracleのクラシック・キャプチャ・モードのプライマリExtractに有効です。統合モードのExtractではサポートされません。データ取得を開始するOracle REDOログの順序番号を指定します。このオプションを使用する前に、Oracleサポートに連絡してください。

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

EXTRBA archive-offset_number

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

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

EOF

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

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

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

LSN value

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

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

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

例:

ADD EXTRACT extsql 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に有効です。

これはログ・ファイル番号です。Microservices Architectureでは、LOGNUM値の前にゼロが含まれる場合、ADD EXTRACTが失敗します。たとえば、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以外に指定します。

THREADS n

Oracleクラシック・キャプチャ・モードに有効です。

REDOログを読み取るためにExtractが保持するプロデューサ・スレッド数を指定します。

プロデューサ・スレッドの数を指定するためにOracle RAC構成で必要です。これらは、様々なRACノードで異なるREDOログを読み取るExtractスレッドです。この値は、REDOデータの取得元のノードの数と同じである必要があります。

PASSIVE

(Classic Architectureのみ)このExtractグループをパッシブ・モードで実行し、ターゲット・システム上の別名Extractグループを起動または停止することによってのみ起動および停止できるように指定します。ソースおよびターゲット間の接続は、このグループではなく、ターゲットの別名Extractグループによって確立されます。

このオプションは、標準Extractグループまたはデータ・ポンプExtractグループに対して使用できます。これは、ネットワークを介してターゲット上のリモート・トレイルにデータを送信するソース・システム上のExtractに対してのみ使用する必要があります。

DESC 'description'

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

ENCRYPTIONPROFILE

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

CRITICAL

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

PROFILE

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

AUTOSTART

Administration ServerのAdministration Serviceの起動時に、管理対象のプロセスを自動的に開始する必要があるかどうかを指定します。デフォルト値は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を指定する必要があります。また、使用するポートと、資格証明ストアのドメインを指定できます。

RMTNAME passive_extract_name

(Classic Architectureのみ)別名Extractに使用します。別名Extractの名前と異なる場合に、パッシブExtractの名前を指定します。

例

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

ADD EXTRACT finance, TRANLOG, BEGIN NOW

次の例(Admin Clientから実行)は、指定した時間以降にトランザクション・ログからデータベースの変更を取得するために、Extractグループ名financeが作成されます。

ADD EXTRACT finance, TRANLOG, BEGIN 2020-08-02T06:05:30.000Z

次の例では、Oracle RACログからデータベースの変更を抽出する、financeという名前のExtractグループを作成します。抽出は、このグループが作成された時刻に生成されたレコードから開始されます。RACインスタンスが4つあるので、Extractスレッド数は4になります。

ADD EXTRACT finance, TRANLOG, BEGIN NOW, THREADS 4

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

ADD EXTRACT finance, INTEGRATED TRANLOG, BEGIN NOW

次の例では、最大パフォーマンス・モードまたは最大保護モードでMySQLとインタフェース接続する、financeという名前のExtractグループを作成します。

ADD EXTRACT finance, TRANLOG, BEGIN NOW

次の例では、ソース証跡dirdat\ltからデータを読み取るepumpという名前のデータ・ポンプExtractグループを作成します。

ADD EXTRACT finance, EXTTRAILSOURCE dirdat\lt

次の例では、loadという名前の初期ロードExtractを作成します。

ADD EXTRACT load, SOURCEISTABLE

Classic Architectureで、次の例では、トランザクション・ログからデータベースの変更を抽出する、financeという名前のパッシブExtractグループを作成します。

GGSCI> ADD EXTRACT finance, TRANLOG, BEGIN NOW, PASSIVE

次の例では、financeという名前の、別名のExtractグループを作成します。別名Extractは、ソース・システムsys上のfinanceという名前のパッシブExtractに関連付けられています。このシステム上のManagerは、ポート7800を使用しています。

ADD EXTRACT finance, RMTHOST sys, MGRPORT 7800, RMTNAME finance

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

ADD EXTRACT finance TRANLOG SCN 123456
ADD EXTRACT finance INTEGRATED TRANLOG SCN 123456

次の例では、使用するホストを指定する別名Extractを作成します。

ADD EXTRACT apmp desc 'alias extract' RMTHOST lc01abc MGRPORT 7813 RMTNAME 
ppmp SOCKSPROXY lc02def:3128 PROXYCSALIAS proxyAlias

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

ADD EXTRACT extcust, TRANLOG LRI 8066.322711

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

ADD EXTRACT Extract1, TRANLOG, BEGIN NOW

次の例では、Admin Clientを使用して、自動起動オプションを指定したExtractを作成します。

OGG (https://localhost:15000 Atlanta) 5> add extract EXT_DEMO tranlog begin now autostart yes
2019-11-20T23:22:54Z  
INFO    OGG-08100  EXTRACT added.

親トピック: 共通コマンドライン・インタフェースのコマンド