Emula Spanner localmente

Il gcloud CLI fornisce un emulatore locale in memoria che puoi utilizzare per sviluppare e testare le tue applicazioni. Poiché l'emulatore archivia i dati solo in memoria, tutti gli stati, inclusi dati, schema e configurazioni, vengono persi al riavvio. L'emulatore offre le stesse API del servizio di produzione Spanner ed è destinato allo sviluppo e ai test locali, non ai deployment di produzione.

L'emulatore supporta sia il dialetto GoogleSQL sia quello PostgreSQL. Supporta tutti i linguaggi delle librerie client. Puoi anche utilizzare l'emulatore con il 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:

  • TLS/HTTPS, autenticazione, Identity and Access Management, autorizzazioni o ruoli.
  • Nelle modalità di query PLAN o PROFILE , il piano di query restituito è vuoto.
  • L'ANALYZEistruzione. L'emulatore la accetta, ma la ignora.
  • Qualsiasi strumento di monitoraggio e logging di controllo.

L'emulatore differisce anche 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 parzialmente supportate, consulta il README file su GitHub.

Opzioni per l'esecuzione dell'emulatore

Esistono due modi comuni per eseguire l'emulatore:

Scegli il modo più adatto al tuo flusso di lavoro di sviluppo e test delle applicazioni.

Configurare l'emulatore per gcloud CLI

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

  • Installa i componenti di gcloud CLI sulla tua workstation:

    gcloud components install cloud-spanner-emulator

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

    gcloud components update

Creare e configurare l'emulatore utilizzando gcloud CLI

Per utilizzare l'emulatore con gcloud CLI, devi disabilitare l'autenticazione ed eseguire l'override dell'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 dalla configurazione dell'emulatore a quella predefinita, esegui:

    gcloud config configurations activate [emulator | default]

  2. Avvia l'emulatore utilizzando gcloud CLI.

Installare 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 ed esegue il mapping delle porte nel container alle stesse porte dell'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.

Avviare 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 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 introduttive. Ignora le istruzioni relative alla creazione del progetto, 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 anche specificare l' emulatordetection opzione 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"
};