Objectifs
Ce tutoriel décrit les étapes suivantes à l'aide de l'API Spanner Pilote JDBC:
- 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 JDBC local
Installez les éléments suivants sur votre ordinateur de développement si ce n'est déjà fait :
- Java 8 JDK (télécharger).
- Maven 3 (télécharger)
Clonez le dépôt de l'exemple d'application sur votre machine locale :
git clone https://github.com/googleapis/java-spanner-jdbc.git
Accédez au répertoire qui contient l'exemple de code Spanner:
cd java-spanner-jdbc/samples/snippets
Créer une instance
Lorsque vous utilisez Spanner pour la première fois, vous devez créer une instance, l'allocation des 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 page À 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.)
Vous devriez obtenir le résultat suivant :
Creating instance...done.
Consulter des exemples de fichiers
Le dépôt d'exemples contient un exemple qui montre comment utiliser Spanner avec JDBC.
pom.xml
ajoute le pilote JDBC Spanner au
du projet et configure le plug-in d'assembly pour créer une
fichier JAR exécutable avec la classe Java définie dans ce tutoriel.
Générez l'exemple à partir du répertoire samples/snippets
:
mvn package -DskipTests
Créer une base de données
Créez une base de données nommée example-db
dans l'instance test-instance
en procédant comme suit :
en exécutant la commande suivante sur la ligne de commande.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createdatabase test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createpgdatabase test-instance example-db
Vous devriez obtenir le résultat suivant :
Created database [projects/my-project/instances/test-instance/databases/example-db]
GoogleSQL
PostgreSQL
L'étape suivante consiste à écrire des données dans la base de données.
Créer une connexion JDBC
Pour pouvoir effectuer des opérations de lecture ou d'écriture, vous devez créer un objetConnection
. Toutes vos interactions
avec Spanner doivent passer par un Connection
. Le nom de la base de données et d'autres
sont spécifiées dans l'URL de connexion JDBC et dans
java.util.Properties
défini.
GoogleSQL
PostgreSQL
Pour obtenir la liste complète des propriétés compatibles, consultez la section Propriétés de l'URL de connexion.
Chaque Connection
utilise des ressources. Il est donc recommandé de fermer
des connexions lorsqu'elles ne sont plus nécessaires, ou utiliser un pool de connexions
et réutiliser des connexions
dans l'ensemble de votre application.
Pour en savoir plus, consultez la documentation Javadoc sur Connection
.
référence.
Connecter le pilote JDBC à l'émulateur
Vous pouvez connecter le pilote JDBC à l'émulateur Spanner dans de deux manières:
- Définissez la variable d'environnement
SPANNER_EMULATOR_HOST
: cela indique au pilote JDBC de se connecter à l'émulateur. Spanner l'instance et la base de données de l'URL de connexion JDBC doivent déjà exister sur le émulateur d'application. - Ajoutez
autoConfigEmulator=true
à l'URL de connexion. Cela indique au pilote JDBC de se connecter à l'émulateur et de créer automatiquement l'instance et la base de données Spanner dans l'URL de connexion JDBC s'ils n'existent pas.
Cet exemple montre comment utiliser l'option d'URL de connexion autoConfigEmulator=true
.
GoogleSQL
PostgreSQL
É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.
Utilisez la méthode PreparedStatement.executeUpdate()
pour exécuter une instruction LMD.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlpg test-instance example-db
Vous devriez obtenir le résultat suivant :
4 records inserted.
Écrire des données avec un lot de LMD
Vous utilisezPreparedStatement#addBatch()
et
PreparedStatement#executeBatch()
pour exécuter plusieurs instructions LMD dans
un lot.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatchpg test-instance example-db
Vous devriez obtenir le résultat suivant :
3 records inserted.
Écrire des données avec des mutations
Vous pouvez également insérer des données à l'aide de mutations.
Vous pouvez écrire des données à l'aide de
Un objet Mutation
.
Un objet Mutation
est un conteneur pour les opérations de mutation. Mutation
représente une séquence d'opérations (insertions, mises à jour et suppressions) effectuées par Spanner
s'applique de manière atomique à différentes lignes et tables d'une base de données Spanner.
newInsertBuilder()
de la classe Mutation
crée une mutation INSERT
, qui insère une
nouvelle ligne d'une table. Si la ligne existe déjà, l'écriture échoue. Par ailleurs,
vous pouvez utiliser la méthode newInsertOrUpdateBuilder
pour créer une mutation INSERT_OR_UPDATE
, qui met à jour les valeurs de colonne
si la ligne existe déjà.
write()
de l'interface CloudSpannerJdbcConnection
écrit les mutations. Tout
d'un même lot sont appliquées de manière atomique.
Vous pouvez désencapsuler l'interface CloudSpannerJdbcConnection
d'une instance Spanner
Connection
JDBC.
Le code ci-dessous montre comment écrire les données à l'aide de mutations :
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
write test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writepg test-instance example-db
Vous devriez obtenir le résultat suivant :
Inserted 10 rows.
Interroger des données à l'aide de SQL
Spanner accepte une interface SQL pour la lecture des données, que vous pouvez via la ligne de commande à l'aide de la Google Cloud CLI de manière programmatique à l'aide le pilote JDBC Spanner.
Sur la ligne de commande
Exécutez l'instruction SQL suivante pour lire les valeurs de toutes les colonnes de la table Albums
:
GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
PostgreSQL
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 le pilote JDBC Spanner
Outre l'exécution d'une instruction SQL via la ligne de commande, vous pouvez utiliser le la même instruction SQL de manière programmatique à l'aide du pilote JDBC Spanner.
Les méthodes et classes ci-dessous sont utilisées pour exécuter la requête SQL :- Méthode
createStatement()
de l'interfaceConnection
: utilisez-la pour créer un objet d'instruction permettant d'exécuter une instruction SQL. - Méthode
executeQuery(String)
de la classeStatement
: utilisez cette méthode pour exécuter une requête sur une base de données. Statement
classe: permet d'exécuter une chaîne SQL.- Classe
ResultSet
: utilisez cette classe pour accéder aux données renvoyées par une instruction SQL.
Le code ci-dessous permet d'exécuter la requête et d'accéder aux données.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
query test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querypg test-instance 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 les 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 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
.
Utiliser un java.sql.PreparedStatement
pour exécuter une requête avec un paramètre.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameter test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameterpg test-instance 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, tandis que
continue de diffuser du trafic. Les mises à jour de schéma ne nécessitent pas
hors ligne et ne verrouillent pas
des tables ou des colonnes entières ; vous pouvez continuer
l'écriture de 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 la page Effectuer des mises à jour de schéma.
Ajouter une colonne
Vous pouvez ajouter une colonne sur la ligne de commande à l'aide de la Google Cloud CLI ou de manière programmatique à l'aide le pilote du pilote JDBC Spanner.
Sur la ligne de commande
Pour ajouter la colonne à la table, utilisez la commande ALTER TABLE
suivante :
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 marketing_budget BIGINT'
Vous devriez obtenir le résultat suivant :
Schema updating...done.
Utiliser le pilote JDBC Spanner
Pour modifier le schéma, utilisez la méthodeexecute(String)
de la classe java.sql.Statement
:
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudgetpg test-instance example-db
Vous devriez obtenir le résultat suivant :
Added MarketingBudget column.
Exécuter un lot LDD
Nous vous recommandons d'exécuter plusieurs modifications de schéma dans un même lot. Utilisez les
addBatch(String)
de java.sql.Statement
pour ajouter plusieurs instructions LDD à un lot.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatchpg test-instance example-db
Vous devriez obtenir le résultat suivant :
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)
.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
update test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
updatepg test-instance example-db
Le résultat doit ressembler à ce qui suit :
Updated albums
Vous pouvez également exécuter une requête SQL ou un appel de lecture 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.
GoogleSQL
PostgreSQL
Pour exécuter cette requête, exécutez la commande suivante:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudgetpg test-instance example-db
Vous devriez obtenir le résultat suivant :
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.
Définissez AutoCommit=false
pour exécuter des transactions en lecture-écriture dans JDBC.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdmlpg test-instance example-db
Tags de transaction et tags de requête
Utilisez des 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
tags de transaction et tags de requête dans le JDBC avec le TRANSACTION_TAG
et STATEMENT_TAG
variables de session.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tags test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tagspg test-instance 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 ReadOnly=true
et AutoCommit=false
sur un java.sql.Connection
, ou utilisez
l'instruction SQL SET TRANSACTION READ ONLY
, pour exécuter une requête
transaction.
L'exemple ci-dessous montre comment exécuter une requête et effectuer une lecture dans la même transaction en lecture seule.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransaction test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransactionpg test-instance 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
partitionQuery
L'API divise une requête en éléments plus petits, ou partitions, et utilise plusieurs
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 standard
de requête, car elle est uniquement destinée à des opérations groupées telles que l'exportation
pour analyser l'ensemble 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 une sur les charges de travail existantes de l'instance Spanner provisionnée. Data Boost n'est compatible qu'avec les requêtes partitionnées.
GoogleSQL
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoost test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoostpg test-instance example-db
Pour en savoir plus sur l'exécution de requêtes partitionnées et l'utilisation de Data Boost avec le pilote JDBC, consultez les ressources suivantes :
- GoogleSQL : Data Boost et instructions de requête partitionnées
- PostgreSQL : Data Boost et instructions de requête partitionnées
LMD partitionné
Le langage de manipulation de données (LMD) partitionné est conçu pour les types de mises à jour et de suppressions groupées suivants :
- Nettoyage périodique et récupération de mémoire.
- Remplissage de nouvelles colonnes avec des valeurs par défaut.
PostgreSQL
Exécutez l'exemple avec la commande suivante :
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdmlpg test-instance example-db
Pour en savoir plus sur AUTOCOMMIT_DML_MODE
, consultez les pages suivantes:
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 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 Spanner dans la console Google Cloud.
Cliquez sur votre instance.
Cliquez sur Supprimer.
Confirmez que vous souhaitez supprimer l'instance, puis cliquez sur Supprimer.
Étape suivante
- Découvrez comment intégrer Spanner à Spring Data JPA (dialecte GoogleSQL).
- Découvrez comment intégrer Spanner à Spring Data JPA (dialecte PostgreSQL).
- Découvrez comment intégrer Spanner à Hibernate ORM (dialecte GoogleSQL).
- Découvrez comment intégrer Spanner à Hibernate ORM (dialecte PostgreSQL).
- En savoir plus sur les commandes de gestion des sessions JDBC (GoogleSQL)
- En savoir plus sur les commandes de gestion des sessions JDBC (PostgreSQL)
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.