Obiettivi
Questo tutorial illustra i passaggi seguenti utilizzando Spanner libreria client per Go:
- Crea un'istanza e un database Spanner.
- Scrivere, leggere ed eseguire query SQL sui dati nel database.
- Aggiorna lo schema del database.
- Aggiornare i dati utilizzando una transazione di lettura/scrittura.
- Aggiungi un indice secondario al database.
- Utilizza l'indice per leggere ed eseguire query SQL sui dati.
- Recupera i dati utilizzando una transazione di sola lettura.
Costi
Questo tutorial utilizza Spanner, che è un componente fatturabile del in Google Cloud. Per informazioni sul costo di utilizzo di Spanner, consulta Prezzi.
Prima di iniziare
Completa i passaggi descritti in Configurazione, che riguardano la creazione e la configurazione 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 utilizzare l'API Cloud Spanner.
In particolare, assicurati di eseguire gcloud auth
application-default login
per configurare l'ambiente di sviluppo locale con le credenziali di autenticazione.
Prepara l'ambiente Go locale
Installa Go (scarica) sul tuo sviluppo se non è già installata.
Configura la variabile di ambiente
GOPATH
, se non è già configurata. come descritto in Verifica l'installazione.Scarica i campioni sulla tua macchina.
git clone https://github.com/GoogleCloudPlatform/golang-samples $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples
Passa alla directory che contiene il codice di esempio di Spanner:
cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/spanner/spanner_snippets
Imposta la variabile di ambiente
GCLOUD_PROJECT
sul tuo progetto Google Cloud ID:export GCLOUD_PROJECT=[MY_PROJECT_ID]
Crea un'istanza
Quando utilizzi Spanner per la prima volta, devi creare un'istanza, ovvero delle risorse usate dai database Spanner. Quando crei un'istanza, scegli una configurazione dell'istanza, che determina dove vengono archiviati i dati e anche il numero di nodi da utilizzare, che determina la quantità di risorse di gestione e archiviazione nell'istanza.
Esegui il seguente comando per creare un'istanza Spanner nella regione
us-central1
con 1 nodo:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
Tieni presente che viene creata un'istanza con le seguenti caratteristiche:
- ID istanza
test-instance
- Nome visualizzato
Test Instance
- Configurazione istanza
regional-us-central1
(archivio configurazioni regionali i dati in una regione, mentre le configurazioni multiregionali distribuiscono i dati in più regioni. Per ulteriori informazioni, consulta Informazioni sulle istanze. - Un conteggio dei nodi pari a 1 (
node_count
) corrisponde alla quantità di risorse di gestione e archiviazione disponibili per i database nell'istanza. Scopri di più in Nodi e unità di elaborazione.
Dovresti vedere:
Creating instance...done.
Esamina i file di esempio
Il repository di esempi contiene un esempio che mostra come utilizzare Spanner con Go.
Dai un'occhiata al filesnippet.go
, che spiega come utilizzare
Spanner. Il codice mostra come creare e utilizzare un nuovo database. I dati
utilizzano lo schema di esempio mostrato nella
pagina Schema e modello dati.
Crea un database
Crea un database denominato example-db
nell'istanza test-instance
eseguendo quanto segue nella riga di comando.
GoogleSQL
go run snippet.go createdatabase projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
PostgreSQL
go run snippet.go pgcreatedatabase projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti vedere:
Created database [example-db]
GoogleSQL
PostgreSQL
Il passaggio successivo è scrivere dati nel database.
Crea un client di database
Prima di poter eseguire operazioni di lettura o scrittura, devi creare unClient
:
Puoi considerare Client
come una connessione a un database: tutte le tue interazioni
con Spanner deve passare attraverso un Client
. In genere, crei un Client
all'avvio dell'applicazione, quindi lo riutilizzi per leggere, scrivere
ed eseguire transazioni. Ogni client utilizza le risorse di Spanner.
Se crei più client nella stessa app, devi chiamare
Client.Close()
per ripulire
le risorse del client, incluse le connessioni di rete, non appena non sono più necessarie.
Scopri di più nel riferimento Client
.
Il codice dell'esempio precedente mostra anche come creare un oggetto
DatabaseAdminClient
,
che viene utilizzato per creare un database.
Scrivi dati con DML
Puoi inserire dati utilizzando il linguaggio Data Manipulation Language (DML) in una transazione di lettura/scrittura.
Utilizzi il metodo Update()
per eseguire un'istruzione DML.
GoogleSQL
PostgreSQL
Esegui il sample utilizzando l'argomento dmlwrite
per Google SQL e l'argomento pgdmlwrite
per PostgreSQL:
GoogleSQL
go run snippet.go dmlwrite projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
PostgreSQL
go run snippet.go pgdmlwrite projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti vedere:
4 record(s) inserted.
Scrivere dati con mutazioni
Puoi anche inserire i dati utilizzando le mutazioni.
Un Mutation
è un contenitore per le operazioni di mutazione. Un Mutation
rappresenta una sequenza di inserimenti, aggiornamenti ed eliminazioni che Spanner applica in modo atomico a righe e tabelle diverse in un database Spanner.
Utilizza Mutation.InsertOrUpdate()
per creare una mutazione INSERT_OR_UPDATE
, che aggiunge una nuova riga o aggiornamenti
i valori della colonna se la riga esiste già. In alternativa, utilizza
Mutation.Insert()
per creare una mutazione INSERT
, che aggiunge una nuova riga.
Client.Apply()
applica
le mutazioni in modo atomico a un database.
Questo codice mostra come scrivere i dati utilizzando le mutazioni:
Esegui l'esempio utilizzando l'argomento write
:
go run snippet.go write projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti vedere che il comando viene eseguito correttamente.
Esegui query sui dati utilizzando SQL
Spanner supporta un'interfaccia SQL per la lettura dei dati, che puoi l'accesso dalla riga di comando utilizzando Google Cloud CLI in modo programmatico utilizzando la libreria client di Spanner per Go.
Nella riga di comando
Esegui questa istruzione SQL per leggere i valori di tutte le colonne dalla
Tabella Albums
:
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
Il risultato dovrebbe essere:
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Usa la libreria client Spanner per Go
Oltre a eseguire un'istruzione SQL sulla riga di comando, puoi inviare la stessa istruzione SQL in modo programmatico mediante la libreria client Spanner per Vai.
Per eseguire la query SQL vengono utilizzati i seguenti metodi e tipi:Client.Single()
: da utilizzare per leggere il valore di una o più colonne da una o più righe in una tabella Spanner.Client.Single
restituisce unReadOnlyTransaction
, che viene utilizzato per eseguire un'istruzione di lettura o SQL.ReadOnlyTransaction.Query()
: utilizza questo metodo per eseguire una query su un database.- Il tipo
Statement
: utilizzalo per costruire una query SQL stringa. - Il tipo
Row
: da utilizzare per accedere ai dati restituiti da un'istruzione SQL o una chiamata di lettura.
Ecco come inviare la query e accedere ai dati:
Esegui l'esempio utilizzando l'argomento query
.
go run snippet.go query projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti vedere il seguente risultato:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Esegui una query utilizzando un parametro SQL
Se la tua applicazione ha una query eseguita di frequente, puoi migliorarne le prestazioni parametrizzandola. La query parametrica risultante può essere memorizzata nella cache e riutilizzata, riduce i costi di compilazione. Per ulteriori informazioni, consulta Utilizzare i parametri di query per velocizzare le query eseguite di frequente.
Ecco un esempio di utilizzo di un parametro nella clausola WHERE
per eseguire query sui record contenenti un valore specifico per LastName
.
GoogleSQL
PostgreSQL
Esegui il sample utilizzando l'argomento querywithparameter
per Google SQL e l'argomento pgqueryparameter
per PostgreSQL.
GoogleSQL
go run snippet.go querywithparameter projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
PostgreSQL
go run snippet.go pgqueryparameter projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti visualizzare un output simile al seguente:
12 Melissa Garcia
Leggere i dati utilizzando l'API di lettura
Oltre all'interfaccia SQL di Spanner, Spanner supporta anche una di lettura.
UtilizzaReadOnlyTransaction.Read()
per leggere le righe dal database. Utilizza KeySet
per definire una raccolta di chiavi e intervalli di chiavi da leggere.
Ecco come leggere i dati:
Esegui l'esempio utilizzando l'argomento read
.
go run snippet.go read projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti visualizzare un output simile al seguente:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Aggiorna lo schema del database
Supponiamo che tu debba aggiungere una nuova colonna denominata MarketingBudget
alla tabella Albums
. L'aggiunta di una nuova colonna a una tabella esistente richiede un aggiornamento dello schema del database. Spanner supporta gli aggiornamenti dello schema di un database mentre il database continua a gestire il traffico. Gli aggiornamenti dello schema non richiedono il mettere offline il database e non bloccano intere tabelle o colonne. Puoi continuare a scrivere dati nel database durante l'aggiornamento dello schema. Scopri di più sugli aggiornamenti dello schema supportati e sul rendimento delle modifiche dello schema in Eseguire aggiornamenti dello schema.
Aggiungi una colonna
Puoi aggiungere una colonna sulla riga di comando utilizzando Google Cloud CLI o programmaticamente utilizzando la libreria client Spanner per Go.
Nella riga di comando
Utilizza il seguente comando ALTER TABLE
per
aggiungere la nuova colonna alla tabella:
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget BIGINT'
Dovresti vedere:
Schema updating...done.
Utilizzare la libreria client Spanner per Go
UtilizzaDatabaseAdminClient.UpdateDatabaseDdl()
per modificare lo schema:
GoogleSQL
PostgreSQL
Esegui l'esempio utilizzando l'argomento addnewcolumn
per Google SQL e l'argomento pgaddnewcolumn
per PostgreSQL.
GoogleSQL
go run snippet.go addnewcolumn projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
PostgreSQL
go run snippet.go pgaddnewcolumn projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti vedere:
Added MarketingBudget column.
Scrivi i dati nella nuova colonna
Il seguente codice scrive i dati nella nuova colonna. Imposta MarketingBudget
su
100000
per la riga con chiave Albums(1, 1)
e in 500000
per la riga con chiave
di Albums(2, 2)
.
Esegui l'esempio utilizzando l'argomento update
.
go run snippet.go update projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Puoi anche eseguire una query SQL o una chiamata di lettura per recuperare i valori appena scritti.
Ecco il codice per eseguire la query:
GoogleSQL
PostgreSQL
Per eseguire questa query, esegui l'esempio utilizzando l'argomento querynewcolumn
per Google SQL e l'argomento pgquerynewcolumn
per PostgreSQL.
GoogleSQL
go run snippet.go querynewcolumn projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
PostgreSQL
go run snippet.go pgquerynewcolumn projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti vedere:
1 1 100000
1 2 NULL
2 1 NULL
2 2 500000
2 3 NULL
Aggiorna dati
Puoi aggiornare i dati utilizzando DML in una transazione di lettura/scrittura.
Utilizzi il metodo Update()
per eseguire un'istruzione DML.
GoogleSQL
PostgreSQL
Esegui l'esempio utilizzando l'argomento dmlwritetxn
.
go run snippet.go dmlwritetxn projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti vedere:
Moved 200000 from Album2's MarketingBudget to Album1's.
Utilizzare un indice secondario
Supponiamo che tu voglia recuperare tutte le righe di Albums
con valori AlbumTitle
in un determinato intervallo. Puoi leggere tutti i valori dalla colonna AlbumTitle
utilizzando
un'istruzione SQL o una chiamata di lettura, quindi ignora le righe che non soddisfano le
ma l'esecuzione di questa scansione completa della tabella è costosa, soprattutto per le tabelle
con molte righe. Puoi accelerare il recupero delle righe quando
Cercare in base a colonne non di chiave primaria creando un
indice secondario nella tabella.
L'aggiunta di un indice secondario a una tabella esistente richiede un aggiornamento dello schema. Come per gli altri aggiornamenti dello schema, Spanner supporta l'aggiunta di un indice mentre il database continua a gestire il traffico. Spanner esegue automaticamente il backfill l'indicizzazione con i dati esistenti. Il completamento dei backfill potrebbe richiedere alcuni minuti ma non è necessario mettere offline il database o evitare di scrivere nell'elenco durante questo processo. Per maggiori dettagli, consulta Aggiungere un indice secondario.
Dopo aver aggiunto un indice secondario, Spanner lo utilizza automaticamente per le query SQL che potrebbero essere eseguite più velocemente con l'indice. Se utilizzi lo strumento devi specificare l'indice che vuoi utilizzare.
Aggiungere un indice secondario
Puoi aggiungere un indice sulla riga di comando utilizzando la CLI gcloud o programmaticamente utilizzando la libreria client Spanner per Go.
Nella riga di comando
Utilizza il seguente comando CREATE INDEX
per aggiungere un indice al database:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
Dovresti vedere:
Schema updating...done.
Utilizzo della libreria client Spanner per Go
UsaUpdateDatabaseDdl()
per aggiungere un indice:
L'aggiunta di un indice può richiedere alcuni minuti. Dopo aver aggiunto l'indice, dovresti vedere:
Added index
Lettura utilizzando l'indice
Per le query SQL, Spanner utilizza automaticamente un indice appropriato. Nell'interfaccia di lettura, devi specificare l'indice nella richiesta.
Per utilizzare l'indice nell'interfaccia di lettura, utilizza
ReadOnlyTransaction.ReadUsingIndex()
, che indica zero o
più righe da un database utilizzando un indice.
Il codice seguente recupera tutte le colonne AlbumId
e AlbumTitle
dall'indice AlbumsByAlbumTitle
.
Esegui l'esempio utilizzando l'argomento readindex
.
go run snippet.go readindex projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti vedere:
2 Forever Hold Your Peace
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk
Aggiungi un indice per le letture solo dell'indice
Potresti aver notato che l'esempio di lettura precedente non include la lettura
la colonna MarketingBudget
. Questo perché l'interfaccia di lettura di Spanner
non supporta la possibilità di unire un indice a una tabella di dati per cercare valori
che non sono archiviati nell'indice.
Crea una definizione alternativa di AlbumsByAlbumTitle
che memorizzi una copia di
MarketingBudget
nell'indice.
Nella riga di comando
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (MarketingBudget)
L'aggiunta di un indice può richiedere alcuni minuti. Una volta aggiunto l'indice, consulta:
Schema updating...done.
Utilizzo della libreria client Spanner per Go
UtilizzaUpdateDatabaseDdl()
per aggiungere un indice con una clausola STORING
per GoogleSQL e una clausola INCLUDE
per PostgreSQL:
GoogleSQL
PostgreSQL
Esegui l'esempio utilizzando l'argomento addstoringindex
.
GoogleSQL
go run snippet.go addstoringindex projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
PostgreSQL
go run snippet.go pgaddstoringindex projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
L'aggiunta di un indice può richiedere alcuni minuti. Dopo aver aggiunto l'indice, dovresti vedere:
Added storing index
Ora puoi eseguire una lettura che recupera tutti i valori AlbumId
, AlbumTitle
e
MarketingBudget
colonne dall'indice AlbumsByAlbumTitle2
:
Esegui l'esempio utilizzando l'argomento readstoringindex
.
go run snippet.go readstoringindex projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti visualizzare un output simile al seguente:
2 Forever Hold Your Peace 300000
2 Go, Go, Go NULL
1 Green NULL
3 Terrified NULL
1 Total Junk 300000
Recuperare i dati utilizzando le transazioni di sola lettura
Supponiamo di voler eseguire più di una lettura per lo stesso timestamp. Le transazioni di sola lettura osservano un prefisso coerente della cronologia dei commit delle transazioni, in modo che l'applicazione riceva sempre dati coerenti.
Utilizza la ReadOnlyTransaction
per l'esecuzione di transazioni di sola lettura. Utilizza
Client.ReadOnlyTransaction()
per ricevere un ReadOnlyTransaction
.
Di seguito viene illustrato come eseguire una query ed eseguire una lettura nella stessa sessione transazione:
Esegui l'esempio utilizzando l'argomento readonlytransaction
.
go run snippet.go readonlytransaction projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db
Dovresti visualizzare un output simile al seguente:
2 2 Forever Hold Your Peace
1 2 Go, Go, Go
2 1 Green
2 3 Terrified
1 1 Total Junk
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Esegui la pulizia
Per evitare che al tuo account di fatturazione Cloud vengano addebitati costi aggiuntivi per le risorse utilizzate in questo tutorial, elimina il database ed elimina l'istanza che hai creato.
Elimina il database
Se elimini un'istanza, tutti i database al suo interno vengono eliminati automaticamente. Questo passaggio mostra come eliminare un database senza eliminare un'istanza (per l'istanza verranno comunque addebitati costi).
Nella riga di comando
gcloud spanner databases delete example-db --instance=test-instance
Utilizzo della console Google Cloud
Vai alla pagina Istanze Spanner nella console Google Cloud.
Fai clic sull'istanza.
Fai clic sul database che vuoi eliminare.
Nella pagina Dettagli database, fai clic su Elimina.
Conferma di voler eliminare il database e fai clic su Elimina.
Elimina l'istanza
L'eliminazione di un'istanza comporta automaticamente l'eliminazione di tutti i database creati in quell'istanza.
Nella riga di comando
gcloud spanner instances delete test-instance
Utilizzo della console Google Cloud
Vai alla pagina Istanze Spanner nella console Google Cloud.
Fai clic sull'istanza.
Fai clic su Elimina.
Conferma di voler eliminare l'istanza e fai clic su Elimina.
Passaggi successivi
Scopri come accedere a Spanner con un'istanza di macchina virtuale.
Scopri di più sulle credenziali di autorizzazione e autenticazione in Eseguire l'autenticazione per i servizi Cloud utilizzando le librerie client.
Scopri di più sulle best practice per la progettazione dello schema di Spanner.