Início rápido da CLI do Spanner

Esta página apresenta a CLI do Spanner e explica como usá-la.

A CLI do Spanner é uma interface de linhas de comando (CLI) que lhe permite estabelecer ligação e interagir com a sua base de dados do Spanner. Está incorporada na CLI do Google Cloud (CLI gcloud) para interagir com o Spanner. Pode usar a CLI do Spanner para executar diretamente declarações GoogleSQL na sua base de dados do Spanner. As suas declarações podem consistir em declarações de linguagem de definição de dados (LDD), linguagem de manipulação de dados (DML) ou linguagem de consulta de dados (DQL). Pode usar a CLI do Spanner para executar scripts de comandos SQL e automatizar tarefas.

Baseia-se 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

Pode usar o Spanner para realizar as seguintes ações:

  • Executar comandos SQL DDL, DML e DQL.
  • Escrever e executar declarações SQL em várias linhas.
  • Use metacomandos para ajudar com tarefas do sistema, como executar um comando de shell do sistema e executar SQL a partir de um ficheiro.
  • Automatize as execuções de SQL escrevendo uma série de declarações SQL num ficheiro de script e, em seguida, dando instruções à CLI do Spanner para executar o script. Além disso, pode redirecionar a saída para um ficheiro de saída.
  • Inicie uma sessão interativa da CLI do Spanner, que lhe permite escrever diretamente declarações SQL e metacomandos, e ver os resultados na CLI.

Antes de começar

Antes de usar a CLI do Spanner, certifique-se de que tem a função necessária e que instalou a CLI.

Funções necessárias

Para receber as autorizações de que precisa para instalar o Spanner, peça ao seu administrador para lhe conceder a função de IAM de administrador do Cloud Spanner (roles/spanner.admin) no Spanner. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Instale a CLI do Spanner

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

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

gcloud components install spanner-cli

Se a instalação através do comando da CLI Google Cloud não for bem-sucedida ou não for viável no seu ambiente de shell, o Spanner fornece pacotes Debian (.deb) e RPM (.rpm) autónomos. Pode usar estes pacotes para instalar manualmente em sistemas compatíveis. Para instalar, execute o seguinte comando:

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

Opções de configuração

A CLI do Spanner suporta as seguintes opções configuráveis:

  • A opção de projeto é obtida através da propriedade core/project. Em alternativa, pode especificar o projeto através da opção --project.
  • A opção de instância é obtida através da propriedade core/instance; em alternativa, pode especificar a instância através da opção --instance.
  • O ponto final da API é obtido através da propriedade api_endpoint_overrides/spanner. Em alternativa, pode especificar o ponto final através das opções --host e --port. O ponto final do Spanner predefinido é usado se não for especificado nenhum ponto final.

Use a CLI do Spanner

  1. Configure um Google Cloud projeto.

  2. Configure a autenticação através da CLI gcloud.

  3. Crie uma instância.

  4. Crie uma base de dados.

  5. Execute o seguinte comando para iniciar a CLI do Spanner e interagir com a sua base de dados do Spanner:

    gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID

    Substitua o seguinte:

    • DATABASE_ID: o ID da base de dados do Spanner. Este é o nome que usou no passo anterior de criação de uma base de dados. Pode usar o comando gcloud spanner databases list para listar as bases de dados do Spanner contidas na instância indicada.
    • INSTANCE_ID: o ID da instância do Spanner. Este é o nome que usou no passo anterior de criação de uma instância. Pode usar o comando gcloud spanner instances list para listar as instâncias do Spanner contidas no projeto indicado.

Executar SQL

Pode executar declarações SQL na CLI do Spanner através da opção execute ou de um método de entrada e saída baseado em ficheiros. As suas declarações SQL podem consistir em DDL, DML ou DQL.

Use a flag execute

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

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

Substitua o seguinte:

  • DATABASE_ID: o ID da base de dados do Spanner à qual quer estabelecer ligação.
  • INSTANCE_ID: o ID da instância do Spanner à qual quer estabelecer ligação.
  • SQL: o SQL que quer executar.

Por exemplo, para executar uma declaraçã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);"

Use uma entrada e uma saída baseadas em ficheiros

Se usar o método de entrada e saída baseado em ficheiros, o Spanner lê a entrada de um ficheiro e escreve a saída noutro ficheiro. Para usar o método de entrada e saída baseado em ficheiros para executar SQL, execute o seguinte comando:

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

Também pode usar o método de entrada e saída de redirecionamento baseado em ficheiros:

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

Substitua o seguinte:

  • DATABASE_ID: o ID da base de dados do Spanner à qual quer estabelecer ligação.
  • INSTANCE_ID: o ID da instância do Spanner à qual quer estabelecer ligação.
  • SOURCE_FILE_PATH: o ficheiro que contém o SQL que quer executar.
  • OUTPUT_FILE_PATH: o ficheiro com nome ao qual anexar uma cópia da saída SQL.

Inicie uma sessão interativa

Pode iniciar uma sessão interativa da CLI do Spanner, que lhe permite escrever diretamente declarações SQL e metacomandos, e ver os resultados na CLI. Para o fazer, execute o seguinte comando:

gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID

Após a ligação bem-sucedida entre a CLI e a sua base de dados, é apresentado um comando (por exemplo, spanner-cli>) onde pode fazer o seguinte:

Depois de premir a tecla ENTER, a declaração ou o comando é enviado para a base de dados do Spanner adequada. Em seguida, o Spanner executa a declaração ou o comando.

No exemplo seguinte, inicia uma sessão interativa em test-database e, em seguida, 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)

Execute a instrução DDL

Para executar uma declaração DDL, pode executar 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)

Execute a instrução DML

Para executar uma declaração DML, pode executar 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)

Execute a declaração DML particionada

Na CLI do Spanner, pode usar a palavra-chave PARTITIONED com os comandos UPDATE e DELETE para executar declarações de DML particionadas eficientes e em grande escala. Quando a CLI do Spanner encontra PARTITIONED UPDATE ou PARTITIONED DELETE, reconhece-os como operações DML particionadas. Estas palavras-chave são úteis para operações que afetam uma parte significativa de uma tabela sem bloquear a tabela inteira durante um período prolongado. O Spanner não aplica as declarações DML particionadas de forma atómica a toda a tabela. Aplica declarações DML particionadas de forma atómica em cada partição.

Para executar uma declaração DML particionada, pode executar 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 suportados

A CLI do Spanner suporta metacomandos de utilidade, que são comandos que operam no cliente, neste caso, a CLI do Spanner. Os seguintes metacomandos são suportados na CLI do Spanner:

Command Sintaxe Descrição
? \? Apresenta informações de ajuda. Igual a \h.
Delimitador \d Define o delimitador de declarações. O delimitador predefinido é um ponto e vírgula.
Sair \q Sai da CLI do Spanner. O mesmo que sair.
Ir \g Envia e executa a declaração SQL no Spanner.
Ajuda \h Apresenta informações de ajuda. Igual a \?.
Notee \t Desativa a escrita no ficheiro de saída definido por \T.
Comando \R Altera o seu comando para uma string de comando do utilizador.
Sair \q Sai da CLI do Spanner. Igual à saída.
Origem \. Executa SQL a partir de um ficheiro de entrada. Usa [filename] como argumento.
Sistema \! Executa um comando de shell do sistema.
Tee \T Anexa o resultado do comando a um [nome do ficheiro] especificado, juntamente com o resultado padrão.
Utilizar \u Estabelece ligação a outra base de dados. Usa o novo nome da base de dados como argumento.

Comandos adicionais suportados

A CLI do Spanner suporta comandos adicionais. Para mais informações, consulte os comandos da CLI do Spanner.

Obter apoio técnico

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

O que se segue?