Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

27 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Kafka Restore Lab

Laboratório de descoberta e reconciliação de tabelas de uma origem PostgreSQL ou SQL Server para PostgreSQL local, com Python, Kafka e publicação blue-green por tabela. A aplicação usa uma conta com SELECT na origem: não instala triggers, não habilita CDC, não cria tabelas de controle remotas e não executa DDL ou DML remoto.

cp .env.example .env
docker compose up -d --build

Faça a cópia apenas na primeira configuração, preservando um .env já existente. Edite esse arquivo para ajustar os padrões do laboratório. Veja Arquivos de ambiente.

Esse comando inicia o cenário PostgreSQL, prepara o proxy, descobre as tabelas, publica o bootstrap das tabelas ainda não inicializadas, aguarda a promoção pelo consumer e inicia o scheduler. O monitor faz parte do conjunto padrão: localhost:8082.

Os bancos de origem do Compose são fixtures com dados fictícios. A reconciliação padrão lê integralmente cada tabela a cada ciclo. O laboratório não foi homologado para produção ou bases de centenas de gigabytes.

Arquivos de ambiente

O Compose interpola as variáveis de .env no docker-compose.yml e envia a cada serviço apenas as entradas declaradas no seu environment. Não há carregamento de dotenv pelo Python. O YAML mantém os valores padrão, permitindo iniciar as fixtures mesmo sem o arquivo local.

Arquivo Uso
.env.example Modelo versionado dos padrões de portas, credenciais das fixtures, sincronização e monitoramento.
.env Configuração local lida automaticamente pelo Compose; ignorada pelo Git.

Toda a configuração local fica em .env, sem argumentos adicionais nos comandos:

docker compose config --quiet
docker compose up -d --build
docker compose run --rm cli discover status
docker compose logs --tail 30 scheduler consumer

Variáveis já exportadas no shell têm prioridade sobre .env. O arquivo configura o Compose, com nomes de serviços da rede Docker; não é um ambiente para executar a aplicação diretamente no host.

Configuração Variáveis
Portas no host REMOTE_DB_HOST_PORT, LOCAL_DB_HOST_PORT, MSSQL_HOST_PORT, KAFKA_HOST_PORT, TOXIPROXY_HOST_PORT, KAFBAT_HOST_PORT, ADMINER_HOST_PORT, MONITOR_HOST_PORT.
Administração das fixtures REMOTE_ADMIN_PASSWORD, LOCAL_ADMIN_PASSWORD, MONITOR_ADMIN_PASSWORD, MSSQL_SA_PASSWORD.
Descoberta e proteção SOURCE_SCHEMAS, MAX_REMOVE_FRACTION, SCHEDULER_INTERVAL_SECONDS, INIT_PROMOTION_TIMEOUT_SECONDS.
Kafka e proxy KAFKA_BOOTSTRAP, KAFKA_TOPIC, KAFKA_AUDIT_TOPIC, TOXIPROXY_URL.
Retenção e manutenção LOG_RETENTION_DAYS, AUDIT_RETENTION_DAYS, KAFKA_RETENTION_DAYS, LOG_CLEANUP_ENABLED, LOG_CLEANUP_INTERVAL_HOURS, DOCKER_LOG_MAX_SIZE, DOCKER_LOG_MAX_FILES.
Origem SQL Server MSSQL_HOST, MSSQL_PORT, MSSQL_USER, MSSQL_PASSWORD, MSSQL_DATABASE.
Painel e coletor Variáveis LAB_* descritas em Monitor: como interpretar.

As portas internas permanecem fixas. Por exemplo, MONITOR_HOST_PORT=8182 muda o acesso para http://localhost:8182, enquanto o processo e seu healthcheck continuam na porta 8082 do container. KAFKA_HOST_PORT também atualiza o endereço anunciado para clientes no host; os containers continuam usando kafka:19092.

As senhas fornecidas são públicas e exclusivas das fixtures descartáveis. Os nomes dos bancos e as contas de leitura/escrita provisionadas continuam definidos em sql/remote.sql, sql/local.sql, sql/monitor.sql e app/sqlserver_fixture.py. Alterar MSSQL_PASSWORD muda a conexão, sem alterar a senha do login na origem. Alterar uma senha administrativa em .env também não muda a senha já gravada num volume: atualize a conta no banco antes de recriar os serviços com o novo valor. LOCAL_ADMIN_PASSWORD alimenta tanto local-db quanto as conexões administrativas da aplicação.

REMOTE_DSN e REMOTE_DIRECT_DSN podem sobrescrever as conexões PostgreSQL completas; os exemplos estão em .env.example e podem ser definidos em .env. O proxy remote_pg é criado com upstream remote-db:5432: alterar o DSN direto não reconfigura esse proxy. As credenciais administrativas da origem continuam restritas ao banco e aos serviços de fixture; o produtor recebe somente as credenciais SELECT da origem.

Depois de editar a configuração, use docker compose config --quiet para validar e docker compose up -d para recriar os serviços afetados. restart não carrega novas variáveis. A forma sem --quiet exibe a configuração resolvida, incluindo senhas.

O build usa ./app como contexto. Por isso, as exclusões ficam em app/.dockerignore, que remove caches Python, ambientes virtuais, logs e arquivos .env* do contexto enviado ao builder. Os arquivos de ambiente da raiz já ficam fora desse contexto. O Dockerfile copia explicitamente os arquivos necessários à aplicação.

Arquitetura

flowchart LR
    subgraph origem["Origem alternativa · conta SELECT"]
        PG[(PostgreSQL)]
        MS[(SQL Server)]
    end
    PG --> P[Toxiproxy]
    MS --> P
    P --> E["Python · descoberta + extração"]
    E -->|"table_start / seen / delta / end"| K[Kafka]
    K --> C[Consumer]
    subgraph local["PostgreSQL local"]
        S[Staging e validações]
        BG["Slots blue / green · JSONB"]
        V["Views tipadas mirror_schema.tabela"]
        A["Catálogo, gerações e journal"]
        S --> BG --> V
    end
    C --> S
    C --> A
    A -.->|"SELECT da auditoria"| MC["Coletor do monitor"]
    MC -->|"Metadados de operação"| MD[("PostgreSQL do monitor")]
    M["Monitor · 8082"] -.->|"SELECT"| MD
    M -.->|"Metadados e lag"| K
    U["Kafbat · 8080"] -.-> K
    D["Adminer · 8081"] -.-> V
Loading

Cada tabela tem um contrato de colunas, uma chave, suas próprias gerações e um slot ativo. As views ficam em mirror_<schema da origem>.<tabela>, por exemplo mirror_public.contracts e mirror_dbo.invoices. Nomes de schema ou tabela muito longos recebem um sufixo derivado do nome original para evitar colisões.

A view legada public.contracts continua disponível para os comandos antigos, mas não é o destino do fluxo padrão de descoberta. Uma instalação existente passa a ter as novas views sem apagar os dados anteriores.

O que acontece em cada ciclo

sequenceDiagram
    autonumber
    participant O as Origem SELECT
    participant P as Produtor Python
    participant K as Kafka
    participant C as Consumer
    participant L as PostgreSQL local
    P->>O: SELECT catálogo de tabelas, colunas e PKs
    loop Cada tabela acessível
        P->>O: Abrir transação consistente e conferir estrutura
        P->>K: table_start com contrato e geração base
        loop Leitura em blocos
            O-->>P: Linhas da tabela inteira
            P->>L: Comparar hashes com a geração ativa
            P->>K: table_seen para cada chave
            P->>K: table_delta para conteúdo novo ou alterado
        end
        P->>O: Revalidar estrutura e encerrar transação
        P->>K: table_end com contagens e hashes
        K-->>C: Eventos ordenados
        C->>L: Validar, alinhar slot inativo e aplicar diferenças
        C->>L: Commit da geração, view, journal e auditoria
        P->>L: Aguardar promoção antes da próxima tabela
    end
    P->>O: Conferir novamente o catálogo completo
    P->>K: table_inventory se o catálogo permaneceu estável
    C->>L: Confirmar ciclo e ausências consecutivas
