gcloud CLI fornisce un emulatore locale in memoria che puoi utilizzare per sviluppare e testare le tue applicazioni gratuitamente senza creare un progetto Google Cloud o un account di fatturazione. Poiché l'emulatore archivia i dati solo in memoria, tutto lo stato, inclusi dati, schema e configurazioni, andrà perso 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 i dialetti GoogleSQL e PostgreSQL. Supporta tutti i linguaggi delle librerie client. Puoi utilizzare l'emulatore anche con Google Cloud CLI e le API REST.
L'emulatore è disponibile anche come progetto open source in GitHub.
Limitazioni e differenze
L'emulatore non supporta quanto segue:
- TLS/HTTPS, autenticazione, IAM, autorizzazioni o ruoli.
- Modalità di query
PLAN
oPROFILE
. Supporta soloNORMAL
. - L'istruzione
ANALYZE
. L'emulatore accetta, ma lo ignora. - Uno qualsiasi degli strumenti di audit logging e monitoraggio.
L'emulatore si differenzia dal servizio di produzione Spanner anche 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 bloccheranno l'intero database per l'accesso esclusivo fino al completamento.
- DML partizionato e Query sulle partizioni sono supportati, ma l'emulatore non controlla che le istruzioni siano partizionabili. Ciò significa che un'istruzione DML partizionata o Query sulle partizioni potrebbe essere eseguita nell'emulatore, ma potrebbe restituire un errore nel servizio di produzione con un errore di istruzione non partizionabile.
Per un elenco completo delle API e delle funzionalità supportate, non supportate e parzialmente supportate, vedi il file README in GitHub.
Installa ed esegui l'emulatore
I due modi più comuni per eseguire l'emulatore sono utilizzando gcloud CLI e Docker. Puoi scegliere il modo appropriato per il flusso di lavoro di sviluppo e test delle applicazioni.
Interfaccia a riga di comando gcloud
Per gli utenti di Windows e MacOS, l'emulatore richiede che Docker sia installato sul sistema e sia disponibile nel percorso del sistema.
Aggiorna
gcloud
per ottenere l'ultima versione:gcloud components update
Avvia l'emulatore:
gcloud emulators spanner start
Se l'emulatore non è già installato, ti verrà chiesto di scaricare e installare il programma binario dell'emulatore.
Per impostazione predefinita, l'emulatore ospita due endpoint locali:
localhost:9010
per le richieste gRPC elocalhost:9020
per le richieste REST.Per maggiori dettagli su questo comando, vedi gcloud emulators spanner.
Docker
Assicurati che Docker sia installato sul sistema e disponibile nel percorso del sistema.
Scarica l'immagine dell'emulatore più recente:
docker pull gcr.io/cloud-spanner-emulator/emulator
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 alle stesse porte dell'host locale. Avrai due endpoint locali:
localhost:9010
per le richieste gRPC elocalhost:9020
per le richieste REST.
Utilizza gcloud CLI con l'emulatore
Per utilizzare l'emulatore con gcloud, devi disabilitare l'autenticazione ed eseguire l'override dell'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 di 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é al servizio di produzione. Puoi verificarlo creando un'istanza con la configurazione delle istanze dell'emulatore:
gcloud spanner instances create test-instance \
--config=emulator-config --description="Test Instance" --nodes=1
Per passare dall'emulatore alla configurazione predefinita, 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
.
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
All'avvio dell'applicazione, la libreria client controlla automaticamente la presenza di SPANNER_EMULATOR_HOST
e si connette all'emulatore, se è in esecuzione.
Dopo aver configurato SPANNER_EMULATOR_HOST
, puoi testare l'emulatore seguendo le guide introduttive riportate di seguito. Puoi ignorare le istruzioni relative alla creazione, all'autenticazione e alle credenziali del progetto perché non sono necessarie per utilizzare l'emulatore.
Guida introduttiva a C#. Devi impostare le opzioni della stringa di connessione. Consulta le istruzioni aggiuntive per C#.
Versioni supportate
Nella tabella seguente sono elencate le versioni delle librerie client che supportano l'emulatore.
Libreria client | Versione minima |
---|---|
C++ | v0.9.x+ |
C# | Versione 3.1.0 e successive |
Go | 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 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. Ecco come fare:
var builder = new SpannerConnectionStringBuilder
{
DataSource = $"projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
EmulatorDetection = "EmulatorOnly"
};