Cómo ejecutar DynamoDB local con Docker: guía completa

DynamoDB Local es la emulación descargable de AWS de DynamoDB en un solo proceso. misma API, sin cuenta AWS, sin red, sin factura por solicitud. Úselo para desarrollo local y pruebas de integración, luego apunte el mismo código a la nube en producción. Ignora el rendimiento aprovisionado y nunca aplica throttling, por lo que no puede sustituir a las pruebas de carga o de límites.

¿Cómo ejecuto DynamoDB Local con Docker?

Ejecute docker run -p 8000:8000 amazon/dynamodb-local para iniciar la imagen oficial, lo que expone el motor DynamoDB en http://localhost:8000. Apunta tu AWS SDK o CLI en ese endpoint con cualquier credencial ficticia, luego cree tablas y ejecute solicitudes exactamente como lo haría contra la nube. Agregue -sharedDb y un montado -dbPath volumen para conservar los datos durante los reinicios.

Iniciar el contenedor

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

Eso expone el motor en http://localhost:8000.

docker-compose

La mayoría de los proyectos lo fijan en docker-compose.yml para que todo el equipo obtenga el mismo endpoint:

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:

La imagen se ejecuta como usuario no root dynamodblocal, que no puede abrir una archivo de base de datos dentro del volumen con nombre de propiedad raíz, sin user: root presionas SQLiteException [14] unable to open database file y todas las llamadas se cuelgan.

Persistencia

De forma predeterminada, DynamoDB Local está en memoria: todas las tablas desaparecen cuando el contenedor se detiene. Dos banderas lo hacen duradero:

• -sharedDb mantiene todos los clients en un archivo de base de datos compartido (sin él, cada conjunto de credenciales/región obtiene su propia base de datos aislada: un mensaje común de "¿dónde está mi tabla go?" sorpresa).
• -dbPath /data + un volumen montado escribe ese archivo en el disco, por lo que los datos sobrevive docker compose down.

Apunta el SDK hacia él

Solo cambia el endpoint; las credenciales pueden ser cualquier valor ficticio:

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

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

Crea una tabla

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

Un schema PK/SK de tabla única como este es un buen valor predeterminado. Cuando cargue fixtures, convierta JSON al formato de cable con el DynamoDB-JSON convertidor.

Verifique que el contenedor esté arriba y la mesa aterrizó:

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

Explorarlo con una GUI

CLI las llamadas se vuelven tediosas rápidamente. Las opciones habituales son el código abierto dynamodb-admin interfaz de usuario web o un client de escritorio. DynoTable se conecta directamente a localhost:8000 (o a cualquier endpoint de LocalStack — vea conectarse a DynamoDB Local y LocalStack) y le permite navegar, hacer query con el SQL Workbench y editar tablas locales con la misma interfaz que usa para las tablas en la nube: sin viajes de ida y vuelta por el CLI de aws.

Lo que Local no emula

Trate a Local como una capa de compatibilidad API, no como un simulador de capacidad. se ignora rendimiento aprovisionado, nunca regresa ProvisionedThroughputExceededException, y no modela el comportamiento de ráfagas bajo demanda. Una prueba de carga contra Local te lo dice nada sobre límites de partición o capacidad adaptativa en AWS.

Otras lagunas aparecen en las pruebas de integración si no las planifica:

Si su prueba afirma throttling, expiración de TTL en segundos o distribución en abanico de streams, ejecute al menos una suite en una tabla de nube desechable o LocalStack con el funciones que necesita habilitadas.

Un flujo de trabajo local práctico

La mayoría de los equipos conectan el local en tres capas:

1. Pruebas unitarias: girar el contenedor en CI, crear tablas en beforeAll, arrancar abajo en afterAll. Mantenga los accesorios pequeños; llanura mariscal JSON a través de la DynamoDB JSON convertidor cuando las pruebas se pegan mapas de atributos a mano.
2. Pruebas de integración: utilice la misma fábrica de SDK client que utiliza su aplicación. intercambiando solo endpoint y credenciales. Afirmar la forma del artículo y escrituras condicionales, no en capacidad consumida (Lo local no devuelve significativo ConsumedCapacity para la elaboración de presupuestos).
3. Exploración manual: conecta DynoTable con un perfil local, ediciones de escenario, y ejecute PartiQL o consultas de condición clave antes de implementar schema cambios.

Cuando se le queda pequeño un solo proceso: múltiples servicios, S3 activadores o IAM enrutamiento: pasar a LocalStack o un cuenta de desarrollador. Local sigue siendo el bucle más rápido para "¿se compila mi patrón de acceso?"

Datos de semillas sin clasificación manual

Cargar diez elementos de dispositivo desde un archivo JSON es más rápido cuando no etiqueta cada valórate a ti mismo. Pegue la matriz en el DynamoDB JSON convertidor, copia el marshalled salida y escritura por lotes con BatchWriteItem contra --endpoint-url http://localhost:8000. Para accesorios que requieren muchas actualizaciones, ensamble el UpdateExpression en el DynamoDB generador de expresiones y pegue el mapas de atributos generados en su arnés de pruebas.

El editor de elementos de DynoTable realiza la misma clasificación al confirmar, lo que resulta útil cuando el fracaso de la prueba te deja mirando {"S":...} manchas sin procesar en el CLI.

Cuándo salir del local

Realice envíos a una mesa real cuando necesite medir cualquiera de los siguientes parámetros en AWS:

• Planificación de capacidad: un elemento de 1 KB consultado 1000 veces por segundo consume aproximadamente 250 RCU eventualmente consistentes por segundo en facturación bajo demanda; locales reporta cero. Modele eso con el calculadora de precios usando tamaños de la calculadora de tamaño de artículo.
• Retraso en la propagación del índice: GSI lecturas eventualmente son consistentes en producción; Local devuelve filas de índice lo suficientemente rápido como para que los errores de lectura obsoletos se oculten hasta su implementación.
• Cuenta cruzada IAM: las funciones y claves de condición con alcance de recursos solo existen en la nube.

Mantenga Local para obtener comentarios rápidos sobre schema y la sintaxis de expresiones; validar el costo y supuestos de coherencia frente a una tabla de preparación antes del tráfico de producción.

Errores que vale la pena solucionar

• Olvidar -sharedDb: cada par de credenciales único obtiene un aislamiento base de datos; CI y su computadora portátil parecen universos diferentes.
• Volumen de propiedad raíz sin user: root: el backend SQLite falla silenciosamente hasta que agregue la anulación de compose de la sección anterior.
• Suponiendo Streams paridad: los Lambdas habilitados para transmisión necesitan una nube o LocalStack objetivo; Los locales por sí solos no ejercerán la distribución en abanico.
• Claves de cadena vacía: permitidas en atributos que no son clave desde 2020, aún rechazadas en llaves; valida los aparatos de la misma manera que lo harías en AWS.

Descargar DynoTable, agregar un perfil apuntado a http://localhost:8000, y explore las tablas que acaba de crear: la misma cuadrícula, generador de filtros y SQL Workbench que utilizas en producción, sin gastar AWS en el ciclo.