Sobre a Openflow Connector for PostgreSQL¶

Como as tabelas são replicadas¶

1. Introspecção de esquema: o conector descobre as colunas na tabela de origem, seus nomes, tipos e, em seguida, irá validá-las de acordo com as limitações do Snowflake e do conector. As falhas de validação fazem com que esse estágio falhe, e o ciclo se complete. Após a conclusão bem-sucedida da introspecção de esquema, o conector cria uma tabela de destino vazia.

2. Carga de instantâneo: o conector copia todos os dados disponíveis na tabela de origem para a tabela de destino. A falha nesse estágio encerra o ciclo, e nenhum outro dado é replicado. Após a conclusão bem-sucedida, todo o conjunto de dados da tabela de origem estará disponível na tabela de destino.

3. Carga incremental: o conector continua rastreando as alterações na tabela de origem e copiando-as para a tabela de destino. Isso continua até que a tabela seja removida da replicação. A falha nesse estágio interrompe permanentemente a replicação da tabela de origem, até que o problema seja resolvido.

   Nota

   Este conector pode ser configurado para iniciar imediatamente a replicação de alterações incrementais para tabelas recém-adicionadas, ignorando a fase de carregamento de instantâneos. Essa opção costuma ser útil ao reinstalar o conector em uma conta em que já existem dados replicados e você deseja continuar a replicação sem precisar criar novos instantâneos das tabelas.

   Para obter detalhes sobre como ignorar o carregamento de instantâneos e usar o processo de carregamento incremental, consulte Replicação incremental.

Suporte ao valor TOASTed¶

O conector oferece suporte à replicação de tabelas com valores TOAST para colunas dos tipos: array, bytea, json, jsonb, text, varchar, xml.

Sempre que o conector encontra um valor TOASTed no fluxo CDC, ele substitui um espaço reservado padrão de __previous_value_unchanged, formatado para o tipo de coluna fornecido e o armazena na tabela de diário. A consulta MERGE então contabiliza os valores de espaço reservado, de modo que a tabela de destino contenha sempre o último valor não relacionado a TOASTed.

Suporte para valores fora do intervalo¶

O conector oferece suporte à replicação de tabelas com colunas dos tipos date, timestamp e timestamptz que contêm valores fora do intervalo. Se o conector encontrar um valor fora do intervalo no fluxo CDC, ele substitui um espaço reservado padrão com base no tipo da coluna.

Status da replicação da tabela¶

Falhas temporárias, como erros de conexão, não impedem a replicação das tabelas. Entretanto, falhas permanentes, como tipos de dados incompatíveis, impedem a replicação das tabelas.

Para solucionar problemas de replicação ou verificar se uma tabela foi removida com êxito do fluxo de replicação, consulte o armazenamento de estado de tabela:

1. Na tela do tempo de execução do Openflow, clique com o botão direito do mouse em um grupo de processadores e escolha Controller Services. Uma tabela que lista os serviços do controlador é exibida.

2. Localize a linha chamada Table State Store, clique no botão More à direita da linha e escolha View State.

Uma lista de tabelas e os respectivos estados atuais é exibida. Digite na caixa de pesquisa para filtrar a lista por nome da tabela. Os estados possíveis são:

• NEW: a tabela está agendada para replicação, mas a replicação não foi iniciada.

• SNAPSHOT_REPLICATION: o conector está copiando os dados existentes. Esse status é exibido até que todos os registros sejam armazenados na tabela de destino.

• INCREMENTAL_REPLICATION: o conector está replicando as alterações ativamente. Esse status é exibido após o término da replicação do instantâneo e continua a ser exibido indefinidamente até que uma tabela seja removida da replicação ou a replicação falhe.

• FAILED: a replicação foi interrompida permanentemente devido a um erro.

Replication state for table <database_name>.<schema_name>.<table_name> changed from <old_state> to <new_state>

Se uma falha permanente impedir a replicação da tabela, remova a tabela da replicação. Depois de resolver o problema que causou a falha, você poderá adicionar a tabela de volta à replicação. Para obter mais informações, consulte Reiniciar a replicação da tabela.

