Transmitir dados de bancos de dados PostgreSQL

Use o Datastream para replicar dados históricos e alterações contínuas de um banco de dados PostgreSQL para o destino, para análise em tempo real e sincronização de banco de dados.

Para se preparar para a replicação do PostgreSQL no Datastream, revise o comportamento de replicação, as versões e os tipos de banco de dados compatíveis, as práticas recomendadas, os requisitos para réplicas de leitura e as limitações conhecidas.

Comportamento

O banco de dados PostgreSQL de origem depende do recurso de decodificação lógica. A decodificação lógica expõe todas as alterações confirmadas no banco de dados e permite consumir e processar essas alterações em um formato fácil de usar com um plug-in de saída. O Datastream usa o plug-in pgoutput, que é o plug-in de decodificação lógica padrão do PostgreSQL para o PostgreSQL 10 e versões mais recentes.

  • É possível selecionar todos os esquemas ou esquemas específicos de uma determinada origem do PostgreSQL, bem como todas as tabelas do esquema ou tabelas específicas.
  • Todos os dados históricos são replicados.
  • Todas as alterações da linguagem de manipulação de dados (DML), como inserções, atualizações e exclusões dos bancos de dados e tabelas especificados, são replicadas.
  • Apenas alterações confirmadas são replicadas.
  • Se você definir uma REPLICA IDENTITY em uma tabela, o Datastream vai tratar as colunas especificadas como chaves primárias.
  • O Datastream envia periodicamente mensagens de sinal de funcionamento ao banco de dados de origem quando ele está conectado a uma instância principal. Como resultado, os eventos de mensagem de decodificação lógica (op:"m") são inseridos diretamente no arquivo WAL. Essas mensagens são necessárias para que o Datastream garanta a disponibilidade da origem e calcule o nível de atualização. Ao usar uma réplica de leitura como origem, é necessário configurar as mensagens de heartbeat externamente. Consulte Replicação de réplicas de leitura para mais informações. Recomendamos que você considere isso se outras configurações de replicação lerem do mesmo banco de dados de origem.

Versões

O Datastream é compatível com o PostgreSQL versão 10 e mais recentes.

O Datastream é compatível com os seguintes tipos de banco de dados PostgreSQL:

  • PostgreSQL auto-hospedado
  • Cloud SQL para PostgreSQL
  • AlloyDB para PostgreSQL
  • AlloyDB Omni
  • Amazon RDS para PostgreSQL
  • Amazon Aurora PostgreSQL

Nível sem custo financeiro

O Datastream permite fazer streaming do AlloyDB para PostgreSQL para o BigQuery usando o nível sem custo financeiro, fornecendo até 100 GiB de dados de captura de dados alterados sem custo financeiro todos os meses. Para mais informações, consulte Preços do Datastream.

Práticas recomendadas

Nesta seção, descrevemos as práticas recomendadas para configurar sua origem do PostgreSQL para uso com o Datastream.

Usar vários streams para evitar o bloqueio de cabeça de linha

Para origens do PostgreSQL, o Datastream usa um único slot de replicação lógica para um stream inteiro. Uma transação grande ou várias atualizações em uma tabela de alto volume podem atrasar a replicação de dados para todas as outras tabelas no mesmo stream.

Para evitar o bloqueio de cabeçalho, crie streams separados para diferentes conjuntos de tabelas. Por exemplo, é possível criar um stream para tabelas de alto volume e outro para tabelas de baixo volume. Isso isola as tabelas com alta rotatividade e evita que elas atrasem a replicação de outras tabelas.

Recomendação:identifique tabelas com taxas de gravação (INSERT/UPDATE/DELETE) excepcionalmente altas e coloque-as no próprio stream dedicado do Datastream com um slot de replicação separado.

Evitar transações de longa duração

Transações de longa duração podem levar ao acúmulo de registros WAL. Como o WAL é sequencial, o PostgreSQL não pode remover os arquivos WAL antigos necessários para o slot de replicação até que a transação longa seja concluída. Isso aumenta o uso do disco do WAL.

Além disso, isso pode deixar a decodificação lógica mais lenta. A lentidão é causada por transações grandes que transferem mudanças para o disco, o que exige uma remontagem lenta e com uso intensivo de E/S na confirmação, bloqueando a replicação de todas as transações subsequentes. Recomendação:no banco de dados de origem, configure os parâmetros statement_timeout e idle_in_transaction_session_timeout para evitar transações de longa duração. Para mais informações, consulte a documentação do PostgreSQL.

Usar a filtragem de tabelas ao criar publicações

