DynoTable
Intermédiaire8 min de lecture

Comment se connecter à DynamoDB Local et LocalStack

Tu as un DynamoDB local qui tourne et ton code lui parle sans souci — mais tu veux voir les tables, pas écrire un script scan à chaque fois. Connecter un client à un endpoint local, c'est deux changements : pointer vers la bonne URL, et lui passer des identifiants jetables. Les détails ci-dessous sont là où les gens se bloquent — le namespacing par région, la règle de clé alphanumérique, et la séparation des ports 8000 vs 4566.

DynamoDB Local vs LocalStack : à quoi te connectes-tu

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

Donc la seule différence pratique pour la connexion est 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 et la CLI d'AWS exigent une clé d'accès et une région même quand on parle à un endpoint local — mais ces valeurs n'ont pas à être réelles. Les docs d'AWS elles-mêmes disent que ces valeurs « n'ont pas à être des valeurs AWS valides pour fonctionner en local » (docs AWS).

Deux pièges qui ne sautent pas aux yeux :

  • La région/clé d'accès namespace silencieusement tes données. Sans le flag -sharedDb, DynamoDB Local écrit un fichier myaccesskeyid_region.db distinct par combinaison 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 app et tes tables ont l'air d'avoir disparu ; elles sont juste dans un autre fichier. Lance avec -sharedDb (un seul shared-local-instance.db pour tous les clients) ou fais correspondre exactement la clé + région que ton app utilise.
  • L'ID de clé d'accès doit être alphanumérique sur DynamoDB Local — pas de symboles. Les docs AWS indiquent 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 ci-dessous.

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 secrète. Les clés d'apparence réelle AKIA…/ASIA… sont rejetées par sécurité et retombent sur le compte factice 000000000000 — le même compte qu'une clé arbitraire comme test résout. Reste sur test.

Se connecter avec la CLI AWS (vérification de base)

Avant de pointer un GUI dessus, confirme que l'endpoint est vivant depuis la CLI. La CLI ne peut pas utiliser un endpoint local par défaut, donc tu passes --endpoint-url à chaque commande.

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 du tout (même factices dans ~/.aws/credentials ou via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), cela renvoie ta liste de tables. Une liste vide sans erreur signifie que l'endpoint fonctionne mais que tu regardes un namespace clé/région différent — voir le piège ci-dessus.

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

Une fois la CLI opérationnelle, un GUI a besoin des trois mêmes valeurs : endpoint, région et n'importe quels identifiants factices. La CLI renvoie du DynamoDB-JSON que tu lis à l'œil ; un GUI rend 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 que ton app utilise — p. ex. us-east-1. C'est une étiquette ici, pas une vraie région AWS, mais elle doit correspondre pour atterrir dans le même namespace de données.
  • Clé d'accès / secret : n'importe quoi (test / test est conventionnel). Alphanumérique seulement pour la clé d'accès sur DynamoDB Local.

À partir de là, tu parcours les items, lances un Query ou un Scan, et édites les lignes visuellement au lieu de marshaller du JSON à la main dans la CLI. Quand tu charges des fixtures, le convertisseur DynamoDB-JSON transforme du JSON ordinaire en format de transport, et Query vs Scan couvre quelle lecture privilégier. Même routine pour un visualiseur LocalStack DynamoDB — seul le port change pour 4566.

DynoTable est un logiciel de bureau uniquement local, donc le pointer vers localhost garde tes fixtures sur ta machine. Pour un aperçu plus large du paysage des GUI, voir la comparaison des GUI DynamoDB.

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

  • Connection refused. 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 alphanumérique uniquement. Une clé avec des symboles qui fonctionnait sur une image antérieure échoue désormais — remplace-la par des lettres/chiffres (p. ex. test) et mets à jour chaque outil pour correspondre.
  • 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 perdu le --endpoint-url / endpoint_url et a touché le vrai endpoint AWS, qui rejette ta clé factice. Confirme que le client pointe bien vers http://localhost:4566.
  • Erreurs d'identifiants du 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 faux profil) pour que la chaîne d'identifiants du SDK se résolve.
  • http vs https. Les endpoints locaux sont en http brut. 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 supportés 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 des valeurs clé/région d'apparence valide en local pour ne changer que l'endpoint au moment du déplacement. Pour modéliser ce schema avant de l'expédier, single-table design et GSI vs LSI couvrent les décisions qui ne changent pas entre local et prod.

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-elles 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 est la différence entre le port 8000 et 4566 ? 8000 est le défaut de DynamoDB Local autonome ; 4566 est le port edge unique de LocalStack qui fronte tous ses services émulés, DynamoDB inclus.

Un seul 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 gratuitement comme JAR et image Docker — il n'y a « aucun coût de débit provisionné, de stockage de données ou de transfert de données » ; il 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 mode d'accès s'appliquent — et les mêmes limites : la grammaire SELECT PartiQL de DynamoDB est SELECT … FROM … WHERE … ORDER BY uniquement — pas de JOIN, pas de GROUP BY, et aucune fonction d'agrégation de groupement comme COUNT/SUM/AVG (voir PartiQL vs SQL). Le SQL Workbench de DynoTable exécute ces requêtes analytiques sur n'importe quelle connexion, locale incluse.

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

Mis à jour