Emula Spanner localmente

Google Cloud CLI fornisce un emulatore in memoria locale per sviluppare e testare le tue applicazioni. Poiché l'emulatore archivia i dati solo in memoria, al riavvio perde tutto lo stato, inclusi dati, schema e configurazioni. L'emulatore offre le stesse API del servizio di produzione Spanner e serve per lo sviluppo e i test locali, non per i deployment di produzione.

L'emulatore supporta i dialetti GoogleSQL e PostgreSQL. Supporta tutti i linguaggi delle librerie client. Puoi utilizzare l'emulatore anche con gcloud 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 (IAM), autorizzazioni o ruoli.
  • Nelle modalità di query PLAN o PROFILE, il piano di query restituito è vuoto.
  • L'istruzione ANALYZE. L'emulatore lo accetta, ma lo ignora.
  • Uno qualsiasi degli strumenti di audit logging e monitoraggio.
  • Protezione dall'eliminazione del database. L'emulatore accetta il campo enable_drop_protection, ma consente l'eliminazione dei database anche se questa proprietà è abilitata.

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

  • I messaggi di errore potrebbero essere diversi 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.
  • L'emulatore supporta DML partizionato e partitionQuery, ma non verifica che le istruzioni siano partizionabili. Ciò significa che un'istruzione DML o partitionQuery partizionata potrebbe essere eseguita nell'emulatore, ma 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 file README su GitHub.

Opzioni per l'esecuzione dell'emulatore

Esistono due modi comuni per eseguire l'emulatore:

Scegli il modo più appropriato per lo sviluppo delle applicazioni e il flusso di lavoro di test.

Esegui l'emulatore utilizzando gcloud CLI

Per eseguire l'emulatore utilizzando gcloud CLI:

  1. Installa il componente cloud-spanner-emulator:

    gcloud components install cloud-spanner-emulator

    Se gcloud CLI è già installata, esegui questo comando per assicurarti che tutti i suoi componenti siano aggiornati:

    gcloud components update

  2. Avvia l'emulatore:

    gcloud emulators spanner start

    L'emulatore utilizza due endpoint locali:

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

Esegui l'emulatore utilizzando Docker

Per eseguire l'emulatore utilizzando Docker:

  1. Installa Docker sul tuo 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 nel container alle stesse porte sul tuo host locale. L'emulatore utilizza due endpoint locali: localhost:9010 per le richieste gRPC e localhost:9020 per le richieste REST.

Configura gcloud CLI per utilizzare l'emulatore

Per utilizzare l'emulatore con gcloud CLI, disattiva l'autenticazione e esegui l'override dell'endpoint. Crea una configurazione gcloud CLI separata per passare rapidamente dall'emulatore al servizio di produzione.

  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/

  2. Una volta configurata, gcloud CLI invia i comandi all'emulatore anziché al servizio di produzione. Verifica creando un'istanza con la configurazione dell'istanza dell'emulatore:

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

Cambia configurazioni

Per passare dall'emulatore alla configurazione predefinita, esegui:

# To switch to default (production) configuration:
gcloud config configurations activate default

# To switch back to emulator configuration:
gcloud config configurations activate emulator

Utilizza 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

All'avvio dell'applicazione, la libreria client verifica automaticamente la presenza di SPANNER_EMULATOR_HOST e si connette all'emulatore se è in esecuzione.

Una volta impostata 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#, specifica 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. L'esempio seguente mostra la stringa di connessione:

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