Datastore-Emulator ausführen

Mit dem Datastore-Emulator können Sie die Datastore-Produktionsumgebung lokal emulieren. Sie können den Emulator verwenden, um Ihre Anwendung lokal zu entwickeln und zu testen. Darüber hinaus kann der Emulator Ihnen helfen, Indexe für Ihre Datastore-Produktionsinstanz zu generieren und nicht benötigte Indexe zu löschen. Auf dieser Seite werden Sie Schritt für Schritt durch die Installation des Emulators, seinen Start sowie die Festlegung der Umgebungsvariablen geführt, um Ihre Anwendung mit dem Emulator zu verbinden.

Bekannte Probleme

Standardmäßig emuliert der Datastore-Emulator keine Features, die von Firestore im Datastore-Modus eingeführt wurden. Die folgenden Standardemulator-Verhalten stimmen nicht mit dem Datastore-Modus überein:

  • Der Emulator simuliert standardmäßig Eventual Consistency. Firestore im Datastore-Modus ist strikt konsistent.
  • Der Emulator lässt Nicht-Ancestor-Abfragen innerhalb von Transaktionen nicht zu. Für Firestore im Datastore-Modus gilt diese Einschränkung nicht mehr.
  • Der Emulator unterstützt keine IN-, !=- und NOT-IN-Abfragen.
  • Der Emulator unterstützt keine Aggregationsabfragen wie COUNT(*).

Mit dem Flag --use-firestore-in-datastore-mode können einige der oben genannten Einschränkungen für Firestore im Datastore-Modus jedoch gelockert werden.

  • Der Emulator simuliert strikt konsistente Nicht-Ancestor-Abfragen.
  • Der Emulator erlaubt Nicht-Ancestor-Abfragen innerhalb von Transaktionen.
  • Im Emulator gilt keine Beschränkung auf 25 Entitätengruppen in einer Transaktion.

Wenn Sie Firestore im Datastore-Modus emulieren möchten, verwenden Sie stattdessen gcloud emulators firestore start --database-mode=datastore-mode.

Hinweise

Zur Verwendung des Datastore-Emulators benötigen Sie Folgendes:

Emulator installieren

Der Datastore-Emulator ist eine Komponente der gcloud CLI. Mit dem Befehl gcloud components install können Sie den Datastore-Emulator installieren:

gcloud components install cloud-datastore-emulator

Emulator-Datenverzeichnisse

Der Emulator simuliert Datastore dadurch, dass eine /WEB-INF/appengine-generated/local_db.bin-Datei in einem angegebenen Datenverzeichnis erstellt und Daten in local_db.bin gespeichert werden. Standardmäßig verwendet der Emulator das Datenverzeichnis ~/.config/gcloud/emulators/datastore/. Die Datei local_db.bin bleibt zwischen den Sitzungen des Emulators erhalten. Sie können mehrere Datenverzeichnisse einrichten und jedes dieser Verzeichnisse als separate, lokale Instanz im Datastore-Modus betrachten. Wenn Sie den Inhalt einer local_db.bin-Datei löschen möchten, beenden Sie den Emulator und löschen Sie die Datei manuell.

Emulator starten

Führen Sie zum Starten des Emulators über eine Eingabeaufforderung den Befehl datastore start aus:

gcloud emulators datastore start [flags]

Dabei sind [flags] optionale Befehlszeilenargumente, die an die gcloud CLI übergeben werden. Beispiel:

  • Mit --data-dir=[DATA_DIR] wird das Datenverzeichnis des Emulators geändert. Der Emulator erstellt die Datei /WEB-INF/appengine-generated/local_db.bin in [DATA_DIR] oder verwendet eine vorhandene Datei, falls verfügbar.

  • Mit --no-store-on-disk wird der Emulator so konfiguriert, dass für die Emulatorsitzung keine Daten auf dem Laufwerk gespeichert werden.

Die vollständige Liste optionaler Flags finden Sie in der Referenz zu gcloud beta emulators datastore start.

