Debezium Server

O Debezium Server é uma engine open-source (Apache 2.0) de Change Data Capture que lê o write-ahead log do seu banco de origem e publica um evento estruturado para cada mudança de linha. No Guara Cloud ele roda como um único pod baseado em Quarkus, dirigido inteiramente por variáveis de ambiente, com um sidecar JMX-para-Prometheus alimentando a aba Insights.

Cada deploy é um pipeline: um connector de origem, um destino, um replication slot. O estado do conector (offsets e, no caso do MySQL, schema history) fica em um volume Longhorn por serviço montado em /debezium/data, de forma que restarts retomam do último ponto comitado.

Quando usar o Debezium

O Debezium é a escolha certa quando:

• Sua origem é PostgreSQL, MySQL ou MongoDB e você quer CDC baseado em log — cada insert, update e delete, em ordem de commit, com atraso próximo de zero na origem.
• Seu destino é NATS JetStream, Apache Kafka ou um webhook HTTP genérico.
• Você quer semântica consagrada de snapshot + streaming: um snapshot inicial das linhas existentes seguido por uma transição contínua para streaming das novas mudanças.
• Você consegue provisionar pelo menos o plano Business — o Debezium Server roda sobre JVM e pede cerca de 1 GiB de heap para aguentar taxas de mudança não triviais.

Use o Conduit no lugar se você quer runtime Go, precisa de origens não relacionais (NATS, HTTP) ou quer gravar o destino em outro banco.

Walkthrough de deploy

Aba Insights

A aba Insights renderiza painéis alimentados por um sidecar bitnami/jmx-exporter que lê os MBeans JMX do Debezium pela loopback do pod (porta 1099) e os republica como métricas Prometheus em :9404/metrics. Os painéis estão agrupados em duas seções:

Saúde da Replicação

• Replication Lag — gauge, segundos atrás do banco de origem. Derivado de debezium_milli_seconds_behind_source / 1000. Abaixo de 30s é a zona de conforto; valores sustentados acima de 60s costumam indicar que o destino está aplicando backpressure ou que a origem emite mais rápido do que o Debezium consegue processar.
• Last Event Timestamp — tabela, timestamp Unix do evento mais recente. Um valor parado por vários minutos, enquanto a origem continua recebendo gravações, sinaliza pipeline travado.
• Snapshot Progress — gauge, percentual do snapshot inicial concluído. Derivado de debezium_rows_scanned / debezium_total_number_of_rows_scanned. Esse valor deve subir monotonicamente de 0 até 100% no primeiro boot e se manter em 100% depois.

Throughput

• Events/sec — área, taxa em janela de 1 minuto de debezium_total_number_of_events_seen. A linha de base depende do volume de gravações — o que você analisa é o formato (picos, platôs, quedas).
• Events Filtered — área empilhada, taxa em janela de 5 minutos de eventos descartados pelas regras de include/exclude. Útil para confirmar se o tableFilter está fazendo o que você espera.
• Queue Remaining — gauge, slots livres na fila interna (debezium_queue_remaining_capacity). Quando se aproxima de zero significa que o destino não está acompanhando.

Troubleshooting

Replication slot não foi removido após deletar o serviço

Apagar um serviço Debezium destrói o pod e seu PVC, mas o replication slot na PostgreSQL de origem continua lá — e um slot retido segura arquivos WAL para sempre, o que lota o disco do banco origem.

Sempre limpe manualmente depois da exclusão:

-- Rode no PostgreSQL DE ORIGEM, não no pod do Debezium
SELECT pg_drop_replication_slot('guara_slot_SEU_SERVICE_SLUG');

O padrão do nome do slot é guara_slot_<serviceSlug>, com - substituído por _. Liste os slots ativos antes de derrubar com SELECT slot_name, active FROM pg_replication_slots;.

Snapshot travado em uma tabela grande

O snapshot inicial executa SELECT * em cada tabela incluída. Em tabelas com alguns milhões de linhas, a primeira varredura pode levar minutos e, na aba Insights, dá a impressão de estar travada. Observe o Snapshot Progress — se estiver subindo, espere; se ficar parado no mesmo valor por mais de 10 minutos, olhe a origem em busca de contenção de locks (algum outro processo segurando a tabela).

Reiniciar o pod retoma o snapshot a partir do último offset comitado, não do zero. Um snapshot que falhou numa tabela grande não vira um “recomeço do zero”.

Mudanças de schema durante o snapshot

O Debezium captura um schema no início do snapshot e espera que ele permaneça estável até o streaming começar. Uma alteração de DDL no meio do snapshot (coluna renomeada, tipo alterado) pode corromper o snapshot em andamento. Espere o Snapshot Progress chegar a 100% antes de rodar migrations, ou derrube o replication slot e reinicie o Debezium para refazer o snapshot.

Dimensionamento no plano Pro

O Debezium Server roda sobre Quarkus, e o teto de 512 MiB de memória do plano Pro só aguenta testes leves e demonstrações. Para qualquer taxa de mudança de produção, provisione no plano Business (1–2 GiB de heap) ou superior. O wizard do catálogo permite o deploy no Pro para avaliação, mas não aponte uma origem OLTP de produção para um pod Debezium dimensionado no Pro.

Kafka externo com SASL/SSL

Quando sinkKind=Apache Kafka em modo externo, cole a URL de bootstrap-servers em sinkExternalUrl e as credenciais SASL em sinkExternalUsername / sinkExternalPassword. O Debezium negocia o protocolo (PLAINTEXT, SASL_PLAINTEXT, SASL_SSL) com base no que o broker anuncia; nenhuma configuração adicional é necessária para SASL/SCRAM ou SASL/PLAIN padrão. Se você precisa de autenticação por client certificate, abra um chamado de suporte — esse caminho exige um truststore customizado que a v1 não expõe no wizard.

PostgreSQL externo recusa replicar

Três parâmetros precisam estar corretos na origem:

• wal_level = logical no postgresql.conf (exige restart).
• O role que conecta tem tanto o atributo LOGIN quanto REPLICATION.
• max_replication_slots e max_wal_senders são, cada um, pelo menos 1 a mais do que o número de consumidores de CDC — o Debezium consome um slot por serviço.

O PostgreSQL gerenciado pelo Guara aplica os três automaticamente; bancos externos precisam que o DBA os configure.

Recursos upstream

• Documentação do Debezium — referência canônica de connectors, propriedades e MBeans.
• Referência do connector PostgreSQL.
• Referência do connector MySQL.
• Referência do connector MongoDB.
• Referência dos tipos de sink — Kafka, NATS JetStream, HTTP e outros.

Próximos passos