Como habilitar CDC no PostgreSQL, MySQL, SQL Server e Oracle

Imagem de capa

Quatro caminhos distintos convergindo para uma mesma linha contínua de registros.

Captura de mudanças (CDC) não é um recurso que se liga na ferramenta de integração. É uma configuração do banco de origem. O banco já grava cada alteração no log de transações, para conseguir se recuperar de uma queda. O que falta é liberar a leitura desse log e garantir que ele não seja descartado antes da hora.

Este guia reúne os comandos para PostgreSQL, MySQL, SQL Server e Oracle, na instalação própria e no Amazon RDS, com o que costuma travar em cada um.

Figura 1 — como o log funciona

Linha do tempo horizontal com as escritas no banco. Abaixo, o log de transações acumulando registros. Uma janela sombreada marca a retenção configurada, e uma seta mostra o leitor avançando dentro dela. À esquerda da janela, os registros mais antigos, já descartados, em cinza.

Três decisões antes de tocar em qualquer banco

Retenção do log. É o único ajuste que causa perda de dado de verdade. Se o banco descartar o log antes da leitura, a única saída é recarregar a tabela inteira. Comece por 24 horas e ajuste depois de medir o volume gerado por dia.

Usuário dedicado. Não use o usuário administrador. Crie um usuário só para a leitura, com as permissões mínimas de cada banco. Quando algo travar, você vai saber exatamente quem estava lendo.

Chave primária. Tabela sem chave primária dá trabalho em todos os quatro. Sem ela, o banco não sabe identificar qual linha mudou, e a configuração muda — quase sempre para pior, gravando mais no log.

Resolva as três antes de abrir o console.

PostgreSQL

Precisa de wal_level em logical. No servidor próprio, isso está no postgresql.conf e exige reiniciar:

wal_level = logical
max_replication_slots = 10
max_wal_senders = 10

Depois, um usuário com atributo de replicação:

CREATE ROLE leitor_cdc WITH LOGIN REPLICATION PASSWORD 'senha';
GRANT SELECT ON ALL TABLES IN SCHEMA public TO leitor_cdc;

Para tabelas sem chave primária, o PostgreSQL não grava os valores antigos em atualizações e exclusões. Resolve-se assim, tabela a tabela:

ALTER TABLE minha_tabela REPLICA IDENTITY FULL;

No Amazon RDS o caminho é outro. O parâmetro wal_level não é editável diretamente. Você cria um grupo de parâmetros próprio, porque o padrão não aceita alteração. Nele, define rds.logical_replication como 1 e reinicia a instância — o parâmetro é estático e só vale depois do reinício.

A AWS aplica o wal_level = logical a partir daí. O usuário de leitura recebe o papel com GRANT rds_replication TO leitor_cdc;.

Confira se ficou valendo:

SHOW wal_level;   -- esperado: logical
SELECT slot_name, active, restart_lsn FROM pg_replication_slots;

O que dá errado aqui: um replication slot (espaço de replicação) criado e nunca lido segura o log indefinidamente. O disco enche e a instância cai. Se você abandonar um teste, remova o slot.

MySQL e MariaDB

O log binário precisa estar ligado, no formato de linha e com a imagem completa:

log_bin = ON
binlog_format = ROW
binlog_row_image = FULL
server_id = 1
binlog_expire_logs_seconds = 86400

binlog_row_image = FULL é o que costuma faltar. Sem ele, o MySQL grava apenas as colunas alteradas, e a linha chega incompleta do outro lado.

O usuário precisa de três permissões:

CREATE USER 'leitor_cdc'@'%' IDENTIFIED BY 'senha';
GRANT SELECT, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'leitor_cdc'@'%';

No Amazon RDS, o log binário só existe se as cópias de segurança automáticas estiverem ativas. A retenção é definida por procedimento, não por parâmetro:

CALL mysql.rds_set_configuration('binlog retention hours', 24);

O teto é 168 horas, ou sete dias. Acima disso o valor não é aceito.

Confira se ficou valendo:

SHOW VARIABLES WHERE Variable_name IN
  ('log_bin','binlog_format','binlog_row_image','server_id');

SQL Server

Aqui a captura é um recurso nomeado do próprio banco. Liga no banco e depois em cada tabela:

EXEC sys.sp_cdc_enable_db;

EXEC sys.sp_cdc_enable_table
  @source_schema = N'dbo',
  @source_name   = N'pedidos',
  @role_name     = NULL,
  @supports_net_changes = 1;

O SQL Server Agent precisa estar rodando o tempo todo. É a dependência que derruba mais implantações. A captura roda como tarefa do Agent. Com ele parado, o log é truncado e as mudanças não lidas se perdem — sem aviso e sem recuperação.

