DynamoDB Streams: o guia completo (com exemplos)

O DynamoDB Streams é um log de change-data-capture: toda inserção, atualização e exclusão em uma tabela é capturada, em ordem, como um fluxo de registros aos quais você pode reagir. É como você transforma uma tabela em uma fonte de eventos sem fazer polling.

No cenário do log de auditoria você quer reagir no instante em que um evento sensível chega — disparar um alerta quando alguém exporta uma fatura ou concede um papel de admin — sem varrer a tabela num timer. O Streams é o lado de push disso.

Como funciona o DynamoDB Streams?

O DynamoDB Streams captura toda inserção, atualização e exclusão em uma tabela como um log de registros ordenado no tempo e deduplicado, retido por até 24 horas. Você escolhe o que cada registro carrega com StreamViewType (chaves, nova imagem, imagem antiga, ou ambas), depois consome o stream com um trigger Lambda para reagir a mudanças de item sem fazer polling.

• O Streams captura mudanças em nível de item como um log ordenado no tempo e deduplicado, retido por até 24 horas.
• Você escolhe o que cada registro carrega via StreamViewType: apenas chaves, a nova imagem, a imagem antiga, ou ambas antiga e nova.
• Os registros são ordenados por item — mudanças em um item chegam na ordem em que foram escritas — e um stream é dividido em shards da mesma forma que a tabela é.
• O consumidor nativo é o Lambda — um trigger que roda por lote de novos registros, com o Kinesis Data Streams como alternativa para fan-out mais rico.

O problema: reagir sem polling

Você precisa de "me alerte quando um evento role.granted for escrito." A abordagem ingênua é um job agendado que varre por novos eventos a cada minuto — o que lê a partição recente inteira toda vez, custa capacidade, e está sempre pelo menos um minuto atrasado.

O que você de fato quer é um push: o DynamoDB te avisa no momento em que um item muda. É exatamente isso que o Streams fornece, com o registro de mudança entregue ao seu código em vez de você caçando por ele.

Como o Streams funciona

Segundo os docs da AWS, o DynamoDB Streams mantém um log deduplicado e ordenado no tempo de mudanças por até 24 horas, com integração nativa com o Lambda (change data capture para DynamoDB). Cada registro descreve uma modificação em nível de item.

Quando você habilita um stream você escolhe um StreamViewType, que controla quanto do item alterado cada registro carrega:

Os registros são ordenados por item — mudanças em um único item aparecem na ordem em que foram escritas — e o stream é dividido em shards ao longo da mesma estrutura de partição da tabela. A retenção é de 24 horas — o Streams é um buffer de reação, não um histórico permanente. Para histórico durável você armazena os eventos em si (que é exatamente o que nossa tabela de log de auditoria já é).

O consumidor nativo é um trigger Lambda: o DynamoDB invoca sua função com um lote de novos registros de stream conforme eles chegam.

Um exemplo trabalhado: alertar em eventos de auditoria sensíveis

A tabela de log de auditoria ganha um stream com NEW_IMAGE, então cada registro carrega o novo evento completo. Um Lambda consome o lote e encaminha apenas os registros que importam:

A função nunca toca a tabela — ela reage puramente ao que o stream lhe entrega. Sem polling, sem scan, e o alerta dispara em segundos após a escrita. Os registros de stream são ordenados por item, então mudanças sucessivas no mesmo item de evento chegam na ordem em que foram escritas.

Esta é também a forma padrão de manter uma cópia downstream: um consumidor de stream pode projetar cada evento no OpenSearch para busca de auditoria de texto completo, ou agregar contagens — tudo derivado do mesmo log de mudanças.

Faça isso no DynoTable

Antes de você conectar um consumidor de stream, você precisa conhecer a forma exata do item que seu Lambda receberá — quais atributos existem, como maps e lists aninhados parecem, o que um registro NEW_IMAGE de fato conterá.

Para converter um item de exemplo entre JSON simples e a forma de attribute-value que um registro de stream usa, o Conversor de JSON do DynamoDB faz isso no seu navegador. E no DynoTable, você pode inspecionar o item completo — incluindo sua forma DynamoDB-JSON — para modelar o registro NEW_IMAGE contra dados reais em vez de adivinhar a forma dos campos.

Se você está testando um consumidor localmente, execute a tabela contra o DynamoDB Local e inspecione-a da mesma forma — veja conectar ao DynamoDB Local.

Armadilhas e próximos passos

• 24 horas não é um backlog. Se seu consumidor ficar fora do ar por um dia, os registros expiram e somem. O Streams é para reação em quase tempo real, não replay durável — mantenha os eventos em si para histórico.
• Escolha o menor StreamViewType de que você precisa. NEW_AND_OLD_IMAGES dobra o payload; se você só precisa da chave para reler o item, KEYS_ONLY é mais barato.
• A ordenação é por item, não por chave de partição ou global. O DynamoDB garante ordem apenas para mudanças sucessivas no mesmo item; não há garantia de ordenação entre itens diferentes, mesmo dentro de uma chave de partição.
• Exclusões por TTL aparecem como registros de stream com o marcador de system-attribute, que é como você arquiva itens que expiram — veja DynamoDB TTL.

O Streams transforma o log de auditoria em uma fonte de eventos. A próxima preocupação operacional é a ponta oposta da vida de um item — expirar eventos antigos automaticamente com DynamoDB TTL.

Baixe o DynoTable para inspecionar a forma exata do item que seu consumidor de stream receberá antes de você escrever uma linha de código Lambda.