Loading

Com PK simples ou composta, cada linha recebe uma identidade derivada dos valores da chave. O produtor lê todo o conteúdo remoto para comparar hashes; envia pelo Kafka os eventos de presença e os payloads divergentes. Isso reduz payloads de dados, não a leitura da origem.

Sem PK, publica uma cópia completa por ciclo, incluindo duplicatas, com identidade interna por posição. O resultado representa o snapshot, mas não permite atribuir de forma confiável cada diferença a INSERT, UPDATE ou DELETE. Nesses lotes, as contagens individuais ficam desconhecidas após o bootstrap.

Operações atendidas

Operação na origem Comportamento do fluxo padrão
CREATE TABLE desconhecida Descoberta no próximo catálogo, desde que visível e acessível à conta de leitura; gera nova view após bootstrap validado.
INSERT em tabela nova ou conhecida Publicado após leitura e validação da tabela.
UPDATE Conteúdo divergente substitui a linha da mesma PK. Sem PK, nova cópia completa.
DELETE físico A ausência de uma chave na leitura completa remove a linha do destino, respeitando a guarda de exclusão.
ADD / DROP COLUMN Mudança de contrato exige cópia completa e recriação transacional da view.
ALTER COLUMN Detecta mudanças observáveis no tipo, tamanho, precisão, escala, nulabilidade e collation; valida a conversão local antes de publicar.
DROP TABLE Após dois ciclos com catálogos completos e estáveis sem o objeto, remove apenas a view gerenciada; mantém dados internos e histórico.

Uma mudança estrutural usa o slot inativo. Se a conversão, a validação ou a substituição da view falhar, a publicação anterior permanece disponível. Dependências externas podem impedir a troca de schema: usamos RESTRICT, sem apagar objetos dependentes. Objetos locais sem a marca de propriedade do laboratório não são sobrescritos.

O status de retirada é missing_or_inaccessible: com SELECT e metadados limitados, a ausência pode significar DROP ou perda de visibilidade/permissão. Uma tabela ainda visível no catálogo, mas sem SELECT, fica inaccessible, gera alerta e preserva a última publicação. Falhas de conexão, erro ao ler o catálogo ou catálogo diferente entre o início e o fim do ciclo não autorizam uma decisão de retirada. No SQL Server, a visibilidade dos metadados depende das permissões sobre os objetos, conforme a documentação da Microsoft.

Acesso à origem e consistência

A conta de extração precisa conectar ao banco e executar SELECT nas tabelas desejadas, inclusive nas criadas depois. No PostgreSQL também precisa de USAGE nos schemas. SOURCE_SCHEMAS, quando definido, limita a descoberta a uma lista de schemas separados por vírgula. Mantenha esse escopo estável: retirar um schema do filtro fará suas tabelas anteriormente conhecidas entrarem no fluxo de ausência.

A aplicação não concede permissões remotas. O administrador da origem deve provisioná-las. As fixtures incluem configurações administrativas apenas para facilitar os testes:

  • PostgreSQL: remote_reader recebe SELECT na tabela inicial e permissões padrão para tabelas futuras criadas pelo administrador da fixture em public. Isso não abrange automaticamente outros proprietários ou schemas.
  • SQL Server: remote_reader recebe SELECT no schema dbo, sem permissões de escrita ou administração.
  • Scripts de inicialização do PostgreSQL só executam em volumes novos. Num volume antigo, o administrador da fixture pode precisar conceder SELECT nas novas tabelas; o sincronizador não fará isso.

No PostgreSQL, a leitura usa REPEATABLE READ READ ONLY. No SQL Server, usa SNAPSHOT quando já habilitado; caso contrário, SERIALIZABLE. Não executa ALTER DATABASE para habilitar isolamento. SERIALIZABLE mantém bloqueios de leitura até o fim da transação e pode bloquear escritores; considere esse custo ao dimensionar a leitura, conforme a documentação de isolamento do SQL Server.

BEGIN, SET de sessão e COMMIT/ROLLBACK controlam a transação de leitura; não exigem permissão de escrita sobre os dados. As consultas de catálogo e conteúdo são SELECT. Cada tabela usa uma transação independente: não há snapshot simultâneo de todo o banco.

Tutorial PostgreSQL

Requisitos: Docker Engine ou Docker Desktop com Compose que suporte !reset para os testes isolados; portas locais disponíveis e memória para Kafka e os bancos. As interfaces são publicadas somente em 127.0.0.1.

1. Iniciar e conferir

docker compose up -d --build
docker compose ps -a
docker compose logs --tail 30 init scheduler consumer
docker compose run --rm cli discover status

init deve terminar com código zero. O scheduler depende desse sucesso e executa ciclos com intervalo de 60 segundos por padrão (SCHEDULER_INTERVAL_SECONDS) após concluir o ciclo anterior. Reiniciar a aplicação não repete bootstrap de tabelas já inicializadas; compara a publicação existente. Tabelas novas recebem seu próprio bootstrap.

docker compose exec local-db psql -U postgres -d lab_local -c 'SELECT count(*) FROM mirror_public.contracts;'

A fixture inicial contém 10.000 contratos. Consulte o monitor, o Kafbat e o Adminer, nas portas padrão. No Adminer: sistema PostgreSQL, servidor local-db, usuário postgres, senha definida em LOCAL_ADMIN_PASSWORD (padrão lab-admin), banco lab_local.

2. Descobrir uma tabela e sincronizar alterações

As operações de escrita abaixo são executadas pelo administrador da fixture descartável, não pela conta de extração.

docker compose exec -T remote-db psql -v ON_ERROR_STOP=1 -U postgres -d lab_remote <<'SQL'
CREATE TABLE public.invoices (
  id BIGINT PRIMARY KEY,
  description TEXT,
  amount NUMERIC(14,2)
);
INSERT INTO public.invoices SELECT g, 'item ' || g, g FROM generate_series(1,10) g;
SQL

Aguarde o próximo ciclo ou pare o scheduler para executar ciclos manuais, evitando dois produtores simultâneos:

docker compose stop scheduler
docker compose run --rm cli discover once
docker compose exec local-db psql -U postgres -d lab_local -c 'TABLE mirror_public.invoices;'
docker compose exec -T remote-db psql -v ON_ERROR_STOP=1 -U postgres -d lab_remote <<'SQL'
INSERT INTO public.invoices VALUES (11, 'new', 12.50);
UPDATE public.invoices SET amount=42.25 WHERE id=1;
DELETE FROM public.invoices WHERE id=2;
ALTER TABLE public.invoices ADD COLUMN currency VARCHAR(3) DEFAULT 'BRL';
ALTER TABLE public.invoices ALTER COLUMN amount TYPE NUMERIC(16,4);
SQL
docker compose run --rm cli discover once
docker compose exec local-db psql -U postgres -d lab_local -c 'TABLE mirror_public.invoices;'

3. Retirar uma tabela

docker compose exec remote-db psql -U postgres -d lab_remote -c 'DROP TABLE public.invoices;'
docker compose run --rm cli discover once
docker compose run --rm cli discover once
docker compose run --rm cli discover status
docker compose start scheduler

A primeira ausência preserva a view. A segunda permite retirá-la. Não há remoção física dos arquivos históricos nem dos dados nos slots internos. Se o objeto reaparecer e puder ser lido, a reconciliação volta a publicar a view após validar os dados.

Tutorial SQL Server

