ADD EXTRACT

Válido para bancos de dados Db2, HP NonStop, MySQL, Oracle, PostgreSQL, SQL Server, Sybase ASE e Yugabyte suportados.

Use ADD EXTRACT para criar um processo de captura do banco de dados de origem, conhecido como Extract. O Extract pode ser criado como um Extract de alteração de dados, que captura transações atuais do log do banco de dados ou por outro meio, dependendo do fornecedor do banco de dados, ou ele pode ser criado como um Extract de carga inicial, que vai capturar os registros que existem nas tabelas de banco de dados.

É recomendado criar apenas um Extract de alteração de dados ou de carga inicial por banco de dados de origem. Porém, em raras situações, é possível melhorar o throughput de captura usando vários Extracts por banco de dados.

O Oracle GoldenGate pode oferecer suporte a um grande número de processos Extract e Replicat simultâneos por implantação, dependendo dos recursos disponíveis no sistema operacional. Contudo, é recomendado monitorar os recursos do sistema à medida que mais processos Extract ou Replicat forem adicionados, e manter o número total de processos em até 300 por implantação.

Observação:

Se você estiver criando um Extract com o mesmo nome de um Extract antigo, certifique-se de que o Extract antigo tenha sido completamente removido e eliminado. Você pode usar DELETE EXTRACT para remover o EXTRACT e todos os seus componentes.
Este comando não pode exceder 500 bytes de tamanho para todas as palavras-chave e entrada, incluindo qualquer texto que você informar para a opção DESC.
No Db2 for i, esse comando estabelece um ponto inicial global para todos os diários e é uma primeira etapa obrigatória. Depois de emitir o comando ADD EXTRACT, é possível posicionar opcionalmente um determinado lançamento em um número de sequência de lançamento específico usando o comando ALTER EXTRACT com uma opção apropriada.
Para bancos de dados Oracle e PostgreSQL, estabeleça uma conexão com o banco de dados de origem usando DBLOGIN USERIDALIAS e, em seguida, emita o comando REGISTER EXTRACT antes de adicionar a Extração. Para obter detalhes, consulte o comando REGISTER EXTRACT.
Para o SQL Server, estabeleça uma conexão com o banco de dados de origem usando DBLOGIN USERIDALIAS, antes de adicionar a Extração. Isso é necessário para que o Administration Service vincule as informações da credencial com o processo Extract.

Sintaxe

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

O nome de um Extract. Ela pode conter até oito caracteres. Consulte Choosing Names for Processes and Files.

SOURCEISTABLE

Cria uma tarefa Extract que extrai registros inteiros das tabelas especificadas para uma carga inicial usando o Oracle GoldenGate. Ao usar SOURCEISTABLE, não especifique nenhuma opção de serviço.

Os parâmetros da tarefa devem ser especificados no arquivo de parâmetros. Consulte Adicionar Extração de Carga Inicial Usando o Cliente Admin na Documentação de Microsserviços do Oracle GoldenGate.

TRANLOG [bsds_name]

Use essa opção para todos os bancos de dados. TRANLOG requer a opção BEGIN.

(Db2 em z/OS) Você pode usar a opção bsds_name para Db2 em um sistema z/OS para especificar o nome de arquivo Inicializar Conjunto de Dados para o log de transação, embora não seja necessário e não seja usado. Não é necessário alterar os parâmetros existentes do TRANLOG.

(Oracle) O Extract lê os redo logs diretamente no sistema Oracle. Consulte INTEGRATED TRANLOG para obter uma configuração alternativa.

INTEGRATED TRANLOG

Válido para Oracle.

Adiciona o Extract no modo de captura integrado. Nesse modo, o Extract se integra ao servidor de logmining do banco de dados, que passa os registros lógicos de alterações (LCRs) diretamente ao Extract. Antes de usar o INTEGRATED TRANLOG, use o comando REGISTER EXTRACT.

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

Especifica um timestamp na origem de dados na qual iniciar o processamento.

Observação: Registre o Extract antes de posicionar o Extract para um timestamp específico.

NOW

NOW especifica o horário em que o comando ADD EXTRACT é emitido e quando o Extract é iniciado, ele tentará se posicionar em um limite de transação no horário específico ou após esse horário. O posicionamento de um Extract por NOW não é tão preciso quanto outros métodos, como o posicionamento por LSN, SCN ou LRI, e exige que o servidor de banco de dados e o servidor do Oracle GoldenGate sejam definidos com os mesmos horários e fusos horários.

No Db2 LUW, apenas os registros de transação de commit e encerramento contêm timestamps. Portanto, a posição inicial do Extract só pode ser calculada em relação a esses timestamps. Essa é uma limitação da API que é usada pelo Oracle GoldenGate. Deve ser observado que o posicionamento por timestamps não é preciso e também pode levar bastante tempo. Recomenda-se o uso de opções LRI ou EOL sempre que possível.
yyyy-mm-ddthh:mm.ssZ

Uma data e hora (timestamp) no formato em questão. Por exemplo, 2017-07-14T14:54:45Z.
yyyy-mm-ddT[ hh:mi:[ss[.cccccc]]]Z

Uma data e hora (timestamp) no formato em questão. Para um Oracle Extract e um Extract para PostgreSQL, o valor do timestamp deve ser maior que o timestamp no qual o Extract foi registrado no banco de dados.

O posicionamento por timestamp no PostgreSQL inclui os seguintes cenários:
- Cenário 1
  
  Se track_commit_timestamp for off, a seguinte saída será exibida quando o processo de Extração for iniciado, independentemente do método de posicionamento usado:
```
2020-04-29T02:15:54Z
```
- Cenário 2
  
  Se o track_commit_timestamp for ativado antes de o Extract ser registrado, o timestamp correto será exibido assim que os registros forem enviados no banco de dados de origem, conforme mencionado no seguinte exemplo:
```
2020-04-29 02:19:07 INFO OGG-01515 Positioning to begin time Apr 29,2020 2:18:38 AM.
```
- Cenário 3
  
  Se o track_commit_timestamp estiver ativado depois que o Extract for registrado, talvez haja chances de que os registros mais antigos estejam disponíveis no log para o qual o timestamp de commit não foi criado com o transaction ID associado. Nesse caso, se o Extract não obtiver o timestamp, ele fará fallback usando o timestamp padrão mencionado no cenário 1. A saída será semelhante à seguinte:
```
020-04-29 01:55:07 INFO OGG-01517 Position of first record processed LSN: 0/221D028, Jan 1, 1970 12:00:00 PM.
```
- O timestamp anterior não poderá ser especificado se o slot de replicação tiver sido movido.

EXTRBA archive-offset_number

Válido para Db2 z/OS.

Especifica o endereço de byte relativo em um log de transação no qual começar a capturar dados.

O formato obrigatório é 0Xnnn, no qual nnn é um número hexadecimal de 1 a 20 dígitos (o primeiro caractere é o dígito zero e o segundo pode ser a letra maiúscula ou minúscula x).

EOL

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

Configura o processamento para começar no final dos arquivos de log (ou diários) nos quais o próximo registro será gravado. As transações ativas não serão capturadas.

Para Db2 LUW, ele configura processamento para começar com o valor LRI ativo nos arquivos de log. O LRI ativo é a posição no final dos arquivos do log nos quais o próximo registro será gravado. As transações ativas não serão capturadas.

Para PostgreSQL, DBLOGIN é obrigatório para a posição por EOL.

No MySQL, ele encontra a posição correspondente ao final do arquivo e inicia a leitura das transações a partir daí. A posição do EOL não será exata se os dados forem gravados continuamente no log binário.

EOF

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

LSN value

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

Especifica a transação LSN na qual os dados de captura devem ser iniciados. Um alias para essa opção é EXTLSN. O posicionamento para um LSN é preciso.