Colunas de metadados da tabela de destino¶

Cada tabela de destino inclui as seguintes colunas de metadados que rastreiam informações de replicação:

Linhas excluídas logicamente¶

Quando uma linha é excluída da tabela de origem, o conector não a remove fisicamente da tabela de destino. Em vez disso, a linha é marcada como excluída definindo a coluna de metadados _SNOWFLAKE_DELETED como true.

Essa abordagem permite:

• Reter dados históricos para fins de auditoria ou conformidade.

• Consultar registros excluídos quando necessário.

• Decidir quando e como remover dados permanentemente com base em suas necessidades.

Para consultar apenas linhas ativas (não excluídas), filtre pela coluna _SNOWFLAKE_DELETED:

SELECT * FROM my_table WHERE _SNOWFLAKE_DELETED = FALSE;

Para consultar linhas excluídas:

SELECT * FROM my_table WHERE _SNOWFLAKE_DELETED = TRUE;

Colunas descartadas¶

Quando uma coluna é descartada da tabela de origem, o conector não descarta a coluna correspondente da tabela de destino. Em vez disso, a coluna é renomeada anexando o sufixo __SNOWFLAKE_DELETED para preservar os valores históricos.

Por exemplo, se uma coluna chamada EMAIL for descartada da tabela de origem, ela será renomeada para EMAIL__SNOWFLAKE_DELETED na tabela de destino. As linhas que existiam antes do descarte da coluna mantêm os valores originais, enquanto as linhas adicionadas após o descarte terão NULL nessa coluna.

Você ainda pode consultar os valores históricos da coluna renomeada:

SELECT EMAIL__SNOWFLAKE_DELETED FROM my_table;

Colunas renomeadas¶

Devido às limitações nos mecanismos de captura de dados de alteração (Change Data Capture, CDC), o conector não consegue distinguir entre uma coluna renomeada e uma coluna descartada seguida da adição de uma nova coluna. Como resultado, quando você renomeia uma coluna na tabela de origem, o conector trata isso como duas operações separadas: descartar a coluna original e adicionar uma nova coluna com o novo nome.

Por exemplo, se você renomear uma coluna de A para B na tabela de origem, a tabela de destino conterá:

• A__SNOWFLAKE_DELETED: contém valores de antes da renomeação. As linhas adicionadas após a renomeação têm NULL nesta coluna.

• B: contém valores de depois da renomeação. As linhas que existiam antes da renomeação têm NULL nesta coluna.

SELECT
    COALESCE(B, A__SNOWFLAKE_DELETED) AS A_RENAMED_TO_B
FROM my_table;

SELECT
    CASE
        WHEN B IS NOT NULL THEN B
        ELSE A__SNOWFLAKE_DELETED
    END AS A_RENAMED_TO_B
FROM my_table;

CREATE VIEW my_table_unified AS
SELECT
    *,
    COALESCE(B, A__SNOWFLAKE_DELETED) AS A_RENAMED_TO_B
FROM my_table;

Tabelas de diário¶

Durante a replicação incremental, as alterações do banco de dados de origem são gravadas primeiro em tabelas de diário antes de serem mescladas às tabelas de destino. O conector não remove automaticamente os dados das tabelas de diário, pois esses dados podem ser úteis para fins de auditoria, depuração ou reprocessamento.

As tabelas de diário são criadas no mesmo esquema que as respectivas tabelas de destino e seguem esta convenção de nomenclatura:

<TABLE_NAME>_JOURNAL_<timestamp>_<number>

Onde:

• <TABLE_NAME> é o nome da tabela de destino.

• <timestamp> é o carimbo de data/hora de criação no formato de época Unix (segundos desde 1º de janeiro de 1970), garantindo a exclusividade.

• <number> começa em 1 e incrementa sempre que o esquema da tabela de destino é alterado, seja devido a alterações no esquema da tabela de origem ou a modificações nos filtros de coluna.

Por exemplo, se a tabela de destino for SALES.ORDERS, a tabela de diário poderá ter o nome SALES.ORDERS_JOURNAL_1705320000_1.