SQL Server é uma origem alternativa, compartilhando o mesmo consumer. Os exemplos abaixo usam o projeto atual; não rode o scheduler PostgreSQL durante o cenário SQL Server.

docker compose stop scheduler
docker compose --profile mssql --profile mssql-tools up -d --build remote-sqlserver local-db kafka toxiproxy consumer monitor
docker compose --profile mssql --profile mssql-tools run --rm mssql-fixture init
docker compose --profile mssql --profile mssql-tools run --rm mssql-cli discover init
docker compose exec local-db psql -U postgres -d lab_local -c 'SELECT count(*) FROM mirror_dbo.contracts;'

A fixture cria 100 contratos e uma conta de leitura. Ela usa sa para preparar exclusivamente o banco sintético; essas credenciais não são usadas pelo produtor. Para um ciclo manual ou acompanhamento:

docker compose --profile mssql --profile mssql-tools run --rm mssql-cli discover once
docker compose --profile mssql --profile mssql-tools run --rm mssql-cli discover status
docker compose --profile mssql --profile mssql-scheduled up -d --build mssql-scheduler

O scheduler SQL Server é opcional e deve ser iniciado depois de discover init. O comando padrão sem perfis continua sendo o cenário PostgreSQL. Use instâncias separadas do laboratório se precisar de destinos independentes; a identidade atual considera motor, schema e tabela, sem um identificador para múltiplos servidores do mesmo motor.

Monitor: como interpretar

O painel mantém o cabeçalho com fluxo, horário de Fortaleza e atualização a cada 20 segundos. Os ícones ? explicam cada indicador ao passar o mouse, tocar ou focar pelo teclado. As tabelas exibem 10 registros por página, com total, primeira/anterior/próxima/última página. Cada tabela mantém sua própria navegação; a atualização automática preserva a URL selecionada. Os históricos apresentados continuam limitados às observações recentes carregadas pelo painel: 40 execuções e 20 observações de schema/faixas.

Os blocos de acompanhamento distinguem a leitura da origem da entrega das mensagens. O primeiro mostra o resultado registrado, a tabela, a data e o link para as evidências; o segundo explica se a fila está em dia, aguardando confirmação, reorganizando consumidores ou sem consumer ativo. Brokers, partições e estado interno do grupo ficam em Detalhes técnicos do Kafka, recolhidos durante a operação normal e abertos automaticamente diante de falhas ou atraso acima do limite. A atividade da extração é uma evidência histórica, sem sonda direta de conectividade à origem.

Indicador Significado
Última promoção Tempo desde a última publicação validada de alguma tabela; não mede disponibilidade da origem.
Tabelas publicadas Quantidade de réplicas com geração ativa; cada uma tem seu slot e contrato.
Lag Kafka Diferença entre offsets publicados e confirmados pelo grupo. Inclui presença e controle, não equivale a linhas.
Cobertura de tabelas Tabelas conhecidas ainda não retiradas com leitura completa validada na janela / total dessas tabelas. 80% significa 8 de 10 tabelas conferidas, não 80% dos dados ou bytes.
Falhas / rejeições Lotes que falharam, foram abortados ou rejeitados nas últimas 24 horas.
Alterações promovidas Contagens de INSERT + UPDATE + DELETE dos lotes confirmados com identidade conhecida. Não inclui atribuição individual em snapshots sem PK.
Catálogo de tabelas Origem, view de destino, estado, linhas da última geração, slot, hash do schema, última conferência e erro.

Uma tabela com falha mantém a última publicação válida e pode continuar contando na cobertura se foi conferida dentro da janela. Confira também o estado e a data: cobertura não substitui os alertas. No modo legado, a cobertura continua medindo faixas numéricas de PK, e usa o rótulo correspondente.

Os nomes das tabelas de origem abrem um modal com o DDL reconstruído do catálogo observado. Nas execuções, o DDL corresponde ao contrato registrado no lote. Os IDs abrem as evidências em modal, com navegação de volta ao lote, fechamento por Esc e preservação da página selecionada. A atualização automática pausa enquanto um modal está aberto. A reconstrução não substitui um dump completo: propriedades não registradas, como índices, FKs ou parâmetros de identidade, podem estar ausentes.

O monitor lê somente seu PostgreSQL separado como monitor_reader e metadados Kafka. Não recebe credenciais do banco mirror nem da origem e não participa do grupo consumer. /status.json expõe os indicadores; /run/<uuid> mostra evidências do lote; /healthz informa que o processo HTTP está vivo; /readyz verifica o banco do monitor, a atualização do coletor, a última leitura da auditoria local e o tópico Kafka, sem certificar igualdade entre bases.

Banco separado do monitor

O Compose mantém três persistências distintas: origem em remote-db/lab_remote, réplica em local-db/lab_local e monitor em monitor-db/lab_monitor. Cada PostgreSQL tem seu próprio volume. O banco do monitor usa monitor_data e não publica porta no host; pelo Adminer, o servidor é monitor-db, banco lab_monitor, usuário monitor_reader, senha monitor-reader.

O serviço monitor-collector consulta somente a auditoria e o catálogo local com a conta de leitura já existente. Não lê as linhas das views mirror_*, os payloads de staging ou o journal de dados. Copia o resumo dos indicadores, as evidências históricas dos lotes e os contratos de DDL para lab_monitor, usando monitor_writer. O painel recebe apenas a conta SELECT desse novo banco; o coletor é o único componente de monitoramento com credenciais dos dois servidores locais.

Os checkpoints, gerações e registros de execução usados pelo produtor e consumer continuam junto da réplica: são necessários para confirmar a promoção na mesma transação dos dados. O novo banco guarda uma projeção desses metadados para consulta. Sua indisponibilidade não bloqueia bootstrap, sincronização, guardas ou rollback. As publicações da projeção também são transacionais: uma coleta ou gravação incompleta preserva a última cópia completa.

O coletor executa uma tentativa a cada 10 segundos após concluir a anterior. Última leitura indica a leitura do painel; Evidências coletadas mostra a data da última coleta completa da auditoria. Os sinais Kafka são consultados pelo próprio painel. Se o coletor ficar mais de 60 segundos sem registrar uma tentativa, aparece MONITOR_COLLECTION_STALE, e a saúde atual da réplica fica não aferida. MONITOR_DB_DOWN identifica falha no banco separado; LOCAL_DB_DOWN ou LOCAL_DB_READ_ERROR identificam erro na leitura da réplica reportado pelo coletor. O histórico já copiado continua consultável em caso de falha da réplica, enquanto o banco do monitor estiver acessível.

Para atualizar uma instalação existente, preservando os volumes da origem e do mirror:

docker compose up -d --build monitor-db monitor-collector monitor
docker compose logs --tail 80 monitor-collector monitor
curl --fail http://localhost:8082/readyz

A primeira coleta recompõe o histórico dentro de AUDIT_RETENTION_DAYS e todas as execuções pendentes, incluindo evidências fora das 40 execuções exibidas na página. Não é necessário apagar volumes nem refazer bootstrap. O monitor pode exibir aviso de coleta pendente durante essa preparação. Para executar o processo HTTP fora do Compose, MONITOR_DSN seleciona o banco separado; o modo de leitura direta com LOCAL_DSN permanece disponível para compatibilidade.

Cada coleta percorre os metadados da janela de auditoria e as execuções pendentes para capturar conclusões tardias e alterações de estado, com memória limitada e gravação apenas dos documentos divergentes. Os detalhes expirados da projeção são removidos periodicamente e não são recopiados. Os limites de janela e de lotes travados devem ser configurados no coletor, que calcula esses indicadores; mantenha os mesmos valores no painel para os rótulos e alertas. Veja Retenção de logs e auditoria para as exceções de recuperação e o resultado da manutenção.

Parâmetros do serviço monitor:

