Obiettivi
Questo tutorial illustra i seguenti passaggi utilizzando la libreria client Cloud Spanner per PHP:
- Creare un'istanza e un database Cloud Spanner.
- Scrivere, leggere ed eseguire query SQL sui dati nel database.
- Aggiorna lo schema del database.
- Aggiorna i dati tramite 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 Cloud Spanner, un componente fatturabile di Google Cloud. Per informazioni sul costo dell'utilizzo di Cloud Spanner, consulta la sezione Prezzi.
Prima di iniziare
Completa i passaggi descritti in Configurare, che descrivono 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 credenziali di autenticazione per l'utilizzo dell'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 PHP locale
Segui i passaggi descritti in Account di servizio per configurare un account di servizio come credenziali predefinite dell'applicazione. Se segui questi passaggi, dovresti ottenere sia un file di chiave dell'account di servizio (in JSON) sia una variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
che ti consenta di autenticarti all'API Cloud Spanner.Installa quanto segue sulla tua macchina di sviluppo se non è già installato:
Clona il repository delle app di esempio sul tuo computer locale:
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
In alternativa puoi scaricare l'esempio come file ZIP ed estrarlo.
Passa alla directory che contiene il codice di esempio di Cloud Spanner:
cd php-docs-samples/spanner
Installa le dipendenze:
composer install
Verrà installata la libreria client Cloud Spanner per PHP, che potrai aggiungere a qualsiasi progetto eseguendo
composer require google/cloud-spanner
.
Crea un'istanza
Quando usi Cloud Spanner per la prima volta, devi creare un'istanza, ovvero un'allocazione delle risorse utilizzate dai database Cloud Spanner. Quando crei un'istanza, scegli una configurazione dell'istanza, che determina dove sono archiviati i tuoi dati, nonché il numero di nodi da utilizzare, che determina la quantità di risorse di archiviazione e archiviazione presenti nell'istanza.
Esegui il comando seguente per creare un'istanza Cloud Spanner nell'area geografica
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 area geografica 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 conteggio dei nodi 1 (
node_count
corrisponde alla quantità di risorse di archiviazione e archiviazione disponibili per i database nell'istanza). Scopri di più nella pagina Conteggio nodi.
Dovresti vedere:
Creating instance...done.
Esaminare i file di esempio
Il repository di esempi contiene un esempio che mostra come utilizzare Cloud Spanner con PHP.
Dai un'occhiata alle funzioni in src/create_database.php
e
src/add_column.php
, che mostrano come creare un database e modificare uno schema
di database. I dati utilizzano lo schema di esempio mostrato nella pagina Schema e modello dei dati.
Crea un database
Crea un database example-db
nell'istanza denominata test-instance
eseguendo questo comando nella riga di comando.
php spanner.php create-database test-instance example-db
Dovresti vedere:
Created database example-db on instance test-instance
Il seguente codice crea un database e due tabelle nel database.
Il passaggio successivo consiste nel scrivere i dati nel database.
Crea un client di database
Per eseguire letture e scritture, devi ottenere un'istanza diGoogle\Cloud\Spanner\Database
.
Puoi considerare Database
come una connessione di database: tutte le interazioni
con Cloud Spanner devono avvenire tramite Database
. In genere, crei un Database
all'avvio dell'applicazione, quindi lo riutilizzi come Database
per leggere, scrivere
ed eseguire transazioni. Ogni client utilizza le risorse in Cloud Spanner.
Se crei più client nella stessa app, devi chiamare Database::close
per pulire le risorse del client, incluse le connessioni di rete, non appena non sono più necessarie.
Scopri di più nel riferimento Database
.
Scrivere dati con DML
Puoi inserire i dati utilizzando DML (Data Manipulation Language) in una transazione di lettura/scrittura.
Utilizzi il metodo executeUpdate()
per eseguire un'istruzione DML.
Esegui il campione utilizzando il comando write-data-with-dml
.
php spanner.php write-data-with-dml test-instance example-db
Dovresti vedere:
Inserted 4 row(s).
Scrivere dati con le mutazioni
Puoi anche inserire i dati utilizzando le mutazioni.
Per scrivere i dati, utilizza il metodo
Database::insertBatch
. insertBatch
aggiunge nuove righe a una tabella. Tutti gli inserimenti in un singolo batch vengono applicati in modo atomico.
Questo codice mostra come scrivere i dati utilizzando le mutazioni:
Esegui il campione utilizzando il comando insert-data
.
php spanner.php insert-data test-instance example-db
Dovresti vedere:
Inserted data.
Query sui dati con SQL
Cloud Spanner supporta un'interfaccia SQL nativa per la lettura dei dati, a cui puoi accedere dalla riga di comando utilizzando l'interfaccia a riga di comando di Google Cloud o in modo programmatico tramite la libreria client di Cloud Spanner per PHP.
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 Cloud Spanner per PHP
Oltre a eseguire un'istruzione SQL sulla riga di comando, puoi eseguire la stessa istruzione SQL in modo programmatico mediante la libreria client Cloud Spanner per PHP.
UtilizzaDatabase::execute()
per eseguire la query SQL.
Ecco come emettere la query e accedere ai dati:
Esegui il campione utilizzando il comando query-data
.
php spanner.php query-data test-instance example-db
Dovresti vedere il seguente risultato:
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
I risultati non saranno necessariamente nell'ordine indicato. Se devi assicurarti di ordinare il risultato, utilizza una clausola ORDER BY
, come documentato nelle best practice per SQL.
Query con 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 la sezione Utilizzare i parametri di ricerca per velocizzare le query eseguite di frequente.
Di seguito è riportato un esempio di utilizzo di un parametro nella clausola WHERE
per eseguire query sui record contenenti un valore specifico per LastName
.
Esegui il campione utilizzando il comando query-data-with-parameter.
php spanner.php query-data-with-parameter test-instance example-db
Dovresti vedere il seguente risultato:
SingerId: 12, FirstName: Melissa, LastName: Garcia
Lettura di dati con l'API di lettura
Oltre a Cloud SQL, interfaccia Cloud Spanner supporta anche un'interfaccia di lettura.
Utilizza Database::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 il campione utilizzando il comando read-data
.
php spanner.php read-data test-instance example-db
Dovresti vedere 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
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. Cloud Spanner supporta gli aggiornamenti dello schema di un database mentre quest'ultimo continua a gestire il traffico. Gli aggiornamenti dello schema non richiedono lo spostamento del 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 degli schemi supportati e sulle prestazioni di modifica dello schema in Aggiornamenti dello schema.
Aggiungi una colonna
Puoi aggiungere una colonna dalla riga di comando utilizzando l'interfaccia a riga di comando di Google Cloud o a livello di programmazione utilizzando la libreria client di Cloud Spanner per PHP.
Dalla riga di comando
Utilizza il seguente comando ALTER TABLE
per aggiungere la nuova colonna alla tabella:
SQL standard 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 Cloud Spanner per PHP
Utilizza Database::updateDdl
per modificare lo schema:
Esegui il campione utilizzando il comando add-column
.
php spanner.php add-column test-instance example-db
Dovresti vedere:
Added the MarketingBudget column.
Scrivere i dati nella nuova colonna
Il codice seguente scrive i dati nella nuova colonna. Imposta MarketingBudget
su
100000
per la riga con chiave Albums(1, 1)
e su 500000
per la riga con chiave
per Albums(2, 2)
.
Esegui il campione utilizzando il comando update-data
.
php spanner.php 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 che hai appena scritto.
Ecco il codice per eseguire la query:
Per eseguire questa query, esegui l'esempio utilizzando l'argomento query-data-with-new-column
.
php spanner.php query-data-with-new-column test-instance example-db
Dovresti vedere:
SingerId: 1, AlbumId: 1, MarketingBudget: 100000
SingerId: 1, AlbumId: 2, MarketingBudget: 0
SingerId: 2, AlbumId: 1, MarketingBudget: 0
SingerId: 2, AlbumId: 2, MarketingBudget: 500000
SingerId: 2, AlbumId: 3, MarketingBudget: 0
Aggiornare dati
Puoi aggiornare i dati utilizzando DML in una transazione di lettura/scrittura.
Utilizzi il metodo executeUpdate()
per eseguire un'istruzione DML.
Esegui il campione utilizzando il comando write-data-with-dml-transaction
.
php spanner.php write-data-with-dml-transaction test-instance example-db
Dovresti vedere:
Transaction complete.
Utilizzare un indice secondario
Supponi 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 questa operazione completa è costosa, soprattutto per le tabelle con molte righe. È invece possibile velocizzare il recupero di righe durante le ricerche in base a 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, Cloud Spanner supporta l'aggiunta di un indice mentre il database continua a gestire il traffico. Cloud Spanner esegue automaticamente il backfill dell'indice con i dati esistenti. Il backfill può richiedere alcuni minuti, ma non devi mettere il database offline o evitare di scrivere nella tabella indicizzata durante questo processo. Per maggiori dettagli, consulta il backfill dell'indice.
Dopo aver aggiunto un indice secondario, Cloud Spanner lo utilizza automaticamente per le query SQL che probabilmente verranno 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 a livello di programmazione utilizzando la libreria client Cloud Spanner per PHP.
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 Cloud Spanner per PHP
Utilizza l'elemento Database::updateDdl
per aggiungere un indice:
Esegui il campione utilizzando il comando create-index
.
php spanner.php create-index test-instance example-db
L'aggiunta di un indice può richiedere alcuni minuti. Dopo l'aggiunta dell'indice, dovresti vedere:
Added the AlbumsByAlbumTitle index.
Lettura tramite l'indice
Per le query SQL, Cloud Spanner utilizza automaticamente un indice appropriato. Nell'interfaccia di lettura, devi specificare l'indice nella richiesta.
Per usare l'indice nell'interfaccia di lettura, utilizza il metodo Database::read
.
Esegui il campione utilizzando il comando read-data-with-index
.
php spanner.php read-data-with-index 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 con indice
Potresti aver notato che l'esempio di lettura riportato sopra non includeva la lettura della colonna MarketingBudget
. Questo perché l'interfaccia di lettura di Cloud Spanner non supporta la possibilità di unire un indice con una tabella di dati per cercare valori non archiviati nell'indice.
Crea una definizione alternativa di AlbumsByAlbumTitle
che memorizzi una copia di
MarketingBudget
nell'indice.
Dalla riga di comando
SQL standard 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. Dopo l'aggiunta dell'indice, dovresti vedere:
Schema updating...done.
Utilizzo della libreria client Cloud Spanner per PHP
UtilizzaDatabase::updateDdl
per aggiungere un indice con una clausola STORING
:
Esegui il campione utilizzando il comando create-storing-index
.
php spanner.php 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 di AlbumsByAlbumTitle2
:
Esegui il campione utilizzando il comando read-data-with-storing-index
.
php spanner.php read-data-with-storing-index test-instance example-db
Dovresti vedere un output simile al seguente:
AlbumId: 2, AlbumTitle: Forever Hold your Peace, MarketingBudget: 300000
AlbumId: 2, AlbumTitle: Go, Go, Go, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Green, MarketingBudget: 0
AlbumId: 3, AlbumTitle: Terrified, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Total Junk, MarketingBudget: 300000
Recuperare i dati utilizzando le transazioni di sola lettura
Supponi di voler eseguire più di una lettura con lo stesso timestamp. Le transazioni di sola lettura osservano un prefisso coerente della cronologia di commit della transazione, quindi l'applicazione riceve sempre dati coerenti.
Utilizza un oggetto Snapshot
per eseguire transazioni di sola lettura. Utilizza il metodo
Database::snapshot
per ottenere un oggetto Snapshot
.
Di seguito viene mostrato come eseguire una query ed eseguire una lettura nella stessa transazione di sola lettura:
Esegui il campione utilizzando il comando read-only-transaction
.
php spanner.php read-only-transaction test-instance example-db
Dovresti vedere un output simile al seguente:
Results from first read:
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
Results from second read:
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
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.
Eliminazione del 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 (comunque dovrai sostenere dei costi per l'istanza).
Dalla riga di comando
gcloud spanner databases delete example-db --instance=test-instance
Utilizzo di Google Cloud Console
Vai alla pagina Istanze Cloud Spanner in Google Cloud Console.
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 Elimina.
Elimina l'istanza
Con l'eliminazione di un'istanza, vengono eliminati automaticamente tutti i database creati in quell'istanza.
Dalla riga di comando
gcloud spanner instances delete test-instance
Utilizzo di Google Cloud Console
Vai alla pagina Istanze Cloud Spanner in Google Cloud Console.
Fai clic sulla tua istanza.
Fai clic su Elimina.
Conferma di voler eliminare l'istanza e fai clic su Elimina.
Passaggi successivi
Accesso a Cloud Spanner in un'istanza di macchina virtuale: crea un'istanza di macchina virtuale con accesso al tuo database Cloud Spanner.
Per informazioni sull'autorizzazione e sulle credenziali di autenticazione, consulta la Guida introduttiva all'autenticazione.
Scopri di più sui concetti di Cloud Spanner.