O psql é um cliente no modo terminal do PostgreSQL. Permite digitar comandos interativamente, submetê-los para o PostgreSQL e ver os resultados. Como alternativa, a entrada pode vir de um arquivo. Além disso, disponibiliza vários meta-comandos e diversas funcionalidades semelhantes às do interpretador de comandos (shell) para facilitar a criação de scripts e automatizar um grande número de tarefas.
Nota: Este modo é fornecido para aqueles que insistem em usá-lo, mas sua utilização não é incentivada. Em particular, se forem misturados comandos SQL e meta-comandos na mesma linha, a ordem de execução nem sempre será clara para o usuário inexperiente.
table
do HTML. Veja \pset para obter detalhes.
O psql retorna para o interpretador de comandos: 0 se terminar normalmente; 1 se ocorrer erro fatal próprio (falta de memória, arquivo não encontrado); 2 se a conexão com o servidor teve problema e a sessão não é interativa; 3 se ocorrer erro no script e a variável ON_ERROR_STOP estiver definida.
O psql é uma aplicação cliente do PostgreSQL comum. Para conectar a um banco de dados é necessário saber o nome do banco de dados, o nome do hospedeiro, o número da porta do servidor e o nome do usuário a ser usado para conectar. O psql pode ser informado sobre estes parâmetros por meio das opções de linha de comando -d, -h, -p e -U, respectivamente. Se for encontrado um argumento que não pertence a nenhuma opção, este será interpretado como o nome do banco de dados (ou o nome do usuário, se o nome do banco de dados já tiver sido fornecido). Nem todas estas opções são requeridas; existem padrões úteis. Se for omitido o nome do hospedeiro, então o psql se conecta através do soquete do domínio Unix ao servidor no hospedeiro local. O número padrão para a porta é determinado na compilação. Uma vez que que o servidor de banco de dados usa o mesmo padrão, não é necessário especificar a porta na maioria dos casos. O nome de usuário padrão é o nome do usuário do Unix, como também é o nome do banco de dados padrão. Deve ser observado que não é possível se conectar a qualquer banco de dados com qualquer nome de usuário. O administrador de banco de dados deve informar as permissões de acesso concedidas. Para evitar a digitação, podem ser definidas as variáveis de ambiente PGDATABASE, PGHOST, PGPORT e PGUSER com os valores apropriados.
Se a conexão não puder ser estabelecida por algum motivo (por exemplo, privilégios insuficientes, o servidor não está executando no hospedeiro de destino, etc.), o psql retorna uma mensagem de erro e termina.
No modo normal de operação, o psql exibe um prompt com o nome do banco de dados ao qual está conectado, seguido pela cadeia de caracteres =>. Por exemplo: [1]
$ psql testdb Bem-vindo ao psql 7.4.1, o terminal interativo do PostgreSQL. Digite: \copyright para mostrar a licença da distribuição \h para ajuda nos comandos SQL \? para ajuda nos comandos de contrabarra internos \g ou finalizar com ponto-e-vírgula para executar o comando \q para sair testdb=>
No prompt o usuário pode digitar comandos SQL. Normalmente, as linhas de entrada são enviadas para o servidor quando é encontrado o caractere ponto-e-vírgula, que termina o comando. Um fim de linha não termina o comando. Portanto, os comandos podem ser distribuídos por várias linhas para maior clareza. Se o comando for enviado e executado sem erro, o resultado do comando será mostrado na tela.
Sempre que um comando é executado, o psql também verifica eventos de notificação assíncronos gerados pelo LISTEN e NOTIFY .
Qualquer texto digitado no psql começando por uma contrabarra (\) (não entre apóstrofos, ') é um meta-comando do psql processado pelo próprio psql. Estes comandos ajudam a tornar o psql mais útil para administração e para scripts. Os meta-comandos são geralmente chamados de comandos de barra ou de contrabarra.
O formato de um comando psql é a contrabarra, seguida imediatamente por um verbo comando, e depois pelos argumentos. Os argumentos são separados do verbo comando, e entre si, por qualquer número de caracteres de espaço em branco.
Para incluir espaço em branco no argumento deve-se colocá-los entre apóstrofos ('). Para incluir um apóstrofo neste tipo de argumento, deve-se precedê-lo por uma contrabarra. Qualquer texto entre apóstrofos está sujeito às substituições no estilo C para \n (nova-linha), \t (tabulação), \dígitos, \0dígitos e \0xdígitos (o caractere com o código decimal, octal ou hexadecimal especificado).
Se um argumento (não entre apóstrofos) começar por dois-pontos (:), será considerado como sendo uma variável do psql, e o valor desta variável será usado como o argumento.
Os argumentos entre crases (`) são considerados como sendo linhas de comando a serem passadas para o interpretador de comandos. A saída do comando (com o caractere de nova-linha final removido) é usada como o valor do argumento. As seqüências de escape (\) acima também se aplicam às crases.
Alguns comandos recebem como argumento um identificador SQL como, por exemplo, o nome de uma tabela. Estes argumentos seguem as regras de sintaxe do SQL: as letras que não se encontram entre aspas (") são transformadas em minúsculas, enquanto as letras que se encontram entre aspas ficam protegidas contra a transformação em minúsculas. As aspas permitem, também, incorporar espaços em branco ao identificador. Quando entre as aspas, um par de aspas é reduzido a uma única aspas no nome resultante. Por exemplo, FOO"BAR"BAZ é interpretado como fooBARbaz, e "Um nome"" estranho" se torna Um nome" estranho.
A análise dos argumentos pára quando é encontrada outra contrabarra (não entre apóstrofos). Esta é considerada como sendo o início de um novo meta-comando. A seqüência especial \\ (duas contrabarras) marca o fim dos argumentos e a continuação da análise dos comandos SQL, se existirem. Desta forma, os comandos SQL e psql podem ser livremente misturados na linha. Mas em nenhum caso os argumentos de um meta-comando podem continuar após o fim da linha.
Os seguintes meta-comandos estão definidos:
Dica: Para ver o diretório de trabalho corrente deve ser usado \!pwd.
Dica: Este operação não é tão eficiente quanto o comando COPY do SQL, porque todos os dados passam através da conexão cliente/servidor. Para uma grande quantidade de dados, o comando SQL pode ser preferível.
Nota: Deve ser observada a diferença de interpretação da stdin da stdout entre as cópias pelo cliente e pelo servidor: na cópia pelo cliente se referem sempre à entrada e saída do psql. Na cópia pelo servidor, stdin vem do lugar onde o próprio comando COPY veio (por exemplo, um script executado com a opção -f), e a stdout se refere à saída do comando (veja o meta-comando \o abaixo).
Nota: Se \d for utilizado sem o argumento padrão, torna-se equivalente a \dtvs, mostrando a lista de todas as tabelas, visões e seqüências. Isto é puramente uma medida de conveniência.
=> \dd version Object descriptions Schema | Name | Object | Description ------------+---------+----------+--------------------------- pg_catalog | version | function | PostgreSQL version string (1 linha)As descrições dos objetos podem ser criadas pelo comando COMMENT do SQL.
Nota: Para reduzir a desordem, o \df não mostra as funções com tipo de dado I/O. Isto é implementado ignorando as funções que recebem ou retornam o tipo cstring.
Dica: O psql procura nas variáveis de ambiente PSQL_EDITOR, EDITOR e VISUAL (nesta ordem) o editor a ser usado. Se nenhuma delas estiver definida, então é usado /bin/vi.
=> \echo `date` Dom Fev 20 05:10:59 BRT 2005Se o primeiro argumento for -n (não entre apóstrofos) não é enviado o caractere de nova-linha final.
Dica: Se for usado o comando \o para redirecionar a saída do comando, talvez seja preferível utilizar \qecho em vez deste comando.
=> \encoding LATIN1
=> SELECT datname FROM pg_database \g | gvim - => Vim: Reading from stdin...
Nota: Para simplificar a digitação, os comandos compostos por várias palavras não necessitam estar entre apóstrofos. Portanto, pode ser digitado \help alter table.
Nota: Se for desejado ver as linhas na tela à medida que são lidas, deve ser definida a variável ECHO como all.
lo_export
, que atua com a permissão do usuário como o qual o servidor de banco de dados está executando, e no sistema de arquivos do servidor.
Dica: Use \lo_list para descobrir os OIDs dos objetos grandes.
foo=> \lo_import '/home/peter/pictures/photo.xcf' 'uma fotografia minha' lo_import 152801A resposta indica que o objeto grande recebeu o identificador de objeto 152801, que deve ser lembrado para acessar o objeto novamente. Por esta razão, recomenda-se associar sempre um comentário inteligível a cada objeto. Estes podem ser vistos utilizando o comando \lo_list. Deve ser observado que este comando é sutilmente diferente da função
lo_import
do servidor, porque atua como o usuário local no sistema de arquivos local, em vez do usuário do servidor no sistema de arquivos do servidor.
Dica: Use \lo_list para descobrir os OIDs dos objetos grandes.
=> \o | gvim - => Vim: Reading from stdin... => \qecho Bancos de Dados => SELECT datname FROM pg_database; => \qecho Linguagens => SELECT lanname FROM pg_language; => \oOs "resultados dos comandos" incluem todas as tabelas, respostas dos comandos e notificações recebidas do servidor de banco de dados, assim como a saída de vários comandos de contrabarra que consultam o banco de dados (como o \d), mas não as mensagens de erro.
Dica: Para intercalar saída de texto entre os resultados dos comandos deve ser utilizado \qecho.
table
do HTML. Estes atributos podem ser, por exemplo, cellpadding ou bgcolor. Deve ser observado que, provavelmente, não será desejado especificar border aqui, porque isto já é tratado pelo \pset border.
Ilustrações mostrando como se parecem estes formatos diferentes podem ser vistas na seção Exemplos .
Dica: Existem vários comandos abreviados para o \pset. Veja \a, \C, \H, \t, \T e \x.
Nota: É errado chamar o \pset sem argumentos. No futuro, esta chamada deverá mostrar o status corrente de todas as opções de exibição.
Nota: Na versão corrente não é mais necessário salvar o histórico de comandos, porque isso é feito automaticamente ao término do programa. O histórico também é carregado, automaticamente, toda vez que o psql inicia.
Nota: Este comando é totalmente distinto do comando SET do SQL.
table
no modo de saída tabular HTML. Este comando equivale a \pset tableattr opções_de_tabela.
=> \w | date Dom Fev 20 07:55:08 BRT 2005 => \w | pwd /root
=> \!date Dom Fev 20 08:04:41 BRT 2005 => \!pwd /root
Vários comandos \d aceitam como parâmetro um padrão para especificar os nomes dos objetos a serem mostrados. O * significa "qualquer seqüência de caracteres" e ? significa "qualquer um único caractere" (Esta notação é semelhante a do padrão para nomes de arquivos do interpretador de comandos do Unix). Os usuários avançados também podem utilizar a notação das expressões regulares, como as classes de caracteres; por exemplo [0-9] correspondendo a "qualquer dígito". Para fazer qualquer um desses caracteres de correspondência com padrão ser interpretado literalmente, deve-se colocá-lo entre aspas.
Um padrão contendo um ponto (não entre aspas) é interpretado como um padrão de nome de esquema seguido por um padrão de nome de objeto. Por exemplo, \dt foo*.bar* mostra todas as tabelas nos esquemas cujos nomes começam por foo, e cujos nomes de tabela começam por bar. Se não houver nenhum ponto, então o padrão corresponde apenas aos objetos visíveis no caminho de procura de esquemas corrente. Por exemplo: (N. do T.)
=> \dt info*.*sizing* Lista de relações Esquema | Nome | Tipo | Dono --------------------+---------------------+--------+---------- information_schema | sql_sizing | tabela | postgres information_schema | sql_sizing_profiles | tabela | postgres (2 linhas) => \dt 'info*.*sizing*' Lista de relações Esquema | Nome | Tipo | Dono --------------------+---------------------+--------+---------- information_schema | sql_sizing | tabela | postgres information_schema | sql_sizing_profiles | tabela | postgres (2 linhas) => \dt "info*.*sizing*" Não foi encontrada relação correspondente.
Sempre que o parâmetro padrão é omitido, o comando \d mostra todos os objetos visíveis no caminho de procura de esquemas corrente. Para mostrar todos os objetos do banco de dados, deve ser usado o padrão *.*.
O psql fornece uma funcionalidade de substituição de variáveis semelhante a dos interpretadores de comando do Unix. As variáveis são simplesmente pares nome/valor, onde o valor pode ser qualquer cadeia de caracteres de qualquer comprimento. Para definir as variáveis é utilizado o meta-comando do psql \set:
testdb=> \set foo bar
define a variável foo com o valor bar. Para acessar o conteúdo da variável deve-se preceder seu nome por dois-pontos (:), e usá-lo como argumento de qualquer comando de contrabarra:
testdb=> \echo :foo bar
Nota: Os argumentos do \set estão sujeitos às mesmas regras de substituição de qualquer outro comando. Portanto, podem ser construídas referências interessantes como \set :foo 'something' e obter "soft links" ou "variable variables" do Perl e do PHP, respectivamente. Desafortunadamente (ou afortunadamente?), não existe nenhuma forma de fazer algo útil com estas construções. Por outro lado, \set bar :foo é uma forma perfeitamente válida de copiar uma variável.
Se \set for chamado sem o segundo argumento, a variável é definida com uma cadeia de caracteres vazia como valor. Para remover a definição (ou excluir) a variável, deve ser utilizado o comando \unset.
Os nomes das variáveis internas do psql podem ser formados por letras, números e sublinhados em qualquer ordem e número. Algumas destas variáveis recebem tratamento especial pelo psql. Denotam determinadas configurações de opção que podem ser mudadas em tempo de execução alterando o valor da variável, ou representam algum estado da aplicação. Embora seja possível usar estas variáveis para qualquer outra finalidade isto não é recomendado, porque o comportamento do programa pode ficar muito estranho, muito rapidamente. Por convenção, todas as variáveis com tratamento especial possuem todas as letras maiúsculas (e possivelmente números e sublinhados). Para garantir a máxima compatibilidade futura, evite usar estes nomes de variáveis para as suas próprias finalidades. Abaixo segue a lista de todas as variáveis com tratamento especial.
Nota: No modo "autocommit-off" toda transação que não for bem-sucedida deve ser explicitamente abandonada entrando com ABORT ou ROLLBACK. Também tenha em mente que, se a sessão for terminada sem a transação ser efetivada, o trabalho será perdido.
Nota: O modo "autocommit-on" é o comportamento tradicional do PostgreSQL, mas o modo "autocommit-off" é mais próximo da especificação SQL. Se for preferido o modo "autocommit-off", este pode ser definido no arquivo ~/.psqlrc do usuário.
=> \echo :AUTOCOMMIT on
=> \echo :DBNAME template1
=> \set ECHO_HIDDEN => \dn ********* QUERY ********** SELECT n.nspname AS "Nome", u.usename AS "Dono" FROM pg_catalog.pg_namespace n LEFT JOIN pg_catalog.pg_user u ON n.nspowner=u.usesysid ORDER BY 1; ************************** Lista dos esquemas Nome | Dono --------------------+---------- information_schema | postgres pg_catalog | postgres pg_temp_1 | postgres pg_toast | postgres public | postgres (5 linhas)
=> \echo :ENCODING LATIN1
Nota: Esta funcionalidade foi desavergonhadamente plagiada do Bash.
Nota: Esta funcionalidade foi desavergonhadamente plagiada do Bash.
Nota: Esta funcionalidade foi desavergonhadamente plagiada do Bash.
Uma funcionalidade adicional útil das variáveis do psql é poderem ser substituídas ("interpoladas") dentro de comandos SQL regulares. Novamente a sintaxe é colocar dois-pontos (:) como prefixo do nome da variável.
testdb=> \set foo 'minha_tabela' testdb=> SELECT * FROM :foo;
faria então a consulta à tabela minha_tabela. O valor da variável é copiado literalmente podendo, portanto, conter apóstrofos não balanceados ou comandos de contrabarra. Deve-se ter certeza que faz sentido onde é colocada. A interpolação de variáveis não é realizada dentro de entidades SQL entre aspas ou apóstrofos. Por exemplo: (N. do T.)
testdb=> \set tabela 'pg_catalog.pg_user' testdb=> \echo :tabela pg_catalog.pg_user testdb=> \echo ':tabela' :tabela testdb=> \echo ":tabela" ":tabela" testdb=> SELECT usename FROM :tabela WHERE usesysid=1; usename ---------- postgres (1 linha) testdb=> SELECT usename FROM ':tabela' WHERE usesysid=1; ERRO: erro de sintaxe em ou próximo de "':tabela'" no caractere 21 testdb=> SELECT usename FROM ":tabela" WHERE usesysid=1; ERRO: a relação ":tabela" não existe
Uma aplicação comum desta funcionalidade é para fazer referência nos comandos subseqüentes ao último OID inserido, para construir um cenário de chave estrangeira. Outra utilização possível deste mecanismo é para copiar o conteúdo de um arquivo para uma coluna de uma tabela. Primeiro deve ser carregado o arquivo na variável, e depois proceder conforme mostrado.
testdb=> \set conteudo '\'' `cat meu_arquivo.txt` '\'' testdb=> INSERT INTO minha_tabela VALUES (:conteudo);
Um problema possível com esta abordagem é que meu_arquivo.txt pode conter apóstrofos, que devem ser precedidos por contrabarra para não causarem erro de sintaxe quando a segunda linha for processada, o que pode ser feito por meio do programa sed:
testdb=> \set conteudo '\'' `sed -e "s/'/\\\\\\'/g" < meu_arquivo.txt` '\''
Deve ser observado o número correto de contabarras (6)! Isto funciona da seguinte maneira: Após o psql ter analisado esta linha, enviará sed -e "s/'/\\\'/g" < meu_arquivo.txt para o interpretador de comandos, que fará suas próprias atividades dentro das aspas e executará o sed com os argumentos -e e s/'/\\'/g. Quando o sed fizer a análise substituirá as duas contrabarras por uma única e, então, fará a substituição. Talvez em algum ponto tenha se pensado ser ótimo todos os comandos Unix utilizarem o mesmo caractere de escape (escape character). Isto tudo ainda ignora o fato de ter que colocar contrabarra na frente de contrabarra também, porque as constantes textos do SQL também estão sujeitas a certas interpretações. Neste caso é melhor preparar o arquivo externamente.
Uma vez que os dois-pontos podem aparecer legalmente nos comandos SQL, a seguinte regra se aplica: a seqüência de caracteres ":nome" não é modificada a menos que "nome" seja o nome de uma variável atualmente definida. Sempre pode ser feito o escape dos dois-pontos com uma contrabarra para protegê-lo da substituição (A sintaxe dos dois-pontos para as variáveis é padrão SQL para linguagens de comandos incorporados, tal como ECPG. A sintaxe de dois-pontos para "faixa de matriz" e "conversão de tipo" são extensões do PostgreSQL, daí o conflito).
Os prompts emitidos pelo psql podem ser personalizados conforme a preferência. As três variáveis PROMPT1, PROMPT2 e PROMPT3 contêm cadeias de caracteres e seqüências especiais de escape que descrevem a aparência do prompt. O prompt 1 é o prompt normal emitido quando o psql solicita um novo comando. O prompt 2 é emitido durante a entrada do comando quando mais entrada é aguardada, porque o comando não foi terminado por um ponto-e-vírgula, ou um apóstrofo não foi fechado. O prompt 3 é emitido quando se executa o comando COPY do SQL, e se espera que os valores das linhas sejam digitados no terminal.
O valor da variável de prompt selecionada é exibido literalmente, exceto quando um sinal de percentagem (%) é encontrado. Dependendo do caractere seguinte, certos outros textos são colocados em seu lugar. As substituições definidas são:
Para inserir um sinal de percentagem no prompt deve ser escrito %%. Os prompts padrão são '%/%R%# ' para os prompts 1 e 2, e '>> ' para o prompt 3.
Nota: Esta funcionalidade foi desavergonhadamente plagiada do tcsh.
O psql usa a biblioteca Readline para fornecer uma recuperação e edição de linha conveniente. O histórico dos comandos é armazenado no arquivo chamado .psql_history no diretório home do usuário, sendo recarregado quando o psql inicia. Completar com a tecla de tabulação também é suportado, embora a lógica do ato de completar não pretenda ser a de um analisador SQL. Se por algum motivo não se gostar de completar com tabulação, pode-se desativar especificando isto no arquivo chamado .inputrc no diretório home do usuário:
$if psql set disable-completion on $endif
(Esta não é uma funcionalidade do psql, mas sim do Readline. Leia sua documentação para obter mais detalhes).
testdb=> \foo Field separator is "oo".talvez não seja o esperado.
O primeiro exemplo mostra como distribuir um comando por várias linhas de entrada. Deve ser observada a mudança do prompt:
testdb=> CREATE TABLE minha_tabela ( testdb(> first integer not null default 0, testdb(> second text testdb-> ); CREATE TABLE
Agora veja novamente a definição da tabela:
testdb=> \d minha_tabela Table "minha_tabela" Attribute | Type | Modifier -----------+---------+-------------------- first | integer | not null default 0 second | text |
Agora o prompt será mudado para algo mais interessante:
testdb=> \set PROMPT1 '%n@%m %~%R%# ' peter@localhost testdb=>
Vamos assumir que a tabela já esteja com dados e queremos vê-los:
peter@localhost testdb=> SELECT * FROM minha_tabela; first | second -------+-------- 1 | one 2 | two 3 | three 4 | four (4 linhas)
As tabelas podem ser mostradas de forma diferente usando o comando \pset:
peter@localhost testdb=> \pset border 2 Border style is 2. peter@localhost testdb=> SELECT * FROM minha_tabela; +-------+--------+ | first | second | +-------+--------+ | 1 | one | | 2 | two | | 3 | three | | 4 | four | +-------+--------+ (4 linhas) peter@localhost testdb=> \pset border 0 Border style is 0. peter@localhost testdb=> SELECT * FROM minha_tabela; first second ----- ------ 1 one 2 two 3 three 4 four (4 linhas) peter@localhost testdb=> \pset border 1 Border style is 1. peter@localhost testdb=> \pset format unaligned Output format is unaligned. peter@localhost testdb=> \pset fieldsep "," Field separator is ",". peter@localhost testdb=> \pset tuples_only Showing only tuples. peter@localhost testdb=> SELECT second, first FROM minha_tabela; one,1 two,2 three,3 four,4
Como alternativa, podem ser usados os comandos curtos:
peter@localhost testdb=> \a \t \x Output format is aligned. Tuples only is off. Expanded display is on. peter@localhost testdb=> SELECT * FROM minha_tabela; -[ RECORD 1 ]- first | 1 second | one -[ RECORD 2 ]- first | 2 second | two -[ RECORD 3 ]- first | 3 second | three -[ RECORD 4 ]- first | 4 second | four
Identificadores SQL em meta-comandos do psql. Este exemplo mostra a diferença de sintaxe dos identificadores SQL quando usados em comandos SQL e meta-comandos do psql. Não é possível utilizar foo"BAR"baz em CREATE TABLE, mas é possivel utilizar em \dt. [10]
=> CREATE TABLE "Um nome"" estranho" (foo text); CREATE TABLE => CREATE TABLE foo"BAR"baz (foo text); ERRO: erro de sintaxe em ou próximo de ""BAR"" no caractere 17 => CREATE TABLE "fooBARbaz" (foo text); CREATE TABLE => \dt Lista de relações Esquema | Nome | Tipo | Dono ---------+-------------------+--------+---------- public | Um nome" estranho | tabela | postgres public | fooBARbaz | tabela | postgres (2 linhas) => \dt fooBARbaz Não foi encontrada relação correspondente. => \dt "fooBARbaz" Lista de relações Esquema | Nome | Tipo | Dono ---------+-----------+--------+---------- public | fooBARbaz | tabela | postgres (1 linha) => \dt foo"BAR"baz Lista de relações Esquema | Nome | Tipo | Dono ---------+-----------+--------+---------- public | fooBARbaz | tabela | postgres (1 linha)
[1] |
Veja no Capítulo 46 um exemplo de como personalizar as mensagens mostradas pelo psql. (N. do T.) |
[2] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
[3] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
[4] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
[5] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
[6] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
[7] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
[8] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
[9] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
[10] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |