Gerenciar e monitorar a replicação lógica

Esta página descreve como monitorar a replicação lógica no Lakebase, como a replicação interage com escala para zero e branches, e como resolver problemas comuns. Para configurar, consulte Replicar dados para o Lakebase e Replicar dados do Lakebase.

Monitorar replicação

Qualquer função Postgres pode query os catálogos de replicação nesta página, com duas exceções. A coluna subconninfo de pg_subscription pode conter a senha de conexão e é restrita; portanto, selecione colunas específicas em vez de usar SELECT *. Em pg_stat_replication, a maioria das colunas está oculta, a menos que sua função tenha pg_read_all_stats, que os membros de databricks_superuser têm.

Em um inscrito, confirme se a inscrição existe e está habilitada:

SQL
SELECT subname, subenabled FROM pg_catalog.pg_subscription;

No editor, confirme se a publicação existe:

SQL
SELECT pubname FROM pg_catalog.pg_publication;

Verifique o status de sincronização por tabela no assinante. Quando cada tabela lê Ready (fully live), a cópia inicial é concluída e a inscrição está em transmissão:

SQL
SELECT
    srrelid::regclass AS table_name,
    CASE srsubstate
        WHEN 'i' THEN 'Initializing'
        WHEN 'd' THEN 'Data copying (in progress)'
        WHEN 's' THEN 'Synchronized (catching up)'
        WHEN 'r' THEN 'Ready (fully live)'
    END AS sync_status
FROM pg_catalog.pg_subscription_rel;

Verifique o status da inscrição e o atraso:

SQL
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time
FROM pg_catalog.pg_stat_subscription;

Compare as contagens de linhas no editor e no assinante para confirmar que uma tabela está sincronizada:

SQL
SELECT COUNT(*) FROM public.playing_with_lakebase;

Em um editor, liste os slots de replicação e o quanto cada um avançou:

SQL
SELECT slot_name, slot_type, active, restart_lsn
FROM pg_catalog.pg_replication_slots;

No Lakebase, os resultados também incluem os slots físicos internos wal_proposer_slot e wal_retention_slot. O Lakebase gerencia esses slots, e eles não fazem parte da replicação lógica.

Replicação lógica e escala para zero

Um Lakebase compute com um assinante ativo não escala para zero, o que pode aumentar o uso de compute.

Verifique os assinantes ativos:

SQL
SELECT *
FROM pg_catalog.pg_stat_replication
WHERE application_name <> 'walproposer';

Slots de replicação e armazenamento

Um slot de replicação faz com que o editor retenha o log de gravação antecipada (WAL) até que o assinante confirme que recebeu as alterações. Se o assinante parar de consumir alterações, por exemplo, porque está desabilitado, desconectado, falhando ou atrasado, o WAL se acumula no editor. Esta é a causa mais comum de problemas graves com a replicação lógica:

O editor pode ficar sem armazenamento. O WAL retido cresce até que o armazenamento do editor esteja cheio, o que pode impedir que o banco de dados aceite gravações e causar uma interrupção.
A exclusão do slot não libera o armazenamento imediatamente. O Postgres remove o WAL retido somente quando recicla os segmentos WAL em um ponto de verificação posterior. Se o editor já tiver ficado sem armazenamento, essa reciclagem pode não ser concluída.
O risco também se aplica a editores externos. Quando o Lakebase se inscreve em uma base de dados externa, o WAL é acumulado nessa fonte externa se a inscrição parar de consumir alterações.

Monitorar o WAL retido

No publicador, verifique quanto WAL cada slot lógico retém e se está ativo:

SQL
SELECT slot_name, active, wal_status,
       pg_catalog.pg_size_pretty(pg_catalog.pg_wal_lsn_diff(pg_catalog.pg_current_wal_lsn(), restart_lsn)) AS retained_wal
FROM pg_catalog.pg_replication_slots
WHERE slot_type = 'logical';

Execute esta query regularmente enquanto a replicação estiver ativa. Investigue quando retained_wal continua crescendo ou active é false. Um wal_status de extended significa que o slot está retendo mais WAL do que o publisher normalmente mantém. Um wal_status de unreserved ou lost significa que o slot excedeu max_slot_wal_keep_size e está perdendo, ou perdeu, o WAL de que precisa, portanto, a inscrição deve ser recriada.

Recuperar de acúmulo de WAL

Encontre o slot que está retendo WAL com a query em Monitorar WAL retido.
Se o assinante puder se recuperar, corrija a causa, como um problema de rede, uma inscrição desabilitada ou uma falha de aplicação, para que o assinante recupere o atraso e o slot avance.
Se você não precisar mais da inscrição, descarte-a no assinante. Se o assinante estiver inacessível, descarte o slot diretamente no editor. Um slot deve estar inativo antes que você possa descartá-lo:
SQL
```
SELECT pg_catalog.pg_drop_replication_slot('<slot_name>');
```
Aguarde até que o editor recicle o WAL retido. Em um editor autogerenciado que está quase sem armazenamento, adicione armazenamento primeiro para que a reciclagem seja concluída.

