Spanner lokal emulieren

Die gcloud CLI stellt einen lokalen Emulator im Speicher bereit, mit dem Sie Ihre Anwendungen mit einer kostenlosen Testinstanz entwickeln und testen können, ohne ein Google Cloud -Projekt oder ein Abrechnungskonto erstellen zu müssen. Da der Emulator die Daten nur zwischenspeichert, geht der gesamte Status, einschließlich Daten, Schema und Konfigurationen, beim Neustart verloren. Der Emulator bietet dieselben APIs wie der Spanner-Produktionsdienst und ist für lokale Entwicklung und Tests vorgesehen, nicht für die Produktionsbereitstellung.

Der Emulator unterstützt sowohl den GoogleSQL- als auch den PostgreSQL-Dialekt. Er unterstützt alle Sprachen der Clientbibliotheken. Sie können den Emulator auch mit der Google Cloud CLI und 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, Berechtigungen oder Rollen.
  • Bei den Abfragemodi vom Typ 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.

Der Emulator unterscheidet sich außerdem folgendermaßen vom Spanner-Produktionsdienst:

  • Fehlermeldungen sind möglicherweise nicht zwischen dem Emulator und dem Produktionsdienst konsistent.
  • Leistung und Skalierbarkeit des Emulators sind nicht mit dem Produktionsdienst vergleichbar.
  • Lese-/Schreibvorgänge und Schemaänderungen sperren bis zu ihrem Abschluss die gesamte Datenbank für exklusiven Zugriff.
  • Partitionierte DML und partitionQuery werden unterstützt. Der Emulator prüft jedoch nicht, ob Anweisungen partitionierbar sind. Dies 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 für Ihre Anwendungsentwicklung und Ihren Workflow geeignete Methode aus.

Emulator für die gcloud CLI einrichten

Windows- und macOS-Nutzer müssen vor der Installation des Emulators Folgendes tun:

  • Installieren Sie die Komponenten der gcloud CLI auf Ihrer Workstation:

    gcloud components install

    Wenn die gcloud CLI bereits installiert ist, führen Sie den folgenden Befehl aus, um sicherzustellen, dass alle Komponenten aktualisiert sind:

    gcloud components update

Emulator mit der gcloud CLI erstellen und konfigurieren

Wenn Sie den Emulator mit der gcloud CLI verwenden möchten, müssen Sie die Authentifizierung deaktivieren und den Endpunkt überschreiben. Wir empfehlen, eine separate gcloud-Befehlszeilenkonfiguration zu erstellen, damit Sie schnell zwischen dem Emulator und dem Produktionsdienst wechseln können.

  1. Emulatorkonfiguration erstellen und aktivieren:

      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/

    Nach der Konfiguration werden Ihre gcloud CLI-Befehle an den Emulator und nicht an den Produktionsdienst gesendet. Sie können dies prüfen, indem Sie eine Instanz mit der Instanzkonfiguration des Emulators erstellen:

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

    Führen Sie folgenden Befehl aus, um zwischen Emulator und Standardkonfiguration zu wechseln:

    gcloud config configurations activate [emulator | default]

  2. Starten Sie den Emulator mit der gcloud CLI.

Emulator in Docker installieren

  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. Emulator in Docker ausführen:

    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.

  4. Starten Sie den Emulator mit der gcloud CLI.

Emulator mit der gcloud CLI starten

Starten Sie den Emulator mit dem Befehl gcloud emulators spanner:

gcloud emulators spanner start

Der Emulator verwendet zwei lokale Endpunkte:

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

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 er ausgeführt wird.

Sobald SPANNER_EMULATOR_HOST festgelegt ist, können Sie den Emulator testen. Folgen Sie dazu den Startleitfäden. Die Anleitung zur Projekterstellung, Authentifizierung und den Anmeldedaten können Sie ignorieren, da diese für die Verwendung des Emulators nicht benötigt werden.

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#

Für die C#-Clientbibliothek müssen Sie auch die Option emulatordetection im Verbindungsstring angeben. Im Gegensatz zu den anderen Clientbibliotheken ignoriert C# standardmäßig die Umgebungsvariable SPANNER_EMULATOR_HOST. Hier ein Beispiel für den Verbindungsstring:

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