A limpeza padrão descarta as mudanças capturadas depois de três dias. Se o seu pipeline puder ficar parado mais que isso, ajuste antes.

No Amazon RDS, a AWS não concede privilégio de administrador do servidor, então o passo no nível do banco muda de procedimento:

EXEC msdb.dbo.rds_cdc_enable_db 'meu_banco';

A partir daí, sys.sp_cdc_enable_table funciona normalmente para cada tabela. Um detalhe que pega desprevenido: restaurações desligam a captura e apagam os metadados. Depois de restaurar uma cópia ou voltar a um ponto no tempo, é preciso habilitar tudo de novo.

Confira se ficou valendo:

SELECT name, is_cdc_enabled FROM sys.databases WHERE name = 'meu_banco';
EXEC sys.sp_cdc_help_change_data_capture;

A edição Express não suporta a captura. A Standard suporta desde a versão 2016 com o primeiro pacote de serviço.

Oracle

Duas exigências: o banco em modo ARCHIVELOG e o registro suplementar ligado. O registro suplementar é o que faz o Oracle gravar as colunas necessárias para identificar a linha alterada — sem ele, o log existe mas não serve.

No servidor próprio:

ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA (PRIMARY KEY) COLUMNS;

No Amazon RDS, você não tem acesso de administrador do sistema, e tudo passa pelo pacote rdsadmin. O modo ARCHIVELOG é ativado indiretamente: basta ligar as cópias de segurança automáticas com retenção maior que zero.

BEGIN
  rdsadmin.rdsadmin_util.set_configuration(
    name  => 'archivelog retention hours',
    value => '24');
END;
/
COMMIT;

EXEC rdsadmin.rdsadmin_util.alter_supplemental_logging('ADD');
EXEC rdsadmin.rdsadmin_util.alter_supplemental_logging('ADD','PRIMARY KEY');

O COMMIT depois da configuração de retenção não é opcional. Sem ele, a alteração não passa a valer — e a documentação da AWS destaca isso porque muita gente esquece.

Para conferir se o registro suplementar ficou ativo:

SELECT supplemental_log_data_min, supplemental_log_data_pk FROM v$database;

Espera-se YES nas duas colunas.

Os quatro bancos lado a lado

Figura 2 — os quatro caminhos

A tabela acima em versão desenhada, com um ícone por banco e destaque na coluna do Amazon RDS. É a peça mais reaproveitável do artigo: serve em redes sociais e em material de apoio comercial.

O que costuma dar errado

Os quatro problemas mais frequentes, em ordem de dor:

• Retenção curta demais. Descoberto sempre depois, quando já não há o que recuperar.
• Espaço de replicação abandonado no PostgreSQL. O oposto do anterior: o log nunca é descartado e o disco enche.
• Tabela sem chave primária. A configuração passa, a carga roda, e as exclusões nunca chegam ao destino.
• Permissão concedida no banco, mas não no esquema correto. Falha só na primeira leitura, não no teste de conexão.

Nenhum desses aparece no dia da implantação. Todos aparecem na segunda semana.

Figura 3 — os dois modos de falha

Duas linhas do tempo empilhadas. Na primeira, o leitor acompanha o log dentro da janela de retenção e tudo chega. Na segunda, o leitor fica parado, a janela avança e um trecho do log é descartado antes da leitura — marcado como recarga completa obrigatória.

Onde o Januss entra

O Januss verifica esses pré-requisitos antes de deixar você salvar a conexão. Se o banco não está preparado, a conexão não passa e a mensagem aponta o que falta — o texto muda conforme o banco, porque o ajuste também muda. Você descobre na tela, não na primeira execução.

Feita a configuração, a leitura é do log de transações nos cinco bancos suportados: PostgreSQL, MySQL, SQL Server, Oracle e MongoDB. E em todos os planos, inclusive o de entrada. Se o log rotacionar antes da leitura, a recarga é automática — sem número errado no destino.

Uma coisa o Januss não faz: alterar o seu banco. Nenhum dos comandos acima é executado pela plataforma. A verificação é de leitura, o comando é seu, e quem decide o que muda em produção é o seu time.

Configurado o banco, o resto é escolher as tabelas e o modo de sincronização. Quer testar com uma tabela sua? São 14 dias de teste, sem cartão de crédito: criar seu ambiente.

Fontes

Os comandos do Amazon RDS foram conferidos na documentação oficial da AWS:

• Logical replication for Amazon RDS for PostgreSQL
• Setting and showing binary log configuration (MySQL)
• Using change data capture for Amazon RDS for SQL Server
• Retaining archived redo logs (Oracle)
• Performing common log-related tasks for Oracle DB instances