Remoção automática de slots inativos no Lakebase

Quando o Lakebase é o editor, ele remove automaticamente um slot de replicação que esteve inativo por aproximadamente 40 horas, para evitar que o slot retenha WAL indefinidamente. Um slot fica inativo quando seu assinante para de consumir alterações e o slot para de avançar. Isso pode acontecer quando um assinante é desativado ou fica indisponível, ou quando um assinante está configurado com um longo atraso de replicação.

Para evitar que um slot seja removido, certifique-se de que o assinante permaneça conectado e continue consumindo alterações. Se o assinante usar um atraso ou frequência de replicação configurável, mantenha-o abaixo de 40 horas para que o slot continue avançando. Se um slot for removido e você ainda precisar dele, recrie a inscrição no assinante.

Os publishers externos não removem slots inativos automaticamente. Em um publisher autogerenciado, defina max_slot_wal_keep_size para limitar o WAL que um slot pode reter. Se um slot exceder o limite, o Postgres o invalidará e você deverá recriar a inscrição.

A restauração de branch remove slots de replicação

Restaurar uma branch exclui todos os slots de replicação nessa branch. Recrie publicações e inscrições após a restauração de uma branch.

As branchs secundárias não herdam inscrições

As inscrições definidas em uma Branch pai não são duplicadas em suas Branch filhas. O Lakebase os descarta de uma branch filha antes que o compute dessa branch comece, de modo que dois computes não repliquem a mesma inscrição. Isso se aplica quando você cria, Reset ou restaura uma Branch filha. Recrie a inscrição na branch filha se precisar de replicação lá.

A exclusão de um banco de dados assinante deixa o slot no editor

Ao excluir um banco de dados que tem inscrições usando o aplicativo Lakebase, a CLI do Databricks ou a API REST, o Lakebase descarta essas inscrições primeiro, mas não remove seus slots de replicação no editor. Cada slot permanece no editor e continua retendo o WAL, o que pode preencher o armazenamento do editor. Em uma migração, o editor costuma ser seu banco de dados de produção.

Um comando SQL DROP DATABASE se comporta como no Postgres padrão: ele falha com database "<name>" is being used by logical replication subscription enquanto o banco de dados tem inscrições.

Para evitar deixar um slot para trás, elimine cada inscrição antes de excluir o banco de dados. Quando o publicador estiver acessível, DROP SUBSCRIPTION também remove o slot no publicador. Consulte Remover uma inscrição ou publicação.

Se você já excluiu o banco de dados, remova o slot restante no editor. Por default, um slot de inscrição tem o mesmo nome da inscrição. Se você definiu slot_name quando criou a inscrição, use esse nome. Para registrar os nomes dos slots antes de excluir um banco de dados, faça a execução de SELECT subname, subslotname FROM pg_catalog.pg_subscription; nesse banco de dados. Confirme se o slot existe e se está inativo:

SQL
SELECT slot_name, database, plugin, active
FROM pg_catalog.pg_replication_slots
WHERE slot_type = 'logical' AND slot_name = '<slot_name>';

Descarte apenas o slot que pertencia à inscrição excluída. Outros slots inativos podem pertencer a inscritos ou ferramentas de captura de dados de alterações (CDC) que estão temporariamente desconectadas, e descartá-los interrompe sua replicação. Descartar o slot:

SQL
SELECT pg_catalog.pg_drop_replication_slot('<slot_name>');

Funções de replicação

Uma função de replicação dedicada deve ter o atributo REPLICATION. As funções criadas no aplicativo Lakebase, na CLI do Databricks ou na API REST têm este atributo, independentemente de serem membros de databricks_superuser. As funções criadas com SQL não recebem o atributo REPLICATION automaticamente. Para criar uma com SQL, inclua o atributo, por exemplo CREATE ROLE replication_user WITH LOGIN REPLICATION PASSWORD '<password>';. Para adicioná-la a uma função existente, execução ALTER ROLE <role_name> REPLICATION;. Ambas as instruções exigem uma função que tenha os atributos CREATEROLE e REPLICATION, como a função do proprietário do projeto.

Verifique os privilégios de uma função:

SQL
SELECT rolname, rolreplication
FROM pg_catalog.pg_roles
WHERE rolname = '<role_name>';

Plugins do decodificador

O Lakebase oferece suporte a dois plugins de saída de decodificação lógica:

pgoutput: o plugin de replicação lógica Postgres integrado e o default. Use-o para replicação padrão Postgres para Postgres.
wal2json: gera alterações de WAL como JSON, para sistemas que consomem dados de alteração em JSON.

Configurações do editor

No Lakebase, max_wal_senders e max_replication_slots são definidos como 10:

Text
max_wal_senders = 10
max_replication_slots = 10

max_wal_senders limita os processos de envio WAL concorrentes que fazem a transmissão de alterações para os assinantes, e max_replication_slots limita os slots de replicação que rastreiam o progresso do assinante. Planeje um de cada por assinante. Para solicitar valores diferentes, entre em contato com a Databricks.

