Strumento a riga di comando psql

psql è il front-end a riga di comando di PostgreSQL. Questa pagina descrive i comandi psql supportati dall'interfaccia PostgreSQL per Spanner. Per scoprire come connetterti con psql, consulta Connessione di psql a un database con dialetto PostgreSQL.

Metacomandi

L'interfaccia PostgreSQL supporta le seguenti categorie di metacomandi psql:

  • Generale
  • Guida
  • Buffer di query
  • Input/Output
  • Condizionale
  • Informativo (solo alcuni comandi \d)
  • Formattazione
  • Sistema operativo
  • Variabili

Le seguenti categorie non sono supportate:

  • Connessione
  • Oggetti di grandi dimensioni

Sono supportati i seguenti comandi informativi:

Comando Descrizione
\d Elenca le tabelle (escluse le tabelle di sistema)
\d table Elenca le colonne della tabella
\dt Elenca le tabelle in tutti gli schemi (dettagliato)
\dt table Tabella elenco (dettagliata)
\dn Elenca schemi

Istruzioni di gestione delle sessioni

psql comunica con Spanner tramite PGAdapter, che utilizza il motore principale del driver JDBC di Spanner. Il driver supporta le istruzioni di gestione delle sessioni descritte in Istruzioni di gestione delle sessioni. Pertanto, puoi utilizzare queste istruzioni con psql.

Batch di istruzione SQL

psql e PGAdapter supportano i batch SQL con più istruzioni. Per raggruppare le istruzioni, utilizza l'opzione psql -c. Questa opzione consente di passare una o più istruzioni SQL o di gestione delle sessioni, separate da punti e virgola (;), come singola richiesta di esecuzione. Un batch può includere qualsiasi istruzione supportata e può combinare DDL, DML e DQL.

Un batch con più istruzioni viene eseguito all'interno di un singolo blocco di transazioni implicite. I blocchi di transazioni implicite vengono chiusi automaticamente alla fine del batch. Se si verificano errori all'interno di un blocco di transazione implicito, viene eseguito il rollback dell'intera transazione.

Sono supportati i controlli delle transazioni BEGIN e COMMIT espliciti, ma un blocco di transazioni esplicito non può contenere istruzioni DDL.

Esempi

DML

L'esempio seguente mostra come inviare un batch di istruzioni INSERT.

psql -h localhost -p 5432 -c "INSERT INTO users (id, age, firstname) VALUES (1, 25, 'Alex'); \
 INSERT INTO users (id, age, firstname) VALUES (2, 31, 'Dana'); \
 INSERT INTO users (id, age, firstname) VALUES (3, 54, 'Izumi');"

L'esempio seguente mostra come eseguire le istruzioni SQL nel file insert_contacts.sql.

psql -h localhost -c "$(cat contacts_insert.sql)"

DDL

Questo esempio invia un batch di ALTER TABLE istruzioni.

psql -h localhost -p 5432 test-db -c "ALTER TABLE users ADD col1 integer; \
 ALTER TABLE users ADD col2 text; ALTER TABLE users ADD col3 float8;"

Comando COPY per l'importazione dei dati

Utilizza il comando COPY FROM STDIN per importare i dati da un file di testo o CSV in un database di dialetti PostgreSQL. Sebbene sia supportato solo STDIN, puoi eseguire l'importazione utilizzando COPY tramite il piping dei file in psql.

Esistono due modi per eseguire il comando COPY:

  • Atomico COPY

    I dati vengono copiati in una singola transazione. Questa è l'impostazione predefinita. Alla transazione si applicano i limiti di transazione standard di Spanner. Ciò significa che in un'operazione COPY possono essere incluse al massimo 80.000 mutazioni o 100 MB di dati.

  • Non atomico COPY

    COPY suddivide automaticamente i dati in più transazioni se il file contiene più di 80.000 mutazioni o più di 100 MB.

    Se si verifica un errore durante l'operazione COPY e l'operazione viene interrotta, alcune righe potrebbero essere già state salvate nel database. Non viene eseguito alcun rollback. Le transazioni vengono eseguite in parallelo, quindi i dati successivi alla riga nel file di importazione che ha causato l'errore potrebbero essere importati nel database prima che l'operazione COPY venga interrotta.

