Obiettivi
Questo tutorial illustra i seguenti passaggi utilizzando la libreria client Spanner per PHP:
- 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, per informazioni su come creare e impostare un progetto Google Cloud predefinito, abilitare la fatturazione, abilitare l'API Cloud Spanner e configurare OAuth 2.0 per ottenere 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 PHP locale
Segui i passaggi in Account di servizio per configurare un account di servizio come credenziali predefinite dell'applicazione. Dopo questi passaggi, dovresti ottenere sia un file di chiave dell'account di servizio (in JSON) che una variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
che ti consentirà di autenticarti nell'API Spanner.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/php-docs-samples
In alternativa puoi scaricare l'esempio come file ZIP ed estrarlo.
Passa alla directory che contiene il codice di esempio di Spanner:
cd php-docs-samples/spanner
Installa le dipendenze:
composer install
Verrà installata la libreria client Spanner per PHP, che puoi aggiungere a qualsiasi progetto eseguendo
composer require google/cloud-spanner
.
Crea un'istanza
La prima volta che utilizzi Spanner, 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, 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 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 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 numero di nodi di 1 (
node_count
corrisponde alla quantità di risorse di gestione e archiviazione disponibili per i database nell'istanza). Scopri di più nella pagina Conteggio 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 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 denominato example-db
nell'istanza denominata test-instance
eseguendo questo comando nella riga di comando.
php src/create_database.php 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 dati nel tuo database.
Crea un client di database
Per eseguire operazioni di lettura e scrittura, devi ottenere un'istanza diGoogle\Cloud\Spanner\Database
.
Puoi considerare una Database
come una connessione di database: tutte le interazioni con Spanner devono passare attraverso una Database
. In genere, crei un Database
all'avvio della tua applicazione, quindi lo 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
per ripulire 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.
Utilizza il metodo executeUpdate()
per eseguire un'istruzione DML.
Esegui il file di esempio src/write_data_with_dml.php
.
php src/write_data_with_dml.php test-instance example-db
Dovresti vedere:
Inserted 4 row(s).
Scrivere dati con le mutazioni
Puoi anche inserire i dati utilizzando le mutazioni.
Scrivi i dati utilizzando il metodo Database::insertBatch
. insertBatch
aggiunge nuove righe a una tabella. Tutti gli inserti in un singolo
batch vengono applicati anatomicamente.
Questo codice mostra come scrivere i dati utilizzando le mutazioni:
Esegui il file di esempio src/insert_data.php
.
php src/insert_data.php test-instance example-db
Dovresti vedere:
Inserted data.
Esegui query sui dati utilizzando 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 tramite la libreria client 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 Spanner per PHP
Oltre a eseguire un'istruzione SQL sulla riga di comando, puoi emettere la stessa istruzione SQL in modo programmatico mediante la libreria client Spanner per PHP.
UtilizzaDatabase::execute()
per eseguire la query SQL.
Ecco come emettere una query e accedere ai dati:
Esegui il file di esempio src/query_data.php
.
php src/query_data.php 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 tuoi risultati non saranno necessariamente in questo ordine. Per assicurarti l'ordinamento dei risultati, utilizza una clausola ORDER BY
, come documentato nelle best practice SQL.
Query mediante 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 ulteriori informazioni, consulta Utilizzare i parametri di ricerca per accelerare 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 il file di esempio src/query_data_with_parameter.php
.
php src/query_data_with_parameter.php test-instance example-db
Dovresti vedere il seguente risultato:
SingerId: 12, FirstName: Melissa, LastName: Garcia
Leggere dati usando l'API di lettura
Oltre all'interfaccia SQL di Spanner, 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 l'esempio nel file read_data.php
.
php read_data.php 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
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 quest'ultimo continua a gestire il traffico. Gli aggiornamenti dello schema non richiedono la disattivazione 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 di schemi supportati e sulle prestazioni di modifica dello schema in Aggiornamenti di schema.
Aggiungi una colonna
Puoi aggiungere una colonna dalla riga di comando utilizzando Google Cloud CLI oppure mediante la libreria client Spanner per PHP.
Dalla riga di comando
Utilizza il comando ALTER TABLE
seguente 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 Spanner per PHP
Utilizza Database::updateDdl
per modificare lo schema:
Esegui il file di esempio src/add_column.php
.
php src/add_column.php 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 500000
per la riga inserita da Albums(2, 2)
.
Esegui il file di esempio src/update_data.php
.
php src/update_data.php 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 il file di esempio src/query-data-with-new-column.php
.
php src/query_data_with_new_column.php 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
Aggiorna dati
Puoi aggiornare i dati utilizzando DML in una transazione di lettura/scrittura.
Utilizza il metodo executeUpdate()
per eseguire un'istruzione DML.
Esegui il file di esempio src/write_data_with_dml_transaction.php
.
php src/write_data_with_dml_transaction.php test-instance example-db
Dovresti vedere:
Transaction complete.
Utilizzare un indice secondario
Supponi di voler recuperare tutte le righe di Albums
che hanno AlbumTitle
in un determinato intervallo. Potresti leggere tutti i valori dalla colonna AlbumTitle
utilizzando un'istruzione SQL o una chiamata di lettura, quindi ignorare le righe che non soddisfano i criteri, ma eseguire questa scansione completa della tabella è costoso, soprattutto per le tabelle con molte righe. Puoi invece accelerare il recupero delle righe quando esegui una ricerca in base a colonne 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 automaticamente il backfill dell'indice con i 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 sezione Riempimento dell'indice.
Dopo aver aggiunto un indice secondario, 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 nella riga di comando utilizzando l'interfaccia a riga di comando gcloud o in modo programmatico utilizzando la libreria client 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 Spanner per PHP
Utilizza Database::updateDdl
per aggiungere un indice:
Esegui il file di esempio src/create_index.php
.
php src/create_index.php test-instance example-db
L'aggiunta di un indice può richiedere alcuni minuti. Dopo avere aggiunto l'indice, dovresti vedere:
Added the AlbumsByAlbumTitle index.
Lettura tramite 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, usa il metodo Database::read
.
Esegui il file di esempio src/read_data_with_index.php
.
php src/read_data_with_index.php 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
Aggiungere un indice per le letture solo dell'indice
Forse avrai notato che l'esempio letto 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 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 avere aggiunto l'indice, dovresti vedere:
Schema updating...done.
Utilizzo della libreria client Spanner per PHP
UtilizzaDatabase::updateDdl
per aggiungere un indice con una clausola STORING
:
Esegui il file di esempio src/create_storing_index.php
.
php src/create_storing_index.php 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 il file di esempio src/read_data_with_storing_index.php
.
php src/read_data_with_storing_index.php test-instance example-db
Dovresti visualizzare 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ù operazioni di lettura con lo stesso timestamp. Le transazioni di sola lettura osservano un prefisso coerente della cronologia dei 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 file di esempio src/read_only_transaction.php
.
php src/read_only_transaction.php test-instance example-db
Dovresti visualizzare 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.
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 (ti verranno comunque addebitati 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 Spanner in Google Cloud Console.
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.
Dalla riga di comando
gcloud spanner instances delete test-instance
Utilizzo di Google Cloud Console
Vai alla pagina Istanze 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
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 autorizzazioni e sull'autenticazione, consulta la guida introduttiva all'autenticazione.
Scopri di più sui concetti di Colab.