Guia de início rápido da CLI do Spanner

A CLI do Spanner é uma interface de linha de comando (CLI) na CLI gcloud que permite se conectar e interagir com seus bancos de dados do Spanner. Por exemplo, é possível usar a CLI do Spanner para executar instruções GoogleSQL e automatizar tarefas. Este documento descreve como configurar e usar a CLI do Spanner.

A CLI do Spanner é baseada no projeto de código aberto spanner-cli.

Para ver uma lista de todos os comandos da CLI do Spanner compatíveis, consulte Comandos gcloud spanner cli.

Principais vantagens

Você pode usar a CLI do Spanner para realizar as seguintes ações:

Antes de começar

Antes de usar a CLI do Spanner, verifique se você tem a função necessária e se instalou a CLI.

Funções exigidas

Para receber as permissões necessárias para instalar o Spanner, peça ao administrador para conceder a você o papel do IAM de Administrador do Cloud Spanner (roles/spanner.admin) no Spanner. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Instalar a CLI do Spanner

A CLI do Spanner está disponível na CLI gcloud. Ao executar o comando gcloud spanner cli pela primeira vez, a CLI gcloud instala automaticamente o componente da CLI do Spanner.

Para instalar a CLI do Spanner manualmente, execute o seguinte comando:

gcloud components install spanner-cli

Se a instalação usando o comando da Google Cloud CLI não for bem-sucedida ou não for viável no seu ambiente shell, o Spanner vai fornecer pacotes Debian (.deb) e RPM (.rpm) autônomos. Você pode usar esses pacotes para instalar manualmente em sistemas compatíveis. Para instalá-lo, execute o seguinte comando:

apt-get install google-cloud-cli-spanner-cli

Opções de configuração

A CLI do Spanner é compatível com as seguintes opções configuráveis:

  • A opção de projeto é recuperada pela propriedade core/project. Como alternativa, você pode especificar o projeto usando a opção --project.
  • A opção de instância é recuperada pela propriedade core/instance. Como alternativa, é possível especificar a instância usando a opção --instance.
  • O endpoint de API é recuperado pela propriedade api_endpoint_overrides/spanner. Como alternativa, é possível especificar o endpoint usando as opções --host e --port. O endpoint padrão do Spanner será usado se nenhum endpoint for especificado.

Usar a CLI do Spanner

  1. Configure um Google Cloud projeto.

  2. Configure a autenticação usando a gcloud CLI.

  3. Crie uma instância.

  4. Crie um banco de dados.

  5. Execute o comando a seguir para iniciar a CLI do Spanner e interagir com seu banco de dados do Spanner:

    gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID

    Substitua:

    • DATABASE_ID: o ID do banco de dados do Spanner. Esse é o nome que você usou na etapa anterior "Criar um banco de dados". Use o comando gcloud spanner databases list para listar os bancos de dados do Spanner contidos na instância especificada.
    • INSTANCE_ID: o ID da instância do Spanner. Esse é o nome que você usou na etapa anterior "Criar uma instância". Use o comando gcloud spanner instances list para listar as instâncias do Spanner contidas no projeto especificado.

Executar SQL

É possível executar instruções SQL na CLI do Spanner usando a opção execute ou um método de entrada e saída baseado em arquivos. Suas instruções SQL podem consistir em DDL, DML ou DQL.

Use a sinalização execute.

Para usar a flag execute e executar SQL, execute o seguinte comando gcloud spanner cli:

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    --execute "SQL"

Substitua:

  • DATABASE_ID: o ID do banco de dados do Spanner a que você quer se conectar.
  • INSTANCE_ID: o ID da instância do Spanner a que você quer se conectar.
  • SQL: o SQL que você quer executar.

Por exemplo, para executar uma instrução DDL:

gcloud spanner cli test-database --instance test-instance \
    --execute "CREATE TABLE Singers ( \
        SingerId   INT64 NOT NULL, \
        FirstName  STRING(1024), \
        LastName   STRING(1024), \
        SingerInfo STRING(1024), \
        BirthDate  DATE \
      ) PRIMARY KEY(SingerId);"

Para executar uma instrução DML:

gcloud spanner cli test-database --instance test-instance \
    --execute "INSERT INTO Singers (SingerId, FirstName, LastName, SingerInfo) \
        VALUES(1, 'Marc', 'Richards', 'nationality: USA'), \
              (2, 'Catalina', 'Smith', 'nationality: Brazil'), \
              (3, 'Andrew', 'Duneskipper', NULL);"

Usar uma entrada e saída baseadas em arquivo

Se você usar o método de entrada e saída baseado em arquivos, o Spanner vai ler a entrada de um arquivo e gravar a saída em outro. Para usar o método de entrada e saída baseado em arquivos para executar SQL, execute o seguinte comando:

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    --source INPUT_FILE_PATH --tee OUTPUT_FILE_PATH

