DynoTable
Intermédiaire8 min de lecture

Se connecter à DynamoDB Local et LocalStack

Tu as un DynamoDB local qui tourne et ton code lui parle très bien — mais tu veux voir les tables, pas écrire un script scan à chaque fois. Connecter un client à un endpoint local se résume à deux changements : pointer vers la bonne URL et lui donner des identifiants jetables. Les détails ci-dessous sont là où les gens coincent — le namespace de région, la règle de la clé alphanumérique, et la distinction de port 8000 vs 4566.

DynamoDB Local vs LocalStack : à quoi tu te connectes

Les deux te donnent une API DynamoDB sur localhost sans compte AWS, mais ce sont deux choses différentes :

La seule différence pratique pour la connexion est donc l'URL de l'endpoint : :8000 pour DynamoDB Local autonome, :4566 pour DynamoDB-via-LocalStack. Tout le reste — l'API, l'astuce des identifiants, la config du GUI — est identique.

La configuration endpoint + identifiants factices qui piège tout le monde

Les SDK AWS et la CLI exigent une clé d'accès et une région même en parlant à un endpoint local — mais ces valeurs n'ont pas besoin d'être réelles. Les propres docs d'AWS indiquent que ces valeurs « n'ont pas besoin d'être des valeurs AWS valides pour tourner en local » (docs AWS).

Deux pièges pas évidents :

  • La région/clé d'accès segmente silencieusement tes données. Sans le flag -sharedDb, DynamoDB Local écrit un fichier myaccesskeyid_region.db distinct par combinaison ID-de-clé-d'accès + région — le nommage exact d'AWS. Connecte-toi avec une clé ou une région différente de celle utilisée par ton application et tes tables semblent avoir disparu ; elles sont juste dans un autre fichier. Lance avec -sharedDb (un seul shared-local-instance.db pour tous les clients) ou reprends exactement la même clé + région que ton application.
  • L'ID de clé d'accès doit être alphanumérique sur DynamoDB Local — pas de symboles. Les docs AWS précisent que AWS_ACCESS_KEY_ID ne peut contenir que A–Z, a–z et 0–9 ; AWS a introduit cela dans DynamoDB Local 2.0.0 (et 1.23.0+), donc une clé avec des caractères spéciaux qui fonctionnait sur une image antérieure échoue désormais (AWS re:Post). Voir l'erreur plus bas.

Pour LocalStack, la valeur par défaut sûre est test / test : il ignore entièrement la clé secrète et ne valide jamais la valeur du secret. Des clés d'aspect réel AKIA…/ASIA… sont rejetées par sécurité et retombent sur le compte factice 000000000000 — le même compte que celui vers lequel une clé arbitraire comme test se résout. Reste sur test.

Se connecter avec la CLI AWS (test de bon fonctionnement)

Avant de pointer un GUI dessus, confirme que l'endpoint est vivant depuis la CLI. La CLI n'a aucun endpoint local par défaut intégré, donc passe soit --endpoint-url par commande, soit AWS_ENDPOINT_URL_DYNAMODB=http://localhost:8000 (CLI v2.13+).

DynamoDB Local :

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

LocalStack (même commande, port différent) :

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

Si tu as des identifiants configurés (même factices dans ~/.aws/credentials ou via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), ça renvoie la liste de tes tables. Une liste vide sans erreur signifie que l'endpoint fonctionne mais que tu regardes un autre namespace clé/région — voir le piège ci-dessus.

GUI DynamoDB Local : parcourir et interroger les tables locales dans DynoTable

Une fois que la CLI fonctionne, un GUI a besoin des mêmes trois valeurs : endpoint, région et des identifiants factices quelconques. La CLI renvoie du DynamoDB-JSON que tu lis à l'œil ; un GUI restitue les mêmes données sous forme de table que tu peux trier, filtrer et éditer.

Dans DynoTable, ajoute une connexion et définis un endpoint personnalisé :

  • Endpoint : http://localhost:8000 (DynamoDB Local) ou http://localhost:4566 (LocalStack)
  • Région : ce qu'utilise ton application — p. ex. us-east-1. C'est une étiquette ici, pas une vraie région AWS, mais elle doit correspondre pour que tu atterrisses dans le même namespace de données.
  • Clé d'accès / secret : n'importe quoi (test / test est conventionnel). Alphanumérique uniquement pour la clé d'accès sur DynamoDB Local.

À partir de là, tu parcours les éléments, tu exécutes un Query ou un Scan, et tu édites les lignes visuellement au lieu de du JSON à la main sur la CLI. Quand tu charges des fixtures, le convertisseur DynamoDB-JSON transforme du JSON simple en format wire, et Query vs Scan explique quelle lecture privilégier. Même topo pour un visualiseur DynamoDB LocalStack — seul le port change en 4566.

