Crea y consulta una base de datos con gcloud CLI

Objetivos

En este instructivo, se explican los siguientes pasos mediante la herramienta de línea de comandos de gcloud.

• Crea una instancia, una base de datos y un esquema de Spanner
• Escribe datos en la base de datos y ejecutar consultas de SQL
• Limpia la base de datos y la instancia

Para obtener la referencia gcloud spanner completa, consulta gcloud spanner.

Nota: Para explorar Spanner con una instancia de prueba gratuita de 90 días, consulta Crea una instancia de prueba gratuita de Spanner.

Precios

En este instructivo, se usa Spanner, que es un componente facturable de Google Cloud. Para obtener información sobre el costo de usar Spanner, consulta Precios.

Antes de comenzar

1. Completa los pasos que se describen en la página de configuración, que incluye cómo crear y configurar un proyecto predeterminado de Google Cloud, habilitar la facturación, habilitar la API de Cloud Spanner y configurar OAuth 2.0 a fin de obtener credenciales de autenticación para usar la API de Cloud Spanner.
   En particular, asegúrate de ejecutar gcloud auth application-default login para configurar tu entorno de desarrollo local con credenciales de autenticación.

Configura un proyecto predeterminado

Si aún no lo hiciste, establece el ID de un proyecto de Google Cloud como el proyecto predeterminado para Google Cloud CLI:

gcloud config set project PROJECT_ID

Si no configuras el proyecto predeterminado, debes pasar --project PROJECT_ID a cada uno de los siguientes comandos como el primer argumento para gcloud spanner. Por ejemplo:

gcloud spanner --project=PROJECT_ID instance-configs list

Instances

Cuando uses Spanner por primera vez, 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 procesamiento tiene.

Instancias y configuraciones de instancias

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

Muestra configuraciones de instancias

Cuando creas una instancia, especificas una configuración de instancia, que define la ubicación geográfica 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, o una configuración de varias regiones, que distribuye los datos en varias regiones. Consulta Instancias para obtener más información.

A fin de ver el conjunto de configuraciones de instancias disponibles para tu proyecto, sigue estos pasos:

gcloud spanner instance-configs list

Deberías ver una lista de configuraciones regionales y multirregionales.

Las configuraciones regionales distribuyen datos en una sola región, mientras que las configuraciones multirregionales distribuyen los datos geográficamente en varias regiones. Obtén más información sobre estas opciones en Instancias.

Cree una instancia

Para crear una instancia llamada test-instance con el nombre comercial My Instance mediante la configuración de instancia regional regional-us-central1 con 1 nodo, sigue estos pasos:

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

En el comando anterior, el nombre de la instancia se configura como test-instance y --description establece el nombre comercial de la instancia. Ambos valores deben ser únicos dentro de un proyecto de Google Cloud Platform.

Nota: Usa el ID de la instancia, no el nombre visible, cuando hagas referencia a una instancia en los comandos gcloud spanner.

Establece la instancia predeterminada

Puedes establecer la instancia predeterminada que usará Cloud Spanner cuando no hayas especificado una instancia en tu comando. Para configurar la instancia predeterminada, sigue estos pasos:

gcloud config set spanner/instance test-instance

Crea una base de datos

Crea una base de datos con el nombre example-db. El dialecto predeterminado de la base de datos es GoogleSQL.

GoogleSQL

gcloud spanner databases create example-db

PostgreSQL

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

Actualiza el esquema

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

Creemos 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 verificar el progreso de la operación, usa gcloud spanner operations describe. Este comando requiere el ID de operación.

Obtén el ID de operación:

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

Reemplaza 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

Reemplaza lo siguiente:

• PROJECT-NAME: Es el nombre del proyecto.
• OPERATION-ID: El ID de la operación que deseas verificar.

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

Escribe datos

Agrega algunos datos de muestra a la 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 en las listas. En el último comando insert, especificamos dos puntos (^:^) como delimitador para que pudiéramos usar una coma en el título del álbum.

PostgreSQL

Nota: Existe un problema conocido en el que gcloud CLI no puede buscar nombres de tablas cuando usa mutaciones para escribir datos en una base de datos de PostgreSQL. Por lo tanto, debes usar DML para insertar datos.

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

Consulta 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'

A fin de obtener la referencia de SQL de Spanner, consulta Sintaxis de consulta para GoogleSQL o Sintaxis de consulta para PostgreSQL.

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

Limpieza

Para evitar que se apliquen cargos adicionales a tu cuenta de Google Cloud por los recursos que se usaron en este instructivo, descarta la base de datos y borra la instancia que creaste.

Desconectar una base de datos

Para borrar una instancia existente, sigue estos pasos:

gcloud spanner databases delete example-db

Borra una instancia

Para borrar una instancia existente, sigue estos pasos:

gcloud spanner instances delete test-instance

Ten en cuenta que la eliminación de una instancia también descarta todas las bases de datos de esa instancia. La eliminación de una instancia no es reversible.