Você também pode usar o método de entrada e saída de redirecionamento com base em arquivos:

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    < INPUT_FILE_PATH > OUTPUT_FILE_PATH

Substitua:

  • DATABASE_ID: o ID do banco de dados do Spanner a que você quer se conectar.
  • INSTANCE_ID: o ID da instância do Spanner a que você quer se conectar.
  • SOURCE_FILE_PATH: o arquivo que contém o SQL que você quer executar.
  • OUTPUT_FILE_PATH: o arquivo nomeado para anexar uma cópia da saída SQL.

Iniciar uma sessão interativa

É possível iniciar uma sessão interativa da CLI do Spanner, que permite digitar diretamente instruções SQL e metacandos e ver os resultados na CLI. Para isso, execute o seguinte comando:

gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID

Após a conexão bem-sucedida entre a CLI e o banco de dados, uma solicitação (por exemplo, spanner-cli>) vai aparecer. Nela, é possível fazer o seguinte:

Depois de pressionar a tecla ENTER, a instrução ou o comando é enviado ao banco de dados do Spanner apropriado. Em seguida, o Spanner executa a instrução ou o comando.

No exemplo a seguir, você inicia uma sessão interativa em test-database e executa SELECT 1;:

gcloud spanner cli test-database --instance test-instance

Welcome to Spanner-Cli Client.
Type 'help;' or '\h' for help.
Type 'exit;' or 'quit;' or '\q' to exit.

spanner-cli> SELECT 1;
+---+
|   |
+---+
| 1 |
+---+

1 rows in set (1.11 msecs)

Executar instrução DDL

Para executar uma instrução DDL, execute o seguinte:

spanner-cli> CREATE TABLE Singers (
          ->         SingerId   INT64 NOT NULL,
          ->         FirstName  STRING(1024),
          ->         LastName   STRING(1024),
          ->         SingerInfo STRING(1024),
          ->         BirthDate  DATE
          -> ) PRIMARY KEY(SingerId);

Query OK, 0 rows affected (17.08 sec)

Executar instrução DML

Para executar uma instrução DML, execute o seguinte:

spanner-cli> INSERT INTO Singers (SingerId, FirstName, LastName, SingerInfo)
          -> VALUES(1, 'Marc', 'Richards', 'nationality: USA'),
          -> (2, 'Catalina', 'Smith', 'nationality: Brazil'),
          -> (3, 'Andrew', 'Duneskipper', NULL);

Query OK, 3 rows affected (0.32 sec)

Executar instrução DML particionada

Na CLI do Spanner, é possível usar a palavra-chave PARTITIONED com os comandos UPDATE e DELETE para executar instruções DML particionadas eficientes e em grande escala. Quando a CLI do Spanner encontra PARTITIONED UPDATE ou PARTITIONED DELETE, ela os reconhece como operações DML particionadas. Essas palavras-chave são úteis para operações que afetam uma parte significativa de uma tabela sem bloquear toda a tabela por um período prolongado. O Spanner não aplica as instruções DML particionadas atomicamente em toda a tabela. Ele aplica instruções DML particionadas atomicamente em cada partição.

Para executar uma instrução DML particionada, execute o seguinte:

-- Update all rows in the 'Products' table by multiplying the price by 2
spanner-cli> PARTITIONED UPDATE Products SET Price = Price * 2 WHERE Price > 100;

-- Delete all rows in the 'Products' table with price less than 500
spanner-cli> PARTITIONED DELETE FROM Products WHERE Price < 500;

Metacomandos aceitos

A CLI do Spanner é compatível com metacontroles de utilidade, que são comandos que operam no cliente, nesse caso, a CLI do Spanner. Os seguintes metacomandos são compatíveis com a CLI do Spanner:

Comando Sintaxe Descrição
? \? Exibe informações de ajuda. Igual a \h
Delimitador \d Define o delimitador de instrução. O delimitador padrão é um ponto e vírgula.
Sair \q Sai da CLI do Spanner. Igual a "Sair".
Go \g Envia e executa instrução SQL no Spanner.
Ajuda \h Exibe informações de ajuda. Igual a \?
Notee \t Desativa a gravação no arquivo de saída definido pelo \T.
Comando \R Muda seu comando para uma string de comando do usuário.
Sair \q Encerra a CLI do Spanner. Igual à saída.
Origem \. Executa SQL de um arquivo de entrada. Usa [nome do arquivo] como argumento.
Sistema \! Executa um comando de shell do sistema.
Tee \T Adiciona resposta ao comando a um [nome do arquivo] especificado, além da saída padrão.
Usar \u Conecta-se a outro banco de dados. Usa o novo nome do banco de dados como argumento.

Outros comandos compatíveis

A CLI do Spanner aceita outros comandos. Para mais informações, consulte Comandos da CLI do Spanner.

Receber suporte

Para informar um problema com a CLI do Spanner, crie um novo problema.

A seguir