DynoTable
Intermediário7 min de leitura

Como Conectar ao DynamoDB Local e ao LocalStack

Você tem um DynamoDB local rodando e seu código fala com ele sem problemas — mas você quer ver as tabelas, não escrever um script de scan toda vez. Conectar um cliente a um endpoint local são duas mudanças: apontar para a URL certa e passar para ele credenciais descartáveis. Os detalhes abaixo são onde as pessoas travam — namespacing por região, a regra de chave alfanumérica e a divisão de portas 8000 vs 4566.

DynamoDB Local vs LocalStack: ao que você está se conectando

Ambos te dão uma API do DynamoDB em localhost sem conta AWS, mas são coisas diferentes:

Então a única diferença prática para conectar é a URL do endpoint: :8000 para o DynamoDB Local autônomo, :4566 para o DynamoDB-via-LocalStack. Todo o resto — a API, o truque das credenciais, a configuração da GUI — é idêntico.

A configuração de endpoint + credenciais fictícias que confunde todo mundo

Os SDKs e a CLI da AWS exigem uma access key e uma região mesmo ao falar com um endpoint local — mas esses valores não precisam ser reais. As próprias docs da AWS dizem que esses valores "não precisam ser valores AWS válidos para rodar localmente" (docs da AWS).

Duas pegadinhas que não são óbvias:

  • A região/access-key faz namespacing silencioso dos seus dados. Sem a flag -sharedDb, o DynamoDB Local escreve um arquivo myaccesskeyid_region.db separado por combinação de access-key-ID + região — a nomenclatura exata da AWS. Conecte com uma chave ou região diferente da que seu app usou e suas tabelas parecem ter sumido; elas só estão em outro arquivo. Rode com -sharedDb (um único shared-local-instance.db para todos os clientes) ou use exatamente a mesma chave + região que seu app usa.
  • O access key ID precisa ser alfanumérico no DynamoDB Local — sem símbolos. As docs da AWS afirmam que AWS_ACCESS_KEY_ID só pode conter A–Z, a–z e 0–9; a AWS introduziu isso no DynamoDB Local 2.0.0 (e 1.23.0+), então uma chave com caracteres especiais que funcionava numa imagem anterior agora falha (AWS re:Post). Veja o erro abaixo.

Para o LocalStack o padrão seguro é test / test: ele ignora a secret key inteiramente e nunca valida o valor do secret. Chaves com cara real (AKIA…/ASIA…) são rejeitadas como salvaguarda e recaem na conta fictícia 000000000000 — a mesma conta para a qual uma chave arbitrária como test resolve. Fique com test.

Conectando com a AWS CLI (verificação de sanidade)

Antes de apontar uma GUI para ele, confirme pela CLI que o endpoint está ativo. A CLI não consegue usar um endpoint local por padrão, então você passa --endpoint-url em cada comando.

DynamoDB Local:

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

LocalStack (mesmo comando, porta diferente):

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

Se você tiver alguma credencial configurada (mesmo falsas em ~/.aws/credentials ou via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), isso retorna sua lista de tabelas. Uma lista vazia sem erro significa que o endpoint funciona, mas você está olhando para um namespace de chave/região diferente — veja a pegadinha acima.

GUI para DynamoDB Local: navegando e consultando tabelas locais no DynoTable

Uma vez que a CLI funcione, uma GUI precisa dos mesmos três valores: endpoint, região e quaisquer credenciais fictícias. A CLI retorna DynamoDB-JSON que você lê de olho; uma GUI renderiza os mesmos dados como uma tabela que você pode ordenar, filtrar e editar.

No DynoTable, adicione uma conexão e defina um endpoint personalizado:

  • Endpoint: http://localhost:8000 (DynamoDB Local) ou http://localhost:4566 (LocalStack)
  • Região: o que seu app usa — por exemplo us-east-1. Aqui é um rótulo, não uma região AWS real, mas precisa coincidir para você cair no mesmo namespace de dados.
  • Access key / secret: qualquer coisa (test / test é o convencional). Apenas alfanumérico para a access key no DynamoDB Local.

A partir daí você navega pelos itens, roda uma Query ou um Scan e edita linhas visualmente em vez de fazer marshalling de JSON à mão na CLI. Quando você carrega fixtures, o conversor de DynamoDB-JSON transforma JSON puro no formato de transporte, e Query vs Scan cobre qual leitura usar. Mesma rotina para um visualizador de DynamoDB do LocalStack — só a porta muda para 4566.

