Emula Spanner localmente

Il gcloud CLI fornisce un emulatore locale in memoria per sviluppare e testare le applicazioni. Poiché l'emulatore archivia i dati solo in memoria, perde tutto lo stato, inclusi dati, schema e configurazioni, al riavvio. 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 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 (IAM), 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.
  • Uno qualsiasi degli strumenti di logging e monitoraggio di controllo.
  • 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 differisce 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 partizionata o partitionQuery potrebbe essere eseguita nell'emulatore, ma non 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 flusso di lavoro di sviluppo e test dell'applicazione.

Eseguire l'emulatore utilizzando gcloud CLI

Per eseguire l'emulatore utilizzando Google Cloud CLI:

  1. Installa il componente cloud-spanner-emulator:

    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

  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

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

Configurare gcloud CLI per utilizzare l'emulatore

Per utilizzare l'emulatore con gcloud CLI, disattiva l'autenticazione ed 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 configurato, gcloud CLI invia i comandi all'emulatore anziché al servizio di produzione. Verifica questa operazione creando un'istanza con la configurazione dell'istanza dell'emulatore:

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

Cambiare 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

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

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