Crea ed esegui query su un database utilizzando Google Cloud CLI

Obiettivi

Questo tutorial illustra i seguenti passaggi utilizzando gcloud CLI:

• Crea un'istanza, un database e uno schema Spanner
• Scrivere dati nel database ed eseguire query SQL su questi dati
• Esegui la pulizia eliminando il database e l'istanza

Le procedure riportate in questa pagina si applicano sia ai database con dialetto Google SQL sia a quelli con dialetto PostgreSQL.

Per il riferimento completo di Spanner gcloud, consulta gcloud.

Nota: per esplorare Spanner utilizzando un'istanza di prova gratuita di 90 giorni, consulta Creare un'istanza di prova gratuita di Spanner.

Prezzi

Questo tutorial utilizza Spanner, un componente fatturabile di Google Cloud. Per informazioni sul costo dell'utilizzo di Spanner, consulta Prezzi.

Prima di iniziare

Completa i passaggi descritti in Installa l'interfaccia a riga di comando gcloud e configura l'API Cloud Spanner, che illustrano la creazione e l'impostazione di un progetto Google Cloud predefinito, l'attivazione della fatturazione, l'attivazione dell'API Cloud Spanner e la configurazione di OAuth 2.0 per ottenere le credenziali di autenticazione per l'utilizzo dell'API Cloud Spanner.

In particolare, assicurati di eseguire gcloud auth application-default login per configurare il tuo ambiente di sviluppo locale con le credenziali di autenticazione.

Impostare un progetto predefinito

Se non l'hai già fatto, imposta l'ID di un progetto Google Cloud come progetto predefinito per Google Cloud CLI:

gcloud config set project PROJECT_ID

Se non imposti il progetto predefinito, devi passare --project PROJECT_ID a ciascuno dei comandi riportati di seguito come primo argomento per gcloud. Ad esempio:

gcloud --project=PROJECT_ID instance-configs list

Istanze

Quando utilizzi Spanner per la prima volta, devi creare un'istanza, ovvero un'allocazione delle risorse utilizzate dai database Spanner. Quando crei un'istanza, scegli dove vengono archiviati i dati e la capacità di calcolo dell'istanza.

Istanze e configurazioni delle istanze

Per creare un'istanza, devi selezionare una configurazione dell'istanza, che è come un modello per l'istanza che definisce il posizionamento geografico e la replica dei dati di Spanner.

Elenca le configurazioni delle istanze

Quando crei un'istanza, specifichi una configurazione dell'istanza, che definisce il posizionamento geografico e la replica dei tuoi database nell'istanza. Puoi scegliere una configurazione regionale, che archivia i dati in una regione, una a due regioni, che archivia i dati in due regioni dello stesso paese, o una configurazione multiregionale, che distribuisce i dati in più regioni. Per ulteriori informazioni, consulta la panoramica delle istanze.

Per visualizzare l'insieme di configurazioni delle istanze disponibili per il tuo progetto:

gcloud instance-configs list

Dovresti visualizzare un elenco di configurazioni a livello di una o più regioni, a due regioni e multiregionali.

Crea un'istanza

Per creare un'istanza denominata test-instance con il nome visualizzato My Instance utilizzando la configurazione dell'istanza regionale regional-us-central1 con 1 nodo:

gcloud instances create test-instance --config=regional-us-central1 \
    --description="My Instance" --nodes=1

Nel comando precedente, il nome dell'istanza è impostato su test-instance e --description imposta il nome visualizzato dell'istanza. Entrambi questi valori devono essere univoci all'interno di un progetto Google Cloud.

Nota: utilizza l'ID istanza, non il nome visualizzato, quando fai riferimento a un'istanza nei comandi gcloud.

Impostare l'istanza predefinita

Puoi impostare l'istanza predefinita utilizzata da Spanner quando non hai specificato un'istanza nel comando. Per impostare l'istanza predefinita:

gcloud config set spanner/instance test-instance

Crea un database

Crea un database denominato example-db. Il dialetto del database predefinito è GoogleSQL.

GoogleSQL

gcloud databases create example-db

PostgreSQL

gcloud databases create example-db --database-dialect=POSTGRESQL

