ADD EXTRACT

Valido per i database Db2, HP NonStop, MySQL, Oracle, PostgreSQL, SQL Server, Sybase ASE e Yugabyte supportati.

Utilizzare ADD EXTRACT per creare un processo di acquisizione del database di origine, noto come Extract. È possibile creare questo processo come un Extract dei dati delle modifiche, che acquisisce le transazioni correnti dal log del database o tramite altri metodi a seconda del fornitore del database, oppure come un Extract di caricamento iniziale, che acquisirà i record esistenti nelle tabelle del database.

Si consiglia di creare uno solo Extract dei dati delle modifiche o di caricamento iniziale per singolo database di origine. Tuttavia, in rari casi, è possibile migliorare il throughput di acquisizione utilizzando più Extract per database.

Oracle GoldenGate può supportare un numero elevato di processi Extract e Replicat concorrenti per singola distribuzione, a seconda delle risorse disponibili nel sistema operativo. Tuttavia, si consiglia di monitorare le risorse di sistema man mano che vengono aggiunti altri processi Extract o Replicat e di mantenere il numero totale di processi per singola distribuzione su 300 o meno.

Nota:

Se si sta creando un estratto con lo stesso nome di un estratto precedente, assicurarsi che il vecchio estratto sia stato completamente rimosso ed eliminato. È possibile utilizzare DELETE EXTRACT per rimuovere EXTRACT e tutti i relativi componenti.
Per questo comando, la dimensione di tutte le parole chiave e dell'input non può superare i 500 byte, compreso l'eventuale testo immesso per l'opzione DESC.
Per Db2 per i, questo comando stabilisce un punto di inizio globale per tutti i diari e costituisce un primo passo obbligatorio. Dopo aver eseguito il comando ADD EXTRACT è possibile posizionare facoltativamente qualsiasi diario in corrispondenza di un numero di sequenza specifico utilizzando il comando ALTER EXTRACT con l'opzione di diaria appropriata.
Per i database Oracle e PostgreSQL, stabilire una connessione al database di origine utilizzando DBLOGIN USERIDALIAS, quindi eseguire il comando REGISTER EXTRACT prima di aggiungere Extract. Per informazioni dettagliate, vedere il comando REGISTER EXTRACT.
Per SQL Server, stabilire una connessione al database di origine utilizzando DBLOGIN USERIDALIAS, prima di aggiungere il processo Extract. Questa operazione è necessaria per consentire al servizio di amministrazione di associare le informazioni sulle credenziali al processo Extract.

Sintassi

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

Il nome di un Extract. Può contenere fino a otto caratteri. Vedere Scelta dei nomi per i processi e i file.

SOURCEISTABLE

Crea un task Extract per estrarre interi record dalle tabelle specificate per un caricamento iniziale utilizzando Oracle GoldenGate. Quando si utilizza SOURCEISTABLE, non specificare alcuna opzione di servizio.

I parametri del task devono essere specificati nel file dei parametri. Vedere Aggiunta dell'estrazione del caricamento iniziale mediante il client di amministrazione nella documentazione sui microservizi Oracle GoldenGate.

TRANLOG [bsds_name]

Utilizzare questa opzione per tutti i database. TRANLOG richiede l'opzione BEGIN.

(Db2 su z/OS) È possibile utilizzare l'opzione bsds_name per Db2 su un sistema z/OS al fine, sebbene non sia necessario nè utilizzato, per specificare il nome file della serie di dati di bootstrap del log delle transazioni. Non è necessario modificare i parametri TRANLOG esistenti.

(Oracle) Extract legge in modo diretto i redo log Oracle. Per informazioni su una configurazione alternativa, vedere INTEGRATED TRANLOG.

INTEGRATED TRANLOG

Valido per Oracle.

Aggiunge Extract in modalità di acquisizione integrata. In questa modalità Extract viene integrato con il server logmining del database, che passa i record LCR (Logical Change Record) direttamente a Extract. Prima di usare INTEGRATED TRANLOG, utilizzare il comando REGISTER EXTRACT.

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

Specifica l'indicatore orario di inizio dell'elaborazione nell'origine dati.

Nota: è necessario registrare l'estrazione prima di posizionare l'estrazione su un indicatore orario specifico.

NOW

NOW specifica l'ora di esecuzione del comando ADD EXTRACT e, all'avvio del processo Extract, tenterà di posizionarlo in un limite di transazione in un'ora specifica o dopo tale data. Il posizionamento di un Extract tramite NOW non è accurato come altri metodi, come il posizionamento tramite LSN, SCN o LRI e richiede che il database server e il server Oracle GoldenGate siano impostati sugli stessi orari e fusi orari.

