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 con 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.

Se basa en el proyecto de código abierto spanner-cli.

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

Ventajas clave

Puedes usar Spanner para realizar las siguientes acciones:

Antes de comenzar

Antes de usar la CLI de Spanner, asegúrate de tener el rol necesario y de haber instalado la CLI.

Roles obligatorios

Para obtener los permisos que necesitas para instalar Spanner, pídele a tu administrador que te otorgue el rol de IAM Administrador de Cloud Spanner (roles/spanner.admin) en Spanner. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Instala la CLI de Spanner

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

Para instalar la CLI de Spanner de forma manual, ejecuta el siguiente comando:

gcloud components install spanner-cli

Si la instalación con el comando de Google Cloud CLI no se realiza correctamente o no es factible en tu entorno de shell, Spanner proporciona paquetes independientes de Debian (.deb) y RPM (.rpm). Puedes usar estos paquetes para realizar la instalación manualmente en sistemas compatibles. Para instalarlo, ejecuta el siguiente comando:

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

Opciones de configuración

La CLI de Spanner admite las siguientes opciones configurables:

  • La opción del proyecto se recupera a través de la propiedad core/project. Como alternativa, puedes especificar el proyecto con la opción --project.
  • La opción de instancia se recupera a través de la propiedad core/instance. Como alternativa, puedes especificar la instancia con la opción --instance.
  • El extremo de API se recupera a través de la propiedad api_endpoint_overrides/spanner. Como alternativa, puedes especificar el extremo con las opciones --host y --port. Si no se especifica ningún extremo, se usa el extremo predeterminado 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, interactúa con tu base de datos de Spanner:

    gcloud 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 dentro de la instancia determinada.
    • INSTANCE_ID: Es el ID de la instancia de Spanner. Este es el nombre que usaste en el paso anterior para 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 SQL pueden consistir en DDL, DML o DQL.

Usa la marca execute

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

gcloud 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 instrucción DDL, haz lo siguiente:

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

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

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

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

Ejecuta una declaración DML particionada

En la CLI de Spanner, puedes usar la palabra clave PARTITIONED con los comandos UPDATE y DELETE para ejecutar declaraciones de DML particionadas eficientes a gran escala. Cuando la CLI de Spanner encuentra PARTITIONED UPDATE o PARTITIONED DELETE, los reconoce como operaciones DML particionadas. Estas palabras clave son útiles para las operaciones que afectan una parte significativa de una tabla sin bloquearla por completo durante un período prolongado. Spanner no aplica las declaraciones DML particionadas de forma atómica en toda la tabla. Aplica las sentencias DML particionadas de forma atómica en cada partición.

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

-- 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;

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 una instrucción de SQL en Spanner.
Ayuda \h Muestra información de ayuda. Igual que \?.
Notee \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 Cierra 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.

Comandos adicionales admitidos

La CLI de Spanner admite comandos adicionales. Para obtener más información, consulta Comandos de la CLI de Spanner.

Obtén asistencia

Para informar un problema con la CLI de Spanner, crea un problema nuevo.

¿Qué sigue?