Obiettivi
Questo tutorial illustra i passaggi seguenti utilizzando Spanner libreria client per Node.js:
- 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 del in Google Cloud. Per informazioni sul costo di utilizzo di Spanner, consulta Prezzi.
Prima di iniziare
Completa i passaggi descritti in Configurazione, che trattano la creazione e impostare un progetto Google Cloud predefinito, abilitare la fatturazione, abilitare l'API Cloud Spanner e la configurazione di OAuth 2.0 per recuperare le credenziali di autenticazione da utilizzare l'API Cloud Spanner.
In particolare, assicurati di eseguire gcloud auth
application-default login
per configurare l'ambiente di sviluppo locale con l'autenticazione
e credenziali.
prepara l'ambiente Node.js locale
Segui i passaggi per configurare un ambiente di sviluppo Node.js
Clona il repository dell'app di esempio nella tua macchina locale:
git clone https://github.com/googleapis/nodejs-spanner
In alternativa puoi scaricare l'esempio come file ZIP ed estrarlo.
Passa alla directory che contiene il codice campione di Spanner:
cd samples/
Installa le dipendenze utilizzando
npm
:npm install
Crea un'istanza
Quando utilizzi Spanner per la prima volta, devi creare un'istanza, ovvero delle risorse usate dai database Spanner. Quando Quando crei un'istanza, scegli una configurazione dell'istanza, che determina dove sono archiviati i dati e il numero di nodi da utilizzare, che determina e 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 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. - Conteggio dei nodi pari a 1 (
node_count
corrisponde alla quantità di pubblicazione e archiviazione e le risorse 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 Node.js.
Dai un'occhiata al file samples/schema.js
, che mostra come
creare un database e modificarne lo schema. I dati utilizzano lo schema di esempio
mostrato in Schema e modello dei dati
.
Crea un database
Crea un database denominato example-db
nell'istanza denominata test-instance
da
eseguendo sulla riga di comando il comando riportato di seguito.
node schema.js createDatabase test-instance example-db MY_PROJECT_ID
Dovresti vedere:
Created database example-db on instance test-instance.
Il codice seguente crea un database e due tabelle nel database.
Il passaggio successivo è scrivere dati nel database.
Crea un client di database
Prima di poter eseguire operazioni di lettura o scrittura, devi creare un elementoDatabase
:
Puoi considerare Database
come una connessione a un database: tutte le tue interazioni
con Spanner deve passare attraverso un Database
. In genere crei un Database
quando l'applicazione si avvia, riutilizzi Database
per leggere, scrivere,
ed eseguire transazioni. Ogni client utilizza le risorse in Spanner.
Se crei più client nella stessa app, devi chiamare
Database.close()
ripulire le risorse del client, incluse le connessioni di rete, non appena viene
non è più necessario.
Scopri di più nel Database
riferimento.
Scrivi dati con DML
Puoi inserire dati utilizzando DML (Data Manipulation Language) in un ambiente transazione.
Utilizzi il metodo runUpdate()
per eseguire un'istruzione DML.
Esegui l'esempio utilizzando l'argomento writeUsingDml
.
node dml.js writeUsingDml test-instance example-db MY_PROJECT_ID
Dovresti vedere:
4 records inserted.
Scrivere dati con mutazioni
Puoi anche inserire i dati utilizzando le mutazioni.
Scrivi i dati utilizzando un
Table
. La
Table.insert()
aggiunge nuove righe alla tabella. Vengono applicati tutti gli inserimenti di un singolo batch
a livello atomico.
Questo codice mostra come scrivere i dati utilizzando le mutazioni:
Esegui l'esempio utilizzando l'argomento insert
.
node crud.js insert test-instance example-db MY_PROJECT_ID
Dovresti vedere:
Inserted data.
Eseguire 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 e la libreria client di Spanner per Node.js.
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
Utilizzare la libreria client Spanner per Node.js
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 in Node.js.
Utilizza Database.run()
per eseguire la query SQL.
Ecco come inviare la query e accedere ai dati:
node crud.js query test-instance example-db MY_PROJECT_ID
Dovresti vedere il seguente risultato:
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
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, vedi Utilizza parametri di ricerca per velocizzare le query eseguite di frequente.
Ecco un esempio di utilizzo di un parametro nella clausola WHERE
per
record di query contenenti un valore specifico per LastName
.
Ecco come inviare la query e accedere ai dati:
node dml.js queryWithParameter test-instance example-db MY_PROJECT_ID
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 una di lettura.
Utilizza Table.read()
per leggere le righe dal 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
.
node crud.js read test-instance example-db MY_PROJECT_ID
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
a Albums
tabella. L'aggiunta di una nuova colonna a una tabella esistente richiede un aggiornamento delle
lo schema del database. Spanner supporta gli aggiornamenti dello schema di un database, mentre
continua a gestire traffico. Gli aggiornamenti dello schema non richiedono
il database è offline e non bloccano intere tabelle o colonne; puoi continuare
dei dati nel database durante l'aggiornamento dello schema. Scopri di più sui servizi supportati
degli aggiornamenti dello schema e delle relative prestazioni in
Aggiorna lo schema.
Aggiungi una colonna
Puoi aggiungere una colonna nella riga di comando utilizzando Google Cloud CLI oppure in modo programmatico e la libreria client di Spanner per Node.js.
Nella riga di comando
Utilizza il seguente comando ALTER TABLE
per
aggiungi 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 Node.js
Utilizza Database.updateSchema
per modificare lo schema:
Esegui l'esempio utilizzando l'argomento addColumn
.
node schema.js addColumn test-instance example-db MY_PROJECT_ID
Dovresti vedere:
Added the 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
.
node crud.js update test-instance example-db MY_PROJECT_ID
Dovresti vedere:
Updated data.
Puoi anche eseguire una query SQL o una chiamata di lettura per recuperare i valori che che ha appena scritto.
Ecco il codice per eseguire la query:
Per eseguire questa query, esegui l'esempio utilizzando l'argomento queryNewColumn
.
node schema.js queryNewColumn test-instance example-db MY_PROJECT_ID
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.
Utilizzi il metodo runUpdate()
per eseguire un'istruzione DML.
Esegui l'esempio utilizzando l'argomento writeWithTransactionUsingDml
.
node dml.js writeWithTransactionUsingDml test-instance example-db MY_PROJECT_ID
Dovresti vedere:
Successfully executed read-write transaction using DML to transfer $200000 from Album 2 to Album 1.
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 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. Mi piace altri aggiornamenti dello schema, Spanner supporta l'aggiunta di un indice, mentre continua a gestire 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 ulteriori dettagli, vedi Aggiungi un indice secondario.
Dopo aver aggiunto un indice secondario, Spanner lo utilizza automaticamente per Query SQL che hanno maggiori probabilità di essere eseguite più velocemente con l'indice. Se utilizzi lo strumento devi specificare l'indice che vuoi utilizzare.
Aggiungi un indice secondario
Puoi aggiungere un indice dalla riga di comando utilizzando gcloud CLI in modo programmatico usando la libreria client Spanner per Node.js.
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 Node.js
Utilizza Database.updateSchema()
per aggiungere un indice:
Esegui l'esempio utilizzando l'argomento createIndex
.
node indexing.js createIndex test-instance example-db MY_PROJECT_ID
L'aggiunta di un indice può richiedere alcuni minuti. Una volta aggiunto l'indice, consulta:
Added the AlbumsByAlbumTitle index.
Leggi utilizzando l'indice
Per le query SQL, Spanner utilizza automaticamente un indice appropriato. Nella di lettura, devi specificare l'indice nella richiesta.
Per utilizzare l'indice nell'interfaccia di lettura, utilizza la
Table.read()
.
Esegui l'esempio utilizzando l'argomento readIndex
.
node indexing.js readIndex test-instance example-db MY_PROJECT_ID
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
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 Node.js
UtilizzaDatabase.updateSchema()
per aggiungere un indice con una clausola STORING
:
Esegui l'esempio utilizzando l'argomento createStoringIndex
.
node indexing.js createStoringIndex test-instance example-db MY_PROJECT_ID
Dovresti vedere:
Added the AlbumsByAlbumTitle2 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
.
node indexing.js readStoringIndex test-instance example-db MY_PROJECT_ID
Dovresti visualizzare un output simile al seguente:
AlbumId: 2, AlbumTitle: Forever Hold your Peace, MarketingBudget: 300000
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: 300000
Recuperare i dati utilizzando le transazioni di sola lettura
Supponiamo di voler eseguire più di una lettura per lo stesso timestamp. Sola lettura
transazioni osservano una coerenza
della cronologia di commit delle transazioni, in modo che l'applicazione
la coerenza dei dati.
Utilizza Database.runTransaction()
per l'esecuzione di transazioni di sola lettura.
Di seguito viene illustrato come eseguire una query ed eseguire una lettura nella stessa sessione transazione:
Esegui l'esempio utilizzando l'argomento readOnly
.
node transaction.js readOnly test-instance example-db MY_PROJECT_ID
Dovresti visualizzare un output simile al seguente:
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
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
Successfully executed read-only transaction.
Esegui la pulizia
Per evitare che al tuo account di fatturazione Cloud vengano addebitati costi aggiuntivi per usate 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 (dovresti sono comunque addebitati costi per l'istanza).
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ù sull'autorizzazione e sulle credenziali di autenticazione in Autenticazione in Cloud mediante librerie client.
Scopri di più sulle best practice per la progettazione dello schema di Spanner.