gcloud spanner

A ferramenta de linha de comando do gcloud permite que haja interação com o Cloud Spanner. Você usa o comando gcloud spanner para interagir com o Cloud Spanner.

Se você ainda não configurou seu ambiente para usar o Cloud Spanner, siga as etapas de Configuração.

Nesta página, descrevemos os comandos gcloud spanner comuns. Você também pode conseguir ajuda da linha de comando ao invocar um comando com um argumento --help. Por exemplo:

gcloud spanner instances create --help
SYNOPSIS
    gcloud spanner instances create INSTANCE --config=CONFIG
        --description=DESCRIPTION --nodes=NODES [--async] [GLOBAL-FLAG ...]

DESCRIPTION
    Cloud Spanner instances create command.

...

Esta página usa diversas variáveis que você deve substituir pelos valores do seu projeto Cloud Spanner.

  • PROJECT_ID: código do projeto
  • INSTANCE_ID: código da instância
  • NODE_COUNT: número de nós em uma instância
  • DATABASE_ID: código do banco de dados
  • SQL_STATEMENT: instrução SQL
  • TABLE_NAME: nome da tabela
  • COL_NAME: nome da coluna
  • COL_VALUE: valor para uma coluna
  • KEY_VALUE: valor para uma coluna de chave primária
  • SESSION_ID: código da sessão
  • POLICY_FILE: nome de um arquivo de política JSON ou YAML

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

Configurar um projeto padrão

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

gcloud config set project PROJECT_ID

Se você não definir o projeto padrão, será preciso 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 e configurações de instâncias

Uma instância do Cloud Spanner é uma alocação de recursos utilizada pelos bancos de dados do Cloud Spanner. Para criar uma instância, você precisa selecionar uma configuração de instância, 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

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 na configuração regional e em várias regiões na configuração de várias regiões. Leia mais sobre esse assunto em instâncias.

Criar instâncias

Depois de selecionar uma configuração de instância que atenda às necessidades do aplicativo, a próxima etapa é escolher o número de nodes a serem usados ​​ao criar a instância. O número de nodes corresponde à quantidade de recursos disponíveis para os bancos de dados na instância. Observe que as instâncias regionais são sempre resilientes a interrupções de zona única, independentemente do número de nodes que elas têm. Para mais informações sobre regiões e zonas, consulte Geografia e regiões.

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

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

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 INSTANCE_ID

Listar instâncias

Para listar todas as instâncias ativas e as configurações correspondentes (por exemplo, contagem de nodes e estado) em um projeto:

gcloud spanner instances list

Listar uma instância específica

Para conseguir a configuração de uma instância específica:

gcloud spanner instances describe INSTANCE_ID

Atualizar instâncias

É possível atualizar apenas o nome de exibição e a contagem de nós de uma instância. Para atualizar o número de nós em uma instância:

gcloud spanner instances update INSTANCE_ID --nodes=NODE_COUNT

Você pode encontrar a configuração das propriedades usando gcloud spanner instances list ou gcloud spanner instances describe INSTANCE_ID.

Excluir instâncias

Para excluir uma instância:

gcloud spanner instances delete INSTANCE_ID

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.

Criar e gerenciar bancos de dados

Criar bancos de dados

Para usar as APIs de leitura e gravação do Cloud Spanner, você precisa criar um banco de dados. Crie vários bancos de dados em uma instância.

Para criar um banco de dados com o código DATABASE_ID na instância INSTANCE_ID:

gcloud spanner databases create DATABASE_ID --instance=INSTANCE_ID

Listar bancos de dados

Para listar os bancos de dados em uma instância:

gcloud spanner databases list --instance=INSTANCE_ID

Excluir bancos de dados

Para excluir o banco de dados DATABASE_ID na instância INSTANCE_ID:

gcloud spanner databases delete DATABASE_ID --instance=INSTANCE_ID

Atualizar bancos de dados

É possível modificar o esquema de um banco de dados. Por exemplo, para criar uma tabela denominada MyTable:

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='CREATE TABLE MyTable ( MyKey INT64, MyValue STRING(MAX) ) PRIMARY KEY (MyKey)'

Consulte Linguagem de definição de dados para a sintaxe do esquema.

Executar instruções SQL

Para executar uma instrução SQL SELECT na linha de comando, use a seguinte sintaxe:

gcloud spanner databases execute-sql DATABASE_ID --instance=INSTANCE_ID \
    --sql=SQL_STATEMENT

Por exemplo, para executar uma SQL SELECT:

gcloud spanner databases execute-sql example-db --instance=test-instance \
    --sql='SELECT * FROM MyTable WHERE MyKey = 1'

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

Gerenciar políticas de IAM

Use a ferramenta gcloud para gerenciar políticas de IAM de instâncias e bancos de dado do Cloud Spanner.

Uma política do IAM é uma coleção de instruções que definem quem tem o acesso a um recurso no Google Cloud Platform.

Conseguir políticas do IAM

Instância

Para conseguir a política do IAM para uma instância:

gcloud spanner instances get-iam-policy INSTANCE_ID

Banco de dados

Para conseguir a política do IAM para um banco de dados:

gcloud spanner databases get-iam-policy DATABASE_ID --instance=INSTANCE_ID

Configurar políticas de IAM

Para configurar a política do IAM para um recurso, defina a política em um arquivo JSON ou YAML e faça referência a esse arquivo no comando set-iam-policy. Se o recurso já tiver uma política do IAM, esse comando substituirá toda a política por aquela no seu arquivo de políticas. Para ter ajuda para trabalhar com arquivos de políticas do IAM, consulte as políticas do Cloud IAM.

Depois de configurar sua política do IAM, você pode atualizá-la adicionando ou removendo vinculações das políticas do IAM. Você não precisa executar o set-iam-policy para atualizar a política.

Instância

Para definir uma política do IAM para uma instância:

gcloud spanner instances set-iam-policy INSTANCE_ID POLICY_FILE

Por exemplo, este comando define a política do IAM definida em myPolicy.json:

gcloud spanner instances set-iam-policy test-instance myPolicy.json

Banco de dados

Para definir uma política do IAM para o banco de dados DATABASE_ID na instância INSTANCE_ID:

gcloud spanner databases set-iam-policy DATABASE_ID --instance=INSTANCE_ID POLICY_FILE

Por exemplo, este comando define a política do IAM definida em myPolicy.json:

gcloud spanner databases set-iam-policy example-db --instance=test-instance myPolicy.json

Adicionar vinculações da política do IAM

A adição de uma política do IAM a atualiza ao conceder permissões a um usuário, grupo ou serviço específico. Cada vinculação de política de IAM identifica um membro, como uma conta do Google, e concede a ele um pacote de permissões denominado papéis, como databaseAdmin. Consulte Controle de acesso para o Cloud Spanner para ver a lista de papéis que controlam o acesso aos recursos do Cloud Spanner.

As amostras de comandos abaixo concedem permissões de databaseAdmin para email1@gmail.com. Elas adicionam uma vinculação de política que concede o papel de databaseAdmin à conta do Google associada a email1@gmail.com.

Instância

É possível adicionar uma vinculação de política a uma instância. Por exemplo, para conceder permissões a uma conta:

gcloud spanner instances add-iam-policy-binding test-instance --member="user:email1@gmail.com" \
    --role="roles/spanner.databaseAdmin"

Banco de dados

É possível adicionar uma vinculação de política a um banco de dados. Por exemplo, para conceder permissões a uma conta:

gcloud spanner databases add-iam-policy-binding example-db --instance=test-instance \
    --member="user:email1@gmail.com" --role="roles/spanner.databaseAdmin"

Remover as vinculações da política do IAM

A remoção de uma vinculação da política do IAM remove um conjunto de permissões da política do IAM usada por um recurso.

Cada vinculação da política do IAM identifica um membro (como uma conta do Google) e concede a ele um pacote de permissões chamado de papéis (como databaseAdmin). A remoção de uma vinculação revoga o pacote de permissões do membro identificado nela. Consulte Controle de acesso para o Cloud Spanner para ver a lista de papéis que controlam o acesso aos recursos do Cloud Spanner.

As amostras de comandos abaixo revogam as permissões de databaseAdmin de email1@gmail.com. Em outras palavras, esses comandos atualizam a política do IAM para remover a vinculação da política que concede o papel databaseAdmin à conta do Google associada a email1@gmail.com. Observe que isso afeta apenas permissões para o recurso que usa essa política do IAM em particular.

Instância

É possível remover uma vinculação de política de uma instância. Por exemplo, para remover permissões de uma conta:

gcloud spanner instances remove-iam-policy-binding test-instance \
    --member="user:email1@gmail.com" --role="roles/spanner.databaseAdmin"

Banco de dados

É possível remover uma vinculação de política de um banco de dados. Por exemplo, para remover permissões de uma conta:

gcloud spanner databases remove-iam-policy-binding example-db --instance=test-instance \
    --member="user:email1@gmail.com" --role="roles/spanner.databaseAdmin"

Gerenciar sessões

Se estiver criando uma biblioteca de cliente ou usando a REST API, convém saber quantas sessões ativas você tem, especialmente se exceder o limite (10.000 sessões por node por banco de dados) para sessões ativas. Para saber mais, consulte Sessões.

Listar todas as sessões ativas

Para listar todas as sessões ativas de um banco de dados:

gcloud spanner databases sessions list --database=DATABASE_ID --instance=INSTANCE_ID

Excluir sessão

Para excluir uma sessão:

gcloud spanner databases sessions delete SESSION_ID --database=DATABASE_ID --instance=INSTANCE_ID

A seguir

Saiba como inserir, atualizar e excluir linhas de uma tabela usando a ferramenta de linha de comando gcloud.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Cloud Spanner