Se você estiver replicando alterações de apenas algumas tabelas, crie uma PUBLICATION que inclua apenas essas tabelas. Quando uma publicação tem como escopo tabelas específicas, o PostgreSQL mantém as mudanças de maneira eficiente apenas para essas tabelas no slot de replicação. Isso ajuda a reduzir o tamanho do slot de replicação e melhora o desempenho da decodificação lógica.

Gerenciar slots de replicação de forma proativa

O Datastream usa um slot de replicação lógica na instância principal do PostgreSQL, o que garante que os arquivos WAL sejam retidos até que o Datastream confirme que eles foram processados. Se um stream falhar, for pausado ou excluído sem descartar o slot de replicação, o PostgreSQL vai continuar retendo os arquivos WAL indefinidamente. Isso pode preencher o disco do servidor de banco de dados e causar uma interrupção na produção.

Recomendação:configure alertas eficientes e monitore o uso do disco WAL no servidor PostgreSQL de origem.

Configurar a identidade da réplica corretamente

A configuração REPLICA IDENTITY informa ao PostgreSQL quais dados gravar no WAL para eventos UPDATE e DELETE, permitindo que o Datastream identifique quais linhas foram alteradas.

Se você usar o BigQuery como destino, evite definir REPLICA IDENTITY como FULL. O Datastream usa as colunas registradas como uma chave lógica para operações MERGE do BigQuery. Se REPLICA IDENTITY for definido como FULL e uma tabela tiver mais de 16 colunas, isso vai exceder o limite de 16 colunas do BigQuery para chaves primárias em operações MERGE e interromper o stream.

Recomendações (em ordem de preferência):

  1. Melhor:use uma chave primária. A configuração padrão de REPLICA IDENTITY DEFAULT usa de forma automática e eficiente a chave primária atual.
  2. Bom:se não houver uma chave primária, crie um índice UNIQUE NOT NULL e defina REPLICA IDENTITY USING INDEX INDEX_NAME.
  3. Menos recomendado:use a configuração REPLICA IDENTITY FULL apenas em tabelas sem identificador exclusivo. Esteja ciente do impacto no desempenho, do limite de 16 colunas e da restrição nos tipos de dados compatíveis com chaves primárias ao replicar para o BigQuery.

Replicação de réplicas de leitura

O Datastream é compatível com a replicação de instâncias de réplica de leitura do PostgreSQL para a versão 16 e mais recentes.

Para replicar de uma réplica de leitura, siga estas etapas de configuração na instância principal:

  1. Criar publicações na instância principal: enquanto o Datastream se conecta à réplica de leitura, as publicações que definem os dados a serem replicados precisam ser criadas na instância principal.
  2. Configurar heartbeats do WAL: o Datastream depende de mensagens periódicas de heartbeat do WAL para o mecanismo de checkpoint. Ao se conectar a uma instância principal, o Datastream lida com a geração desses heartbeats. No entanto, para uma réplica de leitura, esses heartbeats precisam ser gerados externamente.

Uma maneira de configurar heartbeats periódicos é criar uma tarefa cron no PostgreSQL usando a extensão pg_cron:

SELECT cron.schedule_in_database(
    'datastream-heartbeat',             -- Job name
    '* * * * *',                        -- Every minute
   $$SELECT pg_logical_emit_message(true, 'datastream', 'cdc heartbeat')$$,
    'DATABASE_NAME',              -- Change this to your database name
    'USERNAME',                   -- Username to run as
    true                                -- Enabled
);

Substitua:

  • DATABASE_NAME: o nome do banco de dados para o qual você quer gerar heartbeats.
  • USERNAME: o nome do usuário que vai executar a tarefa. Normalmente postgres.

Limitações conhecidas