Variável Padrão Efeito
LAB_SYNC_MODE catalog no Compose Visão por tabela; legacy mostra faixas do fluxo antigo.
LAB_COVERAGE_WINDOW_HOURS 24 Janela de leituras validadas da cobertura.
LAB_STALLED_MINUTES 15 Alerta para lote pendente há muito tempo.
LAB_MAX_CONSUMER_LAG 1000 Limite do alerta de offsets pendentes.
LAB_EXPECTED_INTERVAL_MINUTES 0 Meta opcional de idade da última promoção; zero desabilita.
MONITOR_DSN monitor-db / lab_monitor no Compose Conexão SELECT do painel ao banco separado.
LAB_MONITOR_COLLECTION_MAX_AGE 60 Tempo máximo, em segundos, sem tentativa do coletor antes do alerta de evidências desatualizadas.

Parâmetros exclusivos de monitor-collector: LOCAL_DSN é a conexão SELECT à auditoria da réplica; MONITOR_WRITE_DSN escreve somente a projeção; LAB_MONITOR_COLLECTION_SECONDS define o intervalo entre tentativas, com padrão de 10 segundos. LAB_SYNC_MODE, LAB_COVERAGE_WINDOW_HOURS, LAB_MAX_COVERAGE_INTERVALS e LAB_STALLED_MINUTES controlam a coleta. Ao trocar para o fluxo legado, ajuste LAB_SYNC_MODE=legacy tanto no coletor quanto no painel.

Componentes e serviços

Serviço Responsabilidade Inicialização
remote-db PostgreSQL sintético; provisiona dados e conta SELECT em volume novo. Padrão
local-db Destino PostgreSQL; slots, views, staging, auditoria e journal. Padrão
kafka Transporte ordenado de eventos, uma partição de dados, modo KRaft. Padrão
toxiproxy Intermedia conexão da origem e permite simular falhas de rede. Padrão
consumer Consome eventos, valida o lote e promove cada tabela transacionalmente. Padrão
init Prepara proxy, descobre tabelas, inicializa as novas e aguarda promoção. Padrão, execução única
scheduler Executa os ciclos PostgreSQL após init, sem sobrepor ciclos. Padrão
monitor-db PostgreSQL exclusivo das evidências do monitor, volume monitor_data, sem porta no host. Padrão
monitor-collector Lê auditoria da réplica com SELECT e atualiza a projeção no banco do monitor. Padrão
monitor Painel HTTP com leitura no banco separado e consulta de metadados Kafka. Padrão, porta 8082
kafbat Interface de tópicos, mensagens, grupos e offsets. Padrão, porta 8080
adminer Interface de consultas aos bancos do laboratório. Padrão, porta 8081
cli Comandos manuais PostgreSQL, diagnóstico e recuperação. Perfil tools, ou run cli
seed-fixture Gerador administrativo de massa PostgreSQL sintética. Perfil tools
remote-sqlserver Origem SQL Server Developer sintética. Perfil mssql
mssql-fixture Prepara e modifica a fixture SQL Server como administrador. Perfil mssql-tools + mssql
mssql-cli Comandos de descoberta e sincronização SELECT para SQL Server. Perfil mssql-tools + mssql
mssql-scheduler Reconciliação periódica SQL Server, iniciada após bootstrap manual. Perfil mssql-scheduled + mssql
Arquivo Responsabilidade
.env.example Modelo versionado da configuração local do Compose.
app/.dockerignore Exclusões do contexto de build ./app.
app/lab.py CLI, transporte Kafka, consumer e integração com o fluxo legado.
app/retention.py Configuração central, manutenção limitada, histórico da limpeza e expiração de eventos Kafka confirmados.
app/discovery_catalog.py Catálogos PostgreSQL/SQL Server, permissões observáveis, identificadores, mapeamento de tipos e leitura consistente.
app/discovery_sync.py Orquestra descoberta, comparação, publicação, espera da promoção e scheduler.
app/discovery_store.py Schema local automático, staging por tabela, views tipadas, slots, journal, promoção, retirada e rollback.
app/monitor.py Consultas de auditoria, alertas, HTML, paginação e endpoints dos detalhes.
app/monitor_details.py Reconstrução do DDL observado e apresentação segura dos detalhes das execuções.
app/monitor_collect.py Coleta consistente de metadados locais e publicação transacional no banco do monitor.
app/monitor_store.py Leitura da projeção e dos detalhes históricos, com verificação de atualização da coleta.
app/monitor_ui.js Modais acessíveis, consulta dos detalhes e pausa da atualização durante a leitura.
app/startup.py Inicialização compatível com o fluxo legado de contratos.
app/schema_evolution.py Planejamento, aprovação e backfill de schema no fluxo legado.
app/source_catalog.py Observador explícito de um objeto no catálogo legado.
app/canonical_contract.py Representação canônica dos contratos legados entre motores.
app/mssql_sync.py Extração SQL Server do contrato legado e configuração de seu proxy.
app/sqlserver_fixture.py Ações administrativas restritas à fixture SQL Server.
sql/local.sql Estrutura inicial da réplica e conta de leitura usada pelo coletor.
sql/monitor.sql Banco exclusivo de monitoramento, projeção e contas separadas de escrita e leitura.
sql/remote.sql Fixture PostgreSQL, dados iniciais e concessões SELECT.
tests/ Contratos offline e cenários integrados em projetos descartáveis.

As tabelas replica.discovered_tables, discovered_cycles, discovered_runs e discovered_schema_history guardam o catálogo e a auditoria. discovered_blue/discovered_green guardam payloads JSONB; discovered_seen/discovered_delta são staging descartado ao concluir o lote; discovered_generations e discovered_journal sustentam a linhagem. A criação dessas estruturas é automática, inclusive em um volume local existente.

Configuração, recuperação e limites

Comandos usuais, com o scheduler parado quando houver um produtor manual:

docker compose run --rm cli discover once --batch-size 250 --promotion-timeout 600
docker compose run --rm cli discover status
docker compose run --rm cli discover rollback --db-schema public --table contracts

O rollback alterna para a geração anterior somente quando o schema é compatível. O próximo ciclo volta a reconciliar a origem atual. Schema incompatível bloqueia rollback; uma atualização não é uma migração reversível automática. Pare o scheduler para inspecionar o estado restaurado.

Uma guarda rejeita lotes com remoção acima de MAX_REMOVE_FRACTION (padrão 0.20, configurado no consumer). Isso também se aplica a exclusões físicas legítimas: numa tabela de três linhas, excluir uma supera 20%. Sem PK, a guarda usa a redução líquida da contagem. Uma rejeição preserva a publicação anterior. Ajustar o limite exige recriar o consumer com a configuração escolhida e iniciar uma nova leitura após revisar a origem.

Aplicar uma exclusão intencional bloqueada por Deletion guard

O fluxo é origem remota → destino local. Este procedimento permite refletir no destino uma exclusão já confirmada na origem; a aplicação continua usando somente SELECT remoto. O lote rejeitado permanece no histórico: é necessária uma nova leitura, que gera outro lote.

O limite é a fração removida em relação à última publicação da tabela. Por exemplo, Deletion guard: 2/5, limit=20.00% significa que duas das cinco linhas seriam removidas (40%). Nesse caso, um limite temporário de 0.50 comporta a exclusão. O limite é global para todas as tabelas processadas pelo consumer, e o ciclo manual lê todas as tabelas acessíveis; não existe liberação isolada por tabela ou lote.

Os comandos abaixo usam a origem PostgreSQL padrão. Para SQL Server, substitua scheduler por mssql-scheduler e cli por mssql-cli, mantendo o mesmo serviço consumer. Não mantenha outro produtor manual em execução durante o procedimento.

  1. Confira a tabela, a proporção informada no erro e o conteúdo atual da origem. Confirme que a exclusão foi intencional e que a transação foi efetivada com COMMIT. No exemplo public.lab_teste_ddl, a consulta na origem é SELECT count(*) FROM public.lab_teste_ddl;.

  2. Pare o scheduler para concluir o ciclo atual e evitar concorrência com a leitura manual:

    docker compose stop scheduler
  3. Em .env, localize MAX_REMOVE_FRACTION, anote o valor anterior e ajuste apenas essa variável. Use um limite que comporte a proporção revisada; por exemplo, para remover 40%:

    MAX_REMOVE_FRACTION=0.50

    "1.00" permite remover até 100% das linhas, inclusive esvaziar tabelas. Use esse valor somente quando essa possibilidade tiver sido conferida nas tabelas que serão reconciliadas. Alterar a variável apenas na CLI não modifica a validação do consumer.

  4. Recrie o consumer para carregar a configuração e execute uma nova reconciliação. Um simples restart não atualiza as variáveis de ambiente:

    docker compose up -d --no-deps --force-recreate consumer
    docker compose run --rm cli discover once --promotion-timeout 600
    docker compose run --rm cli discover status
  5. Confira o resultado antes de retomar a rotina. A tabela deve estar active, sem erro atual e com a contagem esperada. No monitor, o novo lote deve estar promoted. Para o exemplo, confira também SELECT count(*) FROM mirror_public.lab_teste_ddl; no banco local e as linhas esperadas. O histórico e o contador de rejeições das últimas 24 horas ainda incluem o lote anterior.

  6. Restaure no mesmo arquivo de ambiente o valor anotado (0.20 no padrão) e recrie novamente o consumer, mesmo se a tentativa falhar:

    docker compose up -d --no-deps --force-recreate consumer
  7. Após confirmar a promoção e restaurar a proteção, retome o scheduler:

    docker compose start scheduler

Se a reconciliação falhar, restaure o limite, mantenha o scheduler parado e consulte docker compose logs --tail 80 consumer e o erro do novo lote antes de tentar novamente. Não é necessário apagar volumes, zerar offsets Kafka ou editar a auditoria para liberar a exclusão.

Lotes pendentes e outros limites

Um lote pendente é retomado aguardando o consumer, sem republicar bootstrap. Se uma publicação foi interrompida antes de table_end, examine Kafka, logs e auditoria antes de abandonar:

docker compose logs --tail 80 consumer scheduler init
docker compose run --rm cli discover abandon --run-id UUID_DO_LOTE --force

O abandono publica um evento de controle ordenado. --force só deve ser usado após verificar se um END já está na fila. Falhas de catálogo inicial ou final ficam registradas como ciclos falhos; não autorizam retirar tabelas.

DISCOVERY_THROTTLE_MS pausa entre blocos de extração; --batch-size limita as linhas de cada bloco, não o tamanho total da leitura. SOURCE_SCHEMAS e o throttle devem ser configurados no serviço que publica (init, scheduler ou CLI). Origem remota usa REMOTE_DSN no PostgreSQL e MSSQL_HOST, MSSQL_PORT, MSSQL_DATABASE, MSSQL_USER, MSSQL_PASSWORD no SQL Server.

Tipos comuns geram colunas tipadas nas views. Valores são transportados como texto ou NULL para preservar precisão numérica; binários usam hexadecimal. Tipos sem correspondência segura permanecem como texto. Datas/horas SQL Server com sete casas fracionárias ficam como texto para preservar a última casa. Não são recriados índices, FKs, defaults de escrita, sequences, identidades, triggers ou permissões da origem. As views de réplica são para leitura.

Colunas com nomes acima do limite local de 63 bytes são bloqueadas explicitamente. Texto com NUL, conversões inválidas, permissões insuficientes e mensagens acima do limite do transporte interrompem o lote; não há promoção parcial. Tipos especializados podem exigir um mapeamento adicional. Não há garantia de equivalência de collation ou de todas as operações SQL entre motores.

A leitura completa, os eventos de presença, os dois slots e o journal têm custo de rede, armazenamento e processamento. O journal e a auditoria da descoberta não têm retenção automática nesta implementação. Polling não observa necessariamente todas as mudanças intermediárias entre ciclos, nem um CREATE seguido de DROP antes da próxima leitura. Não existe SLA de atualização ou igualdade global simultânea.

Para parar sem apagar volumes:

docker compose stop
docker compose up -d --build

Os schedulers terminam o ciclo atual ao receber SIGTERM, dentro do prazo de parada do Compose. docker compose down preserva volumes; adicionar -v apaga os dados do laboratório.

Tutorial: simular latência e falhas de rede

O Toxiproxy já faz parte do fluxo padrão e recebe a conexão do extrator com a origem. Os comandos chaos alteram esse proxy sem modificar dados ou permissões do banco remoto. Execute os exemplos na pasta do projeto, com o laboratório iniciado por docker compose up -d --build.

As simulações atingem todas as tabelas lidas pelo proxy escolhido. Nesta CLI, os efeitos são aplicados às respostas origem → extrator (downstream), com toxicity=1.0, abrangendo todas as conexões desse proxy. Kafka, consumer e banco local não passam por ele. Uma conexão administrativa direta ao banco também não sofre esses efeitos.

1. Preparar uma referência sem falhas

Confira o estado atual antes de alterar a simulação:

docker compose run --rm cli chaos status

O log proxy_status contém state.enabled e state.toxics. Para iniciar uma comparação sem falhas simuladas, remova as condições existentes e confira novamente:

docker compose run --rm cli chaos clear
docker compose run --rm cli chaos status

O resultado esperado é enabled: true e toxics: []. Aguarde um ciclo e anote no monitor a duração e o resultado das execuções de cada tabela. Compare sempre a mesma tabela, com volume semelhante.

2. Adicionar latência com variação

docker compose run --rm cli chaos latency 200
docker compose run --rm cli chaos status

O valor é em milissegundos. A CLI calcula jitter como um quinto inteiro da latência: 200 configura latency=200 e jitter=40, variando o atraso entre 160 e 240 ms no fluxo de resposta. Esse atraso pode incidir várias vezes durante a comunicação; não significa que a duração total do lote aumentará apenas 200 ms.

Para aumentar a condição no mesmo teste:

docker compose run --rm cli chaos latency 500

Isso substitui a condição chamada latency, agora com jitter=100. Outros tipos de condição já ativos continuam valendo. O jitter não tem parâmetro independente nesta CLI.

Observe a duração dos lotes e a idade da última promoção. A leitura completa, as consultas de catálogo e as buscas em blocos podem amplificar o efeito. Mesmo com zero alterações, a tabela continua sendo lida e as presenças de suas chaves são enviadas ao Kafka.

3. Limitar a banda

Para testar a limitação isoladamente, remova a latência do cenário anterior:

docker compose run --rm cli chaos clear
docker compose run --rm cli chaos bandwidth 256

256 limita a resposta a 256 KB/s por conexão, não a soma do tráfego de todos os serviços. Tabelas com mais dados devem apresentar maior impacto. A guarda de exclusão e as demais validações continuam funcionando normalmente.

4. Combinar latência e banda reduzida

docker compose run --rm cli chaos clear
docker compose run --rm cli chaos latency 100
docker compose run --rm cli chaos bandwidth 128
docker compose run --rm cli chaos status

As duas condições ficam ativas ao mesmo tempo. O status deve listar latency e bandwidth em toxics. A CLI mantém uma condição de cada nome; repetir bandwidth troca sua configuração, sem remover latency.

5. Simular uma conexão sem resposta e com fechamento

docker compose run --rm cli chaos clear
docker compose run --rm cli chaos timeout 3000

O toxic timeout bloqueia o fluxo afetado e fecha a conexão após 3000 ms. Ele não concede três segundos para uma consulta concluir. Com valor 0, o bloqueio não fecha a conexão por esse mecanismo e pode deixar uma leitura esperando até outro timeout ou a remoção da condição. Prefira um valor positivo neste primeiro teste.

O erro pode acontecer durante a descoberta do catálogo, antes de existir um lote da tabela. Nesse caso, confira também o último ciclo e os logs do scheduler; não espere obrigatoriamente uma nova linha em Últimas execuções.

6. Simular indisponibilidade e retorno da conexão

docker compose run --rm cli chaos clear
docker compose run --rm cli chaos down
docker compose run --rm cli chaos status

down desabilita o proxy da origem. Aguarde uma tentativa do scheduler para observar a falha de acesso. Para reativá-lo:

docker compose run --rm cli chaos up

up reativa o proxy e mantém os toxics existentes. clear remove todos os toxics desse proxy e também o reativa. Nenhuma dessas ações altera a disponibilidade do processo do banco remoto.

Para testar intermitência, repita manualmente a sequência down/up, aguardando tentativas de leitura entre as mudanças. A CLI atual não agenda quedas, não define duração automática dos efeitos e não oferece um comando próprio de perda aleatória de pacotes.

7. Encerrar o teste e conferir a recuperação

Ao terminar qualquer cenário, inclusive quando ocorrer erro, execute:

docker compose run --rm cli chaos clear
docker compose run --rm cli chaos status
docker compose logs --tail 80 scheduler consumer

Confirme enabled: true, toxics: [] e uma nova promoção no próximo ciclo. Os efeitos não expiram sozinhos: a inicialização normal do extrator preserva a configuração de um proxy já existente. O Compose atual não persiste essa configuração em volume; após reiniciar ou recriar o Toxiproxy, confira novamente o estado em vez de presumir que o cenário foi mantido.

O scheduler padrão espera 60 segundos após terminar o ciclo anterior, e o painel atualiza a cada 20 segundos. Uma pausa entre execuções não equivale à duração do lote. Os tempos exibidos incluem leitura, transporte e processamento no destino; o painel atual não separa a duração de cada etapa. Kafka com lag zero também não comprova uma leitura recente: o produtor pode estar bloqueado antes de publicar mensagens.

Uma leitura incompleta não autoriza exclusões ou promoção parcial dessa tabela; sua publicação anterior é preservada. Tabelas já promovidas no mesmo ciclo permanecem publicadas, pois a unidade de publicação é cada tabela. Se um lote ficar pendente após uma interrupção, siga Lotes pendentes e outros limites antes de abandoná-lo. As falhas anteriores continuam no histórico e no contador das últimas 24 horas após a recuperação.

Usar os mesmos cenários com SQL Server

Com a origem SQL Server preparada, use mssql-cli e informe explicitamente --target sqlserver. Isso escolhe o proxy remote_mssql; o padrão sem esse argumento é remote_pg:

docker compose run --rm mssql-cli chaos status --target sqlserver
docker compose run --rm mssql-cli chaos latency 200 --target sqlserver
docker compose run --rm mssql-cli chaos clear --target sqlserver

As ações bandwidth, timeout, down e up usam o mesmo argumento. Acompanhe mssql-scheduler nos logs se essa for a origem agendada. Use somente o scheduler da origem escolhida, conforme a configuração do laboratório.

As unidades e o comportamento dos toxics seguem a documentação oficial do Toxiproxy. Os comandos, nomes, direção e regras de combinação acima correspondem à CLI implementada neste repositório.

Compatibilidade com os comandos anteriores

initialize, bootstrap, incremental, schedule, status, rollback, schema e catalog continuam disponíveis para o contrato fixo public.contracts. Esse fluxo usa faixas numéricas de ID e seus próprios metadados; não é o scheduler padrão. Para executá-lo manualmente, pare o scheduler de descoberta e use explicitamente os comandos antigos. Não misture os dois fluxos como se tivessem o mesmo checkpoint ou a mesma view.

Os comandos chaos também atendem o fluxo legado; veja o tutorial de simulação de rede. As ações seed, mutate, load e os comandos da fixture SQL Server modificam dados sintéticos com credenciais administrativas; não são mecanismos de sincronização nem devem apontar para uma origem real.

Retenção de logs e auditoria

Diagnóstico anterior à alteração

A auditoria examinou docker-compose.yml, app/lab.py, discovery_store.py, schema_evolution.py, source_catalog.py, o coletor/painel, os três scripts SQL e as configurações efetivas do laboratório em 22/10/2026:

  • Kafka: dados em kafka_data, diretório /var/lib/kafka/data. kafka_ready() criava os dois tópicos com cleanup.policy=delete e retention.ms=604800000 fixos (sete dias), mas ignorava TOPIC_ALREADY_EXISTS sem alterar configurações existentes. Os tópicos reais lab.sync.events e lab.sync.audit tinham esses valores. Não havia variável de retenção nem proteção dos eventos não confirmados contra expiração por idade. __consumer_offsets usava compactação; não é um log operacional a apagar.
  • PostgreSQL local: local_data guarda tanto o histórico quanto o estado essencial em replica. sync_runs, transitions, schema_changes, source_catalog_observations, range_checkpoints e tabelas discovered_* não tinham expiração temporal. Staging era removido por conclusão/aborto; change_journal já tinha poda estrutural pelo caminho entre os slots (prune_journal()), sem prazo em dias. O journal da descoberta e as gerações eram mantidos sem expiração. Variáveis de janela do monitor apenas limitavam consultas, sem remover registros.
  • Docker: Python grava JSON/exceções em stdout/stderr; os PostgreSQL inspecionados usam logging_collector=off, log_destination=stderr. A saída de consumer, scheduler, init, monitor, coletor, Kafka e Toxiproxy fica com o driver de logs do Docker. O Compose não declarava limites. Neste host, os contêineres usavam local com opções vazias: a rotação vinha dos padrões do driver, não de uma política do projeto. Em outro daemon, o comportamento poderia ser diferente. Não havia garantia temporal de sete dias.
  • Arquivos internos Kafka: a inspeção da imagem em execução também encontrou /opt/kafka/logs/server.log, controller.log, state-change.log e outros appenders Log4j2 com rotação horária, sem descarte configurado, na camada gravável do contêiner (fora de kafka_data). O script Java usava ainda GC em arquivos, com limite próprio de 10 × 100 MB. A rotação Docker não alcançava essas cópias internas. config/kafka-log4j2.yaml e KAFKA_GC_LOG_OPTS agora direcionam esses diagnósticos ao stdout; a recriação do contêiner elimina sua camada antiga, preservando o volume de eventos.
  • Monitor: o HTTP em 8082 lê monitor_data (monitoring.collection_state e monitoring.details) e metadados Kafka. O coletor lê apenas a auditoria local e copiava todos os detalhes de execução indefinidamente; as 40 execuções do painel não eram uma política de armazenamento. A projeção não contém linhas de negócio nem checkpoints de restauração.

Configuração e aplicação automática

Arquivos desta implementação: app/retention.py, integração em app/lab.py/app/Dockerfile, projeção em app/monitor_collect.py, apresentação em app/monitor.py, configuração em docker-compose.yml/.env.example/config/kafka-log4j2.yaml e este README. Os testes novos são tests/test_retention.py, tests/test_retention_live.py, tests/test_retention_kafka_live.py, tests/test_retention_monitor_live.py e tests/e2e_retention.sh. Foram ajustados também tests/check_static.py, tests/test_monitor.py, tests/test_monitor_storage.py e tests/test_mssql_paths.py; os dois testes que esperavam portas/usuário fixos agora refletem a interpolação já existente do Compose. A lógica de reconciliação permanece a mesma.

Acrescente ou ajuste no .env existente (os padrões do Compose também permitem usar um .env antigo):

