Objectifs
Ce tutoriel vous guide à travers les étapes suivantes à l'aide de la gcloud CLI :
- 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 décrites sur cette page s'appliquent aux bases de données utilisant le dialecte GoogleSQL et à celles utilisant le dialecte PostgreSQL.
Pour obtenir la documentation de référence complète sur Spanner gcloud, consultez gcloud.
Tarifs
Ce tutoriel utilise Spanner, qui est un composant facturable deGoogle Cloud. Pour en savoir plus sur le coût d'utilisation de Spanner, consultez la page Tarifs.
Avant de commencer
Suivez les étapes décrites dans la section Installer la gcloud CLI 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, activation de l'API Cloud Spanner et configuration d'OAuth 2.0 pour obtenir les identifiants d'authentification permettant d'utiliser l'API Cloud Spanner.
En particulier, veillez à 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 spanner instance-configs list
Instances
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 l'emplacement de stockage de vos donné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 d'instance, qui est comme un plan pour votre instance qui définit l'emplacement géographique et la réplication de vos 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 seule 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 dans 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 spanner instance-configs list
La liste des configurations régionales, birégionales et multirégionales devrait 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 spanner 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 .
Définir l'instance par défaut
Vous pouvez définir l'instance par défaut que Spanner utilise lorsque vous n'avez pas spécifié 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 base de données par défaut est GoogleSQL.
GoogleSQL
gcloud spanner databases create example-db
PostgreSQL
gcloud spanner databases create example-db --database-dialect=POSTGRESQL
Mettre à jour le schéma
Utilisez le langage de définition de données (LDD) de Spanner pour créer, modifier ou supprimer des tables, et pour créer ou supprimer des index.
Créons deux tables :
GoogleSQL
gcloud spanner 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 spanner 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 spanner 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 spanner 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 spanner operations describe.
Cette commande nécessite l'ID de l'opération.
Obtenez l'ID de l'opération :
gcloud spanner 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 spanner operations describe :
gcloud spanner 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 spanner rows insert --database=example-db \ --table=Singers \ --data=SingerId=1,FirstName=Marc,LastName=Richards gcloud spanner rows insert --database=example-db \ --table=Singers \ --data=SingerId=2,FirstName=Catalina,LastName=Smith gcloud spanner rows insert --database=example-db \ --table=Singers \ --data=SingerId=3,FirstName=Alice,LastName=Trentor gcloud spanner rows insert --database=example-db \ --table=Albums \ --data=SingerId=1,AlbumId=1,AlbumTitle="Total Junk" gcloud spanner rows insert --database=example-db \ --table=Albums \ --data=SingerId=2,AlbumId=1,AlbumTitle="Green" gcloud spanner 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 spanner databases execute-sql example-db \ --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')" gcloud spanner databases execute-sql example-db \ --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (2, 'Catalina', 'Smith')" gcloud spanner databases execute-sql example-db \ --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (3, 'Alice', 'Trentor')" gcloud spanner databases execute-sql example-db \ --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (1, 1, 'Total Junk')" gcloud spanner databases execute-sql example-db \ --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 1, 'Green')" gcloud spanner 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 spanner databases execute-sql example-db \ --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
Pour obtenir la documentation de référence sur Spanner SQL, consultez Syntaxe des requêtes pour GoogleSQL ou Syntaxe des requêtes pour PostgreSQL.
Pour afficher la liste des options que vous pouvez utiliser avec la commande execute-sql, consultez gcloud spanner databases execute-sql.
Nettoyage
Pour éviter que des frais supplémentaires ne soient facturés sur votre compte Google Cloud , supprimez la base de données et l'instance. La désactivation de l'API Cloud Billing n'arrête pas les frais. Lorsque vous supprimez une instance, toutes les bases de données qu'elle contient sont supprimées.
Supprimer une base de données
Pour supprimer une instance existante, utilisez la commande suivante :
gcloud spanner databases delete example-db
Supprimer une instance
Pour supprimer une instance existante, utilisez la commande suivante :
gcloud spanner 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.