Aggiorna lo schema

Utilizza il Data Definition Language (DDL) di Spanner per creare, modificare o eliminare tabelle e per creare o eliminare indici.

Creiamo due tabelle:

GoogleSQL

gcloud databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId INT64 NOT NULL, FirstName STRING(1024), LastName STRING(1024), SingerInfo BYTES(MAX) ) PRIMARY KEY (SingerId)'

gcloud databases ddl update example-db \
--ddl='CREATE TABLE Albums ( SingerId INT64 NOT NULL, AlbumId INT64 NOT NULL, AlbumTitle STRING(MAX)) PRIMARY KEY (SingerId, AlbumId), INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

PostgreSQL

gcloud databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId bigint NOT NULL, FirstName varchar(1024), LastName varchar(1024), SingerInfo bytea, PRIMARY KEY (SingerId) )'

gcloud databases ddl update example-db \
--ddl='CREATE TABLE Albums ( SingerId bigint NOT NULL, AlbumId bigint NOT NULL, AlbumTitle varchar, PRIMARY KEY (SingerId, AlbumId) ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

Per controllare l'avanzamento dell'operazione, utilizza gcloud operations describe. Questo comando richiede l'ID operazione.

Recupera l'ID operazione:

gcloud operations list --instance="test-instance" \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

Sostituisci DATABASE-NAME con il nome del database.

Esegui gcloud operations describe:

gcloud operations describe \
  --instance="test-instance" \
  --database="example-db" \
  projects/PROJECT-NAME/instances/test-instance/databases/example-db/operations/OPERATION-ID

Sostituisci quanto segue:

• PROJECT-NAME: il nome del progetto.
• OPERATION-ID: l'ID operazione dell'operazione da controllare.

L'output è simile al seguente:

done: true
metadata:
...
progress:
- endTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
  startTime: '2022-03-01T00:28:04.221401Z'
- endTime: '2022-03-01T00:28:17.624588Z'
  startTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
...

Scrivi dati

Aggiungiamo alcuni dati di esempio al nostro database

GoogleSQL

gcloud rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=1,FirstName=Marc,LastName=Richards

gcloud rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=2,FirstName=Catalina,LastName=Smith

gcloud rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=3,FirstName=Alice,LastName=Trentor

gcloud rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=1,AlbumId=1,AlbumTitle="Total Junk"

gcloud rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=2,AlbumId=1,AlbumTitle="Green"

gcloud rows insert --database=example-db \
  --table=Albums \
  --data=^:^SingerId=2:AlbumId=2:AlbumTitle="Go, Go, Go"

Per impostazione predefinita, viene utilizzata una virgola per delimitare gli elementi negli elenchi. Nell'ultimo comando insert abbiamo specificato due punti (^:^) come delimitatore per poter utilizzare una virgola nel titolo dell'album.

PostgreSQL

Nota: è noto un problema per cui gcloud CLI non riesce a cercare i nomi delle tabelle quando si utilizzano le mutazioni per scrivere dati in un database PostgreSQL. Pertanto, devi utilizzare DML per inserire i dati.

gcloud databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')"

gcloud databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (2, 'Catalina', 'Smith')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (3, 'Alice', 'Trentor')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (1, 1, 'Total Junk')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 1, 'Green')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 2, 'Go, Go, Go')"

Esegui query sui dati utilizzando SQL

Esegui una query sulla riga di comando:

gcloud databases execute-sql example-db \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

Per la documentazione di riferimento di Spanner SQL, consulta Sintassi delle query per GoogleSQL o Sintassi delle query per PostgreSQL.

Per visualizzare un elenco di flag che puoi utilizzare con il comando execute-sql, consulta gcloud databases execute-sql.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi aggiuntivi per le risorse utilizzate in questo tutorial, elimina il database ed elimina l'istanza che hai creato.

Eliminare un database

Per eliminare un'istanza esistente:

gcloud databases delete example-db

Elimina un'istanza

Per eliminare un'istanza esistente:

gcloud instances delete test-instance

Tieni presente che l'eliminazione di un'istanza comporta anche l'eliminazione di tutti i database al suo interno. L'eliminazione di un'istanza non è reversibile.