Créer et interroger une base de données à l'aide de la Google Cloud CLI

Objectifs

Ce tutoriel vous explique comment effectuer les étapes suivantes à l'aide de la CLI gcloud:

  • Créer une instance, une base de données et un schéma Spanner
  • Écrire des données dans la base de données et exécuter des requêtes SQL sur celles-ci
  • Nettoyer en supprimant la base de données et l'instance

Les procédures de cette page s'appliquent aux bases de données en dialecte GoogleSQL et en dialecte PostgreSQL.

Pour obtenir une description complète des commandes gcloud Spanner, consultez la documentation gcloud.

Tarifs

Ce tutoriel utilise Spanner, un composant facturable deGoogle 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 Installer la CLI gcloud et configurer l'API Cloud Spanner, 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.

Définir un projet par défaut

Si vous ne l'avez pas déjà fait, définissez l'ID d'un projet Google Cloud comme projet par défaut pour la Google Cloud CLI:

gcloud config set project PROJECT_ID

Si vous ne définissez pas le projet par défaut, vous devez transmettre --project PROJECT_ID à chacune des commandes ci-dessous en tant que premier argument de gcloud. Exemple :

gcloud --project=PROJECT_ID instance-configs list

Instances

Lorsque vous utilisez Spanner pour la première fois, vous devez créer une instance, c'est-à-dire un élément qui alloue les ressources utilisées par les bases de données Spanner. Lorsque vous créez une instance, vous choisissez l'emplacement où vos données sont stockées et la capacité de calcul de l'instance.

Instances et configurations d'instance

Pour créer une instance, vous devez sélectionner une configuration qui servira de schéma directeur. Elle définit l'emplacement géographique et le mode de réplication des données Spanner.

Afficher la liste des configurations d'instance

Lorsque vous créez une instance, vous devez spécifier une configuration d'instance, qui permet de définir l'emplacement géographique et la réplication de vos bases de données au sein de cette instance. Vous pouvez choisir une configuration régionale, qui stocke les données dans une région, une configuration birégionale, qui stocke les données dans deux régions du même pays, ou une configuration multirégionale, qui répartit les données sur plusieurs régions. Pour en savoir plus, consultez la présentation des instances.

Pour afficher l'ensemble des configurations d'instance disponibles pour votre projet, utilisez la commande suivante :

gcloud instance-configs list

Une liste de configurations régionales, birégionales et multirégionales doit s'afficher.

Créer une instance

Pour créer une instance nommée test-instance avec le nom à afficher My Instance à l'aide de la configuration d'instance régionale regional-us-central1 qui comporte un nœud, exécutez la commande suivante :

gcloud instances create test-instance --config=regional-us-central1 \
    --description="My Instance" --nodes=1

Dans la commande ci-dessus, le nom de l'instance est défini sur test-instance. --description correspond au nom à afficher de l'instance. Ces deux valeurs doivent être uniques dans un projet Google Cloud Platform.

Définir l'instance par défaut

Vous pouvez définir l'instance par défaut que Spanner utilise lorsque vous ne spécifiez pas d'instance dans votre commande. Pour définir l'instance par défaut, exécutez la commande suivante :

gcloud config set spanner/instance test-instance

Créer une base de données

Créez une base de données nommée example-db. Le dialecte de la base de données est GoogleSQL par défaut.

GoogleSQL

gcloud databases create example-db

PostgreSQL

gcloud databases create example-db --database-dialect=POSTGRESQL

Mettre à jour le schéma

Utilisez le langage de définition de données (DDL, Data Definition Language) de Spanner pour créer, modifier ou supprimer des tables, mais aussi pour créer ou supprimer des index.

Créons deux tables:

GoogleSQL

gcloud databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId INT64 NOT NULL, FirstName STRING(1024), LastName STRING(1024), SingerInfo BYTES(MAX) ) PRIMARY KEY (SingerId)'

gcloud databases ddl update example-db \
--ddl='CREATE TABLE Albums ( SingerId INT64 NOT NULL, AlbumId INT64 NOT NULL, AlbumTitle STRING(MAX)) PRIMARY KEY (SingerId, AlbumId), INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

PostgreSQL

gcloud databases ddl update example-db \
--ddl='CREATE TABLE Singers ( SingerId bigint NOT NULL, FirstName varchar(1024), LastName varchar(1024), SingerInfo bytea, PRIMARY KEY (SingerId) )'

gcloud databases ddl update example-db \
--ddl='CREATE TABLE Albums ( SingerId bigint NOT NULL, AlbumId bigint NOT NULL, AlbumTitle varchar, PRIMARY KEY (SingerId, AlbumId) ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE'

Pour vérifier la progression de l'opération, utilisez gcloud operations describe. Cette commande nécessite l'ID de l'opération.

Obtenez l'ID de l'opération:

gcloud operations list --instance="test-instance" \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

Remplacez DATABASE-NAME par le nom de la base de données.

Exécutez gcloud operations describe :

gcloud operations describe \
  --instance="test-instance" \
  --database="example-db" \
  projects/PROJECT-NAME/instances/test-instance/databases/example-db/operations/OPERATION-ID

Remplacez les éléments suivants :

  • PROJECT-NAME: nom du projet.
  • OPERATION-ID: ID de l'opération que vous souhaitez vérifier.

La sortie ressemble à ceci :

done: true
metadata:
...
progress:
- endTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
  startTime: '2022-03-01T00:28:04.221401Z'
- endTime: '2022-03-01T00:28:17.624588Z'
  startTime: '2022-03-01T00:28:06.691403Z'
  progressPercent: 100
...

Écrire des données

Ajoutons des exemples de données à notre base de données

GoogleSQL

gcloud rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=1,FirstName=Marc,LastName=Richards

gcloud rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=2,FirstName=Catalina,LastName=Smith

gcloud rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=3,FirstName=Alice,LastName=Trentor

gcloud rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=1,AlbumId=1,AlbumTitle="Total Junk"

gcloud rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=2,AlbumId=1,AlbumTitle="Green"

gcloud rows insert --database=example-db \
  --table=Albums \
  --data=^:^SingerId=2:AlbumId=2:AlbumTitle="Go, Go, Go"

Par défaut, une virgule est utilisée pour délimiter les éléments des listes. Dans la dernière commande d'insertion, nous avons spécifié un deux-points (^:^) comme délimiteur afin de pouvoir utiliser une virgule dans le titre de l'album.

PostgreSQL

gcloud databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')"

gcloud databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (2, 'Catalina', 'Smith')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (3, 'Alice', 'Trentor')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (1, 1, 'Total Junk')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 1, 'Green')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 2, 'Go, Go, Go')"

Interroger des données à l'aide de SQL

Exécutez une requête sur la ligne de commande :

gcloud databases execute-sql example-db \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

Pour en savoir plus sur le langage SQL Spanner, consultez la page Syntaxe des requêtes GoogleSQL ou Syntaxe des requêtes PostgreSQL.

Pour afficher la liste des options que vous pouvez utiliser avec la commande execute-sql, consultez gcloud databases execute-sql.

Nettoyage

Pour éviter que des frais supplémentaires ne soient facturés sur votre compte Google Cloud pour les ressources utilisées dans ce tutoriel, supprimez la base de données et l'instance que vous avez créées.

Supprimer une base de données

Pour supprimer une instance existante, utilisez la commande suivante :

gcloud databases delete example-db

Supprimer une instance

Pour supprimer une instance existante, utilisez la commande suivante :

gcloud instances delete test-instance

La suppression d'une instance supprime également toutes les bases de données qu'elle contient. Cette opération est irréversible.