Emula Spanner localmente

gcloud CLI fornisce un emulatore in memoria locale, che puoi utilizzare per sviluppare e testare le tue applicazioni gratuitamente senza creare un progetto Google Cloud o account di fatturazione. Poiché l'emulatore archivia i dati solo in memoria, tutti gli stati, inclusi dati, schema e configurazioni, va perso al riavvio. L'emulatore offre le stesse API del servizio di produzione Spanner ed è previsto per lo sviluppo e i test locali, non per i deployment di produzione.

L'emulatore supporta sia GoogleSQL che PostgreSQL dialetti. Supporta tutte le lingue delle librerie client. Puoi anche usare l'emulatore con Google Cloud CLI e 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 anche dal servizio di produzione Spanner per nei seguenti modi:

  • I messaggi di errore potrebbero non essere coerenti tra l'emulatore e la produzione completamente gestito di Google Cloud.
  • Le prestazioni e la scalabilità dell'emulatore non sono paragonabili alla un servizio di produzione.
  • Le transazioni di lettura/scrittura e le modifiche allo schema bloccheranno l'intero database per l'accesso esclusivo fino al loro completamento.
  • DML partizionata e query di partizione sono supportati, ma l'emulatore non verifica che le istruzioni siano partizionabile. Ciò significa che un'istruzione DML partizionata o Query di partizione potrebbe essere eseguito nell'emulatore, ma potrebbe non riuscire nel servizio di produzione non partizionabile.

Per un elenco completo delle API e delle funzionalità supportate, non supportate e sono parzialmente supportati, README in GitHub.

Installa ed esegui l'emulatore

I due modi più comuni per eseguire l'emulatore sono utilizzare gcloud CLI e Docker. Puoi scegliere il modo più appropriato per lo sviluppo delle tue applicazioni e flusso di lavoro di test.

Interfaccia a riga di comando gcloud

  1. Installa l'interfaccia a riga di comando gcloud.

  2. Per gli utenti di Windows e MacOS, l'emulatore è necessario installare Docker sul sistema e disponibili sul percorso di sistema.

  3. Aggiorna gcloud per ottenere l'ultima versione:

    gcloud components update

  4. Avvia l'emulatore:

    gcloud emulators spanner start

    Se l'emulatore non è già installato, ti verrà chiesto di scaricarlo e installo il programma binario dell'emulatore.

    Per impostazione predefinita, l'emulatore ospita due endpoint locali: localhost:9010 per Richieste gRPC e localhost:9020 per le richieste REST.

    Per ulteriori dettagli su vedi gcloud emulators spanner.

Docker

  1. Assicurati che Docker sia installata sul sistema e disponibile nel percorso di sistema.

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

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

  3. Avvia l'emulatore:

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

Utilizza gcloud CLI con l'emulatore

Per utilizzare l'emulatore con gcloud, devi disattivare l'autenticazione e sostituire l'endpoint.

Ti consigliamo di creare una configurazione gcloud separata, in modo da poter passare rapidamente dall'emulatore al servizio di produzione e viceversa. Per creare e attivare una configurazione dell'emulatore, esegui:

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 verranno inviati all'emulatore anziché il servizio di produzione. Puoi verificarlo creando un'istanza con 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]

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. Ci sono 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.

Dopo aver impostato SPANNER_EMULATOR_HOST, puoi testare l'emulatore seguendo le istruzioni riportate in di seguito sono riportate alcune guide introduttive. Puoi ignorare le istruzioni relative al progetto creazione, autenticazione e credenziali poiché non sono necessarie per utilizzare un emulatore.

Versioni supportate

La tabella seguente elenca le versioni delle librerie client che supportano l'emulatore.

Libreria client Versione minima
C++ Versione 0.9.x+
C# Versione 3.1.0 e successive
Vai Versione 1.5.0 e successive
Java Versione 1.51.0 e successive
Node.js Versione 4.5.0 o successiva
PHP Versione 1.25.0 e successive
Python Versione 1.15.0 e successive
Ruby Versione 1.13.0 e successive

Istruzioni aggiuntive per C#

Per la libreria client C#, devi specificare anche il parametro emulatordetection nella stringa di connessione. A differenza delle altre librerie client, C# ignora SPANNER_EMULATOR_HOST variabile di ambiente per impostazione predefinita. Ecco come fare:

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