ADD EXTRACT

Válido para bases de datos compatibles Db2, HP NonStop, MySQL, Oracle, PostgreSQL, SQL Server, Sybase ASE y Yugabyte.

Utilice ADD EXTRACT para crear un proceso de captura de base de datos de origen, conocido como Extract. El Extract se puede crear como un Extract de datos de cambio, que captura las transacciones actuales del log de base de datos o utilizando otros medios en función del proveedor de base de datos; o se puede crear como un Extract de carga inicial, que capturará los registros que existen en las tablas de base de datos.

Se recomienda crear solo un Extract de datos de cambio o uno de carga inicial por base de datos de origen; sin embargo, en casos excepcionales, se puede mejorar el rendimiento de la captura utilizando varios Extracts por base de datos.

Oracle GoldenGate puede soportar un gran número de procesos de Extract y Replicat simultáneos por despliegue, en función de los recursos disponibles con el sistema operativo. Sin embargo, se recomienda supervisar los recursos del sistema a medida que se agregan más procesos de Extract o Replicat y mantener el número total de procesos por despliegue en un máximo de 300.

Nota:

Si va a crear un Extract con el mismo nombre que un Extract antiguo, asegúrese de que el Extract antiguo se haya eliminado y borrado por completo. Puede utilizar el comando DELETE EXTRACT para eliminar el EXTRACT y todos sus componentes.
Este comando no puede exceder los 500 bytes de tamaño para todas las palabras clave y las entradas, incluido cualquier texto que introduzca para la opción DESC.
Para Db2 for i, este comando establece un punto de inicio global para todos los diarios y es un paso inicial necesario. Después de emitir el comando ADD EXTRACT, puede posicionar si lo desea cualquier diario especificado en un número del diario específico mediante el comando ALTER EXTRACT con una opción del diario adecuada.
Para las bases de datos Oracle y PostgreSQL, establezca una conexión a la base de datos de origen mediante DBLOGIN USERIDALIAS y, a continuación, ejecute el comando REGISTER EXTRACT antes de agregar el Extract. Para obtener detalles, consulte el comando REGISTER EXTRACT.
Para SQL Server, establezca una conexión a la base de datos de origen mediante DBLOGIN USERIDALIAS, antes de agregar el Extract. Esto es necesario para que el servicio de administración enlace la información de credenciales con el proceso de Extract.

Sintaxis

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

Nombre de un Extract. Puede contener hasta ocho caracteres. Consulte Choosing Names for Processes and Files.

SOURCEISTABLE

Crea una tarea de Extract que extrae registros completos de las tablas especificadas de una carga inicial mediante Oracle GoldenGate. Al utilizar SOURCEISTABLE, no especifique ninguna opción de servicio.

Se deben especificar parámetros de tarea en el archivo de parámetros. Consulte Agregar extracción de carga inicial mediante el cliente de administración en Oracle GoldenGate Microservices Documentation.

TRANLOG [bsds_name]

Utilice esta opción para todas las base de datos. TRANLOG requiere la opción BEGIN.

(Db2 en z/OS) Puede utilizar la opción bsds_name para Db2 en un sistema z/OS para especificar el nombre del archivo de juego de datos del log de transacción, aunque no es necesario y no se utiliza. No es necesario cambiar los parámetros TRANLOG existentes.

(Oracle) Extract lee los redo logs de Oracle directamente. Consulte INTEGRATED TRANLOG para conocer una configuración alternativa.

INTEGRATED TRANLOG

Válido para Oracle.

Agrega Extract en el modo de captura integrada. En este modo, Extract se integra con el servidor de logmining de la base de datos, el cual transfiere los registros de cambios lógicos (LCR) directamente a Extract. Antes de utilizar INTEGRATED TRANLOG, utilice el comando REGISTER EXTRACT.

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

Especifica el registro de hora en el origen de datos a la que se va a empezar el procesamiento.

Nota: Debe registrar el Extract antes de colocar el Extract en un registro de hora específico.

NOW