LOG_RETENTION_DAYS=7
AUDIT_RETENTION_DAYS=7
KAFKA_RETENTION_DAYS=7
LOG_CLEANUP_ENABLED=true
LOG_CLEANUP_INTERVAL_HOURS=24
DOCKER_LOG_MAX_SIZE=20m
DOCKER_LOG_MAX_FILES=5

Dias e intervalo aceitam inteiros positivos; o habilitador aceita true/false. LOG_RETENTION_DAYS controla o histórico operacional da própria manutenção armazenado no PostgreSQL. As mensagens de stdout/stderr usam os dois limites Docker, pois o driver local não oferece expiração temporal exata. Todos os serviços, inclusive os perfis SQL Server e ferramentas, compartilham essa rotação por tamanho/arquivos, com compressão padrão do driver. Os arquivos pertencem ao Docker e não devem ser apagados por scripts da aplicação.

O Kafka recebe config/kafka-log4j2.yaml como montagem somente leitura, com apenas appender de console, e envia GC ao stdout. Isso evita cópias de diagnóstico com políticas independentes dentro do contêiner. Os diretórios de segmentos de eventos em kafka_data continuam sendo dados Kafka, tratados pela política específica abaixo.

Depois de editar, execute docker compose up -d --build. O consumer cria as duas tabelas auxiliares de manutenção com DDL aditivo idempotente e aplica as configurações dos tópicos por incremental_alter_configs, inclusive em volumes previamente inicializados. Não depende de reexecutar docker-entrypoint-initdb.d, apagar volumes ou mudar código. As políticas são dos dois tópicos configurados em KAFKA_TOPIC/KAFKA_AUDIT_TOPIC, não de tópicos arbitrários do broker. restart sozinho não carrega novas variáveis.

Matriz de retenção e dependências

Componente / dado Classe Retenção padrão Mecanismo e justificativa
stdout/stderr de todos os contêineres A Limite de 20 MB × 5 arquivos por contêiner; sem prazo temporal Driver Docker local, opções explícitas e configuráveis. Volume de mensagens determina quanto tempo cabe.
replica.log_cleanup_history A LOG_RETENTION_DAYS = 7 dias Exclusões em lotes; registra data, duração, contagens, configurações e erros.
lab.sync.audit A/B KAFKA_RETENTION_DAYS = 7 dias Broker: cleanup.policy=delete, retention.ms=dias×86400000, sem limite em bytes, segmentos de até uma hora. Não participa da recuperação do consumer.
lab.sync.events A/C enquanto pendente Idade mínima de KAFKA_RETENTION_DAYS = 7 dias para mensagens confirmadas retention.ms=-1, retention.bytes=-1 impedem expiração autônoma. A manutenção usa DeleteRecords até o menor offset entre a fronteira temporal e o offset confirmado pelo grupo. Suspende se houver lote/ciclo/backfill/migração pendente ou se faltar evidência do offset.
replica.transitions B AUDIT_RETENTION_DAYS = 7 dias Remove transições antigas, preservando a última. Slots/gerações não dependem dessa tabela; o painel usa a última como contexto operacional.
replica.source_catalog_observations B; última observação é referência atual 7 dias, preservando a última por source_key A comparação estrutural lê a observação de maior ID. Ela permanece mesmo antiga para não perder a referência de DDL. Cada observação contém os manifestos e diferenças.
replica.discovered_schema_history B; última observação é referência atual 7 dias, preservando a última por tabela Manifestos usados para publicação/rollback já estão em discovered_tables/discovered_runs. Histórico antigo excedente pode sair sem alterar esses contratos.
sync_runs, discovered_runs, discovered_cycles B + C Sem exclusão por idade IDs terminais também impedem reprocessamento de mensagens Kafka. O protocolo não registra fronteiras Kafka por lote que provem ser seguro remover esses marcadores. Execuções em andamento ficam intactas.
Gerações, slots, estados ativos, range_checkpoints, journals C Sem exclusão por idade FKs e referências lógicas sustentam linhagem, cobertura, rollback e alinhamento. A poda estrutural preexistente de change_journal continua sendo a autoridade.
schema_versions, schema_state, schema_changes, schema_backfill_* B/C Sem exclusão por idade Hash ativo/pendente, evidências de aprovação e intervalos têm dependências de recuperação. schema_changes não encerra todos os estados antigos de forma suficiente para provar descarte seguro; permanece conservadoramente integral.
ingest_*, discovered_delta, discovered_seen, linhas blue/green, arquivos de tabelas retiradas C Pelo ciclo de vida existente Somente a reconciliação pode liberar staging e dados; manutenção temporal não interfere, inclusive em falhas e cargas pendentes.
monitoring.details, tipo run B (cópia) 7 dias após finished_at; pendentes preservados Coletor filtra importação e apaga detalhes expirados em lotes. Nunca altera o registro original. Conclusões sem data também são preservadas.
monitoring.collection_state, detalhes de catálogo atual, log_cleanup_state Estado de operação atual Último estado por chave, sem expiração Atualização por chave; conserva último resultado, inclusive erro, sem acumular snapshots.
__consumer_offsets C Política interna do Kafka, sem alteração pela manutenção Nenhuma exclusão, alteração de configuração ou reset de offsets pelo processo de limpeza.

As FKs de ingest_* e range_checkpoints apontam para sync_runs; checkpoints/journal/slots apontam para generations, que tem referência ao pai. generations.run_id, base_version e result_version também são referências lógicas, mesmo sem FK. Na descoberta, gerações apontam para runs e pais; runs apontam para ciclos e tabelas; staging aponta para runs e journal aponta para gerações. Backfills têm FKs para hashes e runs. A política preserva esses conjuntos inteiros, sem exclusões em cadeia e sem inferir segurança apenas da ausência de uma FK.

Manutenção, replay e limites

O consumer executa uma thread leve com conexão local própria. Ela verifica a agenda persistida a cada 30 segundos; executa na primeira oportunidade e depois a cada LOG_CLEANUP_INTERVAL_HOURS. Reinícios não zeram a agenda. Falhas registradas são tentadas novamente após um minuto. Uma trava consultiva impede limpezas simultâneas. O coletor usa a mesma configuração de intervalo para sua projeção, com resultado persistido no snapshot. Não foi adicionado serviço nem banco.

Cada tabela tem até 20 lotes de 500 linhas por execução, com transações curtas, FOR UPDATE SKIP LOCKED, lock_timeout=1s e statement_timeout=5s. Um acúmulo maior precisa de novas execuções; dry-run conta todos os elegíveis (também limitado pelo timeout), podendo superar o número removido em uma passagem. Registros travados ficam para outra tentativa. Erros por componente não autorizam apagar estado nem cancelar a replicação. O processo não usa TRUNCATE, DROP ou CASCADE. O espaço liberado pode ser reutilizado pelo PostgreSQL após autovacuum; não há VACUUM FULL nem promessa de redução imediata dos arquivos.

No tópico de dados, timestamps novos são do broker (LogAppendTime). Mensagens recentes e offsets não confirmados permanecem; enquanto houver qualquer carga pendente, a expiração dos eventos é suspensa. Isso pode aumentar o uso de disco além de sete dias, inclusive com o consumer parado. Resolver/abandonar cargas continua sendo uma decisão operacional pelos comandos existentes. LOG_CLEANUP_ENABLED=false desliga a limpeza automática SQL e de eventos; a retenção independente do tópico de auditoria e a rotação Docker continuam. Uma execução manual explícita continua disponível.

Kafka expira segmentos e DeleteRecords avança o início lógico do log; a remoção física é assíncrona. Portanto, o prazo é uma janela de elegibilidade, acrescida do intervalo de manutenção e da liberação de segmentos, não uma exclusão pontual no sétimo dia. Retenção Kafka não substitui backup. Depois de expirar eventos, resetar offsets ou tentar reconstruir um PostgreSQL vazio pode exigir novo bootstrap da origem; não se promete reconstrução integral a partir de um trecho retido. Os marcadores locais de replay são conservadoramente preservados.

