Crear y consultar una base de datos con la CLI de Google Cloud

Objetivos

En este tutorial se explican los siguientes pasos con gcloud CLI:

  • Crear una instancia, una base de datos y un esquema de Spanner
  • Escribir datos en la base de datos y ejecutar consultas SQL en esos datos
  • Eliminar la base de datos y la instancia

Los procedimientos de esta página se aplican tanto a las bases de datos con dialecto GoogleSQL como a las bases de datos con dialecto PostgreSQL.

Para consultar la referencia completa de gcloud de Spanner, consulta gcloud.

Precios

En este tutorial se usa Spanner, que es un componente facturable de Google Cloud. Para obtener información sobre el coste de usar Spanner, consulta la página Precios.

Antes de empezar

Sigue los pasos descritos en Instalar la CLI de gcloud y configurar la API Cloud Spanner, donde se explica cómo crear y definir un proyecto predeterminado, habilitar la facturación, habilitar la API Cloud Spanner y configurar OAuth 2.0 para obtener credenciales de autenticación que permitan usar la API Cloud Spanner. Google Cloud

En concreto, asegúrate de ejecutar gcloud auth application-default login para configurar tu entorno de desarrollo local con credenciales de autenticación.

Definir un proyecto predeterminado

Si aún no lo has hecho, define el ID de un proyecto de Google Cloud como proyecto predeterminado de la CLI de Google Cloud:

gcloud config set project PROJECT_ID

Si no defines el proyecto predeterminado, debes pasar --project PROJECT_ID a cada uno de los comandos que se indican a continuación como primer argumento de gcloud. Por ejemplo:

gcloud --project=PROJECT_ID spanner instance-configs list

Instancias

La primera vez que uses Spanner, debes crear una instancia, que es una asignación de recursos que usan las bases de datos de Spanner. Cuando creas una instancia, eliges dónde se almacenan tus datos y cuánta capacidad de computación tiene la instancia.

Instancias y configuraciones de instancias

Para crear una instancia, debes seleccionar una configuración de instancia, que es como un plano de tu instancia que define la ubicación geográfica y la replicación de tus datos de Spanner.

Mostrar lista de configuraciones de instancia

Cuando creas una instancia, especificas una configuración de instancia, que define el emplazamiento geográfico y la replicación de las bases de datos en esa instancia. Puedes elegir una configuración regional, que almacena datos en una región, una configuración de dos regiones, que almacena datos en dos regiones del mismo país, o una configuración de varias regiones, que distribuye los datos en varias regiones. Para obtener más información, consulta la descripción general de las instancias.

Para ver el conjunto de configuraciones de instancia disponibles para su proyecto, escriba:

gcloud spanner instance-configs list

Verás una lista de configuraciones regionales, birregionales y multirregionales.

Crear una instancia

Para crear una instancia llamada test-instance con el nombre visible My Instance con la configuración de instancia regional regional-us-central1 con 1 nodo, haz lo siguiente:

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

En el comando anterior, el nombre de la instancia es test-instance y --description define el nombre visible de la instancia. Ambos valores deben ser únicos en un proyecto de Google Cloud Platform.

Definir la instancia predeterminada

Puedes definir la instancia predeterminada que Spanner utiliza cuando no has especificado ninguna en tu comando. Para definir la instancia predeterminada, sigue estos pasos:

gcloud config set spanner/instance test-instance

Crear una base de datos

Crea una base de datos llamada example-db. El dialecto de la base de datos es GoogleSQL de forma predeterminada.

GoogleSQL 

gcloud spanner databases create example-db

PostgreSQL 

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

Actualizar el esquema

Usa el lenguaje de definición de datos (DDL) de Spanner para crear, modificar o eliminar tablas, así como para crear o eliminar índices.

Vamos a crear dos tablas:

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'

Para comprobar el progreso de la operación, usa gcloud spanner operations describe. Este comando requiere el ID de operación.

Obtén el ID de la operación:

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

Sustituye DATABASE-NAME por el nombre de la base de datos.

Ejecuta 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

Haz los cambios siguientes:

  • PROJECT-NAME: nombre del proyecto.
  • OPERATION-ID: el ID de la operación que quieres comprobar.

El resultado es similar al siguiente:

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

Escribir datos

Vamos a añadir datos de ejemplo a nuestra base de datos

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"

De forma predeterminada, se usa una coma para delimitar los elementos de las listas. En el último comando de inserción, hemos especificado dos puntos (^:^) como delimitador para poder usar una coma en el título del álbum.

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

Consultar datos mediante SQL

Ejecuta una consulta en la línea de comandos:

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

Para consultar la referencia de Spanner SQL, consulta Sintaxis de las consultas de GoogleSQL o Sintaxis de las consultas de PostgreSQL.

Para ver una lista de las marcas que puedes usar con el comando execute-sql, consulta gcloud spanner databases execute-sql.

Limpieza

Para evitar que se apliquen cargos adicionales en tu Google Cloud cuenta por los recursos utilizados en este tutorial, elimina la base de datos y la instancia que has creado.

Desconectar una base de datos

Para eliminar una instancia:

gcloud spanner databases delete example-db

Eliminar una instancia

Para eliminar una instancia:

gcloud spanner instances delete test-instance

Ten en cuenta que, si eliminas una instancia, también se eliminarán todas las bases de datos de esa instancia. La eliminación de una instancia no se puede deshacer.