Per Db2 LUW, solo i record di commit e di fine delle transazioni contengono gli indicatori orari e pertanto la posizione iniziale di Extract può essere calcolata solo rispetto a tali indicatori orari. Si tratta di un limite dell'interfaccia API utilizzata da Oracle GoldenGate. È tuttavia necessario tenere presente che il posizionamento in base all'indicatore orario non è accurato e può anche richiedere molto tempo. Quando è possibile, si consiglia di utilizzare le opzioni LRI o EOL.
yyyy-mm-ddthh:mm.ssZ

Data e ora (indicatore orario) nel formato specificato. Ad esempio, 2017-07-14T14:54:45Z.
yyyy-mm-ddT[ hh:mi:[ss[.cccccc]]]Z

Data e ora (indicatore orario) nel formato specificato. Per un processo Extract Oracle e un processo Extract per PostgreSQL, il valore dell'indicatore orario deve essere successivo al valore dell'indicatore orario di registrazione di Extract con il database.

Il posizionamento in base all'indicatore orario in PostgreSQL prevede gli scenari riportati di seguito.
- Scenario 1
  
  Se l'impostazione di track_commit_timestamp è off, all'avvio del processo Extract verrà visualizzato l'output seguente, indipendentemente dal metodo di posizionamento utilizzato:
```
2020-04-29T02:15:54Z
```
- Scenario 2
  
  Se l'opzione track_commit_timestamp viene abilitata prima di registrare Extract, l'indicatore orario corretto verrà visualizzato dopo l'elaborazione del PUSH dei record nel database di origine, come indicato nell'esempio seguente:
```
2020-04-29 02:19:07 INFO OGG-01515 Positioning to begin time Apr 29,2020 2:18:38 AM.
```
- Scenario 3
  
  se la funzione track_commit_timestamp viene abilitata dopo la registrazione di Extract, può essere possibile che i record meno recenti siano disponibili nel log per il quale l'indicatore orario di commit non viene creato con l'ID transazione (transaction ID) associato. In questo caso, se non ottiene l'indicatore orario, il processo Extract eseguirà il fallback utilizzando l'indicatore orario indicato nello Scenario 1. Il risultato sarà analogo a quanto riportato di seguito.
```
020-04-29 01:55:07 INFO OGG-01517 Position of first record processed LSN: 0/221D028, Jan 1, 1970 12:00:00 PM.
```
- Non è possibile specificare un indicatore orario passato se lo slot di replica è stato spostato altrove.

EXTRBA archive-offset_number

Valido per Db2 z/OS.

Specifica l'indirizzo byte relativo all'interno di un log delle transazioni in corrispondenza del quale iniziare l'acquisizione dei dati.

Il formato richiesto è 0Xnnn, dove nnn rappresenta un valore esadecimale di 1 e 20 cifre (il primo carattere è il numero zero e il secondo carattere può essere la lettera x maiuscola o minuscola).

EOL

Valido per Db2 per i, Db2 LUW, MySQL, PostgreSQL e SQL Server.

Configura l'elaborazione in modo che abbia inizio alla fine dei file di log (o dei diari) in cui verrà scritto il record successivo. Le eventuali transazioni attive non verranno acquisite.

Per Db2 LUW, configura l'elaborazione in modo che abbia inizio nella corrispondenza del valore LRI attivo nei file di log. il valore LRI attivo è la posizione alla fine dei file in cui verrà scritto il record successivo. Le eventuali transazioni attive non verranno acquisite.

Per PostgreSQL, il comando DBLOGIN è obbligatorio per la posizione in base a EOL.

Per MySQL, trova la posizione corrispondente alla fine del file e inizia a leggere le transazioni da tale posizione. La posizione EOL non è esatta se i dati vengono scritti in modo costante nel log binario.

EOF

Valido per MySQL, Db2 z/OS, Db2 LUW, SQL Server, PostgreSQL e Oracle GoldenGate per DAA.

LSN value

Valido per Db2 z/OS, PostgreSQL e SQL Server

Specifica il numero LSN di transazione in corrispondenza della quale avviare l'acquisizione dei dati. Un alias per questa opzione è EXTLSN. Il posizionamento su un numero LSN è preciso.

Per Db2 z/OS, il valore LSN può essere una serie di cifre esadecimali o decimali. Se è in formato esadecimale, deve avere il prefisso 0X o 0x seguito da 1 a 20 cifre esadecimali: 0-9, a-g o A-G. Se è in formato decimale, non ha alcun prefisso ed è composto da 1 a 25 cifre decimali comprese tra 0 e 9.

Per PostgreSQL, il valore LSN può essere hi o lo. Impostare il valore hi per il punto di inserimento del file di log. Lo è l'offset nel file di log. La posizione di LSN deve trovarsi tra la posizione di riavvio dello slot di replica e quella corrente dello slot di immissione suggerita. Se la posizione specificata stessa si trova nell'intervallo indicato, Extract restituirà un errore.

Per SQL Server, LSN specifica il numero LSN di transazione in corrispondenza della quale avviare l'acquisizione dei dati. Un alias per questa opzione è EXTLSN.

Il valore di LSN specificato deve esistere come tran_begin_lsn valido reperibili nella tabella di sistema cdc.lsn_time_mapping, altrimenti Extract tenterà di eseguire il posizionamento dopo il valore LSN fornito.

Le specifiche LSN valide per SQL Server sono costituite da:

stringa esadecimale separata da due punti (8:8:4) con zeri iniziali aggiunti e il prefisso 0X, ad esempio 0X00000d7e:0000036b:0001;
stringa esadecimale separata da due punti con il prefisso 0X e senza zeri iniziali, ad esempio 0Xd7e:36b:1;

Per trovare il valore LSN minimo disponibile eseguire una query:

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

Gli esempi seguenti mostrano l'uso del valore LSN per Db2 z/OS:

Esempio 1:

ADD EXTRACT extn TRANLOG, LSN 0xDEE40E4F27A3245400

Esempio 2:

ADD EXTRACT extn TRANLOG, LSN 22216433159121980904448

Gli esempi seguenti mostrano il valore LSN per SQL Server:

ADD EXTRACT extn TRANLOG, LSN 0X00000d7e:0000036b:0001

LRI value

Valido per Db2 LUW. Specifica una posizione iniziale nei log delle transazioni all'avvio di Extract.

È possibile utilizzare l'opzione LRI per il sistema LUW Db2 per specificare il valore LRI in corrispondenza della quale Extract può iniziare a acquisire i record dal log delle transazioni. Per ottenere il valore LRI è possibile utilizzare la utility Db2 db2logsForRfwd. Questa utility fornisce gli intervalli LRI presenti nei log Db2.

Tenere presente che, sebbene Extract possa impostare la posizione su un determinato valore di LRI, il valore di LRI interessato non dovrebbe essere necessariamente il primo valore che verrà elaborato da Extract. Extract ignora numerosi tipi di record nei file di log, ad esempio i record di log interno Db2. Extract segnalerà l'effettivo valore LRI iniziale nel file di report Extract.

LOGNUM lognum

Valido per MySQL.

Il numero del file di log. Il comando ADD EXTRACT non riuscirà se il valore di LOGNUM è precedente a zeri. Ad esempio, ADD EXTRACT ext1, TRANLOG, LOGNUM 000001, LOGPOS 0 non riuscirà. Per la buona riuscita di questo esempio, impostare LOGNUM su 1.

LOGPOS logpos

Valore di offset di un evento nel file di log che identifica un record di transazione specifico. I valori di offset degli eventi vengono memorizzati nella sezione dell'intestazione di un record di log. Per posizione all'inizio di un file binlog, impostare LOGPOS su 0.

SEQNO sequence_number

Valido per Db2 per i. Avvia l'acquisizione in corrispondenza del numero di sequenza del sistema, un numero decimale con lunghezza massima di 20 cifre, o immediatamente dopo.

SCN value

Valido per Oracle.

Avvia Extract in corrispondenza della transazione del redo log con il numero SCN (System Change Number) specificato. Per Extract in modalità integrata, il valore SCN deve essere maggiore del numero SCN di registrazione di Extract con il database. Per maggiori informazioni, vedere REGISTER EXTRACT.

PARAMS file_name

Specifica il nome percorso completo di un file dei parametri Extract in una posizione diversa dall'impostazione predefinita dirprm all'interno della directory di Oracle GoldenGate.

REPORT file_name

Specifica il nome percorso completo di un file report Extract in una posizione diversa dall'impostazione predefinita dirrpt all'interno della directory di Oracle GoldenGate.

DESC ‘description’

Specifica una descrizione del gruppo, ad esempio 'Extracts account_tab on Serv1'. Racchiudere la descrizione tra apici.

ENCRYPTIONPROFILE

Specifica il nome del profilo di cifratura di Oracle GoldenGate associato al client specifico.

GTIDSET gtidset

Valido per MySQL.

