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 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.
Preços
Este tutorial usa o Spanner, que é um componente faturável do Google Cloud. Para informações sobre o custo do uso do Spanner, consulte Preços.
Antes de começar
- Conclua as etapas descritas em Instale a CLI gcloud e configure a API Cloud Spanner que aborda a criação e a configuração de um projeto padrão do Google Cloud, faturamento, ativar a API Cloud Spanner e configurar o OAuth 2.0 para ter credenciais de autenticação para 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
Defina o ID de um projeto do Google Cloud, caso ainda não tenha feito isso como o projeto padrão da Google Cloud CLI:
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
Quando você usa o Spanner pela primeira vez, precisa criar uma instância, que é um 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, selecione uma instância padrão, que é como um blueprint para sua instância que define o posicionamento geográfico e 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 spanner instance-configs list
Você verá 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 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
É possível definir a instância padrão que o Spanner usa 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 é padronizado para GoogleSQL.
GoogleSQL
gcloud spanner databases create example-db
PostgreSQL
gcloud spanner 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 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
Esse comando exige o ID da operação.
Consiga o ID da operação:
gcloud spanner operations list --instance="test-instance" \ --database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
Substitua DATABASE-NAME pelo nome do banco de dados.
Execute 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:
- PROJECT-NAME: o nome do projeto.
- OPERATION-ID: o ID da operação que você quer verificação.
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 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, uma vírgula é usada para delimitar itens em listas. Na última inserção
especificamos dois-pontos (^:^
) como delimitadores para que pudéssemos usar
vírgula no título do á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 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 acessar a referência do SQL do Spanner, consulte Sintaxe de consulta para GoogleSQL ou Sintaxe de consulta para PostgreSQL.
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.