Obiettivi
Questo tutorial ti guida attraverso i seguenti passaggi utilizzando la libreria client Spanner per PHP:
- Crea un'istanza e un database Spanner.
- Scrivi, leggi ed esegui query SQL sui dati nel database.
- Aggiorna lo schema del database.
- Aggiorna 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, un componente fatturabile di Google Cloud. Per informazioni sul costo dell'utilizzo di Spanner, vedi 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 PHP locale
Segui i passaggi descritti in Service account per configurare uaccount di serviziont come credenziali predefinite dell'applicazione. Seguendo questi passaggi, dovresti ottenere sia un file di chiave del account di servizio (in JSON) sia una variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
che ti consentirà di autenticarti all'API Spanner.Installa i seguenti elementi sul computer di sviluppo, se non sono già installati:
Clona il repository dell'app di esempio sulla tua 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 campione di Spanner:
cd php-docs-samples/spanner
Installa le dipendenze:
composer install
In questo modo verrà installata la libreria client Spanner per PHP, che puoi aggiungere a qualsiasi progetto eseguendo
composer require google/cloud-spanner
.
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 dell'istanza, che determina dove vengono archiviati i dati e il numero di nodi da utilizzare, che determina la quantità di risorse di gestione e archiviazione nell'istanza.
Esegui il comando seguente 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 questa operazione crea 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 quelle multiregionali li distribuiscono in più regioni. Per ulteriori informazioni, vedi Informazioni sulle istanze.) - Il conteggio dei 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 Nodi e unità di elaborazione.)
Dovresti vedere:
Creating instance...done.
Esaminare i file di esempio
Il repository di 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 dati.
Crea un database
GoogleSQL
php src/create_database.php test-instance example-db
PostgreSQL
php src/pg_create_database.php test-instance example-db
Dovresti vedere:
Created database example-db on instance test-instance
GoogleSQL
PostgreSQL
Il passaggio successivo consiste nello scrivere i dati nel database.
Crea un client di database
Per eseguire letture e scritture, devi ottenere un'istanza diGoogle\Cloud\Spanner\Database
.
Puoi pensare a un Database
come a una connessione al database: tutte le tue interazioni
con Spanner devono passare attraverso un Database
. In genere, crei un Database
all'avvio dell'applicazione, poi riutilizzi Database
per leggere, scrivere
ed eseguire transazioni. Ogni client utilizza risorse in 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 Data Manipulation Language (DML) in una transazione di lettura/scrittura.
Utilizzi 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 modifiche
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 inserimenti in un singolo batch vengono applicati in modo atomico.
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.
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 PHP.
Nella riga di comando
Esegui la seguente istruzione SQL per leggere i valori di tutte le colonne della 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 PHP
Oltre a eseguire un'istruzione SQL dalla riga di comando, puoi emettere la stessa istruzione SQL a livello di programmazione utilizzando la libreria client Spanner per PHP.
UtilizzaDatabase::execute()
per eseguire la query SQL.
Ecco come eseguire la 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 risultati non saranno necessariamente in questo ordine. Se devi assicurarti l'ordinamento
del risultato, utilizza una clausola ORDER BY
, come documentato nelle
best practice SQL.
Query che utilizza 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, il che riduce i costi di compilazione. Per ulteriori informazioni, consulta la sezione Utilizzare parametri di ricerca per velocizzare le query eseguite di frequente.
Ecco un esempio di utilizzo di un parametro nella clausola WHERE
per
interrogare i 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
Lettura dei dati utilizzando 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 il database continua a gestire il traffico. Gli aggiornamenti dello schema non richiedono di mettere offline il 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 dello schema e sul rendimento delle modifiche dello schema supportati in Esegui aggiornamenti dello schema.
Aggiungere una colonna
Puoi aggiungere una colonna dalla riga di comando utilizzando Google Cloud CLI o in modo programmatico utilizzando la libreria client Spanner per PHP.
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.
Utilizzare la 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 seguente codice 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
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 che hai appena scritto.
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.
Utilizzi 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
Supponiamo di voler recuperare tutte le righe di Albums
che hanno valori AlbumTitle
in un determinato intervallo. Potresti leggere tutti i valori della colonna AlbumTitle
utilizzando
un'istruzione SQL o una chiamata di lettura, quindi scartare le righe che non soddisfano i
criteri, ma questa scansione completa della tabella è costosa, soprattutto per le tabelle
con molte righe. Puoi invece velocizzare il recupero delle righe quando esegui ricerche in base a colonne non 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 il 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, vedi Aggiungere un indice secondario.
Dopo aver aggiunto un indice secondario, Spanner lo utilizza automaticamente per le query SQL che probabilmente vengono eseguite più velocemente con l'indice. Se utilizzi l'interfaccia di lettura, devi specificare l'indice che vuoi utilizzare.
Aggiungere un indice secondario
Puoi aggiungere un indice dalla riga di comando utilizzando gcloud CLI o in modo programmatico utilizzando la libreria client Spanner per PHP.
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 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 aver aggiunto l'indice, dovresti visualizzare:
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, utilizza 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 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 visualizzare:
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
Supponiamo che tu voglia eseguire più di una lettura con lo stesso timestamp. Le transazioni di sola lettura osservano un prefisso coerente della cronologia dei commit delle transazioni, in modo che la tua applicazione riceva 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 e 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 (continuerai a sostenere 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 in quell'istanza.
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 sull'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 macchina virtuale.
Scopri di più sulle credenziali di autorizzazione e autenticazione in Autenticarsi ai servizi cloud utilizzando le librerie client.
Scopri di più sulle best practice per la progettazione dello schema di Spanner.