Obiettivi
Questo tutorial illustra i passaggi seguenti utilizzando i driver PGAdapter di Spanner per PostgreSQL:
- 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 di utilizzo di Spanner, consulta i 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 PGAdapter locale
Puoi usare i driver PostgreSQL insieme a PGAdapter per connetterti a Spanner. PGAdapter è un proxy locale che traduce il protocollo di rete PostgreSQL nel protocollo gRPC Spanner.
PGAdapter richiede Java o Docker per l'esecuzione.
Installa uno degli elementi seguenti sul tuo computer di sviluppo se nessuna di queste è già installata:
Clona il repository dell'app di esempio nella tua macchina locale:
git clone https://github.com/GoogleCloudPlatform/pgadapter.git
Passa alla directory che contiene il codice campione di Spanner:
psql
cd pgadapter/samples/snippets/psql-snippets
Java
cd pgadapter/samples/snippets/java-snippets mvn package -DskipTests
Go
cd pgadapter/samples/snippets/golang-snippets
Node.js
cd pgadapter/samples/snippets/nodejs-snippets npm install
Python
cd pgadapter/samples/snippets/python-snippets python -m venv ./venv pip install -r requirements.txt cd samples
C#
cd pgadapter/samples/snippets/dotnet-snippets
Creazione di 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 sono archiviati i dati e anche il numero di nodi da utilizzare, che determina 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 dell'istanza
regional-us-central1
(le configurazioni regionali archiviano 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 risorse di servizio e archiviazione 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 PGAdapter.
Dai un'occhiata alla cartellasamples/snippets
, 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 dei dati.
Avvia PGAdapter
Avvia PGAdapter sulla tua macchina di sviluppo locale e indirizzalo all'istanza che hai creato.
I seguenti comandi presuppongono che tu abbia eseguito
gcloud auth application-default login
.
Applicazione Java
wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
&& tar -xzvf pgadapter.tar.gz
java -jar pgadapter.jar -i test-instance
Docker
docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter
docker run \
--name pgadapter \
--rm -d -p 5432:5432 \
-v "$HOME/.config/gcloud":/gcloud:ro \
--env CLOUDSDK_CONFIG=/gcloud \
gcr.io/cloud-spanner-pg-adapter/pgadapter \
-i test-instance -x
Emulator
docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
docker run \
--name pgadapter-emulator \
--rm -d \
-p 5432:5432 \
-p 9010:9010 \
-p 9020:9020 \
gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
PGAdapter viene avviato con un emulatore Spanner incorporato. Questo emulatore incorporato crea automaticamente qualsiasi istanza o database Spanner a cui ti connetti senza doverli creare manualmente in anticipo.
Ti consigliamo di eseguire PGAdapter in produzione come container side-car o come dipendenza in-process. Per ulteriori informazioni sul deployment di PGAdapter in produzione, consulta Scegliere un metodo per l'esecuzione di PGAdapter.
Crea un database
Crea un database denominato example-db
nell'istanza denominata test-instance
eseguendo quanto segue sulla riga di comando.
gcloud spanner databases create example-db --instance=test-instance \
--database-dialect=POSTGRESQL
Dovresti vedere:
Creating database...done.
Creare tabelle
Il codice seguente crea due tabelle nel database.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./create_tables.sh example-db
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar createtables example-db
Go
go run sample_runner.go createtables example-db
Node.js
npm start createtables example-db
Python
python create_tables.py example-db
C#
dotnet run createtables example-db
Il passaggio successivo è scrivere dati nel database.
Crea una connessione
Prima di poter eseguire operazioni di lettura o scrittura, devi creare una connessione a PGAdapter. Tutte le interazioni con Spanner devono passare tramite un valoreConnection
. Il nome del database è specificato nella stringa di connessione.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./create_connection.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar createconnection example-db
Go
go run sample_runner.go createconnection example-db
Node.js
npm start createconnection example-db
Python
python create_connection.py example-db
C#
dotnet run createconnection example-db
Scrivi dati con DML
Puoi inserire dati utilizzando DML (Data Manipulation Language) in una transazione di lettura e scrittura.
Questi esempi mostrano come eseguire un'istruzione DML su Spanner utilizzando un driver PostgreSQL.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./write_data_with_dml.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar writeusingdml example-db
Go
go run sample_runner.go writeusingdml example-db
Node.js
npm start writeusingdml example-db
Python
python write_data_with_dml.py example-db
C#
dotnet run writeusingdml example-db
Dovresti vedere la seguente risposta:
4 records inserted.
Scrivere dati con un batch DML
PGAdapter supporta l'esecuzione di batch DML. L'invio di più istruzioni DML in un unico batch riduce il numero di round trip a Spanner e migliora le prestazioni dell'applicazione.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./write_data_with_dml_batch.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar writeusingdmlbatch example-db
Go
go run sample_runner.go writeusingdmlbatch example-db
Node.js
npm start writeusingdmlbatch example-db
Python
python write_data_with_dml_batch.py example-db
C#
dotnet run writeusingdmlbatch example-db
Dovresti vedere:
3 records inserted.
Scrivere dati con mutazioni
Puoi anche inserire i dati utilizzando le mutazioni.
PGAdapter converte il comando PostgreSQL COPY
in mutazioni. L'utilizzo di COPY
è il modo più efficiente per inserire rapidamente dati nel
tuo database Spanner.
Per impostazione predefinita, le operazioni COPY
sono atomiche. Le operazioni atomiche su Spanner sono vincolate dal limite delle dimensioni del commit.
Per ulteriori informazioni, consulta il limite di CRUD.
Questi esempi mostrano come eseguire un'operazione COPY
non atomica. In questo modo
l'operazione COPY
può superare il limite delle dimensioni del commit.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./write_data_with_copy.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar write example-db
Go
go run sample_runner.go write example-db
Node.js
npm start write example-db
Python
python write_data_with_copy.py example-db
C#
dotnet run write example-db
Dovresti vedere:
Copied 5 singers
Copied 5 albums
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 un driver PostgreSQL.
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 singer_id, album_id, album_title 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
Utilizza un driver PostgreSQL
Oltre a eseguire un'istruzione SQL sulla riga di comando, puoi inviare la stessa istruzione SQL in modo programmatico utilizzando un driver PostgreSQL.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./query_data.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar query example-db
Go
go run sample_runner.go query example-db
Node.js
npm start query example-db
Python
python query_data.py example-db
C#
dotnet run query 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
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 i costi di compilazione. Per maggiori informazioni, consulta Utilizzare parametri di ricerca per velocizzare 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
.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./query_data_with_parameter.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar querywithparameter example-db
Go
go run sample_runner.go querywithparameter example-db
Node.js
npm start querywithparameter example-db
Python
python query_data_with_parameter.py example-db
C#
dotnet run querywithparameter example-db
Dovresti vedere il seguente risultato:
12 Melissa Garcia
Aggiorna lo schema del database
Supponi di dover 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 modalità offline 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 degli schemi supportati e sulle prestazioni delle modifiche degli schemi in Eseguire aggiornamenti dello schema.
Aggiungi una colonna
Puoi aggiungere una colonna nella riga di comando utilizzando Google Cloud CLI o in modo programmatico utilizzando un driver PostgreSQL.
Nella riga di comando
Utilizza il seguente comando ALTER TABLE
per
aggiungere la nuova colonna alla tabella:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE albums ADD COLUMN marketing_budget BIGINT'
Dovresti vedere:
Schema updating...done.
Utilizza un driver PostgreSQL
Esegui l'istruzione DDL utilizzando un driver PostgreSQL per modificare lo schema:
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./add_column.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar addmarketingbudget example-db
Go
go run sample_runner.go addmarketingbudget example-db
Node.js
npm start addmarketingbudget example-db
Python
python add_column.py example-db
C#
dotnet run addmarketingbudget example-db
Dovresti vedere:
Added marketing_budget column
Esegui un batch DDL
Ti consigliamo di eseguire più modifiche dello schema in un unico batch.
Puoi eseguire più istruzioni DDL in un singolo batch utilizzando la funzionalità integrata di raggruppamento in batch del driver PostgreSQL, inviando tutte le istruzioni DDL come una stringa SQL separata da punti e virgola o utilizzando le istruzioni START BATCH DDL
e RUN BATCH
.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./ddl_batch.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar ddlbatch example-db
Go
go run sample_runner.go ddlbatch example-db
Node.js
npm start ddlbatch example-db
Python
python ddl_batch.py example-db
C#
dotnet run ddlbatch example-db
Dovresti vedere:
Added venues and concerts tables
Scrivi i dati nella nuova colonna
Il seguente codice scrive i dati nella nuova colonna. Consente di impostare MarketingBudget
su
100000
per la riga associata a Albums(1, 1)
e su 500000
per la riga associata
a Albums(2, 2)
.
COPY
in mutazioni. I comandi COPY
vengono tradotti per impostazione predefinita in mutazioni Insert
.
Esegui set spanner.copy_upsert=true
per tradurre i comandi COPY
in
InsertOrUpdate
mutazioni. Può essere usato per aggiornare i dati
esistenti in Spanner.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./update_data_with_copy.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar update example-db
Go
go run sample_runner.go update example-db
Node.js
npm start update example-db
Python
python update_data_with_copy.py example-db
C#
dotnet run update example-db
Dovresti vedere:
Updated 2 albums
Puoi anche eseguire una query SQL per recuperare i valori che hai appena scritto.
Ecco il codice per eseguire la query:
psql
Java
Go
Node.js
Python
C#
Esegui la query con questo comando:
psql
PGDATABASE=example-db ./query_data_with_new_column.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar querymarketingbudget example-db
Go
go run sample_runner.go querymarketingbudget example-db
Node.js
npm start querymarketingbudget example-db
Python
python query_data_with_new_column.py example-db
C#
dotnet run querymarketingbudget example-db
Dovresti vedere:
1 1 100000
1 2 null
2 1 null
2 2 500000
2 3 null
Aggiorna dati
Puoi aggiornare i dati utilizzando DML in una transazione di lettura/scrittura.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./update_data_with_transaction.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar writewithtransactionusingdml example-db
Go
go run sample_runner.go writewithtransactionusingdml example-db
Node.js
npm start writewithtransactionusingdml example-db
Python
python update_data_with_transaction.py example-db
C#
dotnet run writewithtransactionusingdml example-db
Dovresti vedere:
Transferred marketing budget from Album 2 to Album 1
Tag di transazione e di richiesta
Utilizza i tag di transazione e di richiesta per risolvere i problemi relativi a transazioni e query in Spanner. Puoi impostare
i tag di transazione e di richiesta con le variabili di sessione SPANNER.TRANSACTION_TAG
e
SPANNER.STATEMENT_TAG
.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./tags.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar tags example-db
Go
go run sample_runner.go tags example-db
Node.js
npm start tags example-db
Python
python tags.py example-db
C#
dotnet run tags example-db
Recuperare i dati utilizzando le transazioni di sola lettura
Supponiamo di voler eseguire più di una lettura per lo stesso timestamp. Le transazioni di sola lettura osservano un prefisso coerente della cronologia di commit delle transazioni, in modo che l'applicazione riceva sempre dati coerenti.
Imposta la connessione su sola lettura o utilizza l'istruzione SQL SET TRANSACTION READ ONLY
per eseguire una transazione di sola lettura.
Di seguito viene illustrato come eseguire una query ed eseguire una lettura nella stessa transazione di sola lettura:
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./read_only_transaction.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar readonlytransaction example-db
Go
go run sample_runner.go readonlytransaction example-db
Node.js
npm start readonlytransaction example-db
Python
python read_only_transaction.py example-db
C#
dotnet run readonlytransaction 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
2 2 Forever Hold Your Peace
1 2 Go, Go, Go
2 1 Green
2 3 Terrified
1 1 Total Junk
Query partizionate e Data Boost
L'API partitionQuery
suddivide una query in parti o partizioni più piccole e utilizza più
macchine per recuperare le partizioni in parallelo. Ogni partizione è identificata da un
token di partizione. L'API PartitionQuery ha una latenza più elevata rispetto all'API Query standard perché è destinata solo a operazioni collettive come l'esportazione o la scansione dell'intero database.
Data Boost consente di eseguire query di analisi ed esportazioni di dati con un impatto quasi zero sui carichi di lavoro esistenti sull'istanza Spanner di cui è stato eseguito il provisioning. Data Boost supporta solo le query partizionate.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./data_boost.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar databoost example-db
Go
go run sample_runner.go databoost example-db
Node.js
npm start databoost example-db
Python
python data_boost.py example-db
C#
dotnet run databoost example-db
Per ulteriori informazioni sull'esecuzione di query partizionate e sull'utilizzo di Data Boost con PGAdapter, consulta: Data Boost e istruzioni per le query partizionate
DML partizionato
DML (Partitioned Data Manipulation Language) è progettato per i seguenti tipi di aggiornamenti ed eliminazioni collettive:
- Pulizia periodica e garbage collection.
- Backfill di nuove colonne con valori predefiniti.
psql
Java
Go
Node.js
Python
C#
Esegui l'esempio con questo comando:
psql
PGDATABASE=example-db ./partitioned_dml.sh
Java
java -jar target/pgadapter-snippets/pgadapter-samples.jar partitioneddml example-db
Go
go run sample_runner.go partitioneddml example-db
Node.js
npm start partitioneddml example-db
Python
python partitioned_dml.py example-db
C#
dotnet run datpartitioneddmlboost example-db
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 (i costi per l'istanza continueranno a essere addebitati).
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ù sulle credenziali di autorizzazione e autenticazione in Autenticare nei servizi Cloud utilizzando librerie client.
Scopri di più sulle best practice per la progettazione dello schema di Spanner.