Inicio rápido de la CLI de Spanner

En esta página, se presenta la CLI de Spanner y se explica cómo usarla.

La CLI de Spanner es una interfaz de línea de comandos (CLI) que te permite conectarte a tu base de datos de Spanner y, luego, interactuar con ella. Se incorpora a la CLI de Google Cloud (gcloud CLI) para interactuar con Spanner. Puedes usar la CLI de Spanner para ejecutar directamente instrucciones de GoogleSQL en tu base de datos de Spanner. Tus declaraciones pueden consistir en declaraciones de lenguaje de definición de datos (DDL), lenguaje de manipulación de datos (DML) o lenguaje de consulta de datos (DQL). Puedes usar la CLI de Spanner para ejecutar secuencias de comandos de comandos SQL y automatizar tareas.

Para obtener más información, consulta la lista de todos los comandos de gcloud alpha spanner cli compatibles.

Ventajas clave

Estos son algunos de los beneficios clave de la CLI de Spanner:

Antes de comenzar

La CLI de Spanner está disponible en la gcloud CLI. Cuando ejecutas el comando gcloud alpha spanner cli por primera vez, gcloud CLI instala automáticamente el componente de la CLI de Spanner.

Usa la CLI de Spanner

  1. Configura un Google Cloud proyecto.

  2. Configura la autenticación con la CLI de gcloud.

  3. Crea una instancia.

  4. Crea una base de datos.

  5. Ejecuta el siguiente comando para iniciar la CLI de Spanner y, luego, interactuar con tu base de datos de Spanner:

    gcloud alpha spanner cli DATABASE_ID --instance=INSTANCE_ID

    Reemplaza lo siguiente:

    • DATABASE_ID: Es el ID de la base de datos de Spanner. Este es el nombre que usaste en el paso anterior Crear una base de datos. Puedes usar el comando gcloud spanner databases list para enumerar las bases de datos de Spanner que se encuentran en la instancia determinada.
    • INSTANCE_ID: Es el ID de la instancia de Spanner. Este es el nombre que usaste en el paso anterior Crear una instancia. Puedes usar el comando gcloud spanner instances list para enumerar las instancias de Spanner que se encuentran en el proyecto determinado.

Ejecutar SQL

Puedes ejecutar instrucciones SQL en la CLI de Spanner con la opción execute o con un método de entrada y salida basado en archivos. Tus declaraciones de SQL pueden consistir en DDL, DML o DQL.

Usa la marca execute

Para usar la marca execute y ejecutar SQL, ejecuta el siguiente comando gcloud alpha spanner cli:

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

Reemplaza lo siguiente:

  • DATABASE_ID: Es el ID de la base de datos de Spanner a la que deseas conectarte.
  • INSTANCE_ID: Es el ID de la instancia de Spanner a la que deseas conectarte.
  • SQL: Es el código SQL que deseas ejecutar.

Por ejemplo, para ejecutar una sentencia DDL, haz lo siguiente:

gcloud alpha 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);"

Para ejecutar una declaración DML, sigue estos pasos:

gcloud alpha 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);"

Usa una entrada y una salida basadas en archivos

Si usas el método de entrada y salida basado en archivos, Spanner lee su entrada desde un archivo y escribe su salida en otro archivo. Para usar el método de entrada y salida basado en archivos para ejecutar SQL, ejecuta el siguiente comando:

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

También puedes usar el método de entrada y salida de redireccionamiento basado en archivos:

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

Reemplaza lo siguiente:

  • DATABASE_ID: Es el ID de la base de datos de Spanner a la que deseas conectarte.
  • INSTANCE_ID: Es el ID de la instancia de Spanner a la que deseas conectarte.
  • SOURCE_FILE_PATH: Es el archivo que contiene el código SQL que deseas ejecutar.
  • OUTPUT_FILE_PATH: Es el nombre del archivo al que se agregará una copia del resultado de SQL.

Cómo iniciar una sesión interactiva

Puedes iniciar una sesión interactiva de la CLI de Spanner, que te permite escribir directamente instrucciones SQL y metacomandos, y ver los resultados en la CLI. Para ello, ejecuta el siguiente comando:

gcloud alpha spanner cli DATABASE_ID --instance=INSTANCE_ID

Cuando se establezca la conexión entre la CLI y tu base de datos, verás un mensaje (por ejemplo, spanner-cli>) en el que podrás hacer lo siguiente:

Después de presionar la tecla ENTER, la instrucción o el comando se envían a la base de datos de Spanner correspondiente. Luego, Spanner ejecuta la instrucción o el comando.

En el siguiente ejemplo, iniciarás una sesión interactiva en test-database y, luego, ejecutarás SELECT 1;:

gcloud alpha 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)

Ejecuta la sentencia DDL

Para ejecutar una sentencia DDL, puedes ejecutar lo siguiente:

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)

Ejecuta la declaración DML

Para ejecutar una declaración DML, puedes ejecutar lo siguiente:

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)

Metacomandos admitidos

La CLI de Spanner admite metacomandos de utilidad, que son comandos que operan en el cliente, en este caso, la CLI de Spanner. Los siguientes metacomandos son compatibles con la CLI de Spanner:

Comando Sintaxis Descripción
? \? Muestra información de ayuda. Igual que \h.
Delimitador \d Establece el delimitador de la instrucción. El delimitador predeterminado es un punto y coma.
Salir \q Sale de la CLI de Spanner. Es lo mismo que salir.
Go \g Envía y ejecuta la instrucción de SQL en Spanner.
Ayuda \h Muestra información de ayuda. Igual que \?.
Nota \t Desactiva la escritura en el archivo de salida establecido por \T.
Instrucción \R Cambia tu instrucción a una cadena de instrucción del usuario.
Salir \q Sale de la CLI de Spanner. Es igual que la salida.
Fuente \. Ejecuta SQL desde un archivo de entrada. Toma [filename] como argumento.
Sistema \! Ejecuta un comando de shell del sistema.
Tee \T Agrega el resultado del comando a un [nombre de archivo] especificado junto con el resultado estándar.
Usar \u Se conecta a otra base de datos. Toma el nuevo nombre de la base de datos como argumento.

¿Qué sigue?