Para Db2 z/OS, o valor do LSN pode ser uma série de dígitos hexadecimais ou uma série de dígitos decimais. Se estiver em formato hexadecimal, ele deverá ser prefixado com 0X ou 0x seguido por 1 a 20 dígitos hexadecimais: 0-9, a-g ou A-G. Se for no formato decimal, não haverá prefixo e haverá de 1 a 25 dígitos decimais de 0 a 9.

Para PostgreSQL, o valor LSN pode ser hi ou lo. Defina o valor como hi para o ponto de entrada do arquivo da log. Lo é o deslocamento no arquivo de log. A posição do LSN deve ficar entre a posição da reinicialização do slot de replicação e a localização atual do log de gravação antecipada. Se existir uma posição especificada por si só entre a faixa mencionada, o Extract vai gerar um erro.

Para o SQL Server, LSN especifica a transação LSN na qual os dados devem ser capturados. Um alias para essa opção é EXTLSN.

O LSN especificado deve existir como um tran_begin_lsn válido encontrado na tabela do sistema cdc.lsn_time_mapping; caso contrário, o Extract tentará posicioná-lo após o valor de LSN fornecido.

As especificações válidas do LSN para o SQL Server consistem no seguinte:

String hexadecimal separada por dois-pontos (8:8:4) preenchida com zeros à esquerda e o prefixo 0X, como em 0X00000d7e:0000036b:0001
String hexadecimal separada por dois-pontos com o prefixo 0X e sem zeros à esquerda, como em 0Xd7e:36b:1

Você pode encontrar o LSN mínimo disponível consultando o seguinte:

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

Os exemplos a seguir mostram o uso do valor do LSN para Db2 z/OS:

Exemplo 1:

ADD EXTRACT extn TRANLOG, LSN 0xDEE40E4F27A3245400

Exemplo 2:

ADD EXTRACT extn TRANLOG, LSN 22216433159121980904448

O seguinte exemplo mostra o valor do LSN para for SQL Server:

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

LRI value

Válido para Db2 LUW. Especifica uma posição inicial nos logs de transação quando o Extract é iniciado.

Você pode usar a opção LRI para sistemas LUW Db2 a fim de especificar o LRI no qual a extração pode iniciar a captura de registros no log da transação. Você pode usar o utilitário Db2 db2logsForRfwd para obter a LRI. Este utilitário fornece faixas LRI presentes nos logs Db2.

Observe que, embora o Extract possa posicionar-se para uma determinada LRI, essa LRI pode não ser necessariamente a primeira que o Extract processará. Há inúmeros tipos de registro nos arquivos de log que o Extract ignora, como registros de log interno do Db2. O Extract reportará o LRI inicial real para o arquivo de relatório do Extract.

LOGNUM lognum

Válido para MySQL.

Este é o número do arquivo de log. ADD EXTRACT falhará se o valor LOGNUM contiver zeros precedendo o valor. Por exemplo, o ADD EXTRACT ext1, TRANLOG, LOGNUM 000001, LOGPOS 0 falhará. Em vez disso, defina LOGNUM como 1 para este exemplo a ser bem-sucedido.

LOGPOS logpos

Este é um valor de referência de evento no arquivo de log que identifica um registro de transação específico. Os valores de referência de evento são armazenados na seção de cabeçalho de um registro de log. Para posicionar no início de um arquivo de binlog, defina LOGPOS como 0.

SEQNO sequence_number

Válido para Db2 for i. Inicia a captura no número sequencial do sistema ou logo após, que é um número decimal com até 20 dígitos.

SCN value

Válido para Oracle.

Inicia o Extract na transação, no redo log que tem o número de alteração do sistema (SCN) Oracle especificado. Para Extract no modo integrado, o valor do SCN deve ser maior que o SCN no qual o Extract foi registrado no banco de dados. Para obter mais informações, consulte REGISTER EXTRACT.

PARAMS file_name

Especifica o nome completo do caminho de um arquivo de parâmetros Extract em um local que não seja o padrão de dirprm no diretório do Oracle GoldenGate.

REPORT file_name

