DynoTable
Intermedio7 min de lectura

Cómo conectarse a DynamoDB Local y LocalStack

Tienes un DynamoDB local corriendo y tu código le habla bien — pero quieres ver las tablas, no escribir un script de scan cada vez. Conectar un client a un endpoint local son dos cambios: apuntar a la URL correcta y darle credenciales desechables. Los detalles de abajo son donde la gente se atasca — el namespace de región, la regla de clave alfanumérica y la división de puertos 8000 vs 4566.

DynamoDB Local vs LocalStack: a qué te estás conectando

Ambos te dan una API de DynamoDB en localhost sin una cuenta AWS, pero son cosas distintas:

Así que la única diferencia práctica para conectar es la URL del endpoint: :8000 para DynamoDB Local standalone, :4566 para DynamoDB-vía-LocalStack. Todo lo demás — la API, el truco de credenciales, la config de la GUI — es idéntico.

La setup de endpoint + credenciales dummy que tropieza a todo el mundo

Los SDKs y la CLI de AWS exigen una access key y una región incluso al hablar con un endpoint local — pero esos valores no tienen que ser reales. Los propios docs de AWS dicen que estos valores "don't have to be valid AWS values to run locally" (docs AWS).

Dos gotchas que no son obvios:

  • La región/access-key hace namespace de tus datos en silencio. Sin el flag -sharedDb, DynamoDB Local escribe un archivo myaccesskeyid_region.db separado por combinación de access-key-ID + región — el naming exacto de AWS. Conéctate con una clave o región distinta a la que usó tu app y tus tablas parecen haber desaparecido; solo están en otro archivo. Arranca con -sharedDb (un shared-local-instance.db para cada client) o iguala la clave + región exactas que usa tu app.
  • El access key ID debe ser alfanumérico en DynamoDB Local — sin símbolos. Los docs AWS dicen que AWS_ACCESS_KEY_ID solo puede contener A–Z, a–z y 0–9; AWS introdujo esto en DynamoDB Local 2.0.0 (y 1.23.0+), así que una clave con caracteres especiales que funcionaba en una imagen anterior ahora falla (AWS re:Post). Mira el error más abajo.

Para LocalStack el default seguro es test / test: ignora el secret key por completo y nunca valida el valor del secret. Claves con aspecto real AKIA…/ASIA… se rechazan como salvaguarda y caen al account dummy 000000000000 — el mismo account al que resuelve una clave arbitraria como test. Quédate con test.

Conectar con la AWS CLI (sanity check)

Antes de apuntar una GUI, confirma que el endpoint está vivo desde la CLI. La CLI no tiene un endpoint local por defecto, así que o pasas --endpoint-url por comando o pones AWS_ENDPOINT_URL_DYNAMODB=http://localhost:8000 (CLI v2.13+).

DynamoDB Local:

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

LocalStack (mismo comando, puerto distinto):

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

Si tienes credenciales configuradas (aunque sean falsas en ~/.aws/credentials o vía AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), esto devuelve tu lista de tablas. Una lista vacía sin error significa que el endpoint funciona pero estás mirando un namespace de clave/región distinto — mira el gotcha de arriba.

GUI de DynamoDB Local: explorar y consultar tablas locales en DynoTable

Una vez que la CLI funciona, una GUI necesita los mismos tres valores: endpoint, región, y unas credenciales dummy. La CLI devuelve DynamoDB-JSON que lees a ojo; una GUI renderiza los mismos datos como una tabla que puedes ordenar, filtrar y editar.

En DynoTable, añade una conexión y pon un endpoint custom:

  • Endpoint: http://localhost:8000 (DynamoDB Local) o http://localhost:4566 (LocalStack)
  • Región: la que use tu app — p. ej. us-east-1. Aquí es una etiqueta, no una región AWS real, pero debe coincidir para aterrizar en el mismo namespace de datos.
  • Access key / secret: lo que sea (test / test es lo convencional). Solo alfanumérico para la access key en DynamoDB Local.

Desde ahí exploras items, ejecutas un Query o un Scan, y editas filas visualmente en vez de JSON a mano en la CLI. Cuando cargas fixtures, el convertidor DynamoDB-JSON pasa JSON plano al formato wire, y Query vs Scan cubre a qué lectura ir. El mismo drill para un visor DynamoDB de LocalStack — solo cambia el puerto a 4566.