Specifica il posizionamento iniziale di Extract utilizzando il tipo di posizione come set GTID per l'acquisizione basata su GTID per MySQL. Le origini MySQL supportate per il set GTID sono MySQL Server 8.0 e versioni successive. La dimensione massima supportata per il set GTID è 64 KB.

Sintassi:

ADD EXTRACT extract_name, TRANLOG, GTIDSET gtidset

CRITICAL

Indica se il processo è di importanza critica per la distribuzione.

PROFILE

Nome del profilo di avvio automatico.

AUTOSTART

Specifica se il processo gestito deve essere avviato in modo automatico all'avvio del servizio di amministrazione. Il valore predefinito è YES.

DELAY

Periodo di tempo di attesa, in secondi, prima dell'avvio del processo.

AUTORESTART

Controlla le modalità di riavvio del processo se terminato.

RETRIES

Numero massimo di tentativi per il riavvio del task prima di annullare gli sforzi di nuovi tentativi. Questa opzione è facoltativa.

WAITSECONDS

Il periodo di tempo, in secondi, durante il quale vengono contati i nuovi tentativi.

RESETSECONDS

Reimposta il periodo di tempo durante il quale vengono contati i nuovi tentativi.

DISABLEONFAILURE

Quando l'impostazione è TRUE, il task viene disabilitato all'esaurimento del numero dei nuovi tentativi consentiti.

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

Da utilizzare per un Extract alias. Specifica il nome host DNS o l'indirizzo IP del server proxy. È possibile utilizzare uno qualsiasi dei due elementi per definire l'host, ma sarà necessario utilizzare l'indirizzo IP se il server DNS non è raggiungibile. Se si utilizza un indirizzo IP, utilizzare un indirizzo mappato IPv6 o IPv4, a seconda dello stack del sistema di destinazione. È necessario specificare PROXYCSALIAS. È inoltre possibile specificare la porta da usare e il dominio dell'area di memorizzazione delle credenziali.

Esempi

Nell'esempio seguente, viene creato un gruppo Extract denominato exte, che acquisisce le modifiche del database dai log delle transazioni. L'estrazione inizia con i record generati quando il gruppo Extract è stato creato e avviato con ADD EXTRACT.

ADD EXTRACT extn, TRANLOG, BEGIN NOW

Nell'esempio seguente viene creato un gruppo Extract denominato extw per recuperare le modifiche al database dai log delle transazioni posizionando Extract in un indicatore orario specifico.

ADD EXTRACT extn, TRANLOG, BEGIN NOW

REGISTER EXTRACT extn DATABASE

ALTER EXTRACT extn BEGIN 2020-08-02T06:05:30.000Z

Il comando seguente crea un gruppo Integrated Extract.

ADD EXTRACT extn, INTEGRATED TRANLOG, BEGIN NOW

Il comando seguente crea un processo Extract di caricamento iniziale denominato extei.

ADD EXTRACT extn, SOURCEISTABLE

L'esempio seguente include tutte le combinazioni dei formati validi del set GTID.

Esempio 1:

ADD EXTRACT exte, TRANLOG, GTIDSET "E11FA47-71CA-11E1-9E33-C80AA9429562:4"

Esempio 2:

ADD EXTRACT exts, TRANLOG, GTIDSET "3E11FA47-71CA-11E1-9E33-C80AA9429562:1-10"

Esempio 3:

ADD EXTRACT extn, TRANLOG, GTIDSET "3E11FA47-71CA-11E1-9E33-C80AA9429562:1-3:11:47-49"

Esempio 4:

ADD EXTRACT extw, TRANLOG, GTIDSET "2174B383-5441-11E8-B90A-C80AA9429562:1-3,24DA167-0C0C-11E8-8442-00059A3C7B00:1-19"

Nota: come mostrato nell'esempio 4, quando il set GTID contiene più uuid, per formare una richiesta API REST, questo set GTID viene suddiviso in più set GTID utilizzando il separatore di virgole.

I comandi seguenti creano e posizionano Extract in corrispondenza di un numero SCN (System Change Number) specifico del redo log.

ADD EXTRACT extn TRANLOG SCN 123456

ADD EXTRACT extn INTEGRATED TRANLOG SCN 123456

Nell'esempio seguente viene creato un Extract in un sistema Db2 LUW.

ADD EXTRACT extn, TRANLOG LRI 8066.322711

Nell'esempio seguente viene creato un Extract con l'opzione di avvio automatico mediante il client di amministrazione.

ADD EXTRACT extn, TRANLOG , BEGIN NOW , AUTOSTART yes