Especifica o nome completo do caminho de um arquivo do relatório Extract em um local diferente do padrão de dirrpt no diretório do Oracle GoldenGate.

DESC ‘description’

Especifica uma descrição do grupo, como 'Extracts account_tab on Serv1'. Coloque a descrição entre aspas simples.

ENCRYPTIONPROFILE

Especifica o nome do perfil de criptografia do Oracle GoldenGate associado ao cliente específico.

GTIDSET gtidset

Válido para MySQL.

Especifica o posicionamento inicial do Extract usando o tipo de posição positiob como conjunto GTID para captura baseada em GTID no MySQL. As origens MySQL com suporte para conjunto GTID são MySQL Server 8.0 e versões posteriores. O tamanho máximo de conjunto GTID com suporte é de 64 KB.

Sintaxe:

ADD EXTRACT extract_name, TRANLOG, GTIDSET gtidset

CRITICAL

Indica se o processo é crítico para a implantação

PROFILE

Nome do perfil de início automático.

AUTOSTART

Especifica se o processo gerenciado deverá ser iniciado automaticamente quando o Administration Service for iniciado. O valor padrão é YES.

DELAY

Tempo de espera em segundos antes de iniciar o processo.

AUTORESTART

Controla como o processo será reiniciado se ele terminar.

RETRIES

O número máximo de tentativas de reiniciar a tarefa antes de cancelar os esforços de repetição. Essa definição é opcional.

WAITSECONDS

A duração (em segundos) na qual as novas tentativas são contadas.

RESETSECONDS

Redefine a duração na qual as novas tentativas são contadas.

DISABLEONFAILURE

Se for definido como TRUE, a tarefa será desativada quando o número de novas tentativas for esgotado.

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

Use para um Extract do alias. Especifica o nome do host ou endereço IP DNS do servidor proxy. Você pode usar qualquer um para definir o host, embora você deva usar o endereço IP caso o seu servidor DNS não esteja acessível. Se você estiver usando um endereço IP, use um endereço mapeado em IPv6 ou IPv4, dependendo da pilha do sistema de destino. Você deve especificar PROXYCSALIAS. Além disso, você pode especificar a porta a ser usada e o domínio do armazenamento de credenciais.

Exemplos

O exemplo a seguir cria um grupo de Extração chamado exte que captura as alterações do banco de Dados dos logs da transação. A extração começa com registros gerados no momento da criação do grupo Extract e é iniciada com ADD EXTRACT.

ADD EXTRACT extn, TRANLOG, BEGIN NOW

No exemplo a seguir, um nome de grupo do Extract extw é criado para obter as alterações do banco de dados dos logs da transação posicionando o Extract em um timestamp específico:

ADD EXTRACT extn, TRANLOG, BEGIN NOW

REGISTER EXTRACT extn DATABASE

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

A opção a seguir cria um grupo Extract integrado.

ADD EXTRACT extn, INTEGRATED TRANLOG, BEGIN NOW

A seguir, cria uma Extração de carga inicial chamada extei.

ADD EXTRACT extn, SOURCEISTABLE

Os exemplos a seguir incluem todas as combinações de formatos válidos de conjunto GTID.

Exemplo 1:

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

Exemplo 2:

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

Exemplo 3:

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

Exemplo 4:

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

Observação: conforme mostrado no exemplo 4, quando o GTID definido contém vários uuids, para formar uma solicitação de API REST, esse GTID definido é dividido em vários GTIDs usando separador de vírgulas.

Os exemplos a seguir criam e posicionam o Extract em um número de alteração do sistema (SCN) específico da Oracle no redo log.

ADD EXTRACT extn TRANLOG SCN 123456

ADD EXTRACT extn INTEGRATED TRANLOG SCN 123456

O exemplo a seguir cria um Extract em um sistema Db2 LUW.

ADD EXTRACT extn, TRANLOG LRI 8066.322711

O exemplo a seguir cria um Extract com a opção de início automático usando o Admin Client.

ADD EXTRACT extn, TRANLOG , BEGIN NOW , AUTOSTART yes