Emulare Spanner localmente

gcloud CLI fornisce un emulatore locale in memoria, che puoi utilizzare per sviluppare e testare le tue applicazioni. 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 è destinato a sviluppo e test locali, non a deployment di produzione.

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

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

Limitazioni e differenze

L'emulatore non supporta quanto segue:

L'emulatore si differenzia dal servizio di produzione Spanner 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 a quelle del servizio di produzione.
  • Le transazioni di lettura/scrittura e le modifiche allo schema bloccano l'intero database per l'accesso esclusivo fino al completamento.
  • DML partizionato e partitionQuery sono supportati, ma l'emulatore non verifica che le istruzioni siano partizionabili. Ciò significa che un'istruzione DML partizionata o partitionQuery potrebbe essere eseguita nell'emulatore, ma potrebbe non riuscire nel servizio di produzione con l'errore di istruzione non partizionabile.

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

Opzioni per l'esecuzione dell'emulatore

Esistono due modi comuni per eseguire l'emulatore:

Scegli il metodo più appropriato per lo sviluppo e il flusso di lavoro di test della tua applicazione.

Configura l'emulatore per gcloud CLI

Per gli utenti Windows e macOS, prima di installare l'emulatore, procedi nel seguente modo:

  • Installa i componenti della gcloud CLI sulla tua workstation:

    gcloud components install

    Se gcloud CLI è già installato, esegui il seguente comando per assicurarti che tutti i suoi componenti siano aggiornati:

    gcloud components update

Crea e configura l'emulatore utilizzando gcloud CLI

Per utilizzare l'emulatore con gcloud CLI, devi disattivare l'autenticazione e sostituire l'endpoint. Ti consigliamo di creare una configurazione gcloud CLI separata in modo da poter passare rapidamente dall'emulatore al servizio di produzione e viceversa.

  1. Crea e attiva una configurazione dell'emulatore:

      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 CLI vengono inviati all'emulatore anziché al servizio di produzione. Puoi verificarlo creando un'istanza con la 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, esegui:

    gcloud config configurations activate [emulator | default]

  2. Avvia l'emulatore utilizzando gcloud CLI.

Installa l'emulatore in Docker

  1. Installa Docker sul tuo sistema e rendilo disponibile nel percorso di sistema.

  2. Scarica l'ultima immagine dell'emulatore:

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

  3. Esegui l'emulatore in Docker:

    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 alle stesse porte sull'host locale. L'emulatore utilizza due endpoint locali: localhost:9010 per le richieste gRPC e localhost:9020 per le richieste REST.

  4. Avvia l'emulatore utilizzando gcloud CLI.

Avvia l'emulatore utilizzando gcloud CLI

Avvia l'emulatore utilizzando il comando gcloud emulators spanner:

gcloud emulators spanner start

L'emulatore utilizza due endpoint locali:

  • localhost:9010 per le richieste gRPC
  • localhost:9020 per le richieste REST

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. Esistono molti modi per farlo. Ad esempio:

Linux/macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

Oppure con gcloud env-init:

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

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

Quando l'applicazione viene avviata, la libreria client verifica automaticamente la presenza di SPANNER_EMULATOR_HOST e si connette all'emulatore se è in esecuzione.

Una volta impostato SPANNER_EMULATOR_HOST, puoi testare l'emulatore seguendo le guide Guida introduttiva. Ignora le istruzioni relative alla creazione di progetti, all'autenticazione e alle credenziali, poiché non sono necessarie per utilizzare l'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+
Vai v1.5.0+
Java v1.51.0+
Node.js v4.5.0+
PHP v1.25.0+
Python v1.15.0+
Ruby v1.13.0+

Istruzioni aggiuntive per C#

Per la libreria client C#, devi specificare anche l'opzione emulatordetection nella stringa di connessione. A differenza delle altre librerie client, C# ignora la variabile di ambiente SPANNER_EMULATOR_HOST per impostazione predefinita. Di seguito è riportato un esempio per la stringa di connessione:

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