Objectifs
Ce tutoriel décrit les étapes suivantes à l'aide des pilotes du proxy local PGAdapter pour PostgreSQL de Spanner:
- Créer une instance et une base de données Spanner
- Écrire ou lire des données dans la base de données, et exécuter des requêtes SQL sur ces données
- Mettre à jour le schéma de base de données
- Mettre à jour les données à l'aide d'une transaction en lecture/écriture
- Ajouter un index secondaire à la base de données
- Utiliser l'index pour lire et exécuter des requêtes SQL sur des données
- Récupérer des données à l'aide d'une transaction en lecture seule
Coûts
Ce tutoriel utilise Spanner, un composant facturable de Google Cloud. Pour en savoir plus sur le coût d'utilisation de Spanner, consultez la page Tarifs.
Avant de commencer
Pour obtenir les identifiants d'authentification permettant d'utiliser l'API Cloud Spanner, suivez les étapes décrites dans la section dédiée à la configuration qui traite des sujets suivants : création et définition d'un projet Google Cloud par défaut, activation de la facturation ainsi que de l'API Cloud Spanner, et configuration d'OAuth 2.0.
Veillez en particulier à exécuter gcloud auth
application-default login
pour configurer votre environnement de développement local avec des identifiants d'authentification.
Préparer votre environnement PGAdapter local
Vous pouvez utiliser des pilotes PostgreSQL en combinaison avec PGAdapter pour vous connecter à Spanner. PGAdapter est un proxy local qui traduit le protocole réseau PostgreSQL en protocole gRPC Spanner.
PGAdapter nécessite Java ou Docker pour s'exécuter.
Installez l'un des éléments suivants sur votre ordinateur de développement si aucun d'entre eux n'est déjà installé:
- Java 8 JDK (télécharger).
- Docker (télécharger)
Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
git clone https://github.com/GoogleCloudPlatform/pgadapter.git
Accédez au répertoire qui contient l'exemple de code 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
Créer une instance
Lorsque vous utilisez Spanner pour la première fois, vous devez créer une instance, qui alloue les ressources utilisées par les bases de données Spanner. Lorsque vous créez une instance, vous choisissez une configuration d'instance, qui détermine l'emplacement de stockage de vos données et le nombre de nœuds à utiliser. Ce dernier paramètre définit la quantité de ressources disponibles dans votre instance pour le stockage et la diffusion.
Exécutez la commande suivante pour créer une instance Spanner dans la région us-central1
avec un nœud:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
Cette commande crée une instance présentant les caractéristiques suivantes :
- ID d'instance :
test-instance
- Nom à afficher :
Test Instance
- Configuration d'instance :
regional-us-central1
(Les configurations régionales stockent les données dans une région, tandis que les configurations multirégionales les distribuent dans plusieurs régions. Pour en savoir plus, consultez la section À propos des instances.) - Nombre de nœuds : 1 (
node_count
correspond à la quantité de ressources de stockage et de diffusion disponibles pour les bases de données de l'instance. Pour en savoir plus, consultez la section Nœuds et unités de traitement.)
La page affichée doit ressembler à celle-ci :
Creating instance...done.
Consulter des exemples de fichiers
Le dépôt d'exemples contient un exemple qui montre comment utiliser Spanner avec PGAdapter.
Examinez le dossiersamples/snippets
, qui montre comment utiliser Spanner. Le code indique comment créer et utiliser une base de données. Les données utilisent l'exemple de schéma présenté sur la page Schéma et modèle de données.
Démarrer PGAdapter
Démarrez PGAdapter sur votre ordinateur de développement local et faites-le pointer vers l'instance que vous avez créée.
Les commandes suivantes supposent que vous avez exécuté gcloud auth application-default login
.
Application 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
Cette opération lance PGAdapter avec un émulateur Spanner intégré. Cet émulateur intégré crée automatiquement toute instance ou base de données Spanner à laquelle vous vous connectez, sans avoir à les créer manuellement au préalable.
Nous vous recommandons d'exécuter PGAdapter en production en tant que conteneur side-car ou en tant que dépendance dans le processus. Pour en savoir plus sur le déploiement de PGAdapter en production, consultez la section Choisir une méthode d'exécution de PGAdapter.
Créer une base de données
Créez une base de données nommée example-db
dans l'instance test-instance
en exécutant la commande suivante dans la ligne de commande.
gcloud spanner databases create example-db --instance=test-instance \
--database-dialect=POSTGRESQL
La page affichée doit ressembler à celle-ci :
Creating database...done.
Créer des tables
Le code suivant crée deux tables dans la base de données.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
L'étape suivante consiste à écrire des données dans la base de données.
Créer une connexion
Pour pouvoir effectuer des opérations de lecture ou d'écriture, vous devez créer une connexion à PGAdapter. Toutes vos interactions avec Spanner doivent passer par unConnection
. Le nom de la base de données est spécifié dans la chaîne de connexion.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
Écrire des données avec le langage LMD
Vous pouvez insérer des données à l'aide du langage de manipulation de données (LMD) dans une transaction en lecture/écriture.
Ces exemples montrent comment exécuter une instruction LMD sur Spanner à l'aide d'un pilote PostgreSQL.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
La réponse suivante devrait s'afficher :
4 records inserted.
Écrire des données avec un lot LMD
PGAdapter permet d'exécuter des lots LMD. L'envoi de plusieurs instructions LMD en un seul lot réduit le nombre d'allers-retours vers Spanner et améliore les performances de votre application.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
La page affichée doit ressembler à celle-ci :
3 records inserted.
Écrire des données avec des mutations
Vous pouvez également insérer des données à l'aide de mutations.
PGAdapter traduit la commande PostgreSQL COPY
en mutations. L'utilisation de COPY
est le moyen le plus efficace d'insérer rapidement des données dans votre base de données Spanner.
Les opérations COPY
sont atomiques par défaut. Les opérations atomiques sur Spanner sont liées à la limite de taille du commit.
Pour en savoir plus, consultez la section Limite CRUD.
Ces exemples montrent comment exécuter une opération COPY
non atomique. Cela permet à l'opération COPY
de dépasser la limite de taille du commit.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
La page affichée doit ressembler à celle-ci :
Copied 5 singers
Copied 5 albums
Interroger des données à l'aide de SQL
Spanner accepte une interface SQL pour la lecture des données. Vous pouvez accéder à cette interface via la ligne de commande à l'aide de Google Cloud CLI, ou de manière automatisée à l'aide d'un pilote PostgreSQL.
Sur la ligne de commande
Exécutez l'instruction SQL suivante pour lire les valeurs de toutes les colonnes de la table Albums
:
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT singer_id, album_id, album_title FROM albums'
Vous devez obtenir le résultat suivant :
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Utiliser un pilote PostgreSQL
Outre l'exécution d'une instruction SQL via la ligne de commande, vous pouvez émettre la même instruction SQL de manière automatisée à l'aide d'un pilote PostgreSQL.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
Vous devriez obtenir le résultat suivant :
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Requête utilisant un paramètre SQL
Si votre application comporte une requête fréquemment exécutée, vous pouvez améliorer ses performances en la paramétrant. La requête paramétrique obtenue peut être mise en cache et réutilisée, ce qui réduit les coûts de compilation. Pour en savoir plus, consultez la section Utiliser des paramètres de requête pour accélérer les requêtes fréquemment exécutées.
Voici un exemple d'utilisation d'un paramètre dans la clause WHERE
pour interroger des enregistrements contenant une valeur spécifique pour LastName
.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
Vous devriez obtenir le résultat suivant :
12 Melissa Garcia
Mettre à jour le schéma de base de données
Supposons que vous deviez ajouter la colonne MarketingBudget
à la table Albums
. L'ajout d'une colonne à une table existante nécessite une mise à jour du schéma de base de données. Spanner permet de mettre à jour le schéma d'une base de données pendant que celle-ci continue à diffuser du trafic. Les mises à jour de schéma ne nécessitent pas de mettre la base de données hors connexion et ne verrouillent pas des tables ou des colonnes entières. Vous pouvez continuer à écrire des données dans la base de données pendant la mise à jour du schéma. Pour en savoir plus sur les mises à jour de schéma acceptées et sur les performances liées aux modifications de schéma, consultez Effectuer des mises à jour de schéma.
Ajouter une colonne
Vous pouvez ajouter une colonne via la ligne de commande à l'aide de la Google Cloud CLI, ou de manière automatisée à l'aide d'un pilote PostgreSQL.
Sur la ligne de commande
Pour ajouter la colonne à la table, utilisez la commande ALTER TABLE
suivante :
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE albums ADD COLUMN marketing_budget BIGINT'
La page affichée doit ressembler à celle-ci :
Schema updating...done.
Utiliser un pilote PostgreSQL
Exécutez l'instruction LDD à l'aide d'un pilote PostgreSQL pour modifier le schéma:
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
La page affichée doit ressembler à celle-ci :
Added marketing_budget column
Exécuter un lot LDD
Il est recommandé d'exécuter plusieurs modifications de schéma dans un seul lot.
Vous pouvez exécuter plusieurs instructions LDD dans un même lot à l'aide de la fonctionnalité de traitement par lot intégrée de votre pilote PostgreSQL, en soumettant toutes les instructions LDD sous la forme d'une chaîne SQL séparée par un point-virgule, ou en utilisant les instructions START BATCH DDL
et RUN BATCH
.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
La page affichée doit ressembler à celle-ci :
Added venues and concerts tables
Écrire des données dans la nouvelle colonne
Le code ci-dessous permet d'écrire des données dans la nouvelle colonne. Il définit MarketingBudget
sur 100000
pour la ligne correspondant à la clé Albums(1, 1)
et sur 500000
pour la ligne correspondant à la clé Albums(2, 2)
.
COPY
en mutations. Par défaut, les commandes COPY
sont traduites en mutations Insert
.
Exécutez set spanner.copy_upsert=true
pour traduire les commandes COPY
en mutations InsertOrUpdate
. Cela permet de mettre à jour des données existantes dans Spanner.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
La page affichée doit ressembler à celle-ci :
Updated 2 albums
Vous pouvez également exécuter une requête SQL pour récupérer les valeurs que vous venez d'écrire.
Le code permettant d'exécuter la requête est présenté ci-dessous.
psql
Java
Go
Node.js
Python
C#
Exécutez la requête à l'aide de la commande suivante:
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
La page affichée doit ressembler à celle-ci :
1 1 100000
1 2 null
2 1 null
2 2 500000
2 3 null
Mettre à jour des données
Vous pouvez mettre à jour des données à l'aide du langage LMD dans une transaction en lecture/écriture.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
La page affichée doit ressembler à celle-ci :
Transferred marketing budget from Album 2 to Album 1
Tags de transaction et tags de requête
Utilisez les tags de transaction et de requête pour résoudre les problèmes liés aux transactions et aux requêtes dans Spanner. Vous pouvez définir des balises de transaction et des balises de requête avec les variables de session SPANNER.TRANSACTION_TAG
et SPANNER.STATEMENT_TAG
.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
Récupérer des données à l'aide de transactions en lecture seule
Supposons que vous souhaitiez exécuter plusieurs opérations de lecture avec le même horodatage. Les transactions en lecture seule tiennent compte d'un préfixe cohérent de l'historique de commit des transactions, de sorte que votre application obtienne toujours des données cohérentes.
Définissez la connexion en lecture seule ou utilisez l'instruction SQL SET TRANSACTION READ ONLY
pour exécuter une transaction en lecture seule.
L'exemple ci-dessous montre comment exécuter une requête et effectuer une lecture dans la même transaction en lecture seule.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
Un résultat semblable à celui-ci s'affiche :
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
Requêtes partitionnées et Data Boost
L'API partitionQuery
divise une requête en parties plus petites, ou partitions, et utilise plusieurs machines pour extraire les partitions en parallèle. Chaque partition est identifiée par un jeton de partition. L'API PartitionQuery présente une latence supérieure à celle de l'API Query standard, car elle est uniquement destinée à des opérations groupées, telles que l'exportation ou l'analyse de l'intégralité de la base de données.
Data Boost vous permet d'exécuter des requêtes d'analyse et des exportations de données avec un impact quasi nul sur les charges de travail existantes sur l'instance Spanner provisionnée. Data Boost n'est compatible qu'avec les requêtes partitionnées.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
Pour en savoir plus sur l'exécution de requêtes partitionnées et l'utilisation de Data Boost avec PGAdapter, consultez la section Instructions de requêtes partitionnées et Data Boost.
LMD partitionné
Le langage de manipulation de données partitionné (LMD) est conçu pour les types suivants de mises à jour et de suppressions groupées:
- Nettoyage périodique et récupération de mémoire.
- Remplissage de nouvelles colonnes avec des valeurs par défaut.
psql
Java
Go
Node.js
Python
C#
Exécutez l'exemple à l'aide de la commande suivante:
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
Nettoyage
Pour éviter que des frais supplémentaires ne soient facturés sur votre compte Cloud Billing pour les ressources utilisées dans ce tutoriel, supprimez la base de données et l'instance que vous avez créées.
Supprimer la base de données
Si vous supprimez une instance, toutes les bases de données qu'elle contient sont automatiquement supprimées. Cette étape montre comment supprimer une base de données sans supprimer l'instance. Des frais continueront à vous être facturés pour cette dernière.
Sur la ligne de commande
gcloud spanner databases delete example-db --instance=test-instance
Utiliser la console Google Cloud
Accédez à la page Instances de Spanner dans la console Google Cloud.
Cliquez sur l'instance.
Cliquez sur la base de données que vous souhaitez supprimer.
Sur la page Détails de la base de données, cliquez sur Supprimer.
Confirmez que vous souhaitez supprimer la base de données, puis cliquez sur Supprimer.
Supprimer l'instance
La suppression d'une instance supprime automatiquement toutes les bases de données créées dans cette instance.
Sur la ligne de commande
gcloud spanner instances delete test-instance
Utiliser la console Google Cloud
Accédez à la page Instances de Spanner dans la console Google Cloud.
Cliquez sur votre instance.
Cliquez sur Supprimer.
Confirmez que vous souhaitez supprimer l'instance, puis cliquez sur Supprimer.
Étapes suivantes
Découvrez comment accéder à Spanner avec une instance de machine virtuelle.
Pour en savoir plus sur les identifiants d'autorisation et d'authentification, consultez la page S'authentifier auprès de services cloud à l'aide de bibliothèques clientes.
En savoir plus sur les bonnes pratiques concernant la conception de schémas Spanner.