Spanner lokal emulieren

Die Google Cloud CLI stellt einen lokalen Emulator im Speicher zur Verfügung, mit dem Sie Ihre Anwendungen entwickeln und testen können. Da der Emulator die Daten nur im Arbeitsspeicher speichert, gehen beim Neustart alle Statusinformationen verloren, einschließlich Daten, Schema und Konfigurationen. Der Emulator bietet dieselben APIs wie der Spanner-Produktionsdienst und dient der lokalen Entwicklung und dem Testen, nicht der Produktionsbereitstellung.

Der Emulator unterstützt sowohl den GoogleSQL- als auch den PostgreSQL-Dialekt. Es werden alle Sprachen der Clientbibliotheken unterstützt. Sie können den Emulator auch mit der gcloud CLI und den REST APIs verwenden.

Der Emulator ist auch als Open-Source-Projekt in GitHub verfügbar.

Beschränkungen und Unterschiede

Der Emulator unterstützt Folgendes nicht:

  • TLS/HTTPS, Authentifizierung, Identity and Access Management (IAM), Berechtigungen oder Rollen.
  • In den Abfragemodi PLAN oder PROFILE ist der zurückgegebene Abfrageplan leer.
  • Die ANALYZE-Anweisung. Der Emulator akzeptiert sie, ignoriert sie aber.
  • Alle Audit-Logging- und Monitoring-Tools.
  • Schutz vor dem Löschen von Datenbanken. Der Emulator akzeptiert das Feld enable_drop_protection, lässt aber das Löschen von Datenbanken zu, auch wenn dieses Attribut aktiviert ist.

Der Emulator unterscheidet sich außerdem in folgenden Punkten vom Spanner-Produktionsdienst:

  • Die Fehlermeldungen können sich zwischen dem Emulator und dem Produktionsdienst unterscheiden.
  • Die Leistung und Skalierbarkeit des Emulators sind nicht mit dem Produktionsdienst vergleichbar.
  • Lese-/Schreibtransaktionen und Schemaänderungen sperren die gesamte Datenbank für den exklusiven Zugriff bis zum Abschluss.
  • Der Emulator unterstützt partitionierte DML und partitionQuery, prüft aber nicht, ob Anweisungen partitionierbar sind. Das bedeutet, dass eine partitionierte DML- oder partitionQuery-Anweisung im Emulator ausgeführt werden kann, aber im Produktionsdienst mit dem Fehler „Nicht partitionierbare Anweisung“ fehlschlägt.

Eine vollständige Liste der unterstützten, nicht unterstützten und teilweise unterstützten APIs und Funktionen finden Sie in der README-Datei in GitHub.

Optionen zum Ausführen des Emulators

Es gibt zwei gängige Möglichkeiten, den Emulator auszuführen:

Wählen Sie die Methode aus, die für die Entwicklung und den Testworkflow Ihrer Anwendung geeignet ist.

Emulator mit der gcloud CLI ausführen

So führen Sie den Emulator über die gcloud CLI aus:

  1. Installieren Sie die Komponente cloud-spanner-emulator:

    gcloud components install cloud-spanner-emulator

    Wenn die gcloud CLI bereits installiert ist, führen Sie den folgenden Befehl aus, um alle Komponenten zu aktualisieren:

    gcloud components update

  2. Starten Sie den Emulator:

    gcloud emulators spanner start

    Der Emulator verwendet zwei lokale Endpunkte:

    • localhost:9010 für gRPC-Anfragen
    • localhost:9020 für REST-Anfragen

Emulator mit Docker ausführen

So führen Sie den Emulator mit Docker aus:

  1. Installieren Sie Docker auf Ihrem System und machen Sie es im Systempfad verfügbar.

  2. Rufen Sie das aktuelle Emulator-Image ab:

    docker pull gcr.io/cloud-spanner-emulator/emulator

  3. Führen Sie den Emulator in Docker aus:

    docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator

    Der Befehl führt den Emulator aus und ordnet die Ports im Container den entsprechenden Ports auf Ihrem lokalen Host zu. Der Emulator verwendet zwei lokale Endpunkte: localhost:9010 für gRPC-Anfragen und localhost:9020 für REST-Anfragen.

gcloud CLI für die Verwendung des Emulators konfigurieren

Wenn Sie den Emulator mit der gcloud CLI verwenden möchten, deaktivieren Sie die Authentifizierung und überschreiben Sie den Endpunkt. Erstellen Sie eine separate gcloud CLI-Konfiguration, um schnell zwischen dem Emulator und dem Produktionsdienst zu wechseln.

  1. Erstellen und aktivieren Sie eine Emulator-Konfiguration:

    gcloud config configurations create emulator
gcloud config set auth/disable_credentials true
gcloud config set project your-project-id
gcloud config set api_endpoint_overrides/spanner http://localhost:9020/

  2. Nach der Konfiguration sendet die gcloud CLI Ihre Befehle an den Emulator und nicht an den Produktionsdienst. Prüfen Sie dies, indem Sie eine Instanz mit der Instanzkonfiguration des Emulators erstellen:

    gcloud spanner instances create test-instance \
  --config=emulator-config --description="Test Instance" --nodes=1

Konfigurationen wechseln

Führen Sie Folgendes aus, um zwischen dem Emulator und Ihrer Standardkonfiguration zu wechseln:

# To switch to default (production) configuration:
gcloud config configurations activate default

# To switch back to emulator configuration:
gcloud config configurations activate emulator

Clientbibliotheken mit dem Emulator verwenden

Sie können unterstützte Versionen der Clientbibliotheken mit dem Emulator verwenden, indem Sie die Umgebungsvariable SPANNER_EMULATOR_HOST festlegen. Dazu gibt es mehrere Vorgehensweisen. Beispiel:

Linux/macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

Oder mit gcloud env-init:

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

gcloud emulators spanner env-init > set_vars.cmd && set_vars.cmd

Wenn Ihre Anwendung gestartet wird, sucht die Clientbibliothek automatisch nach SPANNER_EMULATOR_HOST und stellt eine Verbindung zum Emulator her, wenn dieser ausgeführt wird.

Sobald SPANNER_EMULATOR_HOST festgelegt ist, können Sie den Emulator anhand der Startleitfäden testen. Ignorieren Sie die Anleitungen zur Projekterstellung, Authentifizierung und zu Anmeldedaten, da diese für die Verwendung des Emulators nicht erforderlich sind.

Unterstützte Versionen

In der folgenden Tabelle sind die Versionen der Clientbibliotheken aufgeführt, die den Emulator unterstützen.

Clientbibliothek Mindestversion
C++ v0.9.x+
C# v3.1.0+
Go v1.5.0+
Java v1.51.0+
Node.js v4.5.0+
PHP v1.25.0+
Python v1.15.0+
Ruby v1.13.0+

Zusätzliche Anweisungen für C#

Geben Sie für die C#-Clientbibliothek die Option emulatordetection im Verbindungsstring an. Im Gegensatz zu den anderen Clientbibliotheken ignoriert C# standardmäßig die Umgebungsvariable SPANNER_EMULATOR_HOST. Das folgende Beispiel zeigt den Verbindungsstring:

var builder = new SpannerConnectionStringBuilder
{
    DataSource = $"projects/{projectId}/instances/{instanceId}/databases/{databaseId}",
    EmulatorDetection = "EmulatorOnly"
};