DynoTable es software de escritorio solo-local, así que apuntarlo a localhost mantiene tus fixtures en tu máquina. Para un vistazo más amplio a las opciones de GUI, mira la comparación de GUIs de DynamoDB.

Errores comunes (mismatch de región, puerto, credenciales)

  • Connection refused. Puerto equivocado — 8000 es DynamoDB Local, 4566 es LocalStack. Confirma también que el contenedor publicó el puerto de verdad (docker run -p 8000:8000 amazon/dynamodb-local). Para LocalStack, comprueba que el servicio está up en http://localhost:4566/_localstack/health.
  • The Access Key ID or Security Token is Invalid en DynamoDB Local. Desde la imagen 2.0.0 (y 1.23.0+), el access key ID debe ser solo alfanumérico. Una clave con símbolos que funcionaba en una imagen anterior ahora falla — reemplázala con letras/números (p. ej. test) y actualiza cada tool para que coincida.
  • The security token included in the request is invalid contra LocalStack. Esto es casi siempre un problema de endpoint, no de credenciales — tu client SDK dejó caer el --endpoint-url / endpoint_url y golpeó el endpoint real de AWS, que rechaza tu clave dummy. Confirma que el client apunta de verdad a http://localhost:4566.
  • Errores de credenciales del SDK/CLI. Incluso los endpoints locales necesitan alguna credencial presente. Pon AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (o un perfil falso) para que la credential chain del SDK resuelva.
  • http vs https. Los endpoints locales son http plano. Una URL https:// falla el handshake TLS.

¿Es DynamoDB Local los mismos datos que mis tablas AWS reales?

No — local y cloud son stores completamente separados. DynamoDB Local (y el DynamoDB de LocalStack) guarda datos en un archivo local o en memoria; nunca toca tu cuenta AWS, y las regiones/cuentas AWS no están soportadas a nivel de client en local. Ese es el punto: es para desarrollo y testing. Si quieres las mismas fixtures en la cloud más adelante, AWS sugiere valores de clave/región con aspecto válido en local para solo cambiar el endpoint al moverte. Para modelar ese schema antes de shippearlo, single-table design y GSI vs LSI cubren las decisiones que no cambian entre local y prod.

Lo que te ahorra lo local (y lo que prod sigue facturando)

DynamoDB Local no mide nada — sin RCU, sin WCU, sin transfer. El mismo GetItem contra DynamoDB managed en us-east-1 on-demand factura 0.5 RCU con consistencia eventual o 1 RCU con consistencia fuerte para un item ≤ 4 KB. Cuando cambias --endpoint-url por el endpoint real, cada browse y query vuelve a facturar. Modela el salto con la calculadora de pricing y dimensiona items representativos con la calculadora de tamaño de item.

FAQ

¿Necesito credenciales AWS reales? No. Tanto DynamoDB Local como LocalStack aceptan valores dummy. Solo tienen que estar presentes, ser alfanuméricos (para DynamoDB Local), y ser consistentes entre tus tools.

¿Por qué desaparecen mis tablas cuando cambio de tool? Sin -sharedDb, DynamoDB Local particiona los datos por access-key + región en archivos myaccesskeyid_region.db separados. Usa -sharedDb o mantén esos valores idénticos en todas partes.

¿Cuál es la diferencia entre el puerto 8000 y 4566? 8000 es el default de DynamoDB Local standalone; 4566 es el edge port único de LocalStack que frontea todos sus servicios emulados, DynamoDB incluido.

¿Puede una GUI conectarse a ambos? Sí — hablan la misma API de DynamoDB. Solo cambia la URL del endpoint (:8000 vs :4566).

¿Es gratis DynamoDB Local? Sí. AWS reparte DynamoDB Local sin coste como JAR y como imagen Docker — no hay "provisioned throughput, data storage, or data transfer costs"; está pensado solo para desarrollo y testing, no para producción.

¿Puedo ejecutar SQL contra mis tablas locales? El DynamoDB local habla la misma API que la cloud, así que aplican las mismas reglas de patrón de acceso — y los mismos límites: la gramática SELECT de PartiQL de DynamoDB es solo SELECT … FROM … WHERE … ORDER BY — sin JOIN, sin GROUP BY, y sin funciones de agregación de agrupación como COUNT/SUM/AVG (mira PartiQL vs SQL). El de DynoTable ejecuta esas queries analíticas sobre cualquier conexión, local incluido.

Prueba DynoTable para conectarte directo a localhost:8000 o localhost:4566 y explorar, consultar y editar tus tablas locales con una GUI.

Actualizado