Dá para rodar o DynamoDB localmente?

Sim. A AWS distribui o DynamoDB Local, uma versão gratuita e baixável do DynamoDB que roda na sua própria máquina como uma imagem Docker, um executável Java ou uma dependência do Apache Maven. Ele expõe a mesma API do serviço web, então você consegue desenvolver e testar offline e depois simplesmente apontar seu código para a AWS.

Três formas de rodá-lo

Imagem Docker — a escolha mais comum: um docker run e o endpoint está no ar em uma porta local.
Arquivo baixável — uma aplicação Java que você inicia diretamente (requer um JRE).
Dependência do Apache Maven — incorpore-o em suítes de teste na JVM.

Por que desenvolver localmente

O banco de dados fica autocontido no seu computador, então você economiza em taxas de throughput, armazenamento e transferência de dados — e não precisa de conexão com a internet enquanto desenvolve. Quando estiver pronto para publicar, você remove o endpoint local do código e ele passa a apontar para o serviço web do DynamoDB.

Atenção às diferenças

O DynamoDB Local emula a API, mas não é o motor de produção — a AWS documenta diferenças de comportamento nas notas de uso dele (o throughput não é aplicado, por exemplo). Trate-o como um dublê funcional de dev/teste, não como um modelo de desempenho.

Três divergências que medimos

Mantemos um contêiner do DynamoDB Local rodando para reproduzir os erros citados nas nossas páginas de erro, o que significa que batemos nos limites dele com frequência. Três valem a pena conhecer antes de você confiar em um teste local verde.

O throughput provisionado não é aplicado de forma alguma. Criamos uma tabela com 1 RCU, colocamos um item de 3,5 KB e o lemos de volta com consistência forte em um loop com os retries do SDK desativados (maxAttempts: 1):

reads=5000 ok=5000 errors=0 elapsed=2.5s rate=1997/s

Cinco mil leituras, zero throttles, cerca de 2.000 unidades de leitura por segundo sustentadas contra uma tabela provisionada para uma. O mesmo loop contra o serviço ao vivo lança ProvisionedThroughputExceededException na leitura 49. Um bug de capacidade não tem como falhar localmente.

Um erro muda de nome. Rode o mesmo INSERT de PartiQL duas vezes e o DynamoDB Local responde DuplicateItem com a mensagem Duplicate primary key exists in table. O serviço responde DuplicateItemException com There was an attempt to insert an item with the same primary key as an item that already exists in the DynamoDB table. Um tratamento de erros que ramifica pelo nome passa localmente e erra em produção.

Algumas APIs simplesmente não existem. O ExportTableToPointInTime responde:

UnknownOperationException: An unknown operation was requested.

Esse não é o erro do serviço para a mesma chamada, então um caminho de código que se protege contra PointInTimeRecoveryUnavailableException também não pode ser exercitado localmente.

Aprofunde-se

O guia do DynamoDB Local percorre a configuração passo a passo, e o guia de conexão local & LocalStack mostra como apontar uma GUI para ele — o DynoTable conecta a endpoints locais exatamente como conecta à AWS. Teste sua primeira consulta com o construtor de expressões.

Referências

Verificado pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.

As três divergências foram reproduzidas em 2026-07-28 contra o DynamoDB Local 3.3.0 (amazon/dynamodb-local, Corretto 17.0.17) com @aws-sdk/client-dynamodb 3.1095.0 no Node v24.18.0. Cada linha de saída acima é a do próprio motor, sem edição.