DynoTable
Intermedio7 min de lectura

Cómo conectar a DynamoDB Local y LocalStack

Tienes un DynamoDB local en ejecución y tu código habla con él sin problemas — pero quieres ver las tablas, no escribir un script de scan cada vez. Conectar un cliente a un endpoint local son dos cambios: apuntar a la URL correcta y darle credenciales desechables. Los detalles de más abajo son donde la gente se atasca — el namespacing por región, la regla de claves alfanuméricas y la división de puertos 8000 frente a 4566.

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

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

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

La configuración de endpoint + credenciales ficticias que hace tropezar a todos

Los SDK y la CLI de AWS requieren una clave de acceso y una región incluso al hablar con un endpoint local — pero esos valores no tienen por qué ser reales. La propia documentación de AWS dice que esos valores «no tienen por qué ser valores válidos de AWS para ejecutarse localmente» (documentación de AWS).

Dos detalles que no son obvios:

  • La región/clave de acceso namespacea tus datos en silencio. Sin el flag -sharedDb, DynamoDB Local escribe un archivo myaccesskeyid_region.db separado por cada combinación de ID de clave de acceso + región — la nomenclatura exacta de AWS. Conéctate con una clave o región diferente de la que usó tu aplicación y tus tablas parecerán haberse esfumado; solo están en otro archivo. Ejecuta con -sharedDb (un shared-local-instance.db para cada cliente) o haz coincidir exactamente la clave + región que usa tu aplicación.
  • El ID de la clave de acceso debe ser alfanumérico en DynamoDB Local — sin símbolos. La documentación de AWS indica 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 de más abajo.

Para LocalStack el valor por defecto seguro es test / test: ignora la clave secreta por completo y nunca valida el valor secreto. Las claves de aspecto real AKIA…/ASIA… son rechazadas como salvaguarda y caen a la cuenta ficticia 000000000000 — la misma cuenta a la que resuelve una clave arbitraria como test. Quédate con test.

Conectar con la AWS CLI (comprobación rápida)

Antes de apuntar una GUI a él, confirma que el endpoint está vivo desde la CLI. La CLI no puede usar por defecto un endpoint local, así que pasas --endpoint-url en cada comando.

DynamoDB Local:

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

LocalStack (mismo comando, puerto diferente):

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

Si tienes credenciales configuradas en absoluto (incluso 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 diferente — mira el detalle de arriba.

GUI para 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 ficticias cualesquiera. 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 establece un endpoint personalizado:

  • Endpoint: http://localhost:8000 (DynamoDB Local) o http://localhost:4566 (LocalStack)
  • Región: la que use tu aplicación — p. ej. us-east-1. Aquí es una etiqueta, no una región real de AWS, pero debe coincidir para que aterrices en el mismo namespace de datos.
  • Clave de acceso / secreto: cualquier cosa (test / test es lo convencional). Solo alfanumérico para la clave de acceso en DynamoDB Local.

Desde ahí exploras Items, ejecutas un Query o un Scan y editas filas visualmente en lugar de hacer el marshalling del JSON a mano en la CLI. Cuando cargas fixtures, el conversor de DynamoDB-JSON convierte JSON plano en el formato del cable, y Query frente a Scan cubre qué lectura elegir. El mismo procedimiento para un visor de 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 una visión más amplia del panorama de GUI, mira la comparativa de GUI para DynamoDB.

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

  • Conexión rechazada. Puerto equivocado — 8000 es DynamoDB Local, 4566 es LocalStack. Confirma también que el contenedor realmente publicó el puerto (docker run -p 8000:8000 amazon/dynamodb-local). Para LocalStack, comprueba que el servicio está arriba 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 ID de la clave de acceso 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 herramienta 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 cliente del SDK dejó caer el --endpoint-url / endpoint_url y golpeó el endpoint real de AWS, que rechaza tu clave ficticia. Confirma que el cliente realmente apunta a http://localhost:4566.
  • Errores de credenciales del SDK/CLI. Incluso los endpoints locales necesitan alguna credencial presente. Establece AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (o un perfil falso) para que la cadena de credenciales del SDK resuelva.
  • http frente a https. Los endpoints locales son http plano. Una URL https:// fallará el handshake TLS.

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

No — local y nube son almacenes completamente separados. DynamoDB Local (y el DynamoDB de LocalStack) mantiene los datos en un archivo local o en memoria; nunca toca tu cuenta de AWS, y las regiones/cuentas de AWS no se soportan a nivel de cliente localmente. Ese es el objetivo: es para desarrollo y pruebas. Si quieres los mismos fixtures en la nube después, AWS sugiere valores de clave/región de aspecto válido localmente para que solo intercambies el endpoint cuando migres. Para modelar ese esquema antes de distribuirlo, diseño de tabla única y GSI frente a LSI cubren las decisiones que no cambian entre local y producción.

Preguntas frecuentes

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

¿Por qué desaparecen mis tablas cuando cambio de herramienta? Sin -sharedDb, DynamoDB Local particiona los datos por clave de acceso + 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 el 4566? 8000 es el predeterminado de DynamoDB Local independiente; 4566 es el único puerto edge de LocalStack que fronta todos sus servicios emulados, DynamoDB incluido.

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

¿Es DynamoDB Local gratuito? Sí. AWS distribuye DynamoDB Local sin coste como un JAR y una imagen Docker — no hay «costes de rendimiento aprovisionado, almacenamiento de datos ni transferencia de datos»; está destinado solo a desarrollo y pruebas, no a producción.

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

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

Actualizado