Change Data Capture

Faça streaming de mudanças em nível de linha a partir de um banco de dados. Uma fonte CDC captura inserções, atualizações e exclusões, opcionalmente entrega antes a cada assinante um snapshot consistente das linhas existentes, e entrega tudo como eventos de mudança neutros em relação ao driver. As fontes são endereçáveis pelo seu ID de entrada e consumidas a partir de Lua via o módulo cdc.

Tipos de Entradas

Ambos os tipos expõem a mesma API Lua, o mesmo registro de informações da fonte e o mesmo formato de evento de mudança. O que difere é o conjunto de garantias, publicado por fonte como capacidades.

Configuração do Postgres

- name: pg_cdc
  kind: db.cdc.postgres
  host: ${env:DB_HOST}
  port: 5432
  database: app
  username: ${env:DB_USER}
  password: ${env:app.secrets:db_password}
  slot_name: wippy_slot
  publication: wippy_pub
  tables:
    - public.users
    - public.orders
  snapshot: true
  streaming: true
  standby_interval: "10s"
  status_interval: "10s"
  lifecycle:
    auto_start: true

Zero em qualquer campo max_* seleciona o padrão; o decodificador nunca é ilimitado. Valores negativos são rejeitados.

As credenciais resolvem os placeholders ${env:NAME} através do registro de ambiente no momento da decodificação.

Configuração do SQLite

Uma fonte SQLite não abre seu próprio banco de dados. Ela toma emprestado um recurso db.sql.sqlite existente e assina o observador de mutações confirmadas desse recurso, capturando assim exatamente as escritas feitas através daquele recurso SQL do Wippy — escritas por outro processo, outra conexão ou uma ferramenta externa não são observadas.

- name: cdcdb
  kind: db.sql.sqlite
  file: /var/data/app.db
  lifecycle:
    auto_start: true

- name: changes
  kind: db.cdc.sqlite
  db_resource: app:cdcdb
  tables:
    - users
    - orders
  snapshot: true
  status_interval: "30s"
  lifecycle:
    auto_start: true

A fonte declara o recurso SQL como um requisito de ciclo de vida, então o supervisor inicia o banco de dados primeiro e reinicia a fonte quando a geração do banco de dados é substituída.

Limites de Assinatura

Cada fonte admite um número limitado de assinantes e reserva antecipadamente o backlog de pior caso deles. Um slot de snapshot permanece reservado até que o stream com snapshot habilitado seja fechado.

subscriptions:
  max_subscriptions: 1024
  max_snapshot_subscriptions: 4
  max_bytes: 268435456

Zero seleciona o padrão; valores negativos são rejeitados. Esgotar um limite faz a assinatura falhar com um errors.UNAVAILABLE passível de nova tentativa.

Como Funciona

1. Uma fonte Postgres conecta-se como usuário de replicação e cria (ou retoma) o slot nomeado por slot_name. Uma fonte SQLite toma emprestado seu db_resource e assina o observador de mutações confirmadas desse recurso.
2. Mudanças de linha são decodificadas em eventos de mudança neutros em relação ao driver, com op igual a insert, update, delete ou truncate.
3. Um assinante cujo stream tem snapshot habilitado — pelo campo snapshot da entrada ou por opts.snapshot no stream — recebe primeiro as linhas existentes como eventos com op = "snapshot", e então continua nas mudanças ao vivo sem lacuna entre os dois.
4. Uma fonte Postgres reconhece periodicamente o LSN para que o servidor possa liberar segmentos do WAL (standby_interval).
5. A fonte é registrada sob seu ID de entrada; o código Lua assina com cdc.stream.

Capacidades

Toda fonte publica o que ela garante, de modo que os consumidores ramificam sobre capacidades em vez do tipo da entrada.

As flags de capacidade descrevem o progresso da fonte, não a entrega durável: nenhum driver reproduz eventos para um assinante individual que ficou para trás ou se desconectou.

Informações da Fonte

Cada fonte é descrita por um registro de informações, retornado por cdc.source e cdc.list_sources.

admission conta reservas, não preenchimento de fila: active é a contagem de assinaturas admitidas, snapshots o subconjunto com snapshot habilitado, reserved_bytes o orçamento de backlog reservado e rejected o número acumulado de assinaturas recusadas pelos limites.

Permissões

A autoridade de CDC é separada do acesso ao banco de dados: uma fonte pode expor cada linha capturada, incluindo as imagens anteriores. Filtros de stream apenas restringem a entrega; eles nunca concedem acesso a uma fonte.

- name: cdc_reader
  kind: security.policy
  policy:
    effect: allow
    actions: [cdc.source, cdc.subscribe]
    resources: [app:changes]

Veja Também

• Módulo CDC - API de streaming em Lua
• Banco de Dados - Serviços de banco de dados SQL
• Ambiente - Resolução de credenciais via ${env:NAME}
• Segurança - Políticas e ações