psql [ opções ] [ nome_bd [ nome_usuário ] ]
O psql é um cliente do PostgreSQL em modo terminal. Permite digitar os comandos interativamente, enviá-los para o PostgreSQL e ver os resultados. Alternativamente, a entrada pode vir de um arquivo. Adicionalmente, possui um certo número de meta-comandos e diversas funcionalidades semelhantes às da shell para facilitar a criação de scripts e automatizar uma grande variedade de tarefas.
O psql é um aplicativo cliente do PostgreSQL comum. Para se conectar a um banco de dados é necessário saber o nome do banco de dados, o nome da máquina e o número da porta do servidor, e o nome de usuário a ser usado para a conexão. O psql pode ser informado sobre estes parâmetros através das opções de linha de comando -d, -h, -p e -U, respectivamente. Se for encontrado um argumento que não pertença 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 for fornecido). Nem todas estas opções são requeridas, os padrões se aplicam. Se for omitido o nome da máquina, então o psql se conecta através do soquete do domínio Unix ao servidor na máquina local. O número padrão para a porta é determinado em tempo de compilação. Desde que o servidor de banco de dados use o mesmo padrão, não será 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. Observe que não é possível se conectar a qualquer banco de dados com qualquer nome de usuário. O administrador de banco de dados informa 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 postmaster não está executando no servidor, etc...), o psql retorna uma mensagem de erro e termina.
No modo normal de operação, o psql disponibiliza um prompt com o nome do banco de dados ao qual está conectado, seguido pela cadeia de caracteres =>. Por exemplo:
$ psql testdb
Welcome to psql, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
testdb=>
No prompt o usuário pode digitar comandos SQL. Normalmente, as linhas de entrada são enviadas para o servidor quando o caractere ponto-e-vírgula, que termina o comando, é encontrado. Um caractere de fim-de-linha não termina um comando! Portanto os comandos podem ocupar várias linhas para clareza. Se o comando for enviado e executado sem erro, o resultado do comando será exibido na tela.
Sempre que um comando é executado, o psql também procura por eventos de notificação assíncronos gerados pelo LISTEN e NOTIFY.
Qualquer coisa entrada no psql que comece por uma contrabarra (\) (não entre apóstrofos, ') é um meta-comando do psql que é processado pelo próprio psql. Estes comandos são o que fazem o psql interessante para a administração ou para a edição de scripts. Os meta-comandos são usualmente chamados de comandos de barra ou de contrabarra.
O formato do comando psql é a contrabarra, seguida imediatamente pelas letras do comando e depois pelos argumentos. Os argumentos são separados das letras do comando, e entre si, por qualquer número de caracteres de espaço.
Para incluir caracteres de espaço em um 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 coisa entre apóstrofos está sujeita às substituições no estilo C para o \n (nova-linha), \t (tabulação), \dígitos, \0dígitos e \0xdígitos (o caractere com o código decimal, octal ou hexadecimal informado).
Se o argumento (não entre apóstrofos) começar por dois-pontos (:), este será considerado como sendo uma variável e o valor desta variável será tomado como o argumento.
Os argumentos entre "crases" (`) são considerados como sendo uma linha de comando a ser passada para a shell. A saída do comando (com o caractere de nova-linha final removido) é tomada como o argumento. As seqüências de escape (\) acima também se aplicam às crases.
Alguns comandos recebem como argumento o nome de um identificador SQL (como o nome de uma tabela). Estes argumentos seguem as regras de sintaxe do SQL com relação às aspas ("): um identificador que não esteja entre aspas é convertido para letras minúsculas. Para todos os outros comandos as aspas não são especiais, se tornando parte do argumento.
A leitura dos argumentos termina quando outra contrabarra (não entre apóstrofos) é encontrada. Esta é considerada como sendo o início de um novo meta-comando. A seqüência especial \\ (duas contrabarras) marca o fim dos argumentos e prossegue analisando os comandos SQL, se existirem. Desta forma, os comandos SQL e psql podem ser livremente misturados em uma linha. Mas, em nenhum caso, os argumentos do meta-comando podem continuar além do fim da linha.
Os seguintes meta-comandos estão definidos:
Se o formato atual de saída da tabela for desalinhado, muda para alinhado. Se não for desalinhado, define como desalinhado. Este comando é mantido para compatibilidade com as versões anteriores. Veja o \pset para uma solução geral.
Muda o diretório de trabalho corrente para nome_do_diretório. Sem argumento, muda para o diretório home do usuário corrente.
Tip: Para ver o diretório de trabalho corrente use \!pwd.
Define o título de qualquer tabela sendo exibida como resultado de uma consulta, ou remove a definição deste título. Este comando é equivalente ao \pset title título (O nome deste comando deriva de "caption" (título), porque anteriormente só era usado para definir o título de uma tabela em HTML).
Estabelece a conexão com um novo banco de dados e/ou sob o mesmo nome de usuário. A conexão anterior é fechada. Se o nome_bd for - (hífen), então o nome do banco de dados corrente é assumido.
Se nome_usuário for omitido, o nome do usuário corrente é assumido.
Como regra especial, \connect sem nenhum argumento conecta ao banco de dados padrão como o usuário padrão (da mesma forma que aconteceria se o psql fosse executado sem argumentos).
Se a tentativa de conexão falhar (nome de usuário errado, acesso negado, etc...), a conexão anterior será mantida se, e somente se, o psql estiver no modo interativo. Ao executar um script não interativo, o processamento será imediatamente interrompido com um erro. Esta distinção foi escolhida por ser mais conveniente para o usuário que digita menos, e para garantir um mecanismo seguro que impeça os scripts atuarem acidentalmente no banco de dados errado.
Executa uma cópia pelo cliente. Esta é uma operação que executa o comando SQL COPY, mas em vez do servidor ler ou escrever no arquivo especificado, e conseqüentemente ser necessário o acesso ao servidor e privilégios especiais de usuário, assim como estar limitado pelo sistema de arquivos acessível ao servidor, o psql lê ou escreve o arquivo e roteia os dados entre o servidor e o sistema de arquivos local.
A sintaxe do comando é semelhante à do comando SQL COPY (Consulte sua descrição para obter detalhes). Observe que, por causa disto, regras especiais de análise se aplicam ao comando \copy. Em particular, as regras de substituição de variável e de escapes de contrabarra não se aplicam.
Tip: Este modo de operação não é tão eficiente quanto o comando SQL COPY, porque todos os dados passam através da conexão IP cliente/servidor ou pelo soquete. Para uma grande quantidade de dados, o outro modo pode ser preferível.
Note: Observe a diferença de interpretação da stdin e da stdout entre as cópias feitas no cliente e no servidor: na cópia no cliente estes se referem sempre à entrada e a saída do psql. Na cópia pelo servidor, a stdin vem do mesmo lugar que o 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).
Mostra os termos da distribuição e dos direitos autorais do PostgreSQL.
Mostra todas as colunas da relação (que pode ser uma tabela, visão, índice ou seqüência), seus tipos e os atributos especiais como NOT NULL ou valor padrão, se houver. Se a relação for de fato uma tabela, todos os índices definidos, chaves primárias, restrições de unicidade e de verificação também são listadas. Se a relação for uma visão, a definição da visão também é mostrada.
A forma do comando \d+ é idêntica, mas todos os comentários associados às colunas da tabela também são mostrados.
Note: Se \d for chamado sem nenhum argumento, torna-se equivalente ao \dtvs mostrando uma lista de todas as tabelas, visões e seqüências. Isto é puramente uma medida de conveniência.
Lista todas as funções de agregação disponíveis, juntamente com os tipos de dado com que operam. Se padrão (uma expressão regular) for especificado, somente as agregações correspondentes serão exibidas.
Mostra a descrição do objeto (que pode ser uma expressão regular), ou de todos os objetos se nenhum argumento for fornecido ("Objeto" compreende agregações, funções, operadores, tipos, relações [tabelas, visões, índices, seqüências, objetos grandes], regras e gatilhos). Por exemplo:
=> \dd version
Object descriptions
Name | What | Description
---------+----------+---------------------------
version | function | PostgreSQL version string
(1 row)
As descrições dos objetos podem ser geradas pelo comando SQL COMMENT ON.
Note: O PostgreSQL armazena a descrição dos objetos na tabela do sistema pg_description.
Lista as funções disponíveis, juntamente com o tipo de dado de seus argumentos e do valor retornado. Se padrão (uma expressão regular) for especificado, somente as funções correspondentes serão mostradas. Se a forma \df+ for usada, informações adicionais sobre cada função, incluindo a linguagem e a descrição, são mostradas.
Este não é o verdadeiro nome do comando: As letras i, s, t, v, S correspondem ao índice, seqüência, tabela, visão e tabela do sistema, respectivamente. Pode-se especificar qualquer um deles, ou todos eles, em qualquer ordem, para obter uma listagem dos mesmos juntamente com a informação sobre quem é o dono.
Se o padrão for especificado, é tomado como uma expressão regular que restringe a listagem aos objetos com nomes correspondentes. Se for apensado o caractere "+" ao nome do comando, cada objeto é listado juntamente com a sua descrição, se houver.
Este é um sinônimo para \lo_list, que mostra a lista dos objetos grandes.
Lista os operadores disponíveis juntamente com o tipo de seus operandos e do valor retornado. Se nome for especificado, somente operadores com este nome serão mostrados.
Este é um sinônimo para \z que foi incluído devido ao seu maior valor mnemônico ("display permissions") (mostra permissões).
Lista todos os tipos de dado, ou somente àqueles que correspondem ao padrão. A forma do comando \dT+ mostra informações extras.
Lista todos os usuários configurados, ou somente àqueles que correspondem ao padrão.
Se o nome_do_arquivo for especificado, o arquivo é editado; após o fim da execução do editor, o conteúdo do arquivo é copiado para o buffer de comando. Se nenhum argumento for fornecido, o buffer de comando corrente é copiado para um arquivo temporário, que é editado de maneira idêntica.
O novo buffer de comando é então analisado novamente de acordo com as regras normais do psql, onde todo o buffer é tratado como sendo uma única linha (Portanto, não podem ser gerados scripts dessa maneira. Use o comando \i para fazer isso). Assim sendo, se o comando terminar por (ou contiver) um ponto-e-vírgula será executado imediatamente, senão apenas permanece aguardando no buffer de comando.
Tip: 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, /bin/vi é usado.
Envia os argumentos para a saída padrão, separados por um espaço e seguido por um caractere de nova-linha, podendo ser útil para intercalar informações na saída dos scripts. Por exemplo:
=> \echo `date` Tue Oct 26 21:40:57 CEST 1999
Se o primeiro argumento for -n (não entre apóstrofos) o caractere de nova-linha final não é gerado.
Tip: Se for usado o comando \o para redirecionar a saída dos comandos, talvez se deseje utilizar \qecho no lugar deste comando.
Define a codificação do cliente, se estiver sendo utilizada a codificação multibyte. Sem argumento, este comando mostra a codificação corrente.
Define o separador de campos para a saída de comando não alinhada. O padrão é a barra vertical (|). Consulte também o \pset para ver uma forma genérica de definir as opções de saída.
Envia o buffer de entrada de comando corrente para o servidor e, opcionalmente, salva a saída em nome_do_arquivo, ou envia a saída para uma outra shell do Unix para executar o comando. Um \g puro e simples é virtualmente igual ao ponto-e-vírgula. Um \g com argumento é uma alternativa "expressa" para o comando \o.
Fornece ajuda para a sintaxe do comando SQL especificado. Se o comando não for especificado, então o psql irá listar todos os comandos para os quais a ajuda de sintaxe está disponível. Se o comando for um asterisco ("*"), então é mostrada a ajuda de sintaxe para todos os comandos SQL.
Note: Para simplificar a digitação, os comandos constituídos por várias palavras não necessitam estar entre apóstrofos. Portanto, pode-se digitar \help alter table.
Ativa o formato HTML de saída da consulta. Se o formato HTML já estiver ativado, retorna ao formato de texto alinhado padrão. Este comando existe por compatibilidade e conveniência, mas veja no \pset outras definições de opções de saída.
Ler a entrada no arquivo nome_do_arquivo, e executar como se tivesse sido digitada pelo teclado.
Note: Se for desejado ver as linhas na tela enquanto estas são lidas deve-se definir a variável ECHO como all.
Lista todos os bancos de dados do servidor, assim como seus donos. Deve-se apensar o caractere "+" ao nome do comando para listar as descrições dos bancos de dados também. Se o PostgreSQL foi compilado com suporte à codificação multibyte, o esquema de codificação de cada banco de dados também é mostrado.
Lê do banco de dados o objeto grande com OID igual a loid, e escreve em nome_do_arquivo. Observe que isto é sutilmente diferente da função do servidor lo_export, que atua com a permissão do usuário como o qual o servidor de banco de dados processa, e no sistema de arquivos do servidor.
Tip: Use \lo_list para descobrir os OIDs dos objetos grandes.
Note: Veja a descrição da variável LO_TRANSACTION para obter informações importantes com relação a todas as operações com objetos grandes.
Armazena o arquivo em um "objeto grande" do PostgreSQL. Opcionalmente, associa o comentário fornecido com o objeto. Exemplo:
foo=> \lo_import '/home/peter/pictures/photo.xcf' 'uma fotografia minha' lo_import 152801
A 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 todos os objetos. Estes podem ser vistos através do comando \lo_list.
Observe 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 e sistema de arquivos do servidor.
Note: Veja a descrição da variável LO_TRANSACTION para obter informações importantes com relação a todas as operações com objetos grandes.
Mostra a lista contendo todos os "objetos grandes" do PostgreSQL armazenados atualmente no banco de dados, juntamente com os comentários fornecidos para os mesmos.
Exclui do banco de dados o objeto grande com o OID igual a loid.
Tip: Use \lo_list para descobrir os OIDs dos objetos grandes.
Note: Veja a descrição da variável LO_TRANSACTION para obter informações importantes com relação a todas as operações com objetos grandes.
Salva os resultados das próximas consultas no arquivo nome_do_arquivo, ou envia os próximos resultados para uma outra shell do Unix para executar o comando. Se nenhum argumento for especificado, a saída da consulta será enviada para stdout.
Os "resultados das consultas" incluem todas as tabelas, respostas dos comandos e as notificações obtidas do servidor de banco de dados, assim como a saída dos vários comandos de contrabarra que consultam o banco de dados (como o \d), mas não as mensagens de erro.
Tip: Para intercalar texto entre os resultados das consultas usa-se \qecho.
Envia o buffer de comando corrente para a saída padrão.
Este comando define opções que afetam a saída das tabelas de resultado das consultas. O parâmetro indica qual opção será definida. A semântica do valor depende do parâmetro.
As opções ajustáveis de exibição são:
Define o formato de saída como unaligned (não alinhado), aligned (alinhado), html ou latex. Abreviações únicas são permitidas (O que equivale a dizer que uma letra basta).
O modo "Unaligned" escreve todos os campos da tupla em uma linha, separados pelo separador de campos ativo no momento. Pretende-se com isso poder criar uma saída que sirva de entrada para outro programa (separada por tabulação, por vírgula, etc...). O modo "Aligned" é a saída de texto padrão, inteligível e agradavelmente formatada. Os modos "HTML" e "LaTeX" produzem tabelas feitas para serem incluídas em documentos usando a linguagem de marcação correspondente. Não são documentos completos! (Isto não é tão problemático no HTML, mas no LaTeX deve haver um invólucro completo do documento).
O segundo argumento deve ser um número. Em geral, quanto maior o número mais bordas e linhas a tabela terá, mas isto depende do formato em particular. No modo HTML será traduzido diretamente para o atributo border=..., nos outros modos somente os valores 0 (sem borda), 1 (linhas divisórias internas) e 2 (moldura da tabela) fazem sentido.
Alterna entre os formatos regular e expandido. Quando o formato expandido é ativado todas as saídas possuem duas colunas, ficando o nome do campo à esquerda e o valor à direita. Este modo é útil quando os dados não cabem na tela no modo normal "horizontal".
O modo expandido é suportado por todos os quatro modos de saída.
O segundo argumento é a cadeia de caracteres a ser impressa sempre que o campo for nulo. O padrão é não imprimir nada, o que pode ser facilmente confundido com, por exemplo, uma cadeia de caracteres vazia. Portanto, pode-se preferir escrever \pset null '(nulo)'.
Especifica o separador de campos a ser utilizado no modo de saída não alinhado. Desta forma pode-se criar, por exemplo, uma saída separada por tabulação, por vírgula ou por um outro caractere, conforme a preferência do programa. Para definir o caractere de tabulação como separador de campo deve-se usar \pset fieldsep '\t'. O separador de campos padrão é o '|' (a barra vertical, ou o símbolo do "pipe").
Alterna a exibição do rodapé padrão (x linhas).
Especifica o separador de registro (linha) a ser usado no modo de saída não alinhado. O padrão é o caractere de nova-linha.
Alterna entre exibir somente as tuplas e exibir tudo. O modo exibir tudo pode mostrar informações adicionais como os cabeçalhos das colunas, títulos e vários rodapés. No modo tuplas-apenas somente os dados da tabela são mostrados.
Define o título para as próximas tabelas a serem impressas. Pode ser usado para colocar textos descritivos na saída. Se nenhum argumento for fornecido, a definição é removida.
Note: Anteriormente só afetava o modo HTML. Atualmente pode ser definido título para qualquer formato de saída.
Permite especificar qualquer atributo a ser colocado dentro do marcador table do HTML. Estes atributos podem ser, por exemplo, cellpadding ou bgcolor. Observe que, provavelmente, não vai se desejar especificar border aqui, porque isto já é tratado pelo \pset border.
Alterna o paginador usado para mostrar a saída da tabela. Se a variável de ambiente PAGER estiver definida, a saída é enviada para o programa especificado, senão o more é utilizado.
De qualquer maneira, o psql somente usa o paginador se julgar adequado, significando que, entre outras coisas, a saída é para um terminal e que a tabela normalmente não caberia na tela. Devido a natureza modular das rotinas de impressão, não é sempre possível predizer o número de linhas que serão realmente impressas. Por esta razão, o psql pode parecer não muito discriminativo sobre quando usar ou não o paginador.
Ilustrações mostrando como parecem estes formatos diferentes podem ser vistas na seção Exemplos.
Tip: Existem vários comandos abreviados para o \pset. Veja \a, \C, \H, \t, \T e \x.
Note: Atualmente é errado chamar o \pset sem argumentos. No futuro, esta chamada deverá mostrar o status corrente de todas as opções de impressão.
Sair do programa psql.
Este comando é idêntico ao \echo, exceto que toda a saída é escrita no canal de saída de consulta, definido pelo \o.
Restaura (limpa) o buffer de comando.
Exibe ou salva o histórico da linha de comando em nome_do_arquivo. Se nome_do_arquivo for omitido, o histórico é enviado para a saída padrão. Esta opção somente estará disponível se o psql estiver configurado para usar a biblioteca de histórico GNU.
Note: Na versão corrente não é mais necessário salvar o histórico dos comandos, porque isto é feito, automaticamente, ao término do programa. O histórico também é carregado, automaticamente, toda vez que o psql inicia.
Define a variável interna nome com o valor ou, se mais de um valor for fornecido, com a concatenação de todos eles. Se o segundo valor não for fornecido, a variável é definida sem valor. Para remover a definição da variável deve-se usar o comando \unset.
Nomes válidos de variáveis podem conter letras, dígitos e sublinhados (_). Veja a seção sobre as variáveis do psql para obter detalhes.
Embora possa ser definida qualquer variável, para fazer qualquer coisa que se deseje, o psql trata diversas variáveis como sendo especiais. Elas estão documentadas na seção sobre variáveis.
Note: Este comando é totalmente distinto do comando SQL SET.
Alterna a exibição do cabeçalho contendo o nome das colunas e do rodapé contendo o número de linhas. Este comando é equivalente ao \pset tuples_only, sendo fornecido por conveniência.
Permite especificar opções a serem colocadas na tag table no modo de saída tabular HTML. Este comando é equivalente ao \pset tableattr opções_de_tabela.
Escreve o buffer de comando corrente no arquivo nome_do_arquivo, ou envia para o comando Unix comando através de um pipe.
Alterna o modo estendido de formato de linha. Sendo assim, é equivalente ao \pset expanded.
Produz uma lista contendo todas as tabelas do banco de dados, juntamente com suas permissões de acesso. Se um argumento for fornecido, este será considerado como sendo uma expressão regular, limitando a lista às tabelas correspondentes.
test=> \z
Access permissions for database "test"
Relation | Access permissions
--------------+-------------------------------------
minha_tabela | {"=r","joe=arwR", "group staff=ar"}
(1 row )Deve ser lido da seguinte maneira:
"=r": PUBLIC possui permissão de leitura (SELECT) na tabela.
"joe=arwR": O usuário joe possui permissão para ler, escrever (UPDATE, DELETE), "apensar" (INSERT), e criar regras na tabela.
"group staff=ar": O grupo staff possui permissão para SELECT e INSERT.
Os comandos GRANT e REVOKE são usados para definir as permissões de acesso.
Abre outra shell do Unix, ou executa o comando Unix comando. Os comandos deixam de ser interpretados e são enviados para a shell como estão.
Obtém informação de ajuda para os comandos de contrabarra ("\").
Caso esteja configurado adequadamente, o psql trata tanto as opções curtas no estilo Unix padrão, quanto as opções longas no estilo GNU. Estas últimas não estão disponíveis em todos os sistemas operacionais.
Exibe todas as linhas na tela ao serem lidas. É mais útil para o processamento de scripts do que no modo interativo. Equivale a definir a variável ECHO como all.
Muda para o modo de saída não alinhado (Senão, o modo de saída padrão será o alinhado).
Especifica que o psql deve executar a cadeia de caracteres comando, e depois terminar. Útil para scripts.
O comando deve ser uma cadeia de caracteres que possa ser integralmente analisada pelo servidor (ou seja, não contém nenhuma funcionalidade específica do psql), ou ser um único comando de contrabarra. Portanto, não podem ser misturados comandos SQL com meta-comandos do psql. Para que isto seja obtido, pode-se enviar a cadeia de caracteres para o psql conforme mostrado a seguir: echo "\x \\ select * from foo;" | psql.
Especifica o nome do banco de dados a se conectar. Equivale a especificar o nome_bd como o primeiro argumento não-opção da linha de comando.
Mostra todos os comandos enviados para o servidor. Equivale a definir a variável ECHO como queries.
Exibe o comando real gerado pelo \d e por outros comandos de contrabarra. Pode ser usado caso se deseje incluir uma funcionalidade similar nos próprios programas. Equivale a definir a variável ECHO_HIDDEN a partir do psql.
Usa o arquivo nome_do_arquivo como origem dos comandos, em vez de ler os comandos interativamente. Após o arquivo ser processado, o psql termina. Sob muitos aspectos equivale ao comando interno \i.
Se o nome_do_arquivo for - (hífen) a entrada padrão é lida.
O uso desta opção é sutilmente diferente de escrever psql < nome_do_arquivo. De uma maneira geral as duas fazem o esperado, mas o uso de -f ativa algumas funcionalidades úteis, como as mensagens de erro contendo o número da linha. Ao se usar esta opção também existe uma pequena chance de reduzir a sobrecarga da inicialização. Por outro lado, utilizando o redirecionamento da entrada (em teoria) garante produzir exatamente a mesma saída que seria produzida se tudo tivesse sido digitado manualmente.
Usa separador como o separador de campos. Equivalente ao \pset fieldsep ou ao \f.
Especifica o nome da máquina onde o servidor está executando. Se o nome iniciar por uma barra (/), é usado como sendo o diretório do soquete do domínio Unix.
Ativa a saída tabular HTML. Equivalente ao \pset format html ou ao comando \H.
Lista todos bancos de dados disponíveis e depois termina. Outras opções que não forem de conexão são ignoradas. Semelhante ao comando interno \list.
Envia a saída de todos os comandos para o arquivo nome_do_arquivo. Equivalente ao comando \o.
Especifica a porta TCP/IP ou, por omissão, o soquete do domínio local Unix, onde o postmaster está aguardando as conexões. Por padrão o valor da variável de ambiente PGPORT ou, se não estiver definida, a porta especificada durante a compilação, usualmente 5432.
Permite especificar opções de impressão no estilo \pset pela linha de comando. Observe que aqui o nome e o valor devem estar separados pelo sinal de igual em vez de espaço. Portanto, para definir o formato de saída como LaTeX, deve-se escrever -P format=latex.
Especifica que o psql deve trabalhar em silêncio. Por padrão, são exibidas mensagens de boas-vindas e diversas outras mensagens informativas. Se esta opção for usada, nada disso acontece. É útil juntamente com a opção -c. Dentro do psql pode-se também definir a variável QUIET para obter o mesmo efeito.
Usa o separador como separador de registros. Equivalente ao comando \pset recordsep.
Executa no modo passo-único, significando que será solicitada uma confirmação antes de cada comando ser enviado para o servidor, com a opção de cancelar a execução. Usado na depuração de scripts.
Executa no modo linha-única, onde o caractere de nova-linha termina o comando, como o ponto-e-vírgula faz.
Note: Este modo é fornecido para àqueles que insistem em usá-lo, mas não se encoraja a sua utilização. Em particular, se forem misturados comandos SQL e meta-comandos na mesma linha, a ordem de execução nem sempre vai ser clara para o usuário inexperiente.
Desativa a impressão dos nomes das colunas e do rodapé com o número de linhas do resultado, etc... É totalmente equivalente ao meta-comando \t.
Permite especificar opções a serem colocadas dentro da tag table do HTML. Veja \pset para obter detalhes.
Faz com que o psql solicite o nome do usuário e a senha antes de se conectar ao banco de dados.
Esta opção está obsoleta, sendo conceitualmente errada (Solicitar um nome de usuário não por padrão e solicitar uma senha porque o servidor requer são duas coisas realmente diferentes). Encoraja-se o uso das opções -U e -W em seu lugar.
Conecta-se as banco de dados como o usuário nome_do_usuário em vez do padrão (É necessário ter permissão para fazê-lo, é claro).
Realiza a atribuição de variável, como o comando interno \set. Observe que é necessário separar o nome e o valor, se houver, por um sinal de igual na linha de comando. Para remover a definição de uma variável omite-se sinal de igual. Para definir uma variável sem um valor, usa-se o sinal de igual mas omite-se o valor. Estas atribuições são realizadas durante um estágio bem no princípio da inicialização, portanto as variáveis reservadas para finalidades internas devem ser sobrescritas mais tarde.
Mostra a versão do psql.
Requer que o psql solicite a senha antes de se conectar ao banco de dados. Esta continuará definida por toda a sessão, mesmo que a conexão ao banco de dados seja mudada com o meta-comando \connect.
Na versão corrente o psql solicita, automaticamente, a senha sempre que o servidor requerer autenticação por senha. Uma vez que atualmente isto se baseia em um hack, o reconhecimento automático pode falhar misteriosamente, e por isso existe esta opção para forçar a solicitação. Se a solicitação da senha não for feita, e se o servidor requerer autenticação por senha, a tentativa de conexão vai falhar.
Ativa o modo formato de linha estendido. Equivalente ao comando \x.
Não lê o arquivo de inicialização ~/.psqlrc.
Mostra a ajuda para os argumentos de linha de comando do psql.
O psql fornece uma funcionalidade de substituição de variáveis similar às dos comandos comuns da shell do Unix. Esta funcionalidade é nova e não muito sofisticada ainda, mas existem planos para expandi-la no futuro. As variáveis são simplesmente um par nome/valor, onde o valor pode ser uma cadeia de caracteres de qualquer comprimento. Para definir uma variável usa-se o meta-comando do psql \set:
testdb=> \set foo bar
define a variável "foo" com o valor "bar". Para usar o conteúdo da variável deve-se preceder o nome por dois-pontos (:), e usá-la como argumento de qualquer comando de contrabarra:
testdb=> \echo :foo bar
Note: Os argumentos do \set estão sujeitos às mesmas regras de substituição de qualquer outro comando. Portanto, pode-se construir 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 maneira de se fazer qualquer coisa útil com estas construções. Por outro lado, \set bar :foo é uma forma perfeitamente válida de se copiar uma variável.
Se \set for chamado sem um segundo argumento, a variável é simplesmente definida, mas não possui valor. Para remover a definição (ou excluir) a variável, usa-se o comando \unset.
Os nomes das variáveis internas do psql podem consistir de letras, números e sublinhados em qualquer ordem e em qualquer número deles. Algumas variáveis regulares possuem tratamento especial pelo psql. Elas indicam certas definições de opções que podem ser mudadas em tempo de execução alterando-se o valor da variável, ou representam algum estado do aplicativo. Embora seja possível usar estas variáveis para qualquer outra finalidade, isto não é recomendado, uma vez que o comportamento do programa pode se tornar muito estranho e 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 no futuro, evite estas variáveis. Abaixo segue a lista de todas as variáveis com tratamento especial.
O nome do banco de dados conectado correntemente. É definida toda vez que se conecta a um banco de dados (inclusive na inicialização), mas a definição pode ser removida.
Se for definida como "all", todas as linhas entradas, ou do script, são escritas na saída padrão antes de serem analisadas ou executadas. Para especificar no início do programa usa-se a chave -a. Se for definido como "queries", o psql exibe todos os comandos antes de enviá-los para o servidor. A opção para isto é -e.
Quando esta variável está definida e um comando de contrabarra consulta o banco de dados, a consulta é mostrada previamente. Desta forma, pode-se estudar o PostgreSQL internamente e fornecer funcionalidades semelhantes nos próprios programas. Se a variável for definida como "noexec", a consulta é apenas exibida sem ser enviada para o servidor para executar.
A codificação multibyte corrente do cliente. Se não estiver configurado para usar caracteres multibyte, esta variável irá conter sempre "SQL_ASCII".
Se esta variável estiver definida como ignorespace, as linhas que começam por espaço não são salvas na lista de histórico. Se estiver definida como ignoredups, as linhas idênticas à linha anterior do histórico não são salvas. O valor ignoreboth combina estas duas opções. Se não estiver definida, ou se estiver definida com um valor diferente destes acima, todas as linhas lidas no modo interativo são salvas na lista de histórico.
Note: Esta funcionalidade foi plagiada do bash.
O número de comandos a serem armazenados no histórico de comandos. O valor padrão é 500.
Note: Esta funcionalidade foi plagiada do bash.
O hospedeiro do servidor de banco de dados ao qual se está conectado. É definida toda vez que se conecta a um banco de dados (inclusive na inicialização), mas a definição não pode ser removida.
Se não estiver definida, o envio de um caractere EOF (usualmente Control-D) para uma sessão interativa do psql termina o aplicativo. Se estiver definida com um valor numérico, este número de caracteres EOF são ignorados antes que o aplicativo termine. Se a variável estiver definida, mas não tiver um valor numérico, o padrão é 10.
Note: Esta funcionalidade foi plagiada do bash.
O valor do último oid afetado, retornado por um comando INSERT ou lo_insert. Esta variável somente é garantida como válida até que o resultado do próximo comando SQL tenha sido mostrado.
Se for usada a interface de objeto grande do PostgreSQL para armazenar os dados que não cabem em uma tupla, todas as operações devem estar contidas em um bloco de transação (Consulte a documentação da interface de objetos grandes para obter mais informações). Como o psql não tem maneira de saber se existe uma transação em andamento quando é chamado um de seus comandos internos (\lo_export, \lo_import, \lo_unlink) este precisa tomar alguma decisão arbitrária. Esta ação pode ser desfazer (roll back) alguma transação que esteja em andamento, efetivar esta transação (commit), ou não fazer nada. Neste último caso deve ser fornecido o bloco BEGIN TRANSACTION/COMMIT, ou o resultado não será previsível (geralmente resultando em que a ação desejada não seja realizada em nenhum caso).
Para escolher o que se deseja fazer deve-se definir esta variável como "rollback", "commit" ou "nothing". O padrão é desfazer (roll back) a transação. Se for desejado carregar apenas um ou poucos objetos está tudo bem. Entretanto, se a intenção for transferir muitos objetos grandes, é aconselhável fornecer um bloco de transação explícito em torno dos comandos.
Por padrão, se um script não-interativo encontrar um erro, como um comando SQL ou um meta-comando mal formado, o processamento continua. Este tem sido o comportamento tradicional do psql, mas algumas vezes não é o desejado. Se esta variável estiver definida, o processamento do script vai terminar imediatamente. Se o script for chamado por outro script este vai terminar da mesma maneira. Se o script externo não foi chamado por uma sessão interativa do psql, mas usando a opção -f, o psql retorna um código de erro 3, para distinguir este caso das condições de erro fatal (código de erro 1).
A porta do servidor de banco de dados que se está conectado. Definida toda vez que se conecta ao banco de dados (inclusive na inicialização), mas a definição pode ser removida.
Especificam como os prompts emitidos pelo psql devem se parecer. Veja "Prompt" abaixo.
Esta variável é equivalente à opção de linha de comando -q. Provavelmente não é muito útil no modo interativo.
Esta variável é definida pela opção de linha de comando -S. Pode ser redefinida ou ter a definição removida em tempo de execução.
Esta variável é equivalente à opção de linha de comando -s.
O usuário do banco de dados que se está conectado. Definida toda vez que se conecta ao banco de dados (inclusive na inicialização), mas a definição pode ser removida.
Uma funcionalidade bastante prática das variáveis do psql é que podem ser substituídas ("interpoladas") dentro de comandos regulares do SQL. A sintaxe para isto é novamente prefixar a variável com dois-pontos (:).
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 apóstrofos.
Uma aplicação comum desta funcionalidade é para fazer referência nos comandos seguintes ao último OID inserido, para construir um cenário de chave estrangeira. Outro uso possível deste mecanismo é copiar o conteúdo de um arquivo para um campo. Primeiro deve-se carregar o arquivo na variável e depois proceder coforme mostrado.
testdb=> \set content '\'' `cat meu_arquivo.txt` '\'' testdb=> INSERT INTO minha_tabela VALUES (:content);
Um problema possível com esta abordagem é que o meu_arquivo.txt pode conter apóstrofos, que devem ser precedidos por uma contrabarra para que não causem erro de sintaxe quando a inserção for processada, o que poderia ser feito através do programa sed:
testdb=> \set content '\'' `sed -e "s/'/\\\\\\'/g" < meu_arquivo.txt` '\''
Observe o número correto de contabarras (6)! Isto pode ser visto desta maneira: Após o psql ter analisado esta linha, vai enviar sed -e "s/'/\\\'/g" < meu_arquivo.txt para a shell. A shell fará suas próprias coisas dentro das aspas e vai executar o sed com os argumentos -e e s/'/\\'/g. Quando o sed fizer a análise vai substituir as duas contrabarras por uma única e então vai fazer a substituição. Talvez em um algum ponto tenha se pensado que é ótimo todos os comandos Unix usarem o mesmo caractere de escape (escape character). Isto tudo ainda ignora o fato de se ter que colocar contrabarra na frente de contrabarra também, porque as constantes de texto do SQL também estão sujeitas a certas interpretações. Neste caso é melhor preparar o arquivo externamente.
Como os dois-pontos podem aparecer nos comandos, a seguinte regra se aplica: Se a variável não está definida, a seqüência de caracteres "dois-pontos+nome" não é mudada. De qualquer maneira pode-se colocar uma contrabarra antes dos dois-pontos para protegê-lo de interpretação (A sintaxe de dois-pontos para variáveis é o padrão SQL para as linguagens embutidas, como o ecpg. A sintaxe de dois-pontos para "array slices" e "transformações de tipo" são extensões do PostgreSQL, daí o conflito).
Os prompts mostrados 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 que é mostrado quando o psql requisita um novo comando. O prompt 2 é mostrado quando mais entrada é aguardada durante a entrada do comando, porque o comando não foi terminado por um ponto-e-vírgula, ou um apóstrofo não foi fechado. O prompt 3 é mostrado quando se executa um comando SQL COPY e espera-se que as tuplas sejam digitadas no terminal.
O valor da respectiva variável de prompt é exibido literalmente, exceto quando um sinal de percentagem ("%") é encontrado. Dependendo do caractere seguinte, certos outros textos são substituídos. As substituições definidas são:
O nome completo do hospedeiro do servidor de banco de dados (com o nome do domínio), ou [local] se a conexão for através de um soquete do domínio Unix, ou ainda [local:/dir/name], se o soquete do domínio Unix não estiver no local padrão da compilação.
O nome do hospedeiro do servidor de banco de dados, truncado após o primeiro ponto, ou [local] se a conexão for através de um soquete do domínio Unix.
O número da porta na qual o servidor de banco de dados está na espera.
O nome do usuário que se está conectado (não o nome do usuário do sistema operacional local).
O nome do banco de dados corrente.
Como %/, mas a saída será "~" (til) se o banco de dados for o banco de dados padrão.
Se o usuário corrente for um superusuário do banco de dados, então "#", senão ">".
No prompt 1 normalmente "=", mas "^" se estiver no modo linha-única e "!" se a sessão estiver desconectada do banco de dados (o que pode acontecer se o \connect falhar). No prompt 2 a seqüência é substituída por "-", "*", apóstrofo, ou aspas, dependendo se psql aguarda mais entrada devido ao comando não ter terminado ainda, porque está dentro de um comentário /* ... */, ou porque está entre apóstrofos ou aspas. No prompt 3 a seqüência não se transforma em nada.
Se dígitos começar por 0x os caracteres restantes são interpretados como dígitos hexadecimais e o caractere com o código correspondente é substituído. Se o primeiro dígitos for 0 os caracteres são interpretados como um número octal e o caractere correspondente é substituído. Senão um número decimal é assumido.
O valor da variável nome do psql. Veja a seção "Variáveis" para obter detalhes.
A saída do comando, similar à substituição de "crase" normal.
Para inserir um sinal de percentagem no prompt deve-se escrever %%. Os prompts padrão são equivalentes a '%/%R%# ' para os prompts 1 e 2, e '>> ' para o prompt 3.
Note: Esta funcionalidade foi plagiada da tcsh.
O psql retorna 0 se terminar normalmente, 1 se ocorrer um 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, e 3 se ocorrer um erro em um script e a variável ON_ERROR_STOP estiver definida.
Antes de começar, o psql tenta ler e executar os comandos do arquivo $HOME/.psqlrc. Este pode ser usado para configurar o cliente ou o servidor conforme se deseje (usando os comandos \set e SET).
O psql suporta as bibliotecas de histórico e de leitura de linha por ser conveniente para a edição e recuperação da linha. O histórico dos comandos é armazenado no arquivo chamado .psql_history no diretório home, sendo recarregado quando o psql inicia. Completação por tabulação também é suportado, embora a lógica da completação não pretenda ser a de um analisador SQL. Quando disponíveis, o psql é construído para usar automaticamente estas funcionalidades. Se por algum motivo não se gostar da completação por tabulação, pode-se desativá-la informando isto no arquivo chamado .inputrc no diretório home:
$if psql set disable-completion on $endif
(Esta não é uma funcionalidade do psql, mas sim do readline. Leia a sua documentação para obter mais detalhes).
Se a biblioteca do readline estiver instalada, mas o psql parecer não usá-la, deve-se ter certeza que o script configure do PostgreSQL pode encontrá-la. O script configure precisa encontrar a biblioteca libreadline.a (ou uma biblioteca compartilhada equivalente) e os arquivos de cabeçalho readline.h e history.h (ou readline/readline.h e readline/history.h) nos diretórios apropriados. Se os arquivos de biblioteca e de cabeçalhos estiverem instalados em um lugar obscuro, este local deve ser informado ao configure como, por exemplo:
$ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib ...
Em seguida é necessáro recompilar o psql (não necessariamente toda a árvore do código).
A biblioteca GNU readline pode ser obtida do projeto GNU no servidor de FTP ftp://ftp.gnu.org.
Note: Esta seção somente mostra uns poucos exemplos específicos para o psql. Se for desejado aprender o SQL ou se tornar familiar com o PostgreSQL, é aconselhada a leitura do tutorial que está incluído na distribuição.
O primeiro exemplo mostra como distribuir um comando por várias linhas de entrada. Observe a mudança do prompt:
testdb=> CREATE TABLE minha_tabela ( testdb(> first integer not null default 0, testdb(> second text testdb-> ); CREATE
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 |
Neste ponto pode-se desejar mudar o prompt 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 rows)
Esta tabela pode ser mostrada de forma diferente usando-se 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 rows)
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 rows)
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,4Alternativamente, 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
Nas versões iniciais o psql permitia o primeiro argumento começar logo após o comando (letra-única). Por motivo de compatibilidade isto ainda é suportado de alguma forma, que não será explicada em detalhes aqui porque é desencorajado. Mas, se forem recebidas mensagens estranhas, tenha isso em mente. Por exemplo:
testdb=> \foo Field separator is "oo",
o que talvez não seja o esperado.
O psql somente trabalha adequadamente com servidores da mesma versão. Isto não significa que outras combinações vão falhar inteiramente, mas problemas sutis, e nem-tão-sutis, podem acontecer.
Pressionar Control-C durante um "copy in" (envio de dados para o servidor) não apresenta o mais ideal dos comportamentos. Se for recebida uma mensagem como "COPY state must be terminated first", simplesmente deve-se refazer a conexão entrando com \c - -.