Exécuter l'émulateur Datastore

L'émulateur Datastore fournit une émulation locale de l'environnement de production Datastore. L'émulateur peut vous servir à développer et tester votre application en local. En outre, l'émulateur peut vous aider à générer des index pour votre instance de production Cloud Datastore et à supprimer des index inutiles. Cette page vous guide tout au long de l'installation de l'émulateur, de son démarrage et de la configuration des variables d'environnement permettant de connecter votre application à l'émulateur.

Problèmes connus

Par défaut, l'émulateur Datastore n'émule pas les fonctionnalités introduites par Firestore en mode Datastore. Les comportements d'émulateur par défaut suivants ne correspondent pas au mode Datastore:

  • L'émulateur simule la cohérence à terme par défaut. Firestore en mode Datastore est fortement cohérent.
  • L'émulateur n'autorise pas les requêtes non ascendantes dans les transactions. Firestore en mode Datastore ne présente plus cette limitation.
  • L'émulateur n'est pas compatible avec les requêtes IN, != et NOT-IN.
  • L'émulateur n'est pas compatible avec les requêtes d'agrégation telles que COUNT(*).

Toutefois, l'option --use-firestore-in-datastore-mode permet d'assouplir certaines des restrictions ci-dessus concernant Firestore en mode Datastore.

  • L'émulateur simule des requêtes non ascendantes fortement cohérentes.
  • L'émulateur autorise les requêtes non ascendantes dans les transactions.
  • L'émulateur supprime la limite de 25 groupes d'entités par transaction.

Pour émuler Firestore en mode Datastore, utilisez gcloud emulators firestore start --database-mode=datastore-mode à la place.

Avant de commencer

Pour utiliser l'émulateur Datastore, vous avez besoin des éléments suivants :

Installer l'émulateur

L'émulateur Datastore est un composant de la gcloud CLI. Exécutez la commande gcloud components install pour installer le Émulateur Datastore:

gcloud components install cloud-datastore-emulator

Répertoires de données de l'émulateur

L'émulateur simule Datastore en créant le fichier /WEB-INF/appengine-generated/local_db.bin dans un répertoire de données spécifié et en stockant des données dans local_db.bin. Par défaut, l'émulateur utilise le répertoire de données ~/.config/gcloud/emulators/datastore/. Le fichier local_db.bin persiste entre les sessions de l'émulateur. Vous pouvez configurer plusieurs répertoires de données et les considérer comme une instance en mode Datastore locale et distincte. Pour effacer le contenu d'un fichier local_db.bin, arrêtez l'émulateur et supprimez-manuellement ce fichier.

Démarrer l'émulateur

Pour démarrer l'émulateur, exécutez la commande datastore start à partir d'une invite de commande :

gcloud emulators datastore start [flags]

où [flags] correspond aux arguments facultatifs de ligne de commande fournis à la gcloud CLI. Exemple :

  • --data-dir=[DATA_DIR] modifie le répertoire de données de l'émulateur. L'émulateur crée le fichier /WEB-INF/appengine-generated/local_db.bin dans [DATA_DIR] ou, le cas échéant, utilise un fichier existant.

  • --no-store-on-disk configure l'émulateur pour qu'il ne conserve aucune donnée concernant la session de l'émulateur sur le disque.

Consultez la documentation de référence sur gcloud beta emulators datastore start pour obtenir la liste complète des options facultatives.

Une fois l'émulateur démarré, un message semblable aux lignes suivantes doit s'afficher :

...
[datastore] Dev App Server is now running.

Pour arrêter l'émulateur, appuyez sur les touches CTRL+C à l'invite de commande.

Définir des variables d'environnement

Après avoir démarré l'émulateur, vous devez définir des variables d'environnement pour que votre application se connecte à l'émulateur et non à votre base de données de production en mode Datastore. Définissez ces variables d'environnement sur la même machine que celle utilisée pour exécuter votre application.

Les variables d'environnement doivent être définies chaque fois que vous démarrez l'émulateur. Elles dépendent des numéros de port attribués de manière dynamique, qui sont susceptibles d'être modifiés lorsque vous redémarrez l'émulateur.

Définir les variables automatiquement

Si votre application et l'émulateur s'exécutent sur la même machine, vous pouvez définir les variables d'environnement automatiquement comme suit :

Linux/macOS

Exécutez env-init à l'aide de la substitution de commande :

$(gcloud beta emulators datastore env-init)

Windows

Créez et exécutez un fichier batch à l'aide du résultat de la commande env-init :

gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd

Votre application se connecte alors à l'émulateur Datastore.

Définir les variables manuellement

Si votre application et l'émulateur s'exécutent sur des machines différentes, définissez les variables d'environnement manuellement :

  1. Exécutez la commande env-init :

    gcloud beta emulators datastore env-init

  2. Sur la machine qui exécute votre application, définissez les variables d'environnement, ainsi que ses valeurs, comme indiqué par le résultat de la commande env-init. Exemple :

    Linux/macOS
    export DATASTORE_DATASET=my-project-id
export DATASTORE_EMULATOR_HOST=::1:8432
export DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore
export DATASTORE_HOST=http://::1:8432
export DATASTORE_PROJECT_ID=my-project-id
    Fenêtres
    set DATASTORE_DATASET=my-project-id
set DATASTORE_EMULATOR_HOST=::1:8432
set DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore
set DATASTORE_HOST=http://::1:8432
set DATASTORE_PROJECT_ID=my-project-id

Votre application se connecte alors à l'émulateur Datastore. Notez que l'ID de projet et le port fournis par la commande diffèrent de l'exemple ci-dessus.

Mettre à jour et supprimer des index

En exécutant votre application à l'aide de l'émulateur, vous pouvez générer des index pour votre base de données de production en mode Datastore et supprimer des index inutiles. Pour en savoir plus, consultez la page Utiliser gcloud CLI.

Supprimer des variables d'environnement

Après avoir terminé d'utiliser l'émulateur, arrêtez-le (Control-C) et supprimez les variables d'environnement afin que votre application se connecte à votre base de données de production en mode Datastore.

Supprimer les variables automatiquement

Si votre application et l'émulateur s'exécutent sur la même machine, vous pouvez supprimer les variables d'environnement automatiquement :

Linux/macOS

Exécutez env-unset à l'aide de la substitution de commande :

$(gcloud beta emulators datastore env-unset)

Windows

Créez et exécutez un fichier batch à l'aide du résultat de la commande env-unset :

gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd

Votre application se connecte alors à votre base de données de production en mode Datastore.

Supprimer les variables manuellement

Si votre application et l'émulateur s'exécutent sur des machines différentes, supprimez les variables d'environnement manuellement :

  1. Exécutez la commande env-unset :

    gcloud beta emulators datastore env-unset

  2. Sur la machine qui exécute votre application, supprimez les variables d'environnement comme indiqué par le résultat de la commande env-unset. Exemple :

    Linux/macOS
    unset DATASTORE_DATASET
unset DATASTORE_EMULATOR_HOST
unset DATASTORE_EMULATOR_HOST_PATH
unset DATASTORE_HOST
unset DATASTORE_PROJECT_ID
    Windows
    set DATASTORE_DATASET=
set DATASTORE_EMULATOR_HOST=
set DATASTORE_EMULATOR_HOST_PATH=
set DATASTORE_HOST=
set DATASTORE_PROJECT_ID=

Votre application se connecte alors à votre base de données de production en mode Datastore.