Criar e consultar um banco de dados usando a CLI do Google Cloud

Objetivos

Neste tutorial, você vai aprender as etapas a seguir usando a CLI gcloud:

• Criar uma instância, um banco de dados e um esquema do Spanner
• Gravar dados no banco de dados e executar consultas SQL nesses dados
• Para executar a limpeza, exclua o banco de dados e a instância

Os procedimentos desta página se aplicam a bancos de dados com dialeto GoogleSQL e PostgreSQL.

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

Observação: para conhecer o Spanner usando uma instância de teste gratuito de 90 dias, consulte Criar uma instância de teste gratuito do Spanner.

Preços

Este tutorial usa o Spanner, que é um componente faturável do Google Cloud. Para mais informações sobre o custo do uso do Spanner, consulte Preços.

Antes de começar

Conclua as etapas descritas em Instalar a gcloud CLI e configurar a API Cloud Spanner, que aborda a criação e a configuração de um projeto padrão do Google Cloud, o faturamento, a API Cloud Spanner e a configuração do OAuth 2.0 para receber credenciais de autenticação e usar a API Cloud Spanner.

Especificamente, execute gcloud auth application-default login para configurar o ambiente de desenvolvimento local com credenciais de autenticação.

Configurar um projeto padrão

Se ainda não tiver feito isso, defina o ID de um projeto do Google Cloud como o projeto padrão para a CLI do Google Cloud:

gcloud config set project PROJECT_ID

Se você não definir o projeto padrão, precisará passar --project PROJECT_ID para cada um dos comandos abaixo como o primeiro argumento para gcloud. Por exemplo:

gcloud --project=PROJECT_ID instance-configs list

Instâncias

Ao usar o Spanner pela primeira vez, é necessário criar uma instância, que é uma alocação de recursos usados pelos bancos de dados do Spanner. Ao criar uma instância, você escolhe onde os dados são armazenados e a capacidade de computação dela.

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

Para criar uma instância, você precisa selecionar uma configuração, que é como um modelo para a instância que define o posicionamento geográfico e a replicação dos dados do Spanner.

Listar configurações de instância

Ao criar uma instância, você especifica uma configuração de instância que define a colocação geográfica e a replicação de bancos de dados nesta instância. É possível escolher uma configuração regional, que armazena dados em uma região, uma região dupla, que armazena dados em duas regiões no mesmo país, ou uma configuração multirregional, que distribui dados em várias regiões. Para mais informações, consulte a Visão geral das instâncias.

Para ver as configurações de instância disponíveis para o projeto:

gcloud instance-configs list

Você vai encontrar uma lista de configurações regionais, birregionais e multirregionais.

Criar uma instância

Para criar uma instância chamada test-instance com o nome de exibição My Instance usando a configuração de instância regional regional-us-central1 com um nó:

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

No comando acima, o nome da instância é definido como test-instance, e --description define o nome de exibição da instância. É necessário que os dois valores sejam únicos no projeto do Google Cloud Platform.

Observação: use o código da instância, e não o nome de exibição, ao se referir a uma instância em comandos gcloud.

Definir a instância padrão

Defina a instância padrão usada pelo Spanner quando você não especificou uma instância no comando. Para definir a instância padrão:

gcloud config set spanner/instance test-instance

Crie um banco de dados

Crie um banco de dados chamado example-db. O dialeto do banco de dados é definido como GoogleSQL.

GoogleSQL

gcloud databases create example-db

PostgreSQL

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

Atualizar o esquema

Use o Idioma de Definição de Dados (DDL) do Spanner para criar, alterar ou remover tabelas e criar ou remover índices.

Vamos criar duas tabelas:

GoogleSQL

gcloud 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 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 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 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 operations describe. Esse comando requer o ID da operação.

Consiga o ID da operação:

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

Substitua DATABASE-NAME pelo nome do banco de dados.

Execute gcloud operations describe:

gcloud operations describe \
  --instance="test-instance" \
  --database="example-db" \
  projects/PROJECT-NAME/instances/test-instance/databases/example-db/operations/OPERATION-ID

Substitua:

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

A saída será assim:

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

Gravar dados

Vamos adicionar alguns dados de amostra ao nosso banco de dados

GoogleSQL

gcloud rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=1,FirstName=Marc,LastName=Richards

gcloud rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=2,FirstName=Catalina,LastName=Smith

gcloud rows insert --database=example-db \
  --table=Singers \
  --data=SingerId=3,FirstName=Alice,LastName=Trentor

gcloud rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=1,AlbumId=1,AlbumTitle="Total Junk"

gcloud rows insert --database=example-db \
  --table=Albums \
  --data=SingerId=2,AlbumId=1,AlbumTitle="Green"

gcloud rows insert --database=example-db \
  --table=Albums \
  --data=^:^SingerId=2:AlbumId=2:AlbumTitle="Go, Go, Go"

Por padrão, a vírgula é usada para delimitar itens em listas. No último comando de inserção, especificamos dois pontos (^:^) como delimitador para que possamos usar uma vírgula no título do álbum.

PostgreSQL

Observação: há um problema conhecido em que a CLI gcloud não consegue procurar nomes de tabelas ao usar mutações para gravar dados em um banco de dados PostgreSQL. Portanto, é necessário usar a DML para inserir dados.

gcloud databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')"

gcloud databases execute-sql example-db \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (2, 'Catalina', 'Smith')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Singers (SingerId, FirstName, LastName) VALUES (3, 'Alice', 'Trentor')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (1, 1, 'Total Junk')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 1, 'Green')"

gcloud databases execute-sql example-db   \
  --sql="INSERT INTO Albums (SingerId, AlbumId, AlbumTitle) VALUES (2, 2, 'Go, Go, Go')"

Consultar dados usando SQL

Execute uma consulta na linha de comando:

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

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

Para conferir uma lista de flags que podem ser usadas com o comando execute-sql, consulte gcloud databases execute-sql.

Limpeza

Para evitar cobranças extras na sua conta do Google Cloud pelos recursos usados neste tutorial, descarte o banco de dados e exclua a instância que você criou.

Remover um banco de dados

Para excluir uma instância:

gcloud databases delete example-db

Excluir uma instância

Para excluir uma instância:

gcloud instances delete test-instance

Observe que excluir uma instância também descarta todos os bancos de dados nessa instância. A exclusão de uma instância não é reversível.