NOW especifica la hora a la que se emite el comando ADD EXTRACT y cuando se inicia el Extract, este intentará posicionar un límite a la hora específica o después de esa hora específica. El posicionamiento de un Extract por NOW no es tan preciso como otros métodos, como el posicionamiento por LSN, SCN o LRI, y necesita que el servidor de base de datos y el servidor de Oracle GoldenGate se definan en las mismas horas y zonas horarias.

Para Db2 LUW, solo los registros de finalización y confirmación de transacciones contienen registros de hora, por lo que la posición de inicio del Extract solo se puede calcular en relación con dichos registros de horas. Esta es una limitación de la API que se utiliza en Oracle GoldenGate. Debe tenerse en cuenta que el posicionamiento por registro de hora no es preciso y también que puede tardar mucho tiempo. Se recomienda utilizar las opciones LRI o EOL cuando sea posible.
yyyy-mm-ddthh:mm.ssZ

Fecha y hora (registro de hora) en el formato especificado. Por ejemplo, 2017-07-14T14:54:45Z.
yyyy-mm-ddT[ hh:mi:[ss[.cccccc]]]Z

Fecha y hora (registro de hora) en el formato especificado. Para un Extract de Oracle y un Extract para PostgreSQL, el valor de registro de hora debe ser mayor que el registro de hora en el que se ha registrado el Extract con la base de datos.

El posicionamiento por registro de hora en PostgreSQL incluye los siguientes escenarios:
- Escenario 1
  
  Si track_commit_timestamp es off, se mostrará la siguiente salida cuando se inicie el proceso Extract independientemente del método del posicionamiento que se utilice:
```
2020-04-29T02:15:54Z
```
- Escenario 2
  
  Si se activa track_commit_timestamp antes de que Se registre Extract, se mostrará el registro a hora correcto una vez que se haya transferido los registros en la base del datos de origen como Se menciona en el siguiente ejemplo:
```
2020-04-29 02:19:07 INFO OGG-01515 Positioning to begin time Apr 29,2020 2:18:38 AM.
```
- Escenario 3
  
  Si se activa track_commit_timestamp después del registro Extract, es posible que los registros antiguos estén disponibles en el log para el cual no se haya creado el registro a hora de confirmación con el transaction ID asociado. En ese caso, si Extract no obtiene el registro de hora, utilizará la reserva mediante el registro de hora por defecto que se menciona en el escenario 1. La salida será similar a la siguiente:
```
020-04-29 01:55:07 INFO OGG-01517 Position of first record processed LSN: 0/221D028, Jan 1, 1970 12:00:00 PM.
```
- No se puede especificar el registro de hora en el pasado si se ha movido el espacio de replicación.

EXTRBA archive-offset_number

Válido para Db2 z/OS.

Especifica la dirección de byte relativa en un log de transacciones en la que se va a empezar la captura de datos.

El formato necesario es 0Xnnn, donde nnn es un número hexadecimal de 1 a 20 dígitos (el primer carácter es el dígito cero, y el segundo puede ser el dígito mayúscula o minúscula x).

EOL

Válido para Db2 for i, Db2 LUW, MySQL, PostgreSQL y SQL Server.

Configura que el procesamiento se inicie al final de los archivos log (o los diarios) en los que se escribirá el siguiente registro. No se capturará ninguna transacción activa.

Para Db2 LUW, configura el procesamiento para que se inicie en el valor LRI activo en los archivos log. La LRI activa es la posición al final de los archivos log, en la que se escribirá el siguiente registro. No se capturará ninguna transacción activa.

Para PostgreSQL, DBLOGIN es necesario para la posición por EOL.

Para MySQL, busca la posición que corresponde al final del archivo e inicia la lectura de las transacción desde esta. La posición de EOL no es exacta si los datos se escriben continuamente en el log binario.

EOF

Válido para MySQL, Db2 z/OS, Db2 LUW, SQL Server, PostgreSQL, Oracle GoldenGate for DAA.

LSN value

Válido para Db2 z/OS, PostgreSQL y SQL Server

Especifica la transacción LSN en la que se va a iniciar la captura de datos. El alias de esta opción es EXTLSN. El posicionamiento en un LSN es preciso.

