Emulare Spanner localmente

gcloud CLI fornisce un emulatore in memoria locale, che puoi utilizzare per sviluppare e testare le tue applicazioni gratuitamente senza creare un progetto Google Cloud o account di fatturazione. Poiché l'emulatore memorizza i dati solo in memoria, tutto lo stato, inclusi dati, schema e configurazioni, viene perso al riavvio. L'emulatore offre le stesse API del servizio di produzione Spanner ed è progettato per lo sviluppo e i test locali, non per i deployment di produzione.

L'emulatore supporta i dialetti GoogleSQL e PostgreSQL. Supporta tutte le lingue delle librerie client. Puoi anche usare l'emulatore con Google Cloud CLI e API REST.

L'emulatore è disponibile anche come progetto open source in GitHub.

Limitazioni e differenze

L'emulatore non supporta quanto segue:

L'emulatore si differenzia anche dal servizio di produzione Spanner per nei seguenti modi:

  • I messaggi di errore potrebbero non essere coerenti tra l'emulatore e il servizio di produzione.
  • Le prestazioni e la scalabilità dell'emulatore non sono paragonabili al servizio di produzione.
  • Le transazioni di lettura/scrittura e le modifiche allo schema bloccheranno l'intero database per l'accesso esclusivo fino al loro completamento.
  • Le istruzioni DML partizionate e Query di partizione sono supportate, ma l'emulatore non verifica che le istruzioni siano partizionabili. Ciò significa che un'istruzione DML partizionata o Query di partizione potrebbe essere eseguito nell'emulatore, ma potrebbe non riuscire nel servizio di produzione non partizionabile.

Per un elenco completo delle API e delle funzionalità supportate, non supportate e supportate parzialmente, consulta il file README su GitHub.

Installa ed esegui l'emulatore

I due modi più comuni per eseguire l'emulatore sono utilizzare gcloud CLI e Docker. Puoi scegliere il metodo più adatto per lo sviluppo e il flusso di lavoro di test delle applicazioni.

Interfaccia a riga di comando gcloud

  1. Installa l'interfaccia a riga di comando gcloud.

  2. Per gli utenti di Windows e MacOS, l'emulatore è necessario installare Docker sul sistema disponibili sul percorso di sistema.

  3. Aggiorna gcloud per ottenere l'ultima versione:

    gcloud components update

  4. Avvia l'emulatore:

    gcloud emulators spanner start

    Se l'emulatore non è già installato, ti verrà chiesto di scaricare e installare il file binario per l'emulatore.

    Per impostazione predefinita, l'emulatore ospita due endpoint locali: localhost:9010 per le richieste gRPC e localhost:9020 per le richieste REST.

    Per maggiori dettagli su questo comando, consulta gcloud emulators spanner.

Docker

  1. Assicurati che Docker sia installata sul sistema e disponibile nel percorso di sistema.

  2. Scarica l'immagine dell'emulatore più recente:

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

  3. Avvia l'emulatore:

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

    Questo comando esegue l'emulatore e mappa le porte nel container le stesse porte sull'host locale. Avrai due endpoint locali: localhost:9010 per le richieste gRPC e localhost:9020 per le richieste REST.

Utilizza gcloud CLI con l'emulatore

Per utilizzare l'emulatore con gcloud, devi disattivare l'autenticazione e sostituire l'endpoint.

Ti consigliamo di creare una configurazione gcloud separata, in modo da poter passare rapidamente dall'emulatore al servizio di produzione e viceversa. Per creare e attivare una configurazione dell'emulatore, esegui:

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/

Una volta configurati, i comandi gcloud verranno inviati all'emulatore anziché al servizio di produzione. Puoi verificarlo creando un'istanza con configurazione dell'istanza dell'emulatore:

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

Per passare dall'emulatore alla configurazione predefinita e viceversa, esegui:

gcloud config configurations activate [emulator | default]

Utilizzare le librerie client con l'emulatore

Puoi utilizzare le versioni supportate delle librerie client con l'emulatore impostando la variabile di ambiente SPANNER_EMULATOR_HOST. Ci sono molti modi per farlo. Ad esempio:

Linux / MacOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

In alternativa, con gcloud env-init:

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

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

All'avvio dell'applicazione, la libreria client cerca automaticamenteSPANNER_EMULATOR_HOST e si connette all'emulatore se è in esecuzione.

Una volta impostato SPANNER_EMULATOR_HOST, puoi testare l'emulatore seguendo le guide introduttive riportate di seguito. Puoi ignorare le istruzioni relative al progetto creazione, autenticazione e credenziali poiché non sono necessarie per utilizzare un emulatore.

Versioni supportate

La tabella seguente elenca le versioni delle librerie client che supportano l'emulatore.

Libreria client Versione minima
C++ v0.9.x+
C# v3.1.0 e versioni successive
Vai Versione 1.5.0 e successive
Java Versione 1.51.0 e successive
Node.js v4.5.0 e versioni successive
PHP v1.25.0 e versioni successive
Python v1.15.0 e versioni successive
Ruby v1.13.0 e versioni successive

Istruzioni aggiuntive per C#

Per la libreria client C#, devi specificare anche il parametro emulatordetection nella stringa di connessione. A differenza delle altre librerie client, C# ignora la variabile di ambiente SPANNER_EMULATOR_HOST per impostazione predefinita. Ecco come fare:

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