Obiettivi
Questo tutorial illustra i seguenti passaggi per utilizzare la libreria client Spanner per Ruby:
- 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 dell'utilizzo di Spanner, consulta i prezzi.
Prima di iniziare
Completa i passaggi descritti in Configurare, che spiegano come creare e impostare un progetto Google Cloud predefinito, abilitare la fatturazione, abilitare l'API Cloud Spanner e configurare 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 Ruby locale
Installa quanto segue sulla tua macchina di sviluppo se non è già installata:
Clona il repository dell'app di esempio nella macchina locale:
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples
In alternativa puoi scaricare l'esempio come file ZIP ed estrarlo.
Passa alla directory che contiene il codice campione di Spanner:
cd ruby-docs-samples/spanner/
Installa le dipendenze:
bundle install
Imposta la variabile di ambiente GOOGLE_CLOUD_PROJECT sul tuo ID progetto di Google Cloud Platform:
export GOOGLE_CLOUD_PROJECT=[MY_PROJECT_ID]
Crea 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 di istanza, che determina dove sono archiviati i tuoi dati, nonché il numero di nodi da utilizzare, che determina la quantità di risorse di gestione e archiviazione nell'istanza.
Esegui questo comando per creare un'istanza di 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 a livello di regione archiviano i dati in un'area geografica, mentre le configurazioni a più aree geografiche distribuiscono i dati in più aree geografiche). Scopri di più in Istanze. - Il numero di 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 Numero di nodi.
Dovresti vedere:
Creating instance...done.
Cerca tra i file di esempio
Il repository degli esempi contiene un esempio che mostra come utilizzare Spanner con Ruby.
Dai un'occhiata al filespanner_samples.rb
, che mostra 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 di dati.
Crea un database
Crea un database chiamato example-db
nell'istanza denominata test-instance
eseguendo quanto segue nella riga di comando.
bundle exec ruby spanner_samples.rb create_database test-instance example-db
Dovresti vedere:
Created database example-db on instance test-instance
Il codice seguente crea un database e due tabelle nel database.
.Il passaggio successivo consiste nel scrivere i dati nel database.
Crea un client di database
Prima di poter eseguire operazioni di lettura o scrittura, devi creare unaClient
. Puoi considerare un Client
come una connessione al database: tutte le interazioni con Spanner vengono inviate tramite Client
. Solitamente crei un Client
all'avvio dell'applicazione, quindi lo riutilizzi Client
per leggere, scrivere ed eseguire transazioni. Il codice seguente mostra come creare un client.
Scopri di più nel riferimento Client
.
Scrivi i dati con DML
Puoi inserire i dati utilizzando DML (Data Manipulation Language) in una transazione di lettura/scrittura.
Utilizza il metodo execute_update()
per eseguire un'istruzione DML.
Esegui l'esempio utilizzando l'argomento write_using_dml
.
bundle exec ruby spanner_samples.rb write_using_dml test-instance example-db
Dovresti vedere:
4 records inserted.
Scrivi i dati con mutazioni
Puoi anche inserire i dati utilizzando le modifiche.
Per scrivere i dati, utilizza un oggetto Client
. Il metodo Client#commit
crea ed esegue il commit di una transazione per scritture che vengono eseguite in modo atomico in un unico punto 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
.
bundle exec ruby spanner_samples.rb insert_data test-instance example-db
Dovresti vedere:
Inserted data
Esegui query sui dati tramite SQL
Spanner supporta un'interfaccia SQL nativa per la lettura dei dati, a cui puoi accedere dalla riga di comando utilizzando Google Cloud CLI o mediante la libreria client di Spanner per Ruby.
Dalla riga di comando
Esegui la seguente 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
Utilizzo della libreria client Spanner per Ruby
Oltre a eseguire un'istruzione SQL sulla riga di comando, puoi emettere la stessa istruzione SQL in modo programmatico utilizzando la libreria client Spanner per Ruby.
Utilizza il metodo Client#execute
per eseguire la query SQL. Usa il simbolo Ruby :ColumnName
per accedere ai dati di una colonna specifica da una riga.
Ecco come emettere una query e accedere ai dati:
Esegui l'esempio utilizzando l'argomento query_data
.
bundle exec ruby spanner_samples.rb query_data test-instance 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, riducendo così i costi di compilazione. Per ulteriori informazioni, consulta Utilizzare i parametri di ricerca per velocizzare le query eseguite di frequente.
Ecco un esempio dell'utilizzo di un parametro nella clausola WHERE
per eseguire query sui record contenenti un valore specifico per LastName
.
Esegui l'esempio utilizzando l'argomento query_with_parameter.
bundle exec ruby spanner_samples.rb query_with_parameter test-instance example-db
Dovresti vedere il seguente risultato:
12 Melissa Garcia
Lettura dei dati tramite l'API di lettura
Oltre all'interfaccia SQL di Spanner, Spanner supporta anche un'interfaccia di lettura.
Utilizza il metodo Client#read
della classe Client
per leggere le righe dal database.
Ecco come leggere i dati:
Esegui l'esempio utilizzando l'argomento read_data
.
bundle exec ruby spanner_samples.rb read_data test-instance 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 chiamata 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 di portare il database offline e non bloccano intere tabelle o colonne; puoi continuare a scrivere dati nel database durante l'aggiornamento dello schema. Scopri di più sugli aggiornamenti supportati dallo schema e sulle prestazioni di modifica dello schema in Aggiornamenti dello schema.
Aggiungi una colonna
Puoi aggiungere una colonna dalla riga di comando utilizzando Google Cloud CLI oppure mediante la libreria client Spanner per Ruby.
Dalla riga di comando
Utilizza il seguente comando ALTER TABLE
per aggiungere la nuova colonna alla tabella:
SQL di Google
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.
Utilizzo della libreria client Spanner per Ruby
Utilizza il metodoDatabase#update
della classe Database
per modificare lo schema:
Esegui l'esempio utilizzando l'argomento add_column
.
bundle exec ruby spanner_samples.rb add_column test-instance example-db
Dovresti vedere:
Added the MarketingBudget column
Scrivi i dati nella nuova colonna
Il codice seguente scrive i dati nella nuova colonna. Imposta MarketingBudget
su
100000
per la riga inserita da Albums(1, 1)
e su 500000
per la riga inserita da
Albums(2, 2)
.
Esegui l'esempio utilizzando l'argomento update_data
.
bundle exec ruby spanner_samples.rb update_data test-instance example-db
Dovresti vedere:
Updated data
Puoi anche eseguire una query SQL o una chiamata di lettura per recuperare i valori appena scritti.
Ecco il codice per eseguire la query:
Per eseguire questa query, esegui l'esempio utilizzando l'argomento query_data_with_new_column
.
bundle exec ruby spanner_samples.rb query_data_with_new_column test-instance example-db
Dovresti vedere:
1 1 100000
1 2
2 1
2 2 500000
2 3
Aggiorna dati
Puoi aggiornare i dati utilizzando DML in una transazione di lettura/scrittura.
Utilizza il metodo execute_update()
per eseguire un'istruzione DML.
Esegui l'esempio utilizzando l'argomento write_with_transaction_using_dml
.
bundle exec ruby spanner_samples.rb write_with_transaction_using_dml test-instance example-db
Dovresti vedere:
Transaction complete
Utilizzare un indice secondario
Supponiamo di voler recuperare tutte le righe di Albums
che hanno 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. Puoi invece accelerare il recupero di righe durante la ricerca per colonne di chiave non principali 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 il traffico. Spanner esegue il backfill automatico dell'indice con i tuoi dati esistenti. Il backfill potrebbe richiedere alcuni minuti, ma non è necessario portare il database offline o evitare di scrivere nella tabella indicizzata durante questo processo. Per maggiori dettagli, consulta la pagina relativa al backfill degli indici.
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 l'interfaccia di lettura, devi specificare l'indice che vuoi utilizzare.
Aggiungi un indice secondario
Puoi aggiungere un indice dalla riga di comando utilizzando l'interfaccia a riga di comando gcloud o in modo programmatico utilizzando la libreria client Spanner per Ruby.
Dalla 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 Ruby
Utilizza il metodo Database#update
della classe Database
per aggiungere un indice:
Esegui l'esempio utilizzando l'argomento create_index
.
bundle exec ruby spanner_samples.rb create_index test-instance example-db
L'aggiunta di un indice può richiedere alcuni minuti. Una volta aggiunto l'indice, dovresti vedere:
Added the AlbumsByAlbumTitle 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, fornisci un parametro index
al metodo
read
della classe Client
.
Esegui l'esempio utilizzando l'argomento read_data_with_index
.
bundle exec ruby spanner_samples.rb read_data_with_index test-instance example-db
Dovresti vedere:
2 Forever Hold Your Peace
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk
Aggiungere un indice per le letture solo indice
Forse avrai notato che l'esempio di lettura sopra non includeva la lettura della colonna MarketingBudget
. Questo perché l'interfaccia di lettura di Spanner non supporta la possibilità di unire un indice con una tabella di dati per cercare i valori che non sono archiviati nell'indice.
Crea una definizione alternativa di AlbumsByAlbumTitle
che memorizzi una copia di MarketingBudget
nell'indice.
Dalla riga di comando
SQL di Google
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, dovresti vedere:
Schema updating...done.
Utilizzo della libreria client Spanner per Ruby
Utilizza il metodoDatabase#update
della classe Database
per aggiungere un indice con una clausola STORING
:
Esegui l'esempio utilizzando l'argomento create_storing_index
.
bundle exec ruby spanner_samples.rb create_storing_index test-instance example-db
Dovresti vedere:
Added the AlbumsByAlbumTitle2 index
Ora puoi eseguire una lettura che recupera tutte le colonne AlbumId
, AlbumTitle
e MarketingBudget
dall'indice AlbumsByAlbumTitle2
:
Esegui l'esempio utilizzando l'argomento read_data_with_storing_index
.
bundle exec ruby spanner_samples.rb read_data_with_storing_index test-instance example-db
Dovresti visualizzare un output simile al seguente:
2 Forever Hold Your Peace 300000
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk 300000
Recuperare i dati utilizzando le transazioni di sola lettura
Supponiamo di voler eseguire più operazioni di lettura con lo stesso timestamp. Le transazioni di sola lettura osservano un prefisso coerente della cronologia del commit delle transazioni, in modo che la tua applicazione riceva sempre dati coerenti.
Utilizzare un oggetto Snapshot
per eseguire transazioni di sola lettura. Utilizza il metodo snapshot
della classe Client
per ottenere un oggetto Snapshot
.
Di seguito viene mostrato come eseguire una query ed eseguire una lettura nella stessa transazione di sola lettura:
Esegui l'esempio utilizzando l'argomento read_only_transaction
.
bundle exec ruby spanner_samples.rb read_only_transaction test-instance example-db
Dovresti visualizzare un output simile al seguente:
2 Forever Hold Your Peace 2
2 Go, Go, Go 1
1 Green 2
3 Terrified 2
1 Total Junk 1
1 Total Junk 1
2 Go, Go, Go 1
1 Green 2
2 Forever Hold Your Peace 2
3 Terrified 2
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 (comporterai comunque addebiti per l'istanza).
Dalla 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 da eliminare.
Nella pagina Dettagli database, fai clic su Elimina.
Conferma di voler eliminare il database e fai clic su Delete (Elimina).
Elimina l'istanza
Con l'eliminazione di un'istanza tutti i database creati in quell'istanza vengono eliminati automaticamente.
Dalla 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
Accedi a Spanner in un'istanza di macchina virtuale: crea un'istanza di macchina virtuale con accesso al tuo database Spanner.
Per saperne di più sulle credenziali di autorizzazione e autenticazione, consulta la guida introduttiva all'autenticazione.
Scopri di più sui concetti di Spanner.