YugabyteDB: Tratando Alterações de Esquema

Saiba mais sobre como tratar alterações de esquema no Oracle GoldenGate para YugabyteDB.

Pré-requisitos para Tratar Alterações de Esquema

Para suportar qualquer alteração de esquema nos níveis de tabela e coluna em bancos de dados Yugabyte, as seguintes configurações são necessárias em T-Server e Listas principais de gflag:

cdcsdk_publication_list_refresh_interval_secs

Define o intervalo de atualização da lista de publicações.
Configure de acordo com o tempo de espera adequado para o seu ambiente (padrão: 900 segundos).

cdcsdk_enable_dynamic_table_support

Ativa o suporte a tabelas dinâmicas no CDC.
Por padrão, é definido como true. Confirme se é explicitamente verdadeiro para o Servidor T e Gflags principais.

Diretrizes para tratar alterações de esquema no Oracle GoldenGate for Yugabyte

As seguintes diretrizes são importantes e devem ser consideradas ao executar operações DDL no banco de dados de Yugabyte:

Sempre respeite o intervalo cdcsdk_publication_list_refresh_interval_secs antes de executar operações DML.
Interrompa o processo Extract para garantir alterações de esquema seguras e evitar possíveis problemas de captura de dados.
Depois de reiniciar o Extract, sempre valide se as colunas novas ou restantes foram capturadas corretamente.
O banco de dados Yugabyte não suporta a eliminação de uma tabela. Consulte o seguinte link para saber mais:

https://docs.yugabyte.com/stable/additional-features/change-data-capture/using-logical-replication/#limitations

Tratando Alterações de Esquema no Nível da Tabela

Saiba mais sobre como tratar alterações de esquema no nível da tabela no Oracle GoldenGate para YugabyteDB.

Adicionar uma Nova Tabela a um Processo de Extração Existente

Este procedimento depende da configuração de publicação do Yugabyte. Há dois tipos de publicações:

Publicação Configurada para Todas as Tabelas: Neste tipo de publicação, novas tabelas são adicionadas dinamicamente e nenhuma alteração é necessária para a publicação.
Publicação Configurada para um Conjunto de Tabelas: Se uma nova tabela for criada, a publicação deverá ser alterada para incluir a nova tabela.

Adicionar uma nova tabela a um processo Extract existente

A seguir estão as etapas comuns para adicionar uma nova tabela para um processo Extract existente: 1. Interrompa o processo Extract antes de fazer alterações.

Atualizar o arquivo de parâmetros Extract para adicionar as novas tabelas ou tabelas à configuração Extract.
Aguarde o Intervalo de Atualização definido em cdcsdk_publication_list_refresh_interval_secs.

Opcionalmente, permita uma pequena janela de buffer para garantir que a tabela seja totalmente atualizada no módulo CDC.
Reinicie o processo Extract após a conclusão do intervalo de atualização.
Execute operações DML na nova tabela.
Verifique se o processo Extract captura os novos registros com sucesso.

Adicionar uma Nova Tabela a um Processo de Extração Existente - Exemplo

Considere o cenário deste exemplo:

Existe uma tabela com duas publicações configuradas:

Publicação 1 (pub1): Quadro específico
Publicação 2 (pub2): Todas as tabelas
Dois Extracts (Ext1 usando pub1, Ext2 usando pub2) com listas de tabelas estáticas
As operações DML na tabela estática são capturadas pelos dois processos Extract

O exemplo a seguir fornece as etapas para adicionar uma nova tabela a um processo Extract existente com base nas considerações anteriores:

Pare Ext1 e Ext2.
Crie novas tabelas (table2, table3).
Atualize os arquivos de parâmetros de extração para Ext1 e Ext2.
Altere pub1 para incluir novas tabelas. Pub2 não requer alterações.
Reinicie Ext1 e Ext2.
Aguarde o intervalo de atualização (cdcsdk_publication_list_refresh_interval_secs).
Executar operações DML em novas tabelas e verificar se os dois Extracts as capturam com sucesso.

Eliminar uma Tabela de um Processo de Extração

Há dois cenários a serem considerados ao eliminar uma tabela:

A tabela faz parte de uma publicação

Se a tabela for incluída em uma publicação, não será permitido eliminar a tabela. Se você tentar eliminar a tabela nesse cenário, ela tornará o slot de fluxo ou replicação usado pelo Extract inutilizável, e você poderá encontrar erros como:

2026-03-04 11:21:44 ERROR OGG-30611 Yugabyte has closed the streaming client and has caused the Extract to abend.
Error: ERROR: XX000: LookupByIdRpc(tablet: d092b524eff34d21b45c78ead108122a, num_attempts: 1) failed: Tablet deleted: Table deleted at 2026-03-04 11:21:44 UTC.
CONTEXT: Catalog Version Mismatch: A DDL occurred while processing this query. Try again.LOCATION: YBPrepareCacheRefreshIfNeeded, postgres.c:4160.

2026-03-04 11:22:51 ERROR OGG-30605 Dropping any table used by the Extract will cause the Extract to abend and disconnect the YDB streaming client.
Error: ERROR: XX000: VirtualWAL initialisation failed for stream_id: afdaa2e91ebc288be74724e8fb780342 & session_id: 51: Table 000033cf00003000800000000000400f not found under stream
CONTEXT: Catalog Version Mismatch: A DDL occurred while processing this query. Try again.LOCATION: YBPrepareCacheRefreshIfNeeded, postgres.c:4160.

Cuidado: Se esses erros ocorrerem, a única solução será cancelar o registro do Extract afetado e registrá-lo novamente. Esta etapa é crítica para restaurar o operation.This normal também pode causar perda de dados. Portanto, é necessário cautela.

A tabela não faz parte de uma publicação

Se a tabela não estiver incluída em nenhuma publicação, eliminá-la não terá impacto no fluxo. Nenhuma ação é necessária e a replicação continuará como de costume.

Tratando Alterações de Esquema no Nível da Coluna

Saiba mais sobre como tratar alterações de esquema no nível da coluna, como adicionar e eliminar colunas no Oracle GoldenGate para YugabyteDB.

Adicionar uma Coluna

Para executar uma operação ALTER TABLE … ADD COLUMN em uma tabela que faz parte de uma publicação: 1. Interrompa o processo Extract antes de começar a adicionar uma coluna à tabela. Isso impede que o Extract seja pendente.

Adicione a coluna na tabela que está incluída na publicação usando o seguinte comando:
```
ALTER TABLE...ADD COLUMN
```
Aguarde a duração especificada no cdcsdk_publication_list_refresh_interval_secs para garantir que o módulo CDC seja atualizado e reconheça a nova coluna.
Execute as operações DML (INSERTS, UPDATES ou DELETES) na nova coluna.
Reinicie o processo Extract e verifique se as alterações, incluindo as operações DML na nova coluna, foram capturadas com sucesso.

Eliminar uma Coluna

Para eliminar uma(s) coluna(s) de uma tabela que faça parte de uma publicação: 1. Interrompa o processo Extract. Embora a eliminação de uma coluna geralmente não faça com que o Extract seja encerrado de forma anormal, ainda é recomendável interromper o Extract antes de fazer alterações no esquema.

Execute o seguinte comando na tabela incluída na publicação:
```
ALTER TABLE ... DROP COLUMN
```
Aguarde a duração especificada em cdcsdk_publication_list_refresh_interval_secs para garantir que o módulo CDC seja atualizado.
Execute as operações DML (INSERT, UPDATE, DELETE), conforme necessário.
Reinicie o processo Extract e confirme se as operações DML nas colunas restantes continuam a ser capturadas corretamente.