Crie um slot de replicação dedicado

Alguns serviços de dados exigem um slot de replicação que você cria com antecedência. Crie um com a função Postgres padrão, nomeando o plugin do decodificador:

SQL
SELECT pg_catalog.pg_create_logical_replication_slot('my_replication_slot', 'pgoutput');

Remover uma inscrição ou publicação

Descarte uma inscrição no assinante quando não precisar mais dela. Quando o editor pode ser alcançado, o descarte da inscrição desconecta o editor e remove o slot de replicação no editor. Os dados replicados permanecem no banco de dados do assinante.

SQL
DROP SUBSCRIPTION my_subscription;

Se o editor não estiver acessível, DROP SUBSCRIPTION não será concluído porque não pode se conectar para remover o slot remoto. Desassocie o slot primeiro e depois remova a inscrição:

SQL
ALTER SUBSCRIPTION my_subscription DISABLE;
ALTER SUBSCRIPTION my_subscription SET (slot_name = NONE);
DROP SUBSCRIPTION my_subscription;

Nesse caso, o slot de replicação permanece no editor e continua a reter o WAL. Remova-o no editor para liberar o WAL:

SQL
SELECT pg_catalog.pg_drop_replication_slot('<slot_name>');

Solte uma publicação no editor:

SQL
DROP PUBLICATION my_publication;

Solução de problemas

Sintoma	Causa e resolução
A inscrição não conecta.	Confirme se o editor está acessível e se a string de conexão, a função e a senha estão corretas. Quando o Lakebase é o assinante, confirme se o Endpoint do editor está na lista de permissões da política de rede da account. Veja Replicar dados no Lakebase.
Uma inscrição em outro banco de dados de Lakebase trava e não conecta.	Não há suporte para replicação entre bancos de dados Lakebase na mesma região. A fonte e o destino devem estar em regiões diferentes. Consulte Limitações.
`CREATE SUBSCRIPTION` falha com `restricted by Account Network Policies`.	Sua account impõe uma política de rede e o host do editor não está nos destinos de internet permitidos. Adicione o host à política de rede da account. Consulte Replicar dados para o Lakebase.
O armazenamento cresce e não libera.	Um slot de replicação está retendo WAL porque seu assinante não está consumindo as alterações. Se não for resolvido, o editor poderá ficar sem armazenamento. Verifique o WAL retido e reconecte o assinante ou descarte o slot. O armazenamento é liberado somente depois que o editor recicla o WAL. Consulte Slots de replicação e armazenamento.
As linhas não chegam ao assinante.	Confirme que as tabelas de destino existem com nomes e colunas correspondentes e que a publicação inclui as tabelas esperadas.

Sintoma	Causa e resolução
A inscrição não conecta.	Confirme se o editor está acessível e se a string de conexão, a função e a senha estão corretas. Quando o Lakebase é o assinante, confirme se o Endpoint do editor está na lista de permissões da política de rede da account. Veja Replicar dados no Lakebase.
Uma inscrição em outro banco de dados de Lakebase trava e não conecta.	Não há suporte para replicação entre bancos de dados Lakebase na mesma região. A fonte e o destino devem estar em regiões diferentes. Consulte Limitações.
`CREATE SUBSCRIPTION` falha com `restricted by Account Network Policies`.	Sua account impõe uma política de rede e o host do editor não está nos destinos de internet permitidos. Adicione o host à política de rede da account. Consulte Replicar dados para o Lakebase.
O armazenamento cresce e não libera.	Um slot de replicação está retendo WAL porque seu assinante não está consumindo as alterações. Se não for resolvido, o editor poderá ficar sem armazenamento. Verifique o WAL retido e reconecte o assinante ou descarte o slot. O armazenamento é liberado somente depois que o editor recicla o WAL. Consulte Slots de replicação e armazenamento.
As linhas não chegam ao assinante.	Confirme que as tabelas de destino existem com nomes e colunas correspondentes e que a publicação inclui as tabelas esperadas.

Os passos seguintes

Migrar para o Lakebase : Replique um banco de dados Postgres existente para o Lakebase. Veja Replicar dados para o Lakebase.
Transmissão de Lakebase : publique alterações para um assinante Postgres externo. Consulte Replicar dados do Lakebase.
Entenda o recurso : Revise o que é a replicação lógica e quando usá-la. Consulte Replicação lógica.

Monitorar replicação​

Replicação lógica e escala para zero​

Slots de replicação e armazenamento​

Monitorar o WAL retido​

Recuperar de acúmulo de WAL​

Remoção automática de slots inativos no Lakebase​

A restauração de branch remove slots de replicação​

As branchs secundárias não herdam inscrições​

A exclusão de um banco de dados assinante deixa o slot no editor​

Funções de replicação​

Plugins do decodificador​

Configurações do editor​

Crie um slot de replicação dedicado​

Remover uma inscrição ou publicação​

Solução de problemas​

Os passos seguintes​