Come eseguire DynamoDB Local con Docker: guida completa

DynamoDB Local è l'emulazione scaricabile di AWS di DynamoDB in un unico processo — stesso API, nessun account AWS, nessuna rete, nessuna fattura per richiesta. Usalo per il locale test di sviluppo e integrazione, quindi indirizzare lo stesso codice al cloud in produzione. Ignora il throughput assegnato e non subisce mai limitazioni, quindi non può farlo sostituirsi ai test di carico o di limite.

Come posso eseguire DynamoDB Local con Docker?

Esegui docker run -p 8000:8000 amazon/dynamodb-local per avviare l'immagine ufficiale, che espone il motore DynamoDB su http://localhost:8000. Punta il tuo AWS SDK o CLI su quell'endpoint con credenziali fittizie, quindi crea tabelle ed esegui richieste esattamente come faresti con il cloud. Aggiungi -sharedDb e un montato Volume -dbPath per conservare i dati durante i riavvii.

Avvia il contenitore

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

Ciò espone il motore su http://localhost:8000.

docker-compose

La maggior parte dei progetti lo inserisce in docker-compose.yml in modo che l'intero team ottenga lo stesso punto finale:

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:

L'immagine viene eseguita come utente dynamodblocal non root, che non può aprire un file file di database all'interno del volume denominato di proprietà di root - senza user: root che colpisci SQLiteException [14] unable to open database file e ogni chiamata si blocca.

Persistenza

Per impostazione predefinita, DynamoDB Local è in memoria: ogni tabella scompare quando il file il contenitore si ferma. Due bandiere lo rendono durevole:

• -sharedDb mantiene tutti i client su un file di database condiviso (senza di esso, ciascuno set di credenziali/region ottiene il proprio DB isolato: un comune "dove è finito il mio andare al tavolo?" sorpresa).
• -dbPath /data + un volume montato scrive il file su disco, quindi data sopravvive a docker compose down.

Punta l'SDK su di esso

Cambia solo l'endpoint: le credenziali possono essere valori fittizi:

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

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

Crea una tabella

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

Uno schema a tabella singola PK/SK come questo è un buon predefinito. Quando carichi i dispositivi, converti il semplice JSON nel formato wire con il file Convertitore DynamoDB-JSON.

Verifica che il contenitore sia sollevato e che il tavolo sia atterrato:

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

Sfoglialo con una GUI

Le chiamate CLI diventano noiose in fretta. Le solite opzioni sono l'dynamodb-admin open source interfaccia utente web o un client desktop. DynoTable si collega direttamente a localhost:8000 (o qualsiasi endpoint LocalStack — vedi connessione a DynamoDB Local e LocalStack) e ti consente di sfogliare, eseguire query con SQL Workbench e modificare tabelle locali con stessa interfaccia utente che utilizzi per le tabelle cloud: nessun andata e ritorno CLI aws.

Ciò che Local non emula

Tratta Local come un livello di compatibilità API, non un simulatore di capacità. Ignora il throughput assegnato non viene mai restituito ProvisionedThroughputExceededException, e non modella il comportamento burst su richiesta. Te lo dice un test di carico rispetto a Locale nulla sui limiti delle partizioni o sulla capacità adattiva in AWS.

Altre lacune compaiono nei test di integrazione se non le pianifichi:

Se il test rileva limitazioni, scadenza TTL entro pochi secondi o fan-out dello streaming, esegui almeno una suite su una tabella cloud usa e getta o LocalStack con il file funzionalità che devi abilitare.

Un pratico flusso di lavoro locale

La maggior parte dei team collega Local in tre livelli:

1. Test unitari: ruota il contenitore in CI, crea tabelle in beforeAll, strappa giù in afterAll. Mantieni gli apparecchi piccoli; maresciallo pianura JSON attraverso il Convertitore DynamoDB JSON quando si incollano i test attribuire le mappe a mano.
2. Test di integrazione: utilizza lo stesso client factory SDK utilizzato dalla tua app, scambiando solo endpoint e credenziali. Asserire la forma dell'articolo e scritture condizionali, non sulla capacità consumata (Local non restituisce ConsumedCapacity significativo per il budget).
3. Esplorazione manuale: collega l'DynoTable a un profilo locale, modifiche allo stage, ed eseguire query PartiQL o condizioni chiave prima di distribuire le modifiche allo schema.

Quando diventi troppo grande per un singolo processo: più servizi, trigger S3 o stile IAM routing: passa a LocalStack o a account di sviluppo. Local rimane il ciclo più veloce per "il mio modello di accesso viene compilato?"

Dati seed senza smistamento manuale

Il caricamento di dieci elementi di attrezzatura da un file JSON è più veloce quando non si taggano tutti valorizza te stesso. Incolla l'array nel file Convertitore DynamoDB JSON, copia il marshalling output e scrittura batch con BatchWriteItem su --endpoint-url http://localhost:8000. Per dispositivi che richiedono molti aggiornamenti, assemblare il UpdateExpression nel Generatore di espressioni DynamoDB e incolla il file mappe degli attributi generate nel cablaggio di prova.

L'editor degli elementi di DynoTable esegue lo stesso marshalling al commit, utile quando a il fallimento del test ti lascia a fissare i BLOB {"S":...} grezzi nella CLI.

Quando lasciare Local

Spedisci a un tavolo reale quando hai bisogno di uno dei seguenti elementi misurati sullo stesso AWS:

• Pianificazione della capacità: un elemento da 1 KB interrogato 1.000 volte al secondo viene consumato circa 250 RCU eventualmente coerenti al secondo con fatturazione su richiesta; Locale riporta zero. Modellalo con il calcolatore dei prezzi utilizzando le taglie da calcolatore delle dimensioni dell'articolo.
• Ritardo di propagazione Indice: le letture GSI sono coerenza eventuale in produzione; Locale restituisce le righe dell'indice abbastanza rapidamente da nascondere i bug di lettura obsoleta fino alla distribuzione.
• IAM su più account: i ruoli con ambito risorsa e le chiavi di condizione esistono solo in la nuvola.

Mantieni Local per un feedback rapido sulla sintassi dello schema e dell'espressione; convalidare il costo e presupposti di coerenza rispetto a una tabella di staging prima del traffico di produzione.

Insidie che vale la pena aggirare

• Forgotten -sharedDb: a ciascuna coppia di credenziali univoche viene assegnato un certificato isolato banca dati; CI e il tuo laptop sembrano universi diversi.
• Volume di proprietà root senza user: root: il backend SQLite fallisce silenziosamente finché non aggiungi l'override di composizione dalla sezione precedente.
• Presupponendo la parità dei flussi: i Lambda abilitati per il flusso necessitano di un cloud o LocalStack bersaglio; Il solo locale non eserciterà il fan-out.
• Chiavi a stringa vuota: consentita su attributi non chiave dal 2020, ancora rifiutata sulle chiavi; convalidare i dispositivi nello stesso modo in cui faresti in AWS.

Scarica DynoTable, aggiungi un profilo puntato su http://localhost:8000, e sfoglia le tabelle che hai appena creato: la stessa griglia, il generatore di filtri e SQL Workbench che utilizzi in produzione, con una spesa pari a zero per AWS in loop.