DynoTable est un logiciel de bureau purement local, donc le pointer vers localhost garde tes fixtures sur ta machine. Pour un tour d'horizon plus large des GUI, voir la comparaison des GUI DynamoDB.

Erreurs courantes (discordance de région, port, identifiants)

  • Connexion refusée. Mauvais port — 8000 est DynamoDB Local, 4566 est LocalStack. Confirme aussi que le conteneur a bien publié le port (docker run -p 8000:8000 amazon/dynamodb-local). Pour LocalStack, vérifie que le service est actif sur http://localhost:4566/_localstack/health.
  • The Access Key ID or Security Token is Invalid sur DynamoDB Local. Depuis l'image 2.0.0 (et 1.23.0+), l'ID de clé d'accès doit être uniquement alphanumérique. Une clé avec des symboles qui marchait sur une image antérieure échoue désormais — remplace-la par des lettres/chiffres (p. ex. test) et mets à jour chaque outil pour qu'ils correspondent.
  • The security token included in the request is invalid contre LocalStack. C'est presque toujours un problème d'endpoint, pas d'identifiants — ton client SDK a abandonné le --endpoint-url / endpoint_url et a tapé le vrai endpoint AWS, qui rejette ta clé factice. Confirme que le client pointe bien vers http://localhost:4566.
  • Erreurs d'identifiants depuis le SDK/CLI. Même les endpoints locaux ont besoin de quelques identifiants présents. Définis AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (ou un profil factice) pour que la chaîne d'identifiants du SDK se résolve.
  • http vs https. Les endpoints locaux sont en http simple. Une URL https:// échouera au handshake TLS.

DynamoDB Local contient-il les mêmes données que mes vraies tables AWS ?

Non — le local et le cloud sont des stockages complètement séparés. DynamoDB Local (et le DynamoDB de LocalStack) garde les données dans un fichier local ou en mémoire ; il ne touche jamais ton compte AWS, et les régions/comptes AWS ne sont pas pris en charge au niveau client en local. C'est le but : c'est pour le développement et les tests. Si tu veux les mêmes fixtures dans le cloud plus tard, AWS suggère d'utiliser en local des valeurs clé/région d'aspect valide pour n'avoir qu'à changer l'endpoint lors de la migration. Pour modéliser ce schéma avant de l'expédier, single-table design et GSI vs LSI couvrent les décisions qui ne changent pas entre le local et la prod.

Ce que le local t'économise (et ce que la prod facture quand même)

DynamoDB Local ne compte rien — pas de RCU, pas de WCU, pas de transfert. Le même GetItem sur DynamoDB managé dans us-east-1 en on-demand facture 0,5 RCU en cohérence à terme, ou 1 RCU en cohérence forte, pour un élément ≤ 4 Ko. Dès que tu remplaces --endpoint-url par le vrai endpoint, chaque parcours et chaque requête recommencent à être facturés. Modélise le saut avec le calculateur de tarifs et dimensionne des éléments représentatifs avec le calculateur de taille d'élément.

FAQ

Ai-je besoin de vrais identifiants AWS ? Non. DynamoDB Local et LocalStack acceptent tous deux des valeurs factices. Elles doivent juste être présentes, alphanumériques (pour DynamoDB Local) et cohérentes entre tes outils.

Pourquoi mes tables disparaissent quand je change d'outil ? Sans -sharedDb, DynamoDB Local partitionne les données par clé d'accès + région dans des fichiers myaccesskeyid_region.db distincts. Utilise -sharedDb ou garde ces valeurs identiques partout.

Quelle différence entre le port 8000 et 4566 ? 8000 est le port par défaut de DynamoDB Local autonome ; 4566 est le port edge unique de LocalStack qui fronte tous ses services émulés, DynamoDB compris.

Un même GUI peut-il se connecter aux deux ? Oui — ils parlent la même API DynamoDB. Seule l'URL de l'endpoint change (:8000 vs :4566).

DynamoDB Local est-il gratuit ? Oui. AWS distribue DynamoDB Local sans frais sous forme de JAR et d'image Docker — il n'y a « ni coûts de débit provisionné, ni de stockage de données, ni de transfert de données » ; c'est destiné au développement et aux tests uniquement, pas à la production.

Puis-je exécuter du SQL contre mes tables locales ? Le DynamoDB local parle la même API que le cloud, donc les mêmes règles de patterns d'accès s'appliquent — et les mêmes limites : la grammaire du SELECT PartiQL de DynamoDB est seulement SELECT … FROM … WHERE … ORDER BY — pas de JOIN, pas de GROUP BY, et pas de fonctions d'agrégation de regroupement comme COUNT/SUM/AVG (voir PartiQL vs SQL). Le de DynoTable exécute ces requêtes analytiques sur n'importe quelle connexion, local compris.

Essaie DynoTable pour te connecter directement à localhost:8000 ou localhost:4566 et parcourir, interroger et éditer tes tables locales avec un GUI.

Mis à jour