Primeiros passos com o Cloud Spanner usando o gcloud

Objetivos

Neste tutorial, você verá as etapas a seguir usando a ferramenta de linha de comando gcloud.

  • Criar uma instância, um banco de dados e um esquema do Cloud 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

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

Custos

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

Antes de começar

  1. Conclua as etapas descritas em Configurar, que aborda a criação e a definição de um projeto padrão do Google Cloud, a ativação do faturamento, a ativação da API Cloud Spanner e a configuração do OAuth 2.0 para receber credenciais de autenticação para usar a API Cloud Spanner.
    Especificamente, não esqueça de executar gcloud auth application-default login para configurar seu ambiente de desenvolvimento local com credenciais de autenticação.

Configurar um projeto padrão

Se você ainda não tiver feito isso, configure o ID de um projeto do Google Cloud Platform como o projeto padrão para a ferramenta de linha de comando gcloud:

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 spanner. Por exemplo:

gcloud spanner --project=PROJECT_ID instance-configs list

Instâncias

Ao usar o Cloud Spanner pela primeira vez, é necessário criar uma instância que é uma alocação de recursos usados pelos bancos de dados do Cloud Spanner. Ao criar uma instância, você escolhe onde armazenar seus dados e quantos nodes serão usados por eles.

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 Cloud 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, para armazenar dados em uma região ou uma configuração de várias regiões, para distribuir dados em várias regiões. Saiba mais em Instâncias.

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

gcloud spanner instance-configs list

Você verá uma lista de configurações regionais e de várias regiões.

Os dados são distribuídos conforme a configuração: em uma única região, no caso da configuração regional, e em várias regiões na configuração multirregional. Clique aqui para ler mais sobre esse assunto.

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

Definir a instância padrão

Defina a instância padrão usada pelo Cloud 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.

gcloud spanner databases create example-db

Criar um esquema

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

Vamos criar duas tabelas

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'

Gravar dados

Vamos adicionar alguns dados de amostra ao nosso banco de dados

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 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 vírgula no título do álbum.

Consultar dados usando SQL

Execute uma consulta na linha de comando:

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

Para ver a referência do Cloud Spanner SQL, consulte Sintaxe da consulta.

Para ver uma lista de sinalizações que podem ser usadas com o comando execute-sql, consulte gcloud spanner databases execute-sql.

Limpar

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

Remover um banco de dados

Para excluir uma instância:

gcloud spanner databases delete example-db

Excluir uma instância

Para excluir uma instância:

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