Attiva COPY non atomico

Per abilitare l'operazione COPY non atomica, invia il seguente comando prima di eseguire l'operazione di copia.

SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'

Sintassi

COPY table_name [ ( column_name [, ...] ) ]
    FROM STDIN
    [ [ WITH ] ( option [, ...] ) ]

where option is one of:

    FORMAT format_name
    DELIMITER 'delimiter_character'
    NULL 'null_string'
    QUOTE 'quote_character'
    ESCAPE 'escape_character'
    HEADER [boolean]

and format_name is:
    {text|csv}

and delimiter_character is:
    [!-~] except ' " \

and null_string is:
    {a—z|A—Z|0—9|_}+

and quote_character is:
    [!-~] except ' " \

and escape_character is:
    [!-~] except ' " \

and boolean is:
    {TRUE|ON|1|FALSE|OFF|0}

La tabella deve esistere già. Se non viene specificato un elenco di colonne, vengono copiate tutte le colonne della tabella.

Il valore predefinito per FORMAT è text.

delimiter_character deve essere un carattere di un byte. Il valore predefinito è il carattere di Tab per il formato di testo e una virgola per il formato CSV.

NULL specifica la stringa che rappresenta un valore null. Il valore predefinito è \N (barra rovesciata+N) nel formato di testo e una stringa vuota senza virgolette nel formato CSV. Potresti preferire una stringa vuota anche in formato di testo per i casi in cui non vuoi distinguere i valori null dalle stringhe vuote.

QUOTE specifica il carattere di virgolette da utilizzare quando un valore dei dati è racchiuso tra virgolette. Il valore predefinito sono le virgolette doppie. Deve essere un singolo carattere a un byte. Questa opzione è consentita solo se utilizzi il formato CSV.

ESCAPE specifica il carattere da visualizzare prima di un carattere di dati che corrisponde al valore QUOTE. Il valore predefinito è lo stesso del valore QUOTE (in modo che il carattere di citazione venga raddoppiato se appare nei dati). Deve essere un singolo carattere a un byte. Questa opzione è consentita solo se utilizzi il formato CSV.

HEADER indica se il primo record del file di input è un'intestazione (contiene i nomi delle colonne). Il valore predefinito è TRUE.

Esempi

Questo esempio importa i dati dal file in formato testo denominato mydata.txt nella tabella mytable. Avvia PGAdapter (consulta Avvia PGAdapter) o esegui psql utilizzando Spanner PG Connector (spgc):

cat mydata.txt | psql -h localhost -c "COPY mytable FROM STDIN;"

Per eseguire la stessa importazione utilizzando spgc, esegui questo comando:

cat mydata.txt | spgc psql -d DATABASE_ID -c "COPY mytable FROM STDIN;"

Nel prossimo esempio, mydata.csv è in formato CSV e la prima riga è un'intestazione con i nomi delle colonne separati da virgole.

cat mydata.csv | psql -h localhost \
  -c "COPY mytable FROM STDIN WITH (FORMAT csv, ESCAPE '~', HEADER TRUE);"

L'esempio seguente mostra come avviare un'operazione COPY non atomica.

cat mydata.txt | psql -h localhost \ 
  -c "SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'" -c "COPY mytable FROM STDIN;"

Risoluzione dei problemi

Di seguito sono riportati alcuni errori comuni.

Sintassi di input non valida

Si verifica il seguente errore:

Invalid input syntax for type <type>:"<table_name>"

Questo errore può verificarsi quando il file di input ha una riga di intestazione con i nomi delle colonne e l'opzione HEADER non è stata specificata.

Dati COPY non validi

Si verifica il seguente errore:

Invalid COPY data: Row length mismatched. Expected <number> columns, but only found <number>

Questo errore si verifica quando una riga nel file di input non include un valore (o un valore null) per ogni colonna della tabella. Una causa potrebbe essere un file CSV non valido o una mancata corrispondenza tra l'opzione del delimitatore specificata (o il delimitatore predefinito) e il delimitatore effettivo nel file.

Passaggi successivi