Ferramenta de linhas de comando psql

psql é a interface de linhas de comando do PostgreSQL. Esta página descreve os psqlcomandos que a interface PostgreSQL para o Spanner suporta. Para saber como estabelecer ligação ao psql, consulte o artigo Ligar o psql a uma base de dados de dialeto PostgreSQL.

Metacomandos

A interface do PostgreSQL suporta as seguintes categorias de metacomandos psql:

  • Geral
  • Ajuda
  • Buffer de consultas
  • Entrada/saída
  • Condicional
  • Informativo (apenas alguns comandos \d)
  • Formatação
  • Sistema operativo
  • Variáveis

As seguintes categorias não são suportadas:

  • Connection
  • Objetos grandes

Os seguintes comandos informativos são suportados:

Comando Descrição
\d Apresentar tabelas (excluindo tabelas do sistema)
\d table Apresentar colunas da tabela
\dt Listar tabelas em todos os esquemas (detalhado)
\dt table Tabela de listas (detalhada)
\dn Listar esquemas

Declarações de gestão de sessões

O psql comunica com o Spanner através do PGAdapter, que usa o motor principal do controlador JDBC do Spanner. O controlador suporta as declarações de gestão de sessões descritas em Declarações de gestão de sessões. Por conseguinte, pode usar estas declarações com o código psql.

Processamento em lote de declarações SQL

psql e o PGAdapter suportam lotes de SQL com várias declarações. Para processar declarações em lote, use a opção psql -c. Esta opção permite que uma ou mais declarações de SQL ou de gestão de sessões sejam transmitidas como um único pedido de execução, separadas por pontos e vírgulas (;). Um lote pode incluir quaisquer declarações suportadas e pode misturar DDL, DML e DQL.

Um lote de várias declarações é executado num único bloco de transação implícito. Os blocos de transações implícitas são fechados automaticamente no final do lote. Se ocorrerem erros num bloco de transações implícito, toda a transação é revertida.

Os controlos de transações BEGIN explícitos e COMMIT são suportados, mas um bloco de transações explícito não pode conter declarações DDL.

Exemplos

DML

O exemplo seguinte mostra como enviar um lote de declarações 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');"

O exemplo seguinte mostra como executar as declarações SQL no ficheiro insert_contacts.sql.

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

LDD

Este exemplo envia um lote de declarações ALTER TABLE.

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 para importar dados

Use o comando COPY FROM STDIN para importar dados de um ficheiro de texto ou CSV para uma base de dados de dialeto PostgreSQL. Embora apenas o STDIN seja suportado, pode importar usando COPY ao encaminhar ficheiros para psql.

Existem duas formas de executar o comando COPY:

  • Atómico COPY

    Os dados são copiados numa única transação. Esta é a predefinição. Aplicam-se os limites de transação padrão do Spanner à transação. Isto significa que, no máximo, podem ser incluídas 80 000 mutações ou 100 MB de dados numa operação COPY.

  • Não atómico COPY

    COPY divide automaticamente os dados em várias transações se o ficheiro contiver mais de 80 000 mutações ou mais de 100 MB.

    Se for encontrado um erro durante o COPY e a operação for anulada, algumas linhas podem já ter sido persistidas na base de dados. Não ocorre nenhuma reversão. As transações são executadas em paralelo, pelo que os dados após a linha no ficheiro de importação que causou o erro podem ser importados para a base de dados antes de a operação COPY ser interrompida.

Ative a COPY não atómica

Para ativar o COPY não atómico, envie o seguinte comando antes de executar a operação de cópia.

SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'

Sintaxe

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}

A tabela já tem de existir. Se não for especificada nenhuma lista de colunas, são copiadas todas as colunas da tabela.

A predefinição de FORMAT é text.

delimiter_character tem de ser um caráter de um byte. O valor predefinido é o caráter de tabulação para o formato de texto e uma vírgula para o formato CSV.

NULL especifica a string que representa um valor nulo. O valor predefinido é \N (barra invertida + N) no formato de texto e uma string vazia sem aspas no formato CSV. Pode preferir uma string vazia, mesmo no formato de texto, para os casos em que não quer distinguir valores nulos de strings vazias.

QUOTE especifica o caráter de citação a usar quando um valor de dados é citado. A predefinição é aspas duplas. Tem de ser um único caráter de um byte. Esta opção só é permitida quando usa o formato CSV.

ESCAPE especifica o caráter a apresentar antes de um caráter de dados que corresponda ao valor QUOTE. A predefinição é igual ao valor QUOTE (para que o caráter de aspas seja duplicado se aparecer nos dados). Tem de ser um único caráter de um byte. Esta opção só é permitida quando usa o formato CSV.

HEADER indica se o primeiro registo do ficheiro de entrada é um cabeçalho (contém nomes de colunas). A predefinição é TRUE.

Exemplos

Este exemplo importa dados do ficheiro formatado em texto denominado mydata.txt para a tabela mytable. O PGAdapter tem de estar em execução. Para mais informações, consulte o artigo Iniciar o PGAdapter.

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

No exemplo seguinte, mydata.csv está no formato CSV e a primeira linha é um cabeçalho com nomes de colunas separados por vírgulas.

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

O exemplo seguinte mostra como iniciar uma operação COPY não atómica.

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

Resolução de problemas

Seguem-se alguns erros comuns.

Sintaxe de entrada inválida

Ocorre o seguinte erro:

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

Este erro pode ocorrer quando o ficheiro de entrada tem uma linha de cabeçalho com nomes de colunas e a opção HEADER não foi especificada.

Dados COPY inválidos

Ocorre o seguinte erro:

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

Este erro ocorre quando uma linha no ficheiro de entrada não inclui um valor (ou nulo) para cada coluna na tabela. Uma das causas pode ser um ficheiro CSV com formato incorreto ou uma incompatibilidade entre a opção de delimitador especificada (ou o delimitador predefinido) e o delimitador real no ficheiro.

O que se segue?