As limitações conhecidas do uso do Datastream com um banco de dados PostgreSQL como origem incluem:

  • Os streams são limitados a 10.000 tabelas.
  • O PostgreSQL rejeita estritamente bytes NULL (0x00) em colunas de string UTF-8. O Datastream não remove bytes NULL. Se uma string de origem tiver bytes nulos 0x00, o lote de inserção vai falhar e interromper a replicação. Recomendamos que você limpe ou substitua os caracteres CHAR(0) no banco de dados de origem antes de replicar.
  • Não é possível configurar streams do PostgreSQL para começar na posição mais recente.
  • Uma tabela com mais de 500 milhões de linhas não pode ser preenchida, a menos que as seguintes condições sejam atendidas:
    1. A tabela tem um índice de árvore B exclusivo.
    2. O índice não inclui colunas dos seguintes tipos: DOUBLE, FLOAT, MONEY, REAL, JSON, JSONB, BYTEA, TXID, XML, tipos de dados compostos ou tipos de dados geométricos.
    3. Nenhuma das colunas do índice é anulável.
    4. Todas as colunas do índice estão em ordem crescente ou decrescente.
    5. Todas as colunas do índice são incluídas no stream.
  • As tabelas sem chaves primárias precisam ter uma REPLICA IDENTITY. Caso contrário, apenas os eventos INSERT serão replicados para o destino.
  • As tabelas com chaves primárias não podem ter a REPLICA IDENTITY definida como FULL ou NOTHING. Ele precisa ser definido como DEFAULT.
  • Nem todas as alterações no esquema de origem podem ser detectadas automaticamente. Nesse caso, pode ocorrer corrupção de dados. As seguintes alterações de esquema podem causar corrupção de dados ou falha no processamento de eventos downstream:
    • Como descartar colunas.
    • Adicionar colunas no meio de uma tabela.
    • Alterar o tipo de dados de uma coluna.
    • Reordenar colunas.
    • Remoção de tabelas (relevante se a mesma tabela for recriada com novos dados adicionados).
  • O Datastream não é compatível com colunas dos tipos de dados geometric, como BOX, CIRCLE, LINE, LSEG, PATH, POINT e POLYGON. Essas colunas são replicadas como NULL.
  • O Datastream não é compatível com colunas dos tipos de dados range.
  • O Datastream não é compatível com matrizes de tipos de dados não compatíveis (como tipos espaciais), matrizes de LTREE, matrizes de tipos de dados definidos pelo usuário (incluindo ENUM) ou matrizes de DATE, TIMESTAMP ou TIMESTAMP WITH TIME ZONE (TIMESTAMPTZ). O Datastream ignora essas colunas durante a replicação.
  • Para streams criados antes de 17 de fevereiro de 2026: o Datastream não oferece suporte à replicação de eventos UPDATE para linhas que incluem valores TOAST em colunas que fazem parte da identidade de réplica da tabela. Esses eventos são descartados. As transmissões criadas após essa data não estão sujeitas a essa exceção.
  • O Datastream não é compatível com a replicação de linhas que incluem valores JSON ou JSONB com mais de 2.950 objetos aninhados. Os eventos que contêm esses valores JSON ou JSONB não são replicados para o banco de dados de destino.
  • O Datastream não é compatível com a replicação de linhas que incluem valores NaN em colunas NUMERIC (precision, scale). Os valores nessas colunas são substituídos por valores NULL.
  • O Datastream não é compatível com a replicação de colunas do tipo de dados hstore. Os valores nessas colunas são substituídos por valores NULL.
  • O Datastream não é compatível com a replicação de registros não ASCII de um banco de dados de origem codificado em SQL_ASCII. Esses registros são descartados.
  • O Datastream não é compatível com a replicação de tabelas com políticas de segurança no nível da linha (RLS, na sigla em inglês) definidas. Para saber como contornar essa limitação, consulte Comportamento e limitações da origem do PostgreSQL.
  • Para colunas de streaming com tipos de dados de comprimento variável que usam a técnica de armazenamento de atributos superdimensionados (TOAST, na sigla em inglês): se um valor TOAST inalterado for removido do registro WAL durante uma operação UPDATE, o Datastream vai realizar uma pesquisa ativa no banco de dados de origem para tentar recuperar o valor ausente. Por isso, as mudanças intermediárias podem não ser capturadas em cenários que envolvem atualizações rápidas e consecutivas ou uma exclusão rápida após uma inserção. As operações DELETE não acionam essa operação de pesquisa ativa. Essa limitação para colunas de comprimento variável que usam TOAST é particularmente relevante ao usar o modo de gravação somente anexação, que espera que todas as alterações intermediárias sejam capturadas.
  • O Datastream não captura mudanças feitas em colunas geradas.
  • O Datastream pode parar de funcionar ou não capturar novos eventos quando um upgrade de versão principal do PostgreSQL é realizado no banco de dados. Sugerimos que você elimine os slots de replicação antes do upgrade, faça o upgrade do banco de dados e recrie os slots de replicação. Se os streams falharem, recupere-os especificando o novo nome do slot de replicação e faça um preenchimento se a consistência dos dados for necessária.
  • O Datastream não é compatível com a replicação de tabelas do sistema PostgreSQL ao usar o fluxo de configuração de fluxo automatizado. Se você editar o stream criado usando o fluxo automatizado e adicionar tabelas do sistema, o Datastream vai ignorar essas tabelas silenciosamente e não vai replicar dados ou mudanças delas.

A seguir