Emulare Spanner localmente

L'interfaccia a riga di comando gcloud fornisce un emulatore in-memory locale che puoi utilizzare per sviluppare e testare le tue applicazioni con un'istanza di prova gratuita senza creare un progetto Google Cloud o un account di fatturazione. Poiché l'emulatore immagazzina 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 gli implementazioni di produzione.

L'emulatore supporta i dialetti GoogleSQL e PostgreSQL. Supporta tutte le lingue delle librerie client. Puoi anche utilizzare l'emulatore 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 inoltre dal servizio di produzione Spanner per i seguenti aspetti:

  • 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 bloccano l'intero database per l'accesso esclusivo fino al loro completamento.
  • La DML partizionata e partitionQuery sono supportate, ma l'emulatore non verifica che le istruzioni siano partizionabili. Ciò significa che un'istruzione DML o partitionQuery partizionata 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ù adatto per lo sviluppo e il flusso di lavoro di test dell'applicazione.

Configura l'emulatore per l'interfaccia alla gcloud CLI

Gli utenti Windows e macOS devono eseguire i seguenti passaggi prima di installare l'emulatore:

  • Installa i componenti dell'interfaccia a riga di comando gcloud sulla tua workstation:

    gcloud components install

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

    gcloud components update

Crea e configura l'emulatore utilizzando gcloud CLI

Per utilizzare l'emulatore con l'interfaccia alla 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 e viceversa, esegui:

    gcloud config configurations activate [emulator | default]

  2. Avvia l'emulatore utilizzando gcloud CLI.

Installa l'emulatore in Docker

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

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

    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 del contenitore 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

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

Quando l'applicazione si avvia, 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 per iniziare. 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 e versioni successive
Vai v1.5.0 e versioni successive
Java v1.51.0 e versioni 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 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 di stringa di connessione:

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