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:
SELECT subname, subenabled FROM pg_catalog.pg_subscription;
No editor, confirme se a publicação existe:
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:
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:
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:
SELECT COUNT(*) FROM public.playing_with_lakebase;
Em um editor, liste os slots de replicação e o quanto cada um avançou:
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:
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:
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:
SQLSELECT 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:
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:
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:
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.
wal2json não está disponível no Postgres 19. No Postgres 19, use pgoutput. Consulte Limitações do Postgres 19.
Configurações do editor
No Lakebase, max_wal_senders e max_replication_slots são definidos como 10:
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:
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.
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:
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:
SELECT pg_catalog.pg_drop_replication_slot('<slot_name>');
Solte uma publicação no editor:
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. |
| 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.