Ferramenta de linha de comando psql

psql é o front-end de linha de comando do PostgreSQL. Nesta página, descrevemos os comandos psql compatíveis com a interface PostgreSQL para Spanner. Para saber como se conectar com psql, consulte Como conectar o psql a um banco de dados de dialeto PostgreSQL.

Metacomandos

A Interface PostgreSQL é compatível com as seguintes categorias de metacomandos psql:

  • Geral
  • Ajuda
  • Buffer de consulta
  • Entrada/Saída
  • Condicional
  • Informativo (somente alguns comandos \d)
  • Formatação
  • Sistema operacional
  • Variáveis

As seguintes categorias não são compatíveis:

  • Conexão
  • Objetos grandes

Os comandos informativos a seguir são compatíveis:

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

Instruções de gerenciamento de sessão

O psql se comunica com o Spanner por meio do PGAdapter, que usa o mecanismo principal do driver JDBC do Spanner. O driver oferece suporte às instruções de gerenciamento de sessão descritas em Instruções de gerenciamento de sessão. Portanto, é possível usar essas instruções com psql.

Lote de instrução SQL

O psql e o PGAdapter são compatíveis com lotes SQL de várias instruções. Para agrupar instruções em lote, use a opção psql -c. Essa opção permite que uma ou mais instruções SQL ou de gerenciamento de sessão, separadas por ponto e vírgula (;), sejam transmitidas como uma única solicitação de execução. Um lote pode incluir qualquer instrução compatível e misturar DDL, DML e DQL.

Um lote de várias instruções é executado em um único bloco de transação implícito. Os blocos de transação implícitos são fechados automaticamente no final do lote. Se ocorrerem erros dentro de um bloco de transação implícita, toda a transação será revertida.

Os controles de transação explícitos BEGIN e COMMIT são compatíveis, mas um bloco de transação explícito não pode conter instruções DDL.

Exemplos

DML

O exemplo a seguir mostra como enviar um lote de instruçõ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 a seguir mostra como executar as instruções SQL no arquivo insert_contacts.sql.

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

DDL

Este exemplo envia um lote de instruçõ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 arquivo de texto ou CSV para um banco de dados de dialeto PostgreSQL. Embora apenas STDIN seja compatível, é possível importar usando COPY canalizando arquivos para psql.

Há duas maneiras de executar o comando COPY:

  • Atômico COPY

    Os dados são copiados em uma única transação. Esse é o padrão. Os limites de transação padrão do Spanner se aplicam à transação. Isso significa que, no máximo, 80.000 mutações ou 100 MB de dados podem ser incluídos em uma operação COPY.

  • Não atômico COPY

    O COPY divide automaticamente os dados em várias transações se o arquivo tiver mais de 80.000 mutações ou mais de 100 MB.

    Se um erro for encontrado durante o COPY e a operação for cancelada, algumas linhas já poderão ser mantidas no banco de dados. Nenhuma reversão ocorre. As transações são executadas em paralelo. Portanto, os dados após a linha no arquivo de importação que causou o erro podem ser importados para o banco de dados antes que a operação COPY seja interrompida.

Ativar COPY não atômico

Para ativar o COPY não atômico, envie o comando a seguir 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á deve existir. Se nenhuma lista de colunas for especificada, todas as colunas da tabela serão copiadas.

O padrão para FORMAT é text.

delimiter_character precisa ser um caractere de um byte. O padrão é o caractere 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 padrão é \N (barra invertida+N) no formato de texto e uma string vazia sem aspas no formato CSV. Talvez você prefira uma string vazia, mesmo no formato de texto, para casos em que não queira distinguir nulos de strings vazias.

QUOTE especifica o caractere de aspas a ser usado quando um valor de dados é citado. O padrão é aspas duplas. Precisa ser um único caractere de um byte. Essa opção é permitida apenas ao usar o formato CSV.

ESCAPE especifica o caractere que aparece antes de um caractere de dados que corresponde ao valor QUOTE. O padrão é o mesmo que o valor QUOTE (para que o caractere de aspas seja duplicado se aparecer nos dados). Precisa ser um único caractere de um byte. Essa opção é permitida apenas ao usar o formato CSV.

HEADER indica se o primeiro registro do arquivo de entrada é um cabeçalho (contém nomes de colunas). O padrão é TRUE.

Exemplos

Neste exemplo, os dados do arquivo formatado em texto chamado mydata.txt são importados para a tabela mytable. Inicie o PGAdapter (consulte Iniciar o PGAdapter) ou execute psql usando o conector PG do Spanner (spgc):

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

Para executar a mesma importação usando spgc, execute o seguinte comando:

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

No próximo exemplo, 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 a seguir 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;"

Solução de problemas

Veja a seguir alguns erros comuns.

Sintaxe de entrada inválida

O seguinte erro ocorre:

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

Esse erro pode ocorrer quando o arquivo 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

O seguinte erro ocorre:

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

Esse erro ocorre quando uma linha no arquivo de entrada não inclui um valor (ou nulo) para cada coluna na tabela. Uma causa pode ser um arquivo CSV malformado ou uma incompatibilidade entre a opção de delimitador especificada (ou delimitador padrão) e o delimitador real no arquivo.

A seguir