Nach dem Starten des Emulators wird eine Meldung wie die Folgende angezeigt:

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

Um den Emulator zu beenden, drücken Sie über die Eingabeaufforderung Strg-C.

Umgebungsvariablen festlegen

Nachdem Sie den Emulator gestartet haben, müssen Sie Umgebungsvariablen festlegen, damit Ihre Anwendung eine Verbindung zum Emulator und nicht zur Produktionsdatenbank im Datastore-Modus herstellt. Legen Sie die Umgebungsvariablen auf dem Computer fest, auf dem auch die Anwendung ausgeführt wird.

Sie müssen die Umgebungsvariablen bei jedem Start des Emulators festlegen. Die Umgebungsvariablen hängen von dynamisch zugewiesenen Portnummern ab, die sich beim Neustart des Emulators ändern können.

Variablen automatisch einstellen

Wenn die Anwendung und der Emulator auf demselben Computer ausgeführt werden, können Sie die Umgebungsvariablen automatisch festlegen:

Linux/MacOS

Führen Sie env-init mit Befehlsersetzung aus:

$(gcloud beta emulators datastore env-init)

Windows

Erstellen Sie eine Batchdatei und verwenden Sie bei der Ausführung die Ausgabe von env-init:

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

Ihre Anwendung stellt nun eine Verbindung zum Datastore-Emulator her.

Variablen manuell einstellen

Wenn die Anwendung und der Emulator auf unterschiedlichen Computern ausgeführt werden, legen Sie die Umgebungsvariablen manuell fest:

  1. Führen Sie den Befehl env-init aus:

    gcloud beta emulators datastore env-init

  2. Legen Sie auf dem Computer, auf dem Ihre Anwendung ausgeführt wird, die Umgebungsvariablen und -werte so fest, wie sie in der Ausgabe des Befehls env-init angegeben sind. Beispiel:

    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
    Windows
    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

Ihre Anwendung stellt nun eine Verbindung zum Datastore-Emulator her. Beachten Sie, dass sich die vom Befehl bereitgestellte Projekt-ID und der Port von dem obigen Beispiel unterscheiden.

Indexe aktualisieren und löschen

Wenn Sie Ihre Anwendung mit dem Emulator ausführen, können Sie für die Produktionsdatenbank im Datastore-Modus Indexe generieren und nicht benötigte Indexe löschen. Weitere Informationen finden Sie unter gcloud CLI verwenden.

Umgebungsvariablen entfernen

Nachdem Sie Ihre Arbeit mit dem Emulator abgeschlossen haben, beenden Sie ihn (Strg-C) und entfernen Sie die Umgebungsvariablen wieder, damit Ihre Anwendung wieder mit der Produktionsdatenbank im Datastore-Modus verbunden wird.

Variablen automatisch entfernen

Wenn die Anwendung und der Emulator auf demselben Computer ausgeführt werden, können Sie die Umgebungsvariablen automatisch entfernen:

Linux/MacOS

Führen Sie env-unset mit Befehlsersetzung aus:

$(gcloud beta emulators datastore env-unset)

Windows

Erstellen Sie eine Batchdatei und verwenden Sie bei der Ausführung die Ausgabe von env-unset:

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

Die Anwendung wird nun mit Ihrer Produktionsdatenbank im Datastore-Modus verbunden.

Variablen manuell entfernen

Wenn die Anwendung und der Emulator auf unterschiedlichen Computern ausgeführt werden, entfernen Sie die Umgebungsvariablen manuell:

  1. Führen Sie den Befehl env-unset aus:

    gcloud beta emulators datastore env-unset

  2. Legen Sie auf dem Computer, auf dem die Anwendung ausgeführt wird, die Umgebungsvariablen und den Wert fest, wie in der Ausgabe des Befehls env-unset angegeben. Beispiel:

    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=

Die Anwendung wird nun mit Ihrer Produktionsdatenbank im Datastore-Modus verbunden.