Para Db2 z/OS, el valor de LSN puede ser una serie de dígitos hexadecimales o una serie de dígitos decimales. Si el formato es hexadecimal, debe llevar un prefijo 0X o 0x seguido de 1 a 20 dígitos hexadecimales: 0-9, a-g o A-G. Si el formato es decimal, no hay prefijo y hay 1-25 dígitos decimales: 0-9.

Para PostgreSQL, el valor de LSN puede ser hi o lo. Defina el valor como hi para el punto de entrada del archivo log. Lo es el desplazamiento en el archivo log. La Posición de LSN debe estar entre la Posición de Reinicio del Intervalo de Replicación y el Log de Escritura Avanzada de Ubicación Actual. Si la propia posición especificada existe entre el rango mencionado, Extract devolverá un error.

Para SQL Server, LSN especifica la transacción LSN en la que se va a iniciar la captura de datos. El alias de esta opción es EXTLSN.

El LSN especificado debe existir como un tran_begin_lsn válido encontrado en la tabla del sistema cdc.lsn_time_mapping; en caso contrario, el Extract intentará posicionarse después del valor del LSN proporcionado.

Las especificaciones LSN válidas para SQL Server incluyen lo siguiente:

Una cadena hexadecimal separada por dos puntos (8:8:4) rellenada con ceros iniciales y el prefijo 0X, como en 0X00000d7e:0000036b:0001
Una cadena hexadecimal separada por dos puntos con el prefijo 0X y sin ceros iniciales, como en 0Xd7e:36b:1

Puede encontrar el LSN mínimo disponible realizando una consulta de lo siguiente:

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

Los siguientes ejemplos muestran el uso del valor de LSN para Db2 z/OS:

Ejemplo 1:

ADD EXTRACT extn TRANLOG, LSN 0xDEE40E4F27A3245400

Ejemplo 2:

ADD EXTRACT extn TRANLOG, LSN 22216433159121980904448

El siguiente ejemplo muestra el valor de LSN para SQL Server:

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

LRI value

Válido para Db2 LUW. Especifica un punto de inicio en los logs de transacciones cuando se inicia Extract.

Puede utilizar la opción LRI para que los sistemas Db2 LUW especifiquen la LRI en el que se puede iniciar el proceso de extracción para capturar registros desde el registro de transacciones. Puede utilizar la utilidad Db2 db2logsForRfwd para obtener la LRI. Esta utilidad proporciona LRI rangos presentes en los logs de Db2.

Tenga en cuenta que aunque Extract podría posicionarse en una LRI especificada, dicha LRI podría no ser necesariamente la primera que procesará Extract. Hay varios tipos de registro en los archivos log que Extract ignora, como los registros de log internos de Db2. Extract indicará la LRI real al archivo de informe de Extract.

LOGNUM lognum

Válido para MySQL.

Es el número de archivo log. ADD EXTRACT fallará si el valor de LOGNUM contiene ceros delante del valor. Por ejemplo, ADD EXTRACT ext1, TRANLOG, LOGNUM 000001, LOGPOS 0 fallará. En su lugar, defina LOGNUM en 1 para poder que este ejemplo se ejecute correctamente.

LOGPOS logpos

Es un valor de desfase de evento dentro del archivo log que identifica un registro de transacción específico. Los valores de desfase de evento se almacenan en la sección de cabecera de un registro de log. Para posicionarse al principio de un archivo binlog, defina LOGPOS como 0.

SEQNO sequence_number

Válido para Db2 for i. Inicia la captura en un número de secuencia del sistema, o justo después, que es un número decimal con un máximo de 20 dígitos.

SCN value

Válido para Oracle.

Inicia Extract en la transacción en el redo log que tiene el número de cambio del sistema (SCN) de Oracle. Para Extract en modo integrado, el valor de SCN debe ser mayor que el SCN en el que se ha registrado el Extract con la base de datos. Para obtener más información, consulte REGISTER EXTRACT.

PARAMS file_name

Especifica el nombre de ruta completo de un archivo de parámetro de Extract en una ubicación distinta de la que se define por defecto en dirprm en el directorio Oracle GoldenGate.

REPORT file_name

Especifica el nombre de ruta completo de un archivo de informe de Extract en una ubicación distinta de la que se define por defecto en dirrpt en el directorio Oracle GoldenGate.

