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

Nesta página, apresentamos a CLI do Spanner e explicamos como usá-la.

A CLI do Spanner é uma interface de linha de comando (CLI) que permite conectar e interagir com seu banco de dados do Spanner. Ela é incorporada à Google Cloud CLI (CLI gcloud) para interagir com o Spanner. É possível usar a CLI do Spanner para executar diretamente instruções GoogleSQL no banco de dados do Spanner. Elas podem consistir em instruções de linguagem de definição de dados (DDL), linguagem de manipulação de dados (DML) ou linguagem de consulta de dados (DQL). Use a CLI do Spanner para executar scripts de comandos SQL e automatizar tarefas.

Ele é baseado no projeto de código aberto spanner-cli.

Para mais informações, consulte uma lista de todos os comandos gcloud spanner cli compatíveis.

Principais vantagens

Você pode usar o 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 subcomandos de utilidade, que são comandos que operam no cliente, neste 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. O mesmo que sair.
Go \g Envia e executa uma instrução SQL no Spanner.
Ajuda \h Exibe informações de ajuda. Igual a \?
Observação \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