Obiettivi
Questo tutorial illustra i passaggi seguenti utilizzando la libreria client di Spanner per C++:
- Creare 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 di Google Cloud. Per informazioni sul costo di utilizzo di Spanner, consulta i prezzi.
Prima di iniziare
Completa i passaggi descritti in Configurazione, che riguardano la creazione e l'impostazione di un progetto Google Cloud predefinito, l'abilitazione della fatturazione, l'abilitazione 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 C++ locale
Clona il repository dell'app di esempio nella tua macchina locale:
git clone https://github.com/googleapis/google-cloud-cpp $HOME/google-cloud-cpp
Installa Bazel per Linux seguendo queste istruzioni.
Passa alla directory che contiene il codice campione di Spanner:
cd $HOME/google-cloud-cpp
Crea gli esempi con questo comando:
bazel build //google/cloud/spanner/samples:samples
Configura l'autenticazione e l'autorizzazione per il progetto
google-cloud-cpp
.gcloud auth application-default login
Crea una variabile di ambiente denominata
GCLOUD_PROJECT
. Sostituisci [MY_PROJECT_ID] con l'ID del tuo progetto Google Cloud. Puoi trovare questo ID nella pagina Ti diamo il benvenuto del progetto.export GCLOUD_PROJECT=[MY_PROJECT_ID]
Creazione di un'istanza
Quando utilizzi Spanner per la prima volta, devi creare un'istanza, ovvero un'allocazione di risorse utilizzate dai database Spanner. Quando crei un'istanza, scegli una configurazione dell'istanza, che determina dove sono archiviati i dati e anche il numero di nodi da utilizzare, che determina la quantità di risorse di servizio e archiviazione nell'istanza.
Esegui questo 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 dell'istanza
regional-us-central1
(le configurazioni regionali archiviano i dati in una regione, mentre le configurazioni multiregionali distribuiscono i dati in più regioni. Per ulteriori informazioni, consulta Informazioni sulle istanze. - Conteggio dei nodi pari a 1 (
node_count
corrisponde alla quantità di risorse di servizio 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 C++.
Dai un'occhiata al file google/cloud/spanner/samples/samples.cc
, che mostra come creare
un database e modificarne lo schema. I dati utilizzano lo schema di esempio mostrato nella pagina Schema e modello dei dati.
Crea un database
Crea un database denominato example-db
nell'istanza denominata test-instance
eseguendo quanto segue sulla riga di comando.
bazel run //google/cloud/spanner/samples:samples -- \
create-database $GCLOUD_PROJECT test-instance example-db
Dovresti vedere:
Created database [projects/${GCLOUD_PROJECT}/instances/test-instance/databases/example-db]
Il codice seguente crea un database e due tabelle al suo interno.
Il passaggio successivo è scrivere dati nel database.
Crea un client di database
Prima di poter eseguire operazioni di lettura o scrittura, devi creare un Client
:
Un'Client
consente di leggere, scrivere, eseguire query ed eseguire transazioni su un database Spanner. In genere crei una
Client
quando l'applicazione viene avviata, poi la riutilizzi Client
per
leggere, scrivere ed eseguire transazioni. Ogni client utilizza le risorse in
Spanner. Il distruttore di Client
eseguirà automaticamente la pulizia delle risorse Client
, incluse le connessioni di rete.
Scopri di più su Client
nella
documentazione di riferimento su C++ di Google Cloud Spanner.
Scrivi dati con DML
Puoi inserire dati utilizzando DML (Data Manipulation Language) in una transazione di lettura e scrittura.
Puoi utilizzare la funzione Client::ExecuteDml()
per eseguire un'istruzione DML.
Esegui l'esempio utilizzando l'argomento getting-started-insert
.
bazel run //google/cloud/spanner/samples:samples -- \
getting-started-insert $GCLOUD_PROJECT test-instance example-db
Dovresti vedere:
Insert was successful [spanner_dml_getting_started_insert]
Scrivere dati con mutazioni
Puoi anche inserire i dati utilizzando le mutazioni.
Scrivi i dati utilizzando un oggetto Client
. La funzione Client::Commit()
crea e sottopone a commit una transazione per le scritture eseguite atomicamente in un singolo momento logico nel tempo su colonne, righe e tabelle in un database.
Questo codice mostra come scrivere i dati utilizzando le mutazioni:
Esegui l'esempio utilizzando l'argomento insert-data
.
bazel run //google/cloud/spanner/samples:samples -- \
insert-data $GCLOUD_PROJECT test-instance example-db
Dovresti vedere:
Insert was successful [spanner_insert_data]
Eseguire query sui dati utilizzando SQL
Spanner supporta un'interfaccia SQL per la lettura dei dati, a cui puoi accedere dalla riga di comando utilizzando Google Cloud CLI o in modo programmatico utilizzando la libreria client Spanner per C++.
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 C++
Oltre a eseguire un'istruzione SQL dalla riga di comando, puoi inviare la stessa istruzione SQL in modo programmatico utilizzando la libreria client Spanner per C++.
Puoi usare la funzione Client::ExecuteQuery()
per eseguire la query SQL.
Ecco come inviare la query e accedere ai dati:
Esegui l'esempio utilizzando l'argomento query_data
.
bazel run //google/cloud/spanner/samples:samples -- \
query-data $GCLOUD_PROJECT test-instance example-db
Dovresti vedere il seguente risultato:
SingerId: 1 LastName: Richards
SingerId: 2 LastName: Smith
SingerId: 3 LastName: Trentor
SingerId: 4 LastName: Martin
SingerId: 5 LastName: Lomond
SingerId: 12 LastName: Garcia
SingerId: 13 LastName: Morales
SingerId: 14 LastName: Long
SingerId: 15 LastName: Shaw
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, riducendo i costi di compilazione. Per maggiori informazioni, consulta Utilizzare parametri di ricerca per velocizzare le query eseguite di frequente.
Ecco un esempio di utilizzo di un parametro nella clausola WHERE
per eseguire query su record contenenti un valore specifico per LastName
.
Esegui l'esempio utilizzando il comando query-with-parameter.
bazel run //google/cloud/spanner/samples:samples -- \
query-with-parameter $GCLOUD_PROJECT test-instance example-db
Dovresti vedere il seguente risultato:
SingerId: 12 FirstName: Melissa LastName: Garcia
Leggere i dati utilizzando l'API Read
Oltre all'interfaccia SQL di Spanner, Spanner supporta anche un'interfaccia di lettura.
Utilizzerai la funzione Client::Read()
per leggere le righe del database. Utilizza un oggetto 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-data
.
bazel run //google/cloud/spanner/samples:samples -- \
read-data $GCLOUD_PROJECT test-instance example-db
Dovresti visualizzare un output simile al seguente:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
Aggiorna lo schema del database
Supponi di dover 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 quest'ultimo continua a gestire il traffico. Gli aggiornamenti dello schema non richiedono la modalità offline del 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 degli schemi supportati e sulle prestazioni delle modifiche degli schemi in Eseguire aggiornamenti dello schema.
Aggiungi una colonna
Puoi aggiungere una colonna nella riga di comando utilizzando Google Cloud CLI o in modo programmatico utilizzando la libreria client Spanner per C++.
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.
Usa la libreria client Spanner per C++
Utilizza la funzione DatabaseAdminClient::UpdateDatabase()
per modificare lo schema.
Esegui l'esempio utilizzando il comando add-column
.
bazel run //google/cloud/spanner/samples:samples -- \
add-column $GCLOUD_PROJECT test-instance example-db
Dovresti vedere:
Added MarketingBudget column
Scrivi i dati nella nuova colonna
Il seguente codice scrive i dati nella nuova colonna. Consente di impostare MarketingBudget
su
100000
per la riga associata a Albums(1, 1)
e su 500000
per la riga associata
a Albums(2, 2)
.
Esegui l'esempio utilizzando l'argomento update-data
.
bazel run //google/cloud/spanner/samples:samples -- \
update-data $GCLOUD_PROJECT test-instance example-db
Puoi anche eseguire una query SQL o una chiamata di lettura per recuperare i valori che hai appena scritto.
Ecco il codice per eseguire la query:
Per eseguire questa query, esegui l'esempio utilizzando l'argomento query-new-column
.
bazel run //google/cloud/spanner/samples:samples -- \
query-new-column $GCLOUD_PROJECT test-instance example-db
Dovresti vedere:
SingerId: 1 AlbumId: 1 MarketingBudget: 100000
SingerId: 1 AlbumId: 2 MarketingBudget: NULL
SingerId: 2 AlbumId: 1 MarketingBudget: NULL
SingerId: 2 AlbumId: 2 MarketingBudget: 500000
SingerId: 2 AlbumId: 3 MarketingBudget: NULL
Aggiorna dati
Puoi aggiornare i dati utilizzando DML in una transazione di lettura/scrittura.
Puoi utilizzare la funzione Client::ExecuteDml()
per eseguire un'istruzione DML.
Esegui l'esempio utilizzando l'argomento getting-started-update
.
bazel run //google/cloud/spanner/samples:samples -- \
getting-started-update $GCLOUD_PROJECT test-instance example-db
Dovresti vedere:
Update was successful [spanner_dml_getting_started_update]
Utilizza un indice secondario
Supponiamo di voler recuperare tutte le righe di Albums
con valori AlbumTitle
in un determinato intervallo. Puoi leggere tutti i valori della colonna AlbumTitle
utilizzando
un'istruzione SQL o una chiamata di lettura, quindi ignorare le righe che non soddisfano i
criteri, ma eseguire questa analisi completa della tabella è costosa, soprattutto per le tabelle
con molte righe. In alternativa, puoi velocizzare il recupero delle righe durante la ricerca 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 altri aggiornamenti dello schema, Spanner supporta l'aggiunta di un indice mentre il database continua a gestire traffico. Spanner esegue automaticamente il backfill dell'indice con i dati esistenti. Il completamento dei backfill potrebbe richiedere alcuni minuti, ma non è necessario mettere offline il database o evitare di scrivere nella tabella indicizzata 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 hanno maggiori probabilità di essere eseguite più velocemente con l'indice. Se usi l'interfaccia di lettura, devi specificare l'indice che vuoi utilizzare.
Aggiungi un indice secondario
Puoi aggiungere un indice dalla riga di comando utilizzando gcloud CLI o in modo programmatico utilizzando la libreria client Spanner per C++.
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 C++
Puoi usare la funzione DatabaseAdminClient::UpdateDatabase()
per aggiungere un indice:
Esegui l'esempio utilizzando l'argomento add-index
.
bazel run //google/cloud/spanner/samples:samples -- \
add-index $GCLOUD_PROJECT test-instance example-db
L'aggiunta di un indice può richiedere alcuni minuti. Dopo aver aggiunto l'indice, dovresti vedere un output simile al seguente:
`AlbumsByAlbumTitle` Index successfully added, new DDL:
database: "projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db"
statements: "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"
commit_timestamps {
seconds: 1581011550
nanos: 531102000
}
Leggi 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 la funzione Client::Read()
, che legge zero o più righe da un database utilizzando un indice.
Il seguente codice recupera tutte le colonne AlbumId
e AlbumTitle
dall'indice AlbumsByAlbumTitle
.
Esegui l'esempio utilizzando l'argomento read-data-with-index
.
bazel run //google/cloud/spanner/samples:samples -- \
read-data-with-index $GCLOUD_PROJECT test-instance example-db
Dovresti vedere:
AlbumId: 2 AlbumTitle: Forever Hold Your Peace
AlbumId: 2 AlbumTitle: Go, Go, Go
AlbumId: 1 AlbumTitle: Green
AlbumId: 3 AlbumTitle: Terrified
AlbumId: 1 AlbumTitle: Total Junk
Aggiungi un indice per le letture solo dell'indice
Potresti aver notato che l'esempio di lettura precedente non include la lettura
della 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. Dopo aver aggiunto l'indice, dovresti vedere:
Schema updating...done.
Utilizzo della libreria client Spanner per C++
Puoi usare la funzione DatabaseAdminClient::UpdateDatabase()
per aggiungere un indice
con una clausola STORING
per :
Esegui l'esempio utilizzando l'argomento add-storing-index
.
bazel run //google/cloud/spanner/samples:samples -- \
add-storing-index $GCLOUD_PROJECT test-instance example-db
Dovresti vedere un output simile al seguente:
`AlbumsByAlbumTitle2` Index successfully added, new DDL:
database: "projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db"
statements: "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)"
commit_timestamps {
seconds: 1581012328
nanos: 416682000
}
Ora puoi eseguire una lettura che recupera tutte le colonne AlbumId
, AlbumTitle
e
MarketingBudget
dall'indice AlbumsByAlbumTitle2
:
Leggi i dati utilizzando l'indice di archiviazione che hai creato eseguendo una query che specifica esplicitamente l'indice:
Esegui l'esempio utilizzando l'argomento read-data-with-storing-index
.
bazel run //google/cloud/spanner/samples:samples -- \
read-data-with-storing-index $GCLOUD_PROJECT test-instance example-db
Dovresti visualizzare un output simile al seguente:
AlbumId: 2 AlbumTitle: Forever Hold Your Peace MarketingBudget: 520000
AlbumId: 2 AlbumTitle: Go, Go, Go MarketingBudget: NULL
AlbumId: 1 AlbumTitle: Green MarketingBudget: NULL
AlbumId: 3 AlbumTitle: Terrified MarketingBudget: NULL
AlbumId: 1 AlbumTitle: Total Junk MarketingBudget: 80000
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 di commit delle transazioni, in modo che l'applicazione riceva sempre dati coerenti.
Il tipo Transaction
viene utilizzato per rappresentare tutti i tipi di transazioni.
Utilizza la funzione di fabbrica MakeReadOnlyTransaction()
per creare una transazione di sola lettura.
Di seguito viene illustrato come eseguire una query ed eseguire una lettura nella stessa transazione di sola lettura:
Esegui l'esempio utilizzando l'argomento read-only-transaction
.
bazel run //google/cloud/spanner/samples:samples -- \
read-only-transaction $GCLOUD_PROJECT test-instance example-db
Dovresti visualizzare un output simile al seguente:
Read 1 results
SingerId: 2 AlbumId: 2 AlbumTitle: Forever Hold Your Peace
SingerId: 1 AlbumId: 2 AlbumTitle: Go, Go, Go
SingerId: 2 AlbumId: 1 AlbumTitle: Green
SingerId: 2 AlbumId: 3 AlbumTitle: Terrified
SingerId: 1 AlbumId: 1 AlbumTitle: Total Junk
Read 2 results
SingerId: 2 AlbumId: 2 AlbumTitle: Forever Hold Your Peace
SingerId: 1 AlbumId: 2 AlbumTitle: Go, Go, Go
SingerId: 2 AlbumId: 1 AlbumTitle: Green
SingerId: 2 AlbumId: 3 AlbumTitle: Terrified
SingerId: 1 AlbumId: 1 AlbumTitle: Total Junk
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 (i costi per l'istanza continueranno a essere addebitati).
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 elimina automaticamente tutti i database creati al suo interno.
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 sulla tua 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 una macchina virtuale.
Scopri di più sulle credenziali di autorizzazione e autenticazione in Autenticare nei servizi Cloud utilizzando librerie client.
Scopri di più sulle best practice per la progettazione dello schema di Spanner.