DESC ‘description’

Especifica una descripción del grupo, como 'Extracts account_tab on Serv1'. Incluya la descripción entre comillas simples.

ENCRYPTIONPROFILE

Especifica el nombre del perfil de cifrado de Oracle GoldenGate asociado al cliente específico.

GTIDSET gtidset

Válido para MySQL.

Especifica el posicionamiento inicial de un Extract mediante el tipo de posición como juego de GTID para la captura basada en GTID para MySQL. Los orígenes de MySQL soportados para el juego de GTID son MySQL Server 8.0 y versiones posteriores. El tamaño máximo de juego de GTID soportado es de 64 KB.

Sintaxis:

ADD EXTRACT extract_name, TRANLOG, GTIDSET gtidset

CRITICAL

Indica si el proceso es crítico para el despliegue.

PROFILE

Nombre del perfil de inicio automático.

AUTOSTART

Especifica si el proceso gestionado se tiene que iniciar automáticamente cuando se inicia el servicio de administración. El valor por defecto es YES.

DELAY

Tiempo de espera, en segundos, antes de iniciar el proceso.

AUTORESTART

Controla cómo se reiniciará el proceso en caso de que termine.

RETRIES

Número máximo de intentos para reiniciar la tarea antes de cancelar los esfuerzos de reintento. Esto es opcional.

WAITSECONDS

Duración (en segundos) en la que se cuentan los reintentos.

RESETSECONDS

Restablece la duración en la que se cuentan los reintentos.

DISABLEONFAILURE

Si se define en TRUE, la tarea se desactiva cuando se agota el número de reintentos.

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

Utilícelo para un Extract de alias. Especifica el nombre de host de DNS o la dirección IP del servidor proxy. Utilice cualquiera de ellos para definir el host, aunque debe utilizar la dirección IP si el servidor DNS es inaccesible. Si utiliza una dirección IP, utilice una dirección asignada IPv6 o IPv4 en función de la pila del sistema de destino. Debe especificar PROXYCSALIAS. Además, puede especificar el puerto que se va a utilizar y el dominio de almacenamiento de credenciales.

Ejemplos

En el siguiente ejemplo se crea un grupo de Extract denominado exte que captura las modificaciones de la base de Datos de los registros de transacciones. La extracción comienza con el registro generado en el momento de crear el grupo de Extract y se inició con ADD EXTRACT.

ADD EXTRACT extn, TRANLOG, BEGIN NOW

En el siguiente ejemplo, se crea un nombre de grupo de Extract extw para obtener los cambios de base de datos del log de transacciones posicionando el Extract en un registro de hora específico:

ADD EXTRACT extn, TRANLOG, BEGIN NOW

REGISTER EXTRACT extn DATABASE

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

En el siguiente ejemplo se crea un grupo de Extract integrado.

ADD EXTRACT extn, INTEGRATED TRANLOG, BEGIN NOW

En el siguiente ejemplo se crea un Extract de carga inicial denominado extei.

ADD EXTRACT extn, SOURCEISTABLE

Los siguientes ejemplos incluyen todas las combinaciones de formatos válidos de juego de GTID.

Ejemplo 1:

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

Ejemplo 2:

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

Ejemplo 3:

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

Ejemplo 4:

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

Nota: Como se muestra en el ejemplo 4, cuando el juego de GTID contiene varios uuids, para formar una solicitud de API de REST, este juego de GTID se divide en varios juegos de GTID mediante el separador de comas.

En los siguientes ejemplos se crea y posiciona un Extract en un número de cambio del sistema (SCN) de Oracle específico el redo log.

ADD EXTRACT extn TRANLOG SCN 123456

ADD EXTRACT extn INTEGRATED TRANLOG SCN 123456

En el siguiente ejemplo se crea un Extract en un sistema Db2 LUW.

ADD EXTRACT extn, TRANLOG LRI 8066.322711

En el siguiente ejemplo se crea un Extract con la opción de inicio automático utilizando el cliente del administrador.

ADD EXTRACT extn, TRANLOG , BEGIN NOW , AUTOSTART yes