Manutenção de Openflow Connector for PostgreSQL

Nota

O conector está sujeito aos Termos do conector Snowflake.

This topic describes important maintenance considerations and best practices for maintaining the Openflow Connector for PostgreSQL when making changes to the source PostgreSQL database. In addition, this topic describes how to restart table replication and reinstall the connector.

Restart table replication

A table in FAILED state — for example, due to a missing primary key or unsupported schema change — does not restart automatically. If a table enters a FAILED state or you need to restart replication from scratch, use the following procedure to remove and re-add the table to replication.

Nota

If the failure was caused by an issue in the source table such as a missing primary key, resolve that issue in the source database before continuing.

  1. Remove the table from flow parameters: In the Ingestion Parameters context, either remove the table from the Included Table Names or modify the Included Table Regex so the table is no longer matched.

  2. Verify the table has been removed:

    1. In the Openflow runtime canvas, right-click a processor group and choose Controller Services.

    2. In the table listing controller services, locate the Table State Store row, click the three vertical dots on the right side of the row, then choose View State.

    Importante

    You must wait until the table’s state is fully removed from this list before proceeding. Do not continue until this configuration change has completed.

  3. Clean up the destination: Once the table’s state shows as fully removed, manually DROP the destination table in Snowflake. Note that the connector will not overwrite an existing destination table during the snapshot phase; if the table still exists, replication will fail again. Optionally, the journal table and stream can also be removed if they are no longer needed.

  4. Re-add the table: Update the Included Table Names or Included Table Regex parameters to include the table again.

  5. Verify the restart: Check the Table State Store using the instructions given previously. The state of the table should appear with the status NEW, then transition to SNAPSHOT_REPLICATION, and finally INCREMENTAL_REPLICATION.

Atualização do PostgreSQL

Atualizar o conector requer uma abordagem diferente, dependendo se o PostgreSQL está sendo atualizado para a próxima versão secundária ou principal.

Atualizações de versões secundárias

  • São seguras para os dados.

  • Não exigem tratamento especial.

  • Exigem a interrupção do conector durante a atualização para evitar relatar problemas de conectividade.

  • Continuam replicando após a atualização, sem perda de dados.

Atualizações da versão principal

  • Exigem que o servidor PostgreSQL descarte slots de replicação, incluindo aqueles usados ​ pelo conector.

  • Não conseguem preservar ou migrar slots de replicação para a nova versão. Consulte também Atualizações para versões PostgresSQL 17 e posteriores.

  • Reiniciam a replicação de todas as tabelas da fase de instantâneo anterior.

Para realizar uma atualização de versão secundária, faça o seguinte:

  1. Interrompa o conector, incluindo todos os processadores e serviços dele.

  2. Atualize o PostgreSQL.

  3. Reinicie o conector.

Para realizar uma atualização de versão principal, faça o seguinte:

  1. Remova todas as tabelas da replicação no conector.

  2. Aguarde até que todas as filas no conector estejam vazias.

  3. Interrompa o conector, incluindo todos os processadores e serviços dele.

  4. Abra o grupo Incremental Load no conector.

  5. Clique com o botão direito do mouse no processador superior do grupo, Read PostgreSQL CDC Stream, e selecione View state.

  6. Clique em Clear state.

  7. Clique em Close.

  8. Atualize o PostgreSQL.

  9. Reinicie o conector. Um novo slot de replicação será criado.

  10. Adicione novamente todas as tabelas para iniciar a replicação.

Atualizações para versões PostgresSQL 17 e posteriores

A atualização para a versão PostgreSQL 17 foi aprimorada de forma que não é mais necessário remover slots de replicação ao atualizar para versões posteriores, como 17.1 » 18.0. A atualização para a versão PostgreSQL 17.0 ou posterior a partir de versões anteriores (16 e anteriores) remove slots de replicação e deve ser tratada como uma atualização principal. Versões futuras do PostgreSQL também podem aprimorar ainda mais o processo de atualização.

Reinstalar o conector

Esta seção descreve como reinstalar o conector. Ele aborda situações em que o novo conector é instalado no mesmo tempo de execução, ou quando é movido para um novo tempo de execução. A reinstalação é usada muitas vezes em conjunto com a replicação incremental com snapshots.

Aviso

Para que o conector possa continuar a replicar a partir da mesma posição de fluxo CDC em que parou antes da reinstalação, o banco de dados de origem deve reter o WAL por tempo suficiente para cobrir o tempo desde que o conector antigo foi interrompido e o novo conector foi iniciado. Certifique-se de que o parâmetro max_wal_size do servidor PostgreSQL seja alto o suficiente, dependendo do seu tráfego, e mantenha o tempo de reinstalação no mínimo.

Pré-requisitos

Revise e anote os valores de contexto dos parâmetros do conector. Se você estiver reinstalando o conector no mesmo tempo de execução, É possível reutilizar o contexto existente. Se a nova instância estiver localizada em um tempo de execução diferente, você terá que inserir novamente todos os parâmetros.

Para reinstalar o conector:

  1. Termine o processamento de todos os FlowFiles em andamento no conector existente e, em seguida, interrompa o conector.

    1. Faça login no Snowsight.

    2. No menu de navegação, selecione Ingestion » Openflow.

    3. Selecione Launch Openflow.

    4. No painel Openflow, selecione a guia Runtimes.

    5. Selecione o tempo de execução que contém o conector.

    6. Selecione o conector.

    7. Pare o processador mais alto Set Tables for Replication no grupo Snapshot Load.

    8. Pare o processador mais alto Read PostgreSQL CDC Stream no grupo Incremental Load.

    9. Se você alterou o valor do parâmetro Merge Task Schedule CRON, retorne-o para * * * * * ?, caso contrário, as filas não serão esvaziadas até a próxima execução agendada.

      Aguarde até que todos os FlowFiles do conector tenham sido processados e todas as filas estejam vazias. Quando todos os FlowFiles tiverem sido processados, o valor de Queued no grupo de processadores do conector se tornará zero. Se houver itens restantes nas filas do conector original, poderá haver lacunas de dados quando o novo conector for iniciado.

    10. Pare todos os processadores e serviços de controle no conector.

  2. Encontre e copie o nome do slot de replicação usado pelo conector original, visualizando o estado do processador mais alto no grupo Incremental Load com nome Read PostgreSQL CDC Stream. O nome do slot de replicação é armazenado sob a chave replication.slot.name. Copie o valor da chave para um editor de texto.

  3. Crie uma nova instância do conector. Se você estiver usando o mesmo tempo de execução do conector original, é possível optar por manter os contextos de parâmetro existentes e reutilizar as configurações.

    Cuidado

    O conector existente pode permanecer no tempo de execução e não interferir na nova instância, desde que permaneça parado.

  4. Se você estiver instalando em um tempo de execução diferente ou tiver excluído os contextos de parâmetro anteriores, insira todas as definições de configuração nos novos contextos de parâmetro, incluindo os nomes de tabela e padrões conforme descrito em Configure o Openflow Connector for PostgreSQL.

  5. Abra o contexto PostgreSQL Ingestion Parameters e defina o parâmetro Ingestion Type como incremental. Para mais informações sobre as preocupações, consulte Habilitação de replicação incremental sem instantâneos.

  6. Abra o contexto PostgreSQL Source Parameters, e defina o Replication Slot Name para o valor que você copiou anteriormente.

  7. Inicie o novo conector.

Notas de uso

O novo conector usará as mesmas tabelas de destino existentes criadas pelo conector original, mas criará novas tabelas de diário.