Cette page a été traduite par l'API Cloud Translation.

Démarrage rapide de la CLI Spanner

Cette page présente la CLI Spanner et explique comment l'utiliser.

L'interface de ligne de commande (CLI) Spanner vous permet de vous connecter à votre base de données Spanner et d'interagir avec elle. Elle est intégrée à la Google Cloud CLI (CLI gcloud) pour interagir avec Spanner. Vous pouvez utiliser la CLI Spanner pour exécuter directement des instructions GoogleSQL dans votre base de données Spanner. Vos instructions peuvent être des instructions LDD (langage de définition de données), LMD (langage de manipulation de données) ou LQD (langage de requête de données). Vous pouvez utiliser la CLI Spanner pour exécuter des scripts de commandes SQL et automatiser des tâches.

Il est basé sur le projet Open Source spanner-cli.

Pour en savoir plus, consultez la liste de toutes les commandes gcloud spanner cli compatibles.

Principaux avantages

Vous pouvez utiliser Spanner pour effectuer les actions suivantes :

Exécutez des commandes SQL LDD, LMD et DQL.
Écrivez et exécutez des instructions SQL sur plusieurs lignes.
Utilisez des méta-commandes pour vous aider à effectuer des tâches système telles que l'exécution d'une commande shell système et l'exécution de SQL à partir d'un fichier.
Automatisez les exécutions SQL en écrivant une série d'instructions SQL dans un fichier de script, puis en demandant à la CLI Spanner d'exécuter le script. Vous pouvez également rediriger la sortie vers un fichier de sortie.
Démarrez une session interactive Spanner CLI, qui vous permet de saisir directement des instructions SQL et des méta-commandes, et d'afficher les résultats dans la CLI.

Avant de commencer

Avant d'utiliser la CLI Spanner, assurez-vous de disposer du rôle requis et d'avoir installé la CLI.

Rôles requis

Pour obtenir les autorisations nécessaires pour installer Spanner, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Cloud Spanner (roles/spanner.admin) sur Spanner. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Installer la CLI Spanner

La CLI Spanner est disponible dans la gcloud CLI. Lorsque vous exécutez la commande gcloud spanner cli pour la première fois, gcloud CLI installe automatiquement le composant Spanner CLI.

Pour installer manuellement la CLI Spanner, exécutez la commande suivante :

gcloud components install spanner-cli

Si l'installation à l'aide de la commande Google Cloud CLI échoue ou n'est pas possible dans votre environnement de shell, Spanner fournit des packages Debian (.deb) et RPM (.rpm) autonomes. Vous pouvez utiliser ces packages pour effectuer une installation manuelle sur les systèmes compatibles. Pour l'installer, exécutez la commande suivante :

apt-get install google-cloud-cli-spanner-cli

Options de configuration

La CLI Spanner est compatible avec les options configurables suivantes :

L'option de projet est récupérée via la propriété core/project. Vous pouvez également spécifier le projet à l'aide de l'option --project.
L'option d'instance est récupérée via la propriété core/instance. Vous pouvez également spécifier l'instance à l'aide de l'option --instance.
Le point de terminaison de l'API est récupéré via la propriété api_endpoint_overrides/spanner. Vous pouvez également spécifier le point de terminaison à l'aide des options --host et --port. Le point de terminaison Spanner par défaut est utilisé si aucun point de terminaison n'est spécifié.

Utiliser la CLI Spanner

Configurer un projet Google Cloud
Configurez l'authentification à l'aide de gcloud CLI.
Créer une instance
Créez une base de données.
Exécutez la commande suivante pour démarrer la CLI Spanner et interagir avec votre base de données Spanner :
```
gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID
```
Remplacez les éléments suivants :
- DATABASE_ID : ID de la base de données Spanner. Il s'agit du nom que vous avez utilisé à l'étape précédente "Créer une base de données". Vous pouvez utiliser la commande gcloud spanner databases list pour lister les bases de données Spanner contenues dans l'instance donnée.
- INSTANCE_ID : ID de l'instance Spanner. Il s'agit du nom que vous avez utilisé à l'étape précédente "Créer une instance". Vous pouvez utiliser la commande gcloud spanner instances list pour lister les instances Spanner contenues dans le projet donné.

Exécuter du code SQL

Vous pouvez exécuter des instructions SQL dans la CLI Spanner à l'aide de l'option execute ou d'une méthode d'entrée et de sortie basée sur des fichiers. Vos instructions SQL peuvent être de type LDD, LMD ou DQL.

Utilisez l'option `execute`.

Pour utiliser l'option execute afin d'exécuter SQL, exécutez la commande gcloud spanner cli suivante :

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    --execute "SQL"

Remplacez les éléments suivants :

DATABASE_ID : ID de la base de données Spanner à laquelle vous souhaitez vous connecter.
INSTANCE_ID : ID de l'instance Spanner à laquelle vous souhaitez vous connecter.
SQL : le code SQL que vous souhaitez exécuter.

Par exemple, pour exécuter une instruction LDD :

gcloud spanner cli test-database --instance test-instance \
    --execute "CREATE TABLE Singers ( \
        SingerId   INT64 NOT NULL, \
        FirstName  STRING(1024), \
        LastName   STRING(1024), \
        SingerInfo STRING(1024), \
        BirthDate  DATE \
      ) PRIMARY KEY(SingerId);"

Pour exécuter une instruction LMD :

gcloud spanner cli test-database --instance test-instance \
    --execute "INSERT INTO Singers (SingerId, FirstName, LastName, SingerInfo) \
        VALUES(1, 'Marc', 'Richards', 'nationality: USA'), \
              (2, 'Catalina', 'Smith', 'nationality: Brazil'), \
              (3, 'Andrew', 'Duneskipper', NULL);"

Utiliser une entrée et une sortie basées sur des fichiers

Si vous utilisez la méthode d'entrée et de sortie basée sur des fichiers, Spanner lit son entrée à partir d'un fichier et écrit sa sortie dans un autre fichier. Pour utiliser la méthode d'entrée et de sortie basée sur des fichiers pour exécuter SQL, exécutez la commande suivante :

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    --source INPUT_FILE_PATH --tee OUTPUT_FILE_PATH

Vous pouvez également utiliser la méthode d'entrée et de sortie de redirection basée sur des fichiers :

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    < INPUT_FILE_PATH > OUTPUT_FILE_PATH

Remplacez les éléments suivants :

DATABASE_ID : ID de la base de données Spanner à laquelle vous souhaitez vous connecter.
INSTANCE_ID : ID de l'instance Spanner à laquelle vous souhaitez vous connecter.
SOURCE_FILE_PATH : fichier contenant le code SQL que vous souhaitez exécuter.
OUTPUT_FILE_PATH : nom du fichier auquel ajouter une copie du résultat SQL.

Démarrer une session interactive

Vous pouvez démarrer une session interactive Spanner CLI, qui vous permet de saisir directement des instructions SQL et des métacommandes, et d'afficher les résultats dans la CLI. Pour ce faire, exécutez la commande suivante :

gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID

Une fois la connexion établie entre la CLI et votre base de données, une invite (par exemple, spanner-cli>) s'affiche. Vous pouvez alors effectuer les opérations suivantes :

Saisissez directement des instructions GoogleSQL :
Exécuter des transactions
Utiliser les méta-commandes compatibles

Après avoir appuyé sur la touche ENTER, l'instruction ou la commande est envoyée à la base de données Spanner appropriée. Spanner exécute ensuite l'instruction ou la commande.

Dans l'exemple suivant, vous démarrez une session interactive dans test-database, puis exécutez SELECT 1; :

gcloud spanner cli test-database --instance test-instance

Welcome to Spanner-Cli Client.
Type 'help;' or '\h' for help.
Type 'exit;' or 'quit;' or '\q' to exit.

spanner-cli> SELECT 1;
+---+
|   |
+---+
| 1 |
+---+

1 rows in set (1.11 msecs)

Exécuter une instruction LDD

Pour exécuter une instruction LDD, vous pouvez exécuter la commande suivante :

spanner-cli> CREATE TABLE Singers (
          ->         SingerId   INT64 NOT NULL,
          ->         FirstName  STRING(1024),
          ->         LastName   STRING(1024),
          ->         SingerInfo STRING(1024),
          ->         BirthDate  DATE
          -> ) PRIMARY KEY(SingerId);

Query OK, 0 rows affected (17.08 sec)

Exécuter une instruction LMD

Pour exécuter une instruction LMD, vous pouvez exécuter la commande suivante :

spanner-cli> INSERT INTO Singers (SingerId, FirstName, LastName, SingerInfo)
          -> VALUES(1, 'Marc', 'Richards', 'nationality: USA'),
          -> (2, 'Catalina', 'Smith', 'nationality: Brazil'),
          -> (3, 'Andrew', 'Duneskipper', NULL);

Query OK, 3 rows affected (0.32 sec)

Exécuter une instruction LMD partitionnée

Dans la CLI Spanner, vous pouvez utiliser le mot clé PARTITIONED avec les commandes UPDATE et DELETE pour exécuter des instructions LMD partitionné efficaces à grande échelle. Lorsque la CLI Spanner rencontre PARTITIONED UPDATE ou PARTITIONED DELETE, elle les reconnaît comme des opérations LMD partitionnées. Ces mots clés sont utiles pour les opérations qui affectent une partie importante d'une table sans verrouiller l'intégralité de la table pendant une période prolongée. Spanner n'applique pas les instructions LMD partitionnées de manière atomique sur l'ensemble de la table. Il applique les instructions en mode LMD partitionné de manière atomique sur chaque partition.

Pour exécuter une instruction LMD partitionnée, vous pouvez exécuter la commande suivante :

-- Update all rows in the 'Products' table by multiplying the price by 2
spanner-cli> PARTITIONED UPDATE Products SET Price = Price * 2 WHERE Price > 100;

-- Delete all rows in the 'Products' table with price less than 500
spanner-cli> PARTITIONED DELETE FROM Products WHERE Price < 500;

Métacommandes acceptées

La CLI Spanner accepte les méta-commandes utilitaires, qui sont des commandes fonctionnant sur le client, en l'occurrence la CLI Spanner. Les méta-commandes suivantes sont acceptées dans la CLI Spanner :

Commande	Syntaxe	Description
?	`\?`	Affiche des informations d'aide. Identique à `\h`.
Délimiteur	`\d`	Définit le délimiteur d'instruction. Le délimiteur par défaut est un point-virgule.
Quitter	`\q`	Quitte la CLI Spanner. Identique à "Quitter".
Go	`\g`	Envoie et exécute une instruction SQL dans Spanner.
Aide	`\h`	Affiche des informations d'aide. Identique à `\?`.
Notee	`\t`	Désactive l'écriture dans le fichier de sortie défini par `\T`.
Prompt	`\R`	Transforme votre requête en chaîne de requête utilisateur.
Quitter	`\q`	Quitte la CLI Spanner. Identique à la sortie.
Source	`\.`	Exécute le code SQL à partir d'un fichier d'entrée. Prend [filename] comme argument.
Système	`\!`	Exécute une commande shell système.
Tee	`\T`	Ajoute la sortie de la commande à un [nom de fichier] spécifié, ainsi qu'à la sortie standard.
Utilisation	`\u`	Se connecte à une autre base de données. Prend le nouveau nom de la base de données comme argument.

Autres commandes compatibles

La CLI Spanner est compatible avec d'autres commandes. Pour en savoir plus, consultez Commandes de l'interface de ligne de commande Spanner.

Obtenir de l'aide

Pour signaler un problème lié à la CLI Spanner, créez un problème.

Étapes suivantes

Consultez la liste de toutes les commandes de la CLI Spanner compatibles.
Consultez la liste de toutes les commandes gcloud spanner cli compatibles.