Inspeção, dry-run e resultado

# Configuração validada; consulta mostra apenas parâmetros de retenção e resultados.
docker compose config --quiet
docker compose run --rm cli cleanup --status

# Conta elegíveis, sem apagar histórico ou mensagens; registra a simulação separadamente.
docker compose run --rm cli cleanup --dry-run
docker compose run --rm cli cleanup
docker compose logs --tail 80 consumer monitor-collector

# Configuração efetiva dos tópicos, inclusive dos volumes antigos.
docker compose exec -T kafka /opt/kafka/bin/kafka-configs.sh --bootstrap-server kafka:19092 --entity-type topics --describe

# Últimos resultados locais (automatic, manual e dry_run).
docker compose exec -T local-db psql -U postgres -d lab_local -c 'SELECT job,document FROM replica.log_cleanup_state ORDER BY job'

O dry-run grava apenas seu resultado nas tabelas de controle, sem adiar a agenda automática. A expiração Kafka mostra offsets, que não equivalem a linhas de negócio nem a bytes físicos. Para simular separadamente a projeção do monitor, sem fornecer novas credenciais à CLI:

docker compose run --rm --no-deps --entrypoint python monitor-collector -c 'import os,json,psycopg,retention,monitor_collect as c; from datetime import datetime,timezone; conn=psycopg.connect(os.environ["MONITOR_WRITE_DSN"]); print(json.dumps(c.cleanup_projection(conn,os.getenv("LAB_SYNC_MODE","catalog"),datetime.now(timezone.utc),retention.Settings.from_env(),True))); conn.close()'

Em localhost:8082/#maintenance e /status.json, o coletor publica períodos configurados, resultados automáticos/manuais/simulações, duração, contagens por tabela, fronteira Kafka e erros. Falhas geram LOG_CLEANUP_FAILED/MONITOR_CLEANUP_FAILED; uma execução automática atrasada gera LOG_CLEANUP_OVERDUE. A exibição usa a coleta existente e conserva sua indicação de atualização.

Referências dos mecanismos: retenção de tópicos Kafka, API administrativa Kafka Python e driver de logs local do Docker. As APIs e configurações também foram verificadas nas imagens usadas pelo laboratório.

Verificações

Testes offline, sem bancos ou Kafka:

python3 tests/check_static.py
python3 tests/test_discovery_catalog.py
python3 tests/test_monitor.py
python3 tests/test_monitor_modals.py
python3 tests/test_monitor_storage.py
python3 tests/test_startup.py
python3 tests/test_reconcile.py
python3 tests/test_generation_paths.py
python3 tests/test_schema_contract.py
python3 tests/test_source_catalog.py
python3 tests/test_mssql_contract.py
python3 tests/test_mssql_paths.py
python3 tests/test_retention.py  # requer as dependências de app/requirements.txt

Integração dos dois motores em projetos descartáveis, sem publicar portas do host:

LAB_DISCOVERY_TEST=1 bash tests/e2e_discovery.sh
# Ou apenas um motor:
LAB_DISCOVERY_TEST=1 LAB_DISCOVERY_ENGINE=postgresql bash tests/e2e_discovery.sh
LAB_DISCOVERY_TEST=1 LAB_DISCOVERY_ENGINE=sqlserver bash tests/e2e_discovery.sh

# Retenção real em stack própria, também sem portas publicadas:
LAB_RETENTION_TEST=1 bash tests/e2e_retention.sh

O teste valida início padrão, recusa de escrita pela conta SELECT, descoberta, INSERT/UPDATE/DELETE, rollback compatível, guarda de exclusão, ADD/ALTER COLUMN, bloqueio de rollback incompatível, PK composta, tabela sem PK, DROP seguro, evidências HTTP e paginação. O teste SQL Server desabilita SNAPSHOT na fixture para exercitar o fallback SERIALIZABLE sem permissão administrativa no produtor. Os recursos e volumes criados pelo teste são removidos ao terminar.

O teste de retenção usa test_retention_live.py, test_retention_kafka_live.py e test_retention_monitor_live.py: verifica sete dias, alteração para trinta dias no PostgreSQL e quatorze no tópico existente, registros recentes/últimos preservados, antigos elegíveis removidos, pendências e migrações preservadas, checkpoints/gerações/journals intactos, agenda persistida após recriações, dry-run, idempotência, consumer após DeleteRecords, ausência de recópia de detalhes expirados e bootstrap/incremental/rollback/DDL depois da manutenção. Aguarda estabilização do grupo entre recriações para não confundir rebalanceamento com falha de promoção. As fixtures SQL locais do primeiro módulo são desfeitas por rollback; os tópicos e grupos sintéticos são exclusivos da stack descartável.

Validação executada em 22/10/2026: verificações offline listadas acima aprovadas, incluindo cinco testes unitários de retenção (com contagem preservada após falha parcial e sem contar uma transação que falhou no commit); e2e_retention.sh aprovado com PostgreSQL/Kafka reais; e2e_discovery.sh aprovado para PostgreSQL e SQL Server. A primeira tentativa da integração de retenção excedeu o timeout durante rebalanceamentos após duas recriações; o teste passou ao aguardar o grupo estável, sem mudar a reconciliação. O Compose foi aplicado ao laboratório, com init finalizado, painel operational, lag zero, driver local efetivamente em 20m/5 e sem novos arquivos em /opt/kafka/logs após configurar stdout. O dry-run no laboratório retornou zero elegíveis e nenhum erro; a remoção efetiva de dados antigos foi comprovada nas fixtures isoladas.

Não foram aguardados sete dias de relógio: os testes usam datas SQL e mensagens sintéticas antigas em tópico exclusivo para verificar o corte temporal. Não foram medidos liberação física de disco após sete dias, carga de produção ou enormes acúmulos históricos. Os experimentos legados e2e_schema.sh/e2e.sh e o teste visual Playwright não foram repetidos nesta alteração; a integração atual, os testes offline de linhagem/DDL e as fixtures de estados pendentes cobrem os caminhos exercitados, sem equivaler a uma nova homologação desses experimentos.

Para conferir promoção idempotente, limpeza de lotes abortados e distinção entre SELECT negado e catálogo ausente no armazenamento local, execute docker compose exec -T -e LAB_DISCOVERY_STORE_TEST=1 consumer python - < tests/test_discovery_store_live.py. Esse teste cria objetos dentro de uma transação e desfaz tudo com ROLLBACK; não acessa a origem.

Para validar a separação do monitor, execute LAB_MONITOR_STORAGE_TEST=1 bash tests/e2e_monitor_storage.sh. O teste usa um projeto Docker descartável sem portas publicadas, verifica permissões, histórico completo, DDL em modal, publicação atômica e alertas de coleta. Também desliga o banco do monitor, confirma que a replicação continua e verifica a recuperação. Os containers e volumes de teste são removidos ao terminar.

Com o monitor inicializado e Playwright instalado no ambiente de testes, LAB_MONITOR_BROWSER_TEST=1 node tests/e2e_monitor_modals.cjs verifica os modais no navegador: teclado, foco, DDL histórico, navegação de volta, pausa da atualização, paginação e layout móvel. LAB_MONITOR_URL permite escolher outra instância; PLAYWRIGHT_CHROMIUM_EXECUTABLE permite indicar o navegador instalado.

Os demais scripts tests/e2e_*.sh mantêm experimentos específicos do fluxo legado. Leia a condição de ativação de cada script antes de executá-lo. tests/e2e_startup.sh verifica a compatibilidade da inicialização antiga; tests/e2e_discovery.sh verifica o caminho padrão atual.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages