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.

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

Principais vantagens

Os principais benefícios da CLI do Spanner incluem:

  • Executa comandos SQL DDL, DML e DQL.
  • Você pode escrever e executar instruções SQL em várias linhas.
  • Oferece suporte a metacomandos para ajudar você com tarefas do sistema, como executar um comando de shell do sistema e executar SQL de um arquivo.
  • É possível automatizar as execuções de SQL gravando uma série de instruções SQL em um arquivo de script e instruindo a CLI do Spanner a executar o script. Além disso, é possível redirecionar a saída para um arquivo.
  • É 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.

Antes de começar

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

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 alpha 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 alpha spanner cli:

gcloud alpha 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 alpha 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 alpha 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 baseada 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 alpha 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 alpha 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 alpha 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 alpha 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)

Metacomandos compatíveis

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 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 a "Saída".
Origem \. Executa SQL de um arquivo de entrada. Usa [nome do arquivo] como argumento.
Sistema \! Executa um comando do shell do sistema.
Tee \T Adiciona resposta ao comando a um [nome do arquivo] especificado junto com a saída padrão.
Usar \u Conecta-se a outro banco de dados. Usa o novo nome do banco de dados como argumento.

A seguir