O DynoTable é software desktop apenas local, então apontá-lo para localhost mantém suas fixtures na sua máquina. Para uma visão mais ampla do cenário de GUIs, veja a comparação de GUIs para DynamoDB.

Erros comuns (incompatibilidade de região, porta, credenciais)

  • Connection refused. Porta errada — 8000 é DynamoDB Local, 4566 é LocalStack. Confirme também que o container realmente publicou a porta (docker run -p 8000:8000 amazon/dynamodb-local). Para o LocalStack, verifique se o serviço está no ar em http://localhost:4566/_localstack/health.
  • The Access Key ID or Security Token is Invalid no DynamoDB Local. Desde a imagem 2.0.0 (e 1.23.0+), o access key ID precisa ser apenas alfanumérico. Uma chave com símbolos que funcionava numa imagem anterior agora falha — substitua por letras/números (por exemplo test) e atualize toda ferramenta para coincidir.
  • The security token included in the request is invalid contra o LocalStack. Isso é quase sempre um problema de endpoint, não de credenciais — seu cliente SDK perdeu o --endpoint-url / endpoint_url e atingiu o endpoint real da AWS, que rejeita sua chave fictícia. Confirme que o cliente está de fato apontado para http://localhost:4566.
  • Erros de credencial do SDK/CLI. Mesmo endpoints locais precisam de alguma credencial presente. Defina AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (ou um profile falso) para que a cadeia de credenciais do SDK resolva.
  • http vs https. Endpoints locais são http puro. Uma URL https:// falhará no handshake TLS.

O DynamoDB Local tem os mesmos dados das minhas tabelas AWS reais?

Não — local e nuvem são stores completamente separados. O DynamoDB Local (e o DynamoDB do LocalStack) mantém os dados em um arquivo local ou em memória; ele nunca toca na sua conta AWS, e Regiões/contas AWS não são suportadas no nível do cliente localmente. Esse é o objetivo: é para desenvolvimento e testes. Se você quiser as mesmas fixtures na nuvem depois, a AWS sugere valores de chave/região com cara de válidos localmente, para que você só troque o endpoint ao migrar. Para modelar esse schema antes de colocá-lo no ar, single-table design e GSI vs LSI cobrem as decisões que não mudam entre local e produção.

FAQ

Preciso de credenciais AWS reais? Não. Tanto o DynamoDB Local quanto o LocalStack aceitam valores fictícios. Eles só precisam estar presentes, alfanuméricos (para o DynamoDB Local) e consistentes entre suas ferramentas.

Por que minhas tabelas somem quando troco de ferramenta? Sem -sharedDb, o DynamoDB Local particiona os dados por access-key + região em arquivos myaccesskeyid_region.db separados. Use -sharedDb ou mantenha esses valores idênticos em todo lugar.

Qual a diferença entre a porta 8000 e a 4566? 8000 é o padrão do DynamoDB Local autônomo; 4566 é a porta de borda única do LocalStack que fica na frente de todos os seus serviços emulados, DynamoDB incluído.

Uma GUI consegue conectar a ambos? Sim — eles falam a mesma API do DynamoDB. Só a URL do endpoint muda (:8000 vs :4566).

O DynamoDB Local é gratuito? Sim. A AWS distribui o DynamoDB Local sem custo como um JAR e uma imagem Docker — não há "custos de throughput provisionado, armazenamento de dados ou transferência de dados"; é destinado apenas a desenvolvimento e testes, não a produção.

Posso rodar SQL contra minhas tabelas locais? O DynamoDB local fala a mesma API que a nuvem, então as mesmas regras de padrão de acesso valem — e os mesmos limites: a gramática do SELECT do PartiQL do DynamoDB é apenas SELECT … FROM … WHERE … ORDER BY — sem JOIN, sem GROUP BY e sem funções de agregação como COUNT/SUM/AVG (veja PartiQL vs SQL). O SQL Workbench do DynoTable roda essas consultas analíticas sobre qualquer conexão, local incluído.

Experimente o DynoTable para conectar direto ao localhost:8000 ou localhost:4566 e navegar, consultar e editar suas tabelas locais com uma GUI.

Atualizado