Como executar DynamoDB local com Docker – Guia completo

DynamoDB Local é a emulação de DynamoDB para download do AWS em um único processo - mesmo API, sem conta AWS, sem rede, sem fatura por solicitação. Use-o para locais testes de desenvolvimento e integração e, em seguida, aponte o mesmo código para a nuvem em produção. Ele ignora a taxa de transferência provisionada e nunca limita, portanto não pode substituir testes de carga ou limite.

Como executo o DynamoDB Local com Docker?

Execute docker run -p 8000:8000 amazon/dynamodb-local para iniciar a imagem oficial, que expõe o mecanismo DynamoDB no http://localhost:8000. Aponte seu SDK AWS ou CLI nesse endpoint com quaisquer credenciais fictícias, crie tabelas e execute solicitações exatamente como faria na nuvem. Adicione -sharedDb e um montado Volume -dbPath para manter os dados durante as reinicializações.

Inicie o contêiner

docker run -p 8000:8000 amazon/dynamodb-local

Isso expõe o motor no http://localhost:8000.

docker-compose

A maioria dos projetos fixa-o no docker-compose.yml para que toda a equipe obtenha o mesmo ponto final:

services:
  dynamodb:
    image: amazon/dynamodb-local
    user: root
    command: '-jar DynamoDBLocal.jar -sharedDb -dbPath /data'
    ports:
      - '8000:8000'
    volumes:
      - dynamodb-data:/data
volumes:
  dynamodb-data:

A imagem é executada como o usuário dynamodblocal não root, que não pode abrir um arquivo de banco de dados dentro do volume nomeado de propriedade da raiz - sem user: root você acessa SQLiteException [14] unable to open database file e todas as chamadas são interrompidas.

Persistência

Por padrão, o DynamoDB Local está na memória — todas as tabelas desaparecem quando o o contêiner para. Duas bandeiras o tornam durável:

• -sharedDb mantém todos os clientes em um arquivo de banco de dados compartilhado (sem ele, cada conjunto de credenciais/region obtém seu próprio banco de dados isolado - um comum "onde foi meu mesa vai?" surpresa).
• -dbPath /data + um volume montado grava esse arquivo no disco, então os dados sobrevive ao docker compose down.

Aponte o SDK para ele

Somente o endpoint muda — as credenciais podem ser quaisquer valores fictícios:

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({
  endpoint: 'http://localhost:8000',
  region: 'local',
  credentials: {accessKeyId: 'x', secretAccessKey: 'x'}
});

Crie uma tabela

aws dynamodb create-table \
  --endpoint-url http://localhost:8000 \
  --table-name AppData \
  --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
  --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

Um esquema PK/SK tabela única como este é um bom padrão. Ao carregar equipamentos, converta JSON simples para o formato de fio com o Conversor DynamoDB-JSON.

Verifique se o contêiner está aberto e a mesa pousou:

aws dynamodb list-tables --endpoint-url http://localhost:8000

Navegue com uma GUI

As chamadas CLI ficam entediantes rapidamente. As opções usuais são o dynamodb-admin de código aberto UI da web ou um cliente de desktop. DynoTable conecta-se diretamente ao localhost:8000 (ou qualquer endpoint LocalStack - consulte conectando ao DynamoDB Local e LocalStack) e permite navegar, consultar com o SQL Workbench e editar tabelas locais com o a mesma UI que você usa para tabelas na nuvem — sem viagens de ida e volta da CLI do aws.

O que o Local não emula

Trate o Local como uma camada de compatibilidade API, não como um simulador de capacidade. Ele ignora taxa de transferência provisionada, nunca retorna ProvisionedThroughputExceededException, e não modela o comportamento de burst on-demand. Um teste de carga no Local informa nada sobre limites de partição ou capacidade adaptativa no AWS.

Outras lacunas aparecem nos testes de integração se você não planejá-las:

Se o seu teste indicar limitação, expiração do TTL em segundos ou distribuição de fluxo, execute pelo menos um conjunto em uma tabela de nuvem descartável ou LocalStack com o recursos que você precisa ativar.

Um fluxo de trabalho local prático

A maioria das equipes conecta o Local em três camadas:

1. Testes de unidade — gire o contêiner no CI, crie tabelas no beforeAll, rasgue para baixo em afterAll. Mantenha os acessórios pequenos; marechal plain JSON através do Conversor DynamoDB JSON quando os testes são colados mapas de atributos manualmente.
2. Testes de integração — exercite a mesma fábrica de cliente SDK que seu aplicativo usa, trocando apenas endpoint e credenciais. Afirme a forma do item e escritas condicionais, não na capacidade consumida (Local não retorna ConsumedCapacity significativo para orçamento).
3. Exploração manual — conecte DynoTable com um perfil local, edições de estágio, e execute consultas PartiQL ou de condição-chave antes de implantar alterações de esquema.

Quando você supera um único processo – vários serviços, gatilhos S3 ou estilo IAM roteamento - mude para LocalStack ou um conta de desenvolvedor. Local continua sendo o loop mais rápido para "meu padrão de acesso é compilado?"

Dados iniciais sem triagem manual

Carregar dez itens de fixture de um arquivo JSON é mais rápido quando você não marca todos valorize a si mesmo. Cole a matriz no Conversor DynamoDB JSON, copie o empacotado saída e gravação em lote com BatchWriteItem em --endpoint-url http://localhost:8000. Para equipamentos com muitas atualizações, monte o UpdateExpression no Construtor de expressão DynamoDB e cole o mapas de atributos gerados em seu equipamento de teste.

O editor de itens do DynoTable executa o mesmo empacotamento no commit - útil quando um a falha no teste deixa você olhando para blobs {"S":...} brutos na CLI.

Quando sair do local

Envie para uma tabela real quando precisar de qualquer um dos seguintes itens medidos na própria AWS:

• Planejamento de capacidade — um item de 1 KB consultado 1.000 vezes por segundo consome cerca de 250 RCU eventualmente consistentes por segundo no faturamento on-demand; locais reporta zero. Modele isso com o calculadora de preços usando tamanhos do calculadora de tamanho de item.
• Atraso na propagação do índice — As leituras do GSI são eventualmente consistentes na produção; Local retorna linhas de índice com rapidez suficiente para que bugs de leitura obsoleta se escondam até a implantação.
• IAM entre contas — funções com escopo de recurso e chaves de condição só existem em a nuvem.

Mantenha o Local para feedback rápido sobre sintaxe de esquema e expressão; valide custo e suposições de consistência em relação a uma tabela intermediária antes do tráfego de produção.

Armadilhas que valem a pena criar scripts

• -sharedDb esquecido — cada par de credenciais exclusivo recebe um banco de dados isolado; CI e seu laptop parecem universos diferentes.
• Volume de propriedade raiz sem user: root — o back-end do SQLite falha silenciosamente até você adicionar a substituição de composição da seção acima.
• Assumindo paridade de Streams — Lambdas habilitados para stream precisam de uma nuvem ou LocalStack alvo; O local por si só não exercerá o fan-out.
• Chaves de string vazia — permitidas em atributos não-chave desde 2020, ainda rejeitadas nas chaves; valide os fixtures da mesma forma que você faria no AWS.

Baixe DynoTable, adicione um perfil apontado para http://localhost:8000, e navegue nas tabelas que você acabou de criar - a mesma grade, construtor de filtro e SQL Ambiente de trabalho que você usa na produção, com zero gasto de AWS no loop.