Crie e consulte uma base de dados com a Google Cloud CLI

Objetivos

Este tutorial explica os seguintes passos através da CLI gcloud:

• Crie uma instância, uma base de dados e um esquema do Spanner
• Escrever dados na base de dados e executar consultas SQL desses dados
• Limpe eliminando a base de dados e a instância

Os procedimentos nesta página aplicam-se a bases de dados com dialeto GoogleSQL e bases de dados com dialeto PostgreSQL.

Para a referência completa do Spanner gcloud, consulte o comando gcloud.

Nota: para explorar o Spanner através de uma instância de avaliação gratuita de 90 dias, consulte o artigo Crie uma instância de avaliação gratuita do Spanner.

Preços

Este tutorial usa o Spanner, que é um componente faturável do Google Cloud. Para obter informações sobre o custo de utilização do Spanner, consulte a secção Preços.

Antes de começar

Conclua os passos descritos em Instale a CLI gcloud e configure a API Cloud Spanner, que abordam a criação e a definição de um projeto Google Cloud predefinido, a ativação da faturação, a ativação da API Cloud Spanner e a configuração do OAuth 2.0 para obter credenciais de autenticação para usar a API Cloud Spanner.

Em particular, certifique-se de que executa gcloud auth application-default login para configurar o seu ambiente de desenvolvimento local com credenciais de autenticação.

Predefina um projeto

Se ainda não o fez, defina o ID de um Google Cloud projeto como o projeto predefinido para a Google Cloud CLI:

gcloud config set project PROJECT_ID

Se não definir o projeto predefinido, tem de transmitir --project PROJECT_ID a cada um dos comandos abaixo como o primeiro argumento para gcloud. Por exemplo:

gcloud --project=PROJECT_ID spanner instance-configs list

Instâncias

Quando usa o Spanner pela primeira vez, tem de criar uma instância, que é uma atribuição de recursos usados pelas bases de dados do Spanner. Quando cria uma instância, escolhe onde os dados são armazenados e a capacidade de computação da instância.

Instâncias e configurações de instâncias

Para criar uma instância, tem de selecionar uma configuração de instância, que é como um projeto para a sua instância que define o posicionamento geográfico e a replicação dos seus dados do Spanner.

Apresente configurações de instâncias

Quando cria uma instância, especifica uma configuração da instância, que define o posicionamento geográfico e a replicação das suas bases de dados nessa instância. Pode escolher uma configuração regional, que armazena dados numa região, uma configuração de duas regiões, que armazena dados em duas regiões no mesmo país, ou uma configuração multirregional, que distribui dados por várias regiões. Para mais informações, consulte a Vista geral das instâncias.

Para ver o conjunto de configurações de instâncias disponíveis para o seu projeto:

gcloud spanner instance-configs list

É apresentada uma lista de configurações regionais, de duas regiões e multirregionais.

Crie uma instância

Para criar uma instância denominada test-instance com o nome a apresentar My Instance usando a configuração da instância regional regional-us-central1 com 1 nó:

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

No comando acima, o nome da instância está definido como test-instance e --description define o nome a apresentar da instância. Ambos os valores têm de ser exclusivos num projeto da Google Cloud Platform.

Nota: use o ID da instância e não o nome a apresentar quando se referir a uma instância em comandos gcloud.

Predefina a instância

Pode definir a instância predefinida que o Spanner usa quando não especificou uma instância no comando. Para definir a instância predefinida:

gcloud config set spanner/instance test-instance

Crie uma base de dados

Crie uma base de dados com o nome example-db. O dialeto da base de dados é predefinido como GoogleSQL.

GoogleSQL

gcloud spanner databases create example-db

PostgreSQL

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

Atualize o esquema

Use a linguagem de definição de dados (DDL) do Spanner para criar, alterar ou eliminar tabelas, bem como para criar ou eliminar índices.

Vamos criar duas tabelas:

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 o progresso da operação, use gcloud spanner operations describe. Este comando requer o ID da operação.

Obtenha o ID da operação:

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

Substitua DATABASE-NAME pelo nome da base de dados.

Corrida 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

Substitua o seguinte:

• PROJECT-NAME: o nome do projeto.
• OPERATION-ID: o ID da operação que quer verificar.

O resultado tem um aspeto semelhante ao seguinte:

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

Escrever dados

Vamos adicionar alguns dados de amostra à nossa base de dados

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"

Por predefinição, é utilizada uma vírgula para delimitar os itens nas listas. No último comando de inserção, especificámos dois pontos (^:^) como delimitador para podermos usar uma vírgula no título do álbum.

PostgreSQL

Nota: existe um problema conhecido em que a CLI gcloud não consegue procurar nomes de tabelas quando usa mutações para escrever dados numa base de dados PostgreSQL. Por conseguinte, tem de usar DML para inserir dados.

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 dados através de SQL

Execute uma consulta na linha de comandos:

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

Para a referência do SQL do Spanner, consulte a sintaxe de consulta do GoogleSQL ou a sintaxe de consulta do PostgreSQL.

Para ver uma lista de sinalizadores que pode usar com o comando execute-sql, consulte gcloud spanner databases execute-sql.

Limpeza

Para evitar incorrer em custos adicionais na sua conta Google Cloud relativos aos recursos usados neste tutorial, elimine a base de dados e a instância que criou.

Elimine uma base de dados

Para eliminar uma instância existente:

gcloud spanner databases delete example-db

Elimine uma instância

Para eliminar uma instância existente:

gcloud spanner instances delete test-instance

Tenha em atenção que a eliminação de uma instância também elimina todas as bases de dados nessa instância. A eliminação de uma instância não é reversível.