Guida rapida all'interfaccia a riga di comando Spanner

Nota sull'interfaccia PostgreSQL: Per i database di dialetti PostgreSQL, puoi utilizzare lo strumento a riga di comando psql. Gli esempi riportati in questo documento sono destinati ai database con dialetto GoogleSQL.

Questa pagina introduce la CLI di Spanner e spiega come utilizzarla.

La CLI di Spanner è un'interfaccia a riga di comando (CLI) che ti consente di connetterti e interagire con il tuo database Spanner. È incorporato in Google Cloud CLI (gcloud CLI) per interagire con Spanner. Puoi utilizzare la CLI Spanner per eseguire direttamente istruzioni GoogleSQL nel tuo database Spanner. Le istruzioni possono essere costituite da istruzioni DDL (Data Definition Language), DML (Data Manipulation Language) o DQL (Data Query Language). Puoi utilizzare la CLI di Spanner per eseguire script di comandi SQL e automatizzare le attività.

Si basa sul progetto open source spanner-cli.

Per ulteriori informazioni, consulta un elenco di tutti i comandi gcloud spanner cli supportati.

Vantaggi principali

Puoi utilizzare la chiave per eseguire le seguenti azioni:

• Esegui comandi SQL DDL, DML e DQL.
• Scrivi ed esegui istruzioni SQL su più righe.
• Utilizza i metacomandi per facilitare le attività di sistema, ad esempio l'esecuzione di un comando shell di sistema e l'esecuzione di SQL da un file.
• Automatizza le esecuzioni SQL scrivendo una serie di istruzioni SQL in un file di script e poi chiedendo alla CLI di Spanner di eseguire lo script. Inoltre, puoi reindirizzare l'output a un file di output.
• Avvia una sessione interattiva della CLI Spanner, che ti consente di digitare direttamente istruzioni SQL e meta-comandi e visualizzare i risultati nella CLI.

Prima di iniziare

Prima di utilizzare la CLI di Spanner, assicurati di disporre del ruolo richiesto e di aver installato la CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per installare Spanner, chiedi all'amministratore di concederti il ruolo IAM Cloud Spanner Admin (roles/spanner.admin) su Spanner. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Installa l'interfaccia a riga di comando Spanner

La CLI di Spanner è disponibile in gcloud CLI. Quando esegui il comando gcloud spanner cli per la prima volta, gcloud CLI installa automaticamente il componente Spanner CLI.

Per installare manualmente la CLI Spanner, esegui questo comando:

gcloud components install spanner-cli

Nota: se utilizzi spanner-cli open source, devi installare manualmente Spanner CLI perché la versione open source non viene aggiornata automaticamente.

Se l'installazione tramite il comando Google Cloud CLI non va a buon fine o non è fattibile nel tuo ambiente shell, Spanner fornisce pacchetti Debian (.deb) e RPM (.rpm) autonomi. Puoi utilizzare questi pacchetti per l'installazione manuale su sistemi compatibili. Per installare, esegui questo comando:

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

Opzioni di configurazione

La CLI di Spanner supporta le seguenti opzioni configurabili:

• L'opzione del progetto viene recuperata tramite la proprietà core/project; in alternativa, puoi specificare il progetto utilizzando l'opzione --project.
• L'opzione dell'istanza viene recuperata tramite la proprietà core/instance; in alternativa, puoi specificare l'istanza utilizzando l'opzione --instance.
• L'endpoint API viene recuperato tramite la proprietà api_endpoint_overrides/spanner; in alternativa, puoi specificare l'endpoint utilizzando le opzioni --host e --port. Se non viene specificato alcun endpoint, viene utilizzato l'endpoint Spanner predefinito.

Utilizza la CLI di Spanner

1. Configura un progetto Google Cloud .

2. Configura l'autenticazione utilizzando gcloud CLI.

3. Crea un'istanza.

4. Crea un database.

5. Esegui questo comando per avviare la CLI di Spanner e interagire con il tuo database Spanner:

   gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID
   

   Sostituisci quanto segue:

   • DATABASE_ID: l'ID del database Spanner. Questo è il nome che hai utilizzato nel passaggio precedente Crea un database. Puoi utilizzare il comando gcloud spanner databases list per elencare i database Spanner contenuti nell'istanza specificata.
   • INSTANCE_ID: l'ID dell'istanza Spanner. Questo è il nome che hai utilizzato nel passaggio precedente Crea un'istanza. Puoi utilizzare il comando gcloud spanner instances list per elencare le istanze Spanner contenute nel progetto specificato.

Esegui SQL

Puoi eseguire istruzioni SQL nella CLI Spanner utilizzando l'opzione execute o un metodo di input e output basato su file. Le istruzioni SQL possono essere costituite da DDL, DML o DQL.

Utilizza il flag execute

Per utilizzare il flag execute per eseguire SQL, esegui il seguente comando gcloud spanner cli:

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

Sostituisci quanto segue:

• DATABASE_ID: l'ID del database Spanner a cui vuoi connetterti.
• INSTANCE_ID: l'ID dell'istanza Spanner a cui vuoi connetterti.
• SQL: l'SQL che vuoi eseguire.

Ad esempio, per eseguire un'istruzione 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);"

Per eseguire un'istruzione 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);"

Utilizzare un input e un output basati su file

Se utilizzi il metodo di input e output basato su file, Spanner legge l'input da un file e scrive l'output in un altro file. Per utilizzare il metodo di input e output basato su file per eseguire SQL, esegui questo comando:

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

Puoi anche utilizzare il metodo di input e output basato su file:

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

Sostituisci quanto segue:

• DATABASE_ID: l'ID del database Spanner a cui vuoi connetterti.
• INSTANCE_ID: l'ID dell'istanza Spanner a cui vuoi connetterti.
• SOURCE_FILE_PATH: il file che contiene l'SQL che vuoi eseguire.
• OUTPUT_FILE_PATH: il file denominato a cui aggiungere una copia dell'output SQL.

Avviare una sessione interattiva

Puoi avviare una sessione interattiva di Spanner CLI, che ti consente di digitare direttamente istruzioni SQL e meta-comandi e visualizzare i risultati nella CLI. Per farlo, esegui il seguente comando:

gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID

Una volta stabilita la connessione tra la CLI e il database, vedrai un prompt (ad esempio spanner-cli>) in cui puoi:

• Digita direttamente le istruzioni GoogleSQL:
  • Riferimento DDL GoogleSQL
  • Riferimento DML di GoogleSQL
  • Sintassi delle query GoogleSQL
• Eseguire transazioni
• Utilizzare i metacomandi supportati

Dopo aver premuto il tasto ENTER, l'istruzione o il comando viene inviato al database Spanner appropriato. Spanner quindi esegue l'istruzione o il comando.

Nell'esempio seguente, avvii una sessione interattiva in test-database e poi esegui 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)

Esegui istruzione DDL

Per eseguire un'istruzione DDL, puoi eseguire quanto segue:

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)

Esegui l'istruzione DML

Per eseguire un'istruzione DML, puoi eseguire quanto segue:

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)

Esegui l'istruzione DML partizionata

Nella CLI di Spanner, puoi utilizzare la parola chiave PARTITIONED con i comandi UPDATE e DELETE per eseguire istruzioni DML partizionate efficienti e su larga scala. Quando l'interfaccia a riga di comando di Spanner rileva PARTITIONED UPDATE o PARTITIONED DELETE, li riconosce come operazioni DML partizionate. Queste parole chiave sono utili per le operazioni che interessano una parte significativa di una tabella senza bloccare l'intera tabella per un periodo prolungato. Spanner non applica le istruzioni DML partizionate in modo atomico all'intera tabella. Applica le istruzioni DML partizionate in modo atomico a ogni partizione.

Per eseguire un'istruzione DML partizionata, puoi eseguire quanto segue:

-- 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;

Meta-comandi supportati

La CLI Spanner supporta i meta-comandi di utilità, ovvero comandi che operano sul client, in questo caso la CLI Spanner. I seguenti meta-comandi sono supportati nella CLI Spanner:

Comando	Sintassi	Descrizione
?	\?	Visualizza le informazioni della guida. Uguale a \h.
Delimitatore	\d	Imposta il delimitatore dell'istruzione. Il delimitatore predefinito è un punto e virgola.
Esci	\q	Esce dalla CLI Spanner. Uguale a Esci.
Vai	\g	Invia ed esegue l'istruzione SQL in Spanner.
Guida	\h	Visualizza le informazioni della guida. Uguale a \?.
Notee	\t	Disattiva la scrittura nel file di output impostato da \T.
Prompt	\R	Modifica il prompt in una stringa di prompt utente.
Esci	\q	Esce dalla CLI di Spanner. Uguale all'uscita.
Origine	\.	Esegue SQL da un file di input. Accetta [filename] come argomento.
Sistema	\!	Esegue un comando della shell di sistema.
Tee	\T	Aggiunge l'output comando a un [nome file] specificato insieme all'output standard.
Utilizza	\u	Si connette a un altro database. Prende il nome del nuovo database come argomento.

Comandi supportati aggiuntivi

La CLI Spanner supporta comandi aggiuntivi. Per saperne di più, consulta Comandi della CLI di Spanner.

Assistenza

Per segnalare un problema con la CLI di Spanner, crea un nuovo problema.

Passaggi successivi

• Visualizza un elenco di tutti i comandi della CLI Spanner supportati.
• Visualizza un elenco di tutti i comandi gcloud spanner cli supportati.