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.
Envia todas as linhas de entrada para a saída padrão à medida que são lidas. É mais útil para o processamento de scripts do que no modo interativo. Equivale a definir a variável ECHO como all.
Comuta para o modo de saída não alinhado (o modo de saída padrão é o alinhado).
Especifica que o psql deve executar a cadeia de comandos, comando e, em seguida, terminar. Útil em scripts do interpretador de comandos.
O comando deve ser uma cadeia de comandos inteiramente analisável pelo servidor (ou seja, não contém funcionalidades específicas do psql), ou ser um único comando de contrabarra. Portanto, não podem ser misturados comandos SQL com meta-comandos do psql. Para misturar, a cadeia de caracteres pode ser enviada para o psql conforme mostrado a seguir: echo "\x \\ select * from foo;" | psql.
Se a cadeia de comandos contiver vários comandos SQL, os mesmos serão processados em uma única transação, a menos que existam comandos BEGIN/COMMIT explícitos incluídos na cadeia para dividi-los em várias transações. Este comportamento é diferente do que ocorre quando a mesma cadeia é introduzida na entrada padrão do psql.
Especifica o nome do banco de dados a se conectar. Equivale a especificar nome_do_banco_de_dados como o primeiro argumento não-opção na linha de comando.
Copia todos os comandos SQL enviados para o servidor para a saída padrão também. Equivale a definir a variável ECHO como queries.
Exibe os verdadeiros comandos gerados por \d e por outros comandos de contrabarra. Pode ser usado para estudar as operações internas do psql. Equivale a definir a variável ECHO_HIDDEN dentro do psql.
Usa o arquivo nome_do_arquivo como origem dos comandos, em vez de ler os comandos interativamente. Após processar o arquivo, o psql termina. Sob muitos aspectos equivale ao comando interno \i.
Se o nome_do_arquivo for - (hífen), então será lida a entrada padrão.
O uso desta opção é sutilmente diferente de escrever psql < nome_do_arquivo. De uma maneira geral, as duas formas fazem o esperado, mas o uso da opção -f ativa algumas funcionalidades úteis, como mensagens de erro com o número da linha. Ao se usar esta opção existe, também, uma pequena chance de reduzir a sobrecarga de inicialização. Por outro lado, a utilização do redirecionamento da entrada na linha de comando garante, teoricamente, que será produzida exatamente a mesma saída que seria produzida se tudo fosse entrado à mão.
Usa o separador como separador de campos para a saída não alinhada. Equivale aos comandos \pset fieldsep ou \f.
Especifica o nome de hospedeiro da máquina onde o servidor está executando. Se o nome iniciar por barra (/), será utilizado como o diretório do soquete do domínio Unix.
Ativa a saída tabular HTML. Equivale aos comandos \pset format html ou \H.
Mostra todos os bancos de dados disponíveis, e depois termina. As outras opções, fora as de conexão, são ignoradas. Semelhante ao comando interno \list.
Escreve a saída de todos os comandos no arquivo nome_do_arquivo, além do destino normal da saída.
Coloca a saída de todos os comandos no arquivo nome_do_arquivo. Equivale ao comando \o.
Especifica a porta TCP, ou a extensão do arquivo de soquete do domínio Unix local, onde o servidor está atendendo as conexões. O padrão é obter o valor a partir da variável de ambiente PGPORT, se esta estiver definida, senão usar o valor padrão compilado (normalmente 5432).
Permite especificar opções de exibição no estilo do \pset pela linha de comando. Deve ser observado 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 ser escrito -P format=latex.
Especifica que o psql deve trabalhar em silêncio. Por padrão, são exibidas mensagens de boas-vindas e várias outras mensagens informativas. Se esta opção for utilizada nada disso acontecerá. É útil em conjunto com a opção -c. Dentro do psql é possível obter o mesmo efeito definindo a variável QUIET.
Usa o separador como separador de registros para a saída não alinhada. Equivale 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 também. Usado para depurar scripts.
Executa no modo linha-única, onde o caractere de nova-linha termina o comando SQL, como o ponto-e-vírgula faz.
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 linha, a ordem de execução nem sempre será clara para o usuário inexperiente.
Desativa a exibição dos nomes das colunas, rodapés com contadores de linhas do resultado, etc. Equivale ao comando \t.
Permite especificar opções a serem colocadas dentro da marca table do HTML. Para obter detalhes deve ser consultado \pset .
Força o psql solicitar o nome do usuário e a senha antes de conectar ao banco de dados.
Esta opção está em obsolescência, porque é conceitualmente falha (Solicitar um nome de usuário não padrão e solicitar uma senha porque o servidor requer são realmente duas coisas diferentes). Incentiva-se a olhar as opções -U e -W em vez desta.
Conecta ao banco de dados como o usuário nome_do_usuário em vez do usuário padrão (É necessário ter permissão para fazê-lo, é claro).
Realiza atribuição de variável, como o comando interno \set. Deve ser observado que na linha de comando é necessário separar o nome e o valor, se houver, por um sinal de igual. Para remover a definição de uma variável deve ser omitido o sinal de igual. Para apenas definir uma variável, sem um valor, o sinal de igual é usado mas o valor é omitido. Estas atribuições são feitas durante um estágio bem no começo da inicialização e, portanto, as variáveis reservadas para finalidades internas poderão ser sobrescritas posteriormente.
Mostra a versão do psql, e depois termina.
Força o psql solicitar a senha antes de conectar ao banco de dados.
O psql deve solicitar, automaticamente, a senha sempre que o servidor requerer autenticação por senha. Como atualmente a detecção de solicitação de senha não é inteiramente confiável, existe esta opção para obrigar a solicitação da senha. Se a senha não for solicitada, e o servidor requerer autenticação por senha, a tentativa de conexão não será bem-sucedida.
Esta opção continuará definida por toda a sessão, mesmo que se mude a conexão com o banco de dados através do meta-comando \connect.
Ativa o modo formatação de tabela expandido. Equivale ao comando \x.
Não lê o arquivo de inicialização (nem o arquivo global do sistema psqlrc, nem o arquivo do usuário ~/.psqlrc).
Quando o psql executa um script com a opção -f, adicionar esta opção coloca os comandos BEGIN/COMMIT em torno do script para executá-lo como uma única transação. Isto garante que todos os comandos serão bem-sucedidos, ou nenhuma modificação será aplicada.
Se o próprio script utilizar os comandos BEGIN, COMMIT, ou ROLLBACK, esta opção não produzirá os efeitos desejados. Além disso, se o script contiver algum comando que não pode ser executado dentro de um bloco de transação, especificar esta opção fará com que este comando (e, portanto, toda a transação) falhe.
Mostra a ajuda sobre os argumentos de linha de comando do psql, e depois termina.
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 tiver problema e a sessão não for interativa; 3 se ocorrer erro no script e a variável ON_ERROR_STOP estiver definida.
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 conectará através do soquete do domínio Unix ao servidor no hospedeiro local, ou através de TCP/IP ao localhost nas maquinas que não possuem soquete do domínio Unix. O número padrão para a porta é determinado na compilação. Desde que o servidor de banco de dados utilize 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 de 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.
Quando os padrões não estão como o desejado, a digitação pode ser reduzida definindo as variáveis de ambiente PGDATABASE, PGHOST, PGPORT e/ou PGUSER com os valores apropriados (Para as demais variáveis de ambiente deve ser consultada a Seção 29.12). Também é conveniente criar o arquivo ~/.pgpass para evitar ter que digitar regularmente as senhas Para obter informações adicionais deve ser consultada a Seção 29.13 .
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 retornará uma mensagem de erro e terminará.
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 8.2.0, 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 do psql
\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. O 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 do psql é a contrabarra, seguida imediatamente pelo verbo do comando, e depois pelos argumentos. Os argumentos são separados do verbo do 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, devem ser utilizados dois apóstrofos. Qualquer texto entre apóstrofos está sujeito às substituições no estilo C para \n (nova-linha), \t (tabulação), \dígitos (octal) e \xdígitos (hexadecimal).
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 aspa 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.
Estão definidos os seguintes meta-comandos:
Se o formato corrente de saída de tabela for desalinhado, troca para alinhado. Se não for desalinhado, define como desalinhado. Este comando é mantido para compatibilidade com as versões anteriores. Veja em \pset uma solução mais geral.
Muda o diretório de trabalho corrente para diretório. Sem argumento, muda para a pasta base (home) do usuário corrente.
Dica: Para mostrar o diretório de trabalho corrente deve ser utilizado o comando \!pwd.
Define o título de todas as tabelas mostradas como resultado de uma consulta, ou remove a definição deste título. Este comando equivale a \pset title título (O nome deste comando deriva de "caption" (título), porque anteriormente só era usado para definir título em uma tabela HTML).
Estabelece uma nova conexão com o servidor PostgreSQL. Se a nova conexão for bem-sucedida, a conexão anterior será fechada. Se nome_do_banco_de_dados, nome_do_usuário, hospedeiro ou porta for omitido ou especificado como -, será utilizado o valor deste parâmetro na conexão anterior. Se não existir conexão anterior, será utilizado o padrão da libpq para o valor do parâmetro.
Se a tentativa de conexão não for bem-sucedida (nome de usuário errado, acesso negado, etc.), a conexão anterior somente será mantida se o psql estiver no modo interativo. Quando estiver executando um script não interativo, o processamento será interrompido imediatamente com erro. Esta separação foi escolhida por ser mais conveniente para o usuário com relação a erros de digitação, e como um mecanismo de segurança impedindo os scripts atuem acidentalmente no banco de dados errado.
Executa uma cópia pelo cliente. Esta é uma operação que executa o comando COPY do SQL, mas em vez do servidor ler ou escrever no arquivo especificado, o psql lê ou escreve no arquivo e roteia os dados entre o servidor e o sistema de arquivos local. Isto significa que a acessibilidade ao arquivo e os privilégios são do usuário local, e não do servidor, e que não há necessidade de privilégios de superusuário SQL.
A sintaxe deste comando é semelhante à sintaxe do comando COPY do SQL (Consulte sua descrição para obter detalhes). Deve ser observado que, por isso, são aplicadas regras especiais de análise ao comando \copy. Em particular, não se aplicam as regras de substituição de variável e de escape de contrabarra (\).
\copy ... from stdin | to stdout lê/escreve baseado na entrada e saída do comando, respectivamente. Todas as linhas são lidas a partir da mesma fonte que emitiu o comando, continuando até ser encontrado um \., ou o fluxo chegar ao EOF. A saída é enviada para o mesmo local de saída do comando. Para ler/escrever da entrada ou saída padrão do psql, deve ser utilizado pstdin ou pstdout. Esta opção é útil para carregar tabelas com dados contidos dentro do arquivo de script SQL.
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.
O exemplo abaixo, executado no Kubuntu, cria uma tabela e carrega os seus dados a partir de um arquivo de script que contém, no mesmo arquivo, tanto os comandos de definição de dados quanto os dados a serem carregados na tabela. Abaixo está mostrado o arquivo de script: [2]
-- Arquivo: copy.sql \pset null '(nulo)' BEGIN; CREATE TEMPORARY TABLE t1 (c1 integer, c2 text) ON COMMIT DROP; \COPY t1 (c1,c2) FROM stdin WITH DELIMITER '|' 1|'um' 2|\N 3|'três' \. SELECT * FROM t1; COMMIT;
e abaixo está mostrada a execução deste script:
# psql -h Kubuntu -U teste -f copy.sql -o copy.out -q teste # cat copy.out c1 | c2 ----+-------- 1 | 'um' 2 | (nulo) 3 | 'três' (3 linhas)
Mostra os termos da distribuição e dos direitos autorais do PostgreSQL.
Para cada relação (tabela, visão, índice ou seqüência) correspondendo ao padrão, mostra todas as colunas, seus tipos, o espaço de tabelas (se não for o padrão) e os atributos especiais como NOT NULL ou valor padrão, se houver. Os índices, restrições, regras e gatilhos associados também são mostrados, assim como a definição da visão se a relação for uma visão (A "Correspondência com padrão" é definida abaixo).
A forma \d+ do comando é idêntica, exceto por mostrar informações adicionais: são mostrados todos os comentários associados às colunas da tabela, e também a presença de OIDs na tabela.
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.
Lista todas as funções de agregação disponíveis, junto com o tipo de dado com que operam. Se for especificado o padrão, somente serão mostradas as agregações cujos nomes correspondem ao padrão.
Lista todos os espaços de tabela disponíveis. Se for especificado o padrão, somente serão mostrados os espaços de tabela cujos nomes correspondem ao padrão. Se for anexado o caractere + ao nome do comando, cada objeto será listado junto com suas permissões associadas.
Lista todas as conversões entre codificações de conjunto de caracteres disponíveis. Se for especificado o padrão, somente serão mostradas as conversões cujos nomes correspondem ao padrão.
Mostra todas as conversões de tipo (cast) disponíveis.
Mostra a descrição dos objetos cujos nomes correspondem ao padrão, ou todos os objetos visíveis se nenhum argumento for especificado. Nos dois casos somente são listados os objetos que possuem uma descrição ("Objeto" compreende agregações, funções, operadores, tipos, relações [tabelas, visões, índices, seqüências e objetos grandes], regras e gatilhos). Por exemplo:
=> \dd version
Descrição dos Objetos
Esquema | Nome | Objeto | Descrição
------------+---------+--------+---------------------------
pg_catalog | version | função | PostgreSQL version string
(1 linha)
As descrições dos objetos podem ser criadas pelo comando COMMENT do SQL.
Lista todos os domínios disponíveis. Se for especificado o padrão, somente serão mostrados os domínios cujos nomes correspondem ao padrão.
Lista as funções disponíveis, junto com os tipos de dado de seus argumentos e do valor retornado. Se for especificado o padrão, somente serão mostradas as funções cujos nomes correspondem ao padrão. Se for usada a forma \df+, são mostradas informações adicionais sobre cada função, incluindo a linguagem e a descrição.
Nota: Para procurar por funções recebendo argumentos ou retornando valores de um determinado tipo, deve ser utilizada a capacidade de procurar do paginador para rolar através da saída do \df.
Para reduzir a desordem, o \df não mostra as funções com tipo de dado E/S. Isto é implementado ignorando as funções que recebem ou retornam o tipo cstring.
Lista todos os papéis do bancos de dados. Se for especificado o padrão, somente serão mostrados os papéis cujos nomes correspondem ao padrão (Agora este comando é efetivamente o mesmo que \du).
Este não é, na verdade, o nome do comando: As letras i, s, t, v, S correspondem a índice, seqüência, tabela, visão e tabela do sistema, respectivamente. Pode ser especificada qualquer uma ou todas estas letras, em qualquer ordem, para obter a listagem de todos os objetos correspondentes. A letra S restringe a listagem aos objetos do sistema; sem o S, somente são mostrados os objetos que não são do sistema. Se for anexado o caractere + ao nome do comando, cada objeto será listado junto com sua descrição associada, se houver.
Se for especificado o padrão, somente serão mostrados os objetos cujos nomes correspondem ao padrão.
Este é um outro nome para \lo_list, que mostra a lista dos objetos grandes.
Lista todos os esquemas (espaços de nomes) disponíveis. Se for especificado o padrão (uma expressão regular), somente serão mostrados os esquemas cujos nomes correspondem ao padrão. Os esquemas temporários não-locais são suprimidos. Se for anexado o caractere + ao nome do comando, cada objeto será listado junto com sua descrição e permissões associadas, se houver.
Lista os operadores disponíveis junto com os tipos de seus operandos e do valor retornado. Se for especificado o padrão, somente serão mostrados os operadores cujos nomes correspondem ao padrão.
Produz uma lista contendo todas as tabelas, visões e seqüências disponíveis, junto com seus privilégios de acesso associados. Se for especificado o padrão, somente serão mostradas as tabelas, visões e seqüências cujos nomes correspondem ao padrão.
Os comandos GRANT e REVOKE são utilizados para definir os privilégios de acesso.
Mostra todos os tipos de dado, ou somente aqueles que correspondem ao padrão. A forma do comando \dT+ mostra informações adicionais.
Lista todos os papéis do banco de dados, ou somente aqueles que correspondem ao padrão.
Se for especificado o nome_do_arquivo, o arquivo é editado; após o fim da edição (fechar o editor), o conteúdo do arquivo é copiado para o buffer de comando. Se não for fornecido nenhum argumento, o buffer de comando corrente será copiado para um arquivo temporário, e editado de forma 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 forma). Significa também que, se o comando terminar por (ou contiver) um ponto-e-vírgula, será executado imediatamente. Se não contiver, apenas permanecerá aguardando no buffer de comando.
Dica: O psql procura nas variáveis de ambiente PSQL_EDITOR, EDITOR e VISUAL (nesta ordem) o editor a ser usado. Se nenhuma destas variáveis estiver definida, então será utilizado o vi nos sistemas Unix, ou o notepad.exe no Windows.
Envia os argumentos para a saída padrão, separados por um espaço e seguido por um caractere de nova-linha, o que pode ser útil para colocar informações na saída dos scripts. Por exemplo: [3]
=> \echo `date` - `hostname` Qua Mar 14 18:20:32 BRT 2007 - halleypo
Se o primeiro argumento for -n (não entre apóstrofos), não será escrito o caractere de nova-linha no final da linha.
Dica: Se for utilizado o comando \o para redirecionar a saída do comando, talvez seja preferível utilizar \qecho em vez deste comando.
Define a codificação do conjunto de caracteres do cliente. Sem argumento, este comando mostra a codificação corrente. Por exemplo: [4]
=> \encoding LATIN1
Define o separador de campos para a saída de comando não alinhada. O padrão é a barra vertical (|). Veja também em \pset uma forma genérica para definir as opções de saída.
Envia o buffer de entrada de comando corrente para o servidor e, opcionalmente, armazena a saída do comando no nome_do_arquivo, ou redireciona a saída para outro interpretador de comandos do Unix executando o comando. Um \g puro e simples é virtualmente equivalente ao ponto-e-vírgula. Um \g com argumento é uma alternativa "de uma única vez" para o comando \o.
O exemplo abaixo coloca a saída do comando SELECT na janela de edição do editor gvim: [5]
=> SELECT datname FROM pg_database \g | gvim - => Vim: Reading from stdin...
Fornece ajuda de sintaxe para o comando SQL especificado. Senão for especificado o comando, então o psql listará todos os comandos para os quais existe ajuda de sintaxe disponível. Se o comando for um asterisco ("*"), então será mostrada a ajuda de sintaxe para todos os comandos SQL.
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.
Ativa o formato HTML para saída de comando. Se o formato HTML já estiver ativado, retornará ao formato de texto alinhado padrão. Este comando existe por compatibilidade e comodidade, mas devem ser vistas em \pset as definições das outras opções de saída.
Lê a entrada no arquivo nome_do_arquivo, e executa como se tivesse sido digitada pelo teclado.
Nota: Se for desejado ver as linhas na tela à medida que são lidas, deve ser definida a variável ECHO como all.
Lista o nome, dono e codificação do conjunto de caracteres de todos os bancos de dados do servidor. Se for adicionado o caractere + ao nome do comando, também serão mostradas todas as descrições dos bancos de dados.
Lê no banco de dados o objeto grande com OID igual a loid, e escreve em nome_do_arquivo. Deve ser observado 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 está executando, e no sistema de arquivos do servidor.
Dica: Deve ser utilizado \lo_list para descobrir os OIDs dos objetos grandes.
Armazena o arquivo em um objeto grande do PostgreSQL. Opcionalmente, associa o comentário fornecido ao objeto. Exemplo:
foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' 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 cada objeto, que 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.
Mostra a lista de todos os objetos grandes do PostgreSQL armazenados neste instante no banco de dados, junto com os comentários fornecidos para os mesmos.
Remove do banco de dados o objeto grande com o OID igual a loid.
Dica: Deve ser utilizado \lo_list para descobrir os OIDs dos objetos grandes.
Salva os resultados dos próximos comandos no arquivo nome_do_arquivo, ou redireciona os próximos resultados para um interpretador de comandos do Unix em separado para executar o comando. Se não for especificado nenhum argumento, a saída do comando será redefinida para a saída padrão.
Os "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.
O exemplo abaixo coloca a saída dos comandos SELECT e \qecho na janela de edição do editor gvim: [6]
=> \o | gvim - => Vim: Reading from stdin... => \qecho Bancos de Dados => SELECT datname FROM pg_database; => \qecho Linguagens => SELECT lanname FROM pg_language; => \o
Envia o buffer de comando corrente para a saída padrão.
Muda a senha do usuário especificado (por padrão, o usuário corrente). Este comando solicita a nova senha, criptografa a mesma, e envia para o servidor como um comando ALTER ROLE. Isto faz com que a nova senha não apareça em texto limpo no histórico de comandos, no registro do servidor, ou em qualquer outro lugar.
Este comando define opções que afetam a saída das tabelas de resultado das consultas. O parâmetro descreve qual opção será definida. A semântica do valor depende do parâmetro.
As opções de exibição ajustáveis são:
Define o formato de saída como unaligned (não alinhado), aligned (alinhado), html, latex ou troff-ms. São permitidas abreviações únicas (O que significa que basta uma letra).
O modo "unaligned" escreve todas as colunas de uma linha em uma única linha, separadas pelo separador de campos ativo corrente. Pretende-se com isso criar uma saída que sirva de entrada para outros programas (separada por tabulação, vírgula, etc.). O modo "aligned" é a saída de texto formatada adequadamente, humanamente inteligível, padrão. Os modos "HTML" e "LaTeX" produzem tabelas feitas para serem incluídas em documentos que utilizam 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. No modo HTML será traduzido diretamente para o atributo border=..., nos demais modos só fazem sentido os valores: 0 (sem borda); 1 (linhas divisórias internas); e 2 (moldura da tabela).
Alterna entre os formatos regular e expandido. Quando o formato expandido está ativado, todos os resultados das consultas são mostrados em duas colunas, com o nome da coluna à esquerda e o dado à direita. Este modo é útil quando os dados não cabem na tela no modo normal "horizontal".
O modo expandido é suportado por todos os quatro formatos de saída.
O segundo argumento é a cadeia de caracteres a ser mostrada sempre que a coluna for nula. O padrão é não mostrar nada, 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 ser criada, por exemplo, uma saída separada por tabulação ou por vírgula, que outros programas podem preferir. Para definir o caractere de tabulação como separador de campos deve ser usado \pset fieldsep '\t'. O separador de campos padrão é '|' (a barra vertical).
Alterna a exibição do rodapé padrão (x linhas).
Alterna a exibição do caractere sensível ao idioma para separar grupos de dígitos à esquerda do marcador de decimais. Também ativa o marcador de decimal sensível ao idioma.
Especifica o separador de registro (linha) a ser utilizado no modo de saída não alinhado. O padrão é o caractere de nova-linha.
Alterna entre mostrar somente as tuplas e mostrar tudo. O modo mostrar tudo pode mostrar informações adicionais como os cabeçalhos das colunas, títulos e vários rodapés. No modo somente-tuplas são mostrados apenas os dados da tabela.
Define o título da tabela para as próximas tabelas mostradas. Pode ser usado para colocar marcas descritivas na saída. Se não for fornecido nenhum argumento, o título será removido.
Permite especificar qualquer atributo a ser colocado dentro da marca 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 comando \pset border.
Controla o uso do paginador para os comandos e para a saída da ajuda do psql. Se a variável de ambiente PAGER estiver definida, a saída será direcionada para o programa especificado, senão será utilizado o padrão dependente da plataforma (como o more).
Se o paginador estiver desativado, não será feita a paginação. Se o paginador estiver ativado, a paginação será feita somente quando for apropriado, ou seja, quando a saída for para um terminal e não couber na tela (O psql não realiza um trabalho perfeito ao avaliar quando o paginador deve ser utilizado). \pset pager ativa e desativa o paginador. O paginador também pode ser definido como always, que faz o paginador ser utilizado sempre.
Podem ser vistas na seção Exemplos ilustrações mostrando como estes formatos diferentes se parecem.
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.
Terminar o programa psql.
Este comando é idêntico a \echo, exceto que toda a saída é escrita no canal de saída de comando, conforme definido por \o.
Redefine (limpa) o buffer de comando.
Mostra ou salva o histórico da linha de comando em nome_do_arquivo. Se o nome_do_arquivo for omitido, o histórico será escrito na saída padrão. Esta opção somente está disponível quando o psql está configurado para usar a biblioteca Readline do GNU.
Define a variável interna nome com o valor ou, se for fornecido mais de um valor, com a concatenação de todos os valores. Se o segundo argumento não for fornecido, a variável somente será definida, sem nenhum valor. Para remover a definição da variável deve ser utilizado o comando \unset.
Os nomes de variáveis válidos podem conter letras, dígitos e sublinhados (_). Para obter detalhes deve ser consultada a seção Variáveis abaixo. Os nomes das variáveis diferenciam letras minúsculas de maiúsculas.
Embora possa ser definida qualquer variável como qualquer nome desejado, o psql trata várias variáveis como sendo especiais, conforme documentado na seção sobre variáveis.
Nota: Este comando é totalmente distinto do comando SET do SQL.
Alterna a exibição do cabeçalho contendo o nome das colunas e do rodapé contendo o número de linhas. Este comando equivale a \pset tuples_only, sendo fornecido apenas por conveniência.
Permite especificar atributos a serem colocados na marca table no modo de saída tabular HTML. Este comando equivale a \pset tableattr opções_de_tabela.
Alterna a exibição de quanto tempo cada comando SQL demora em milissegundos.
Escreve o buffer de comando corrente no arquivo nome_do_arquivo, ou envia para o comando Unix comando através de um pipe.
O exemplo abaixo utiliza o comando \w para enviar o buffer de comando corrente para a janela de edição do gvim: [7]
=> \w | gvim - Vim: Reading from stdin...
Alterna o modo de formatação de tabela estendido. Como tal equivale ao comando \pset expanded.
Produz uma lista contendo todas as tabelas, visões e seqüências disponíveis, junto com seus privilégios de acesso associados. Se o padrão for especificado, somente serão mostradas as tabelas, visões e seqüências cujos nomes correspondem ao padrão.
São utilizados os comandos GRANT e REVOKE para definir os privilégios de acesso.
Este comando é um outro nome para o comando \dp ("display privileges").
Abre um interpretador de comandos do Unix em separado, se o argumento for omitido, ou executa o comando do Unix comando. Os argumentos não são mais interpretados, sendo enviados para o interpretador de comandos como estão.
O exemplo abaixo utiliza o meta-comando \! para executar dois comandos do sistema operacional Unix: [8]
=> \!date Dom Fev 20 08:04:41 BRT 2005 => \!pwd /home/halley
Mostra informação de ajuda para os comandos de contrabarra ("\").
Os vários comandos \d aceitam como parâmetro um padrão para especificar os nomes dos objetos a serem mostrados. No caso mais simples, o padrão é apenas o nome do objeto. As letras dentro do padrão normalmente são convertidas para minúsculas, como nos nomes SQL; por exemplo, \dt FOO mostra a tabela chamada foo. Como nos nomes SQL, colocar aspas em torno do padrão impede a conversão em minúsculas. Se for necessário escrever o caractere aspa no padrão, o mesmo deverá ser escrito como um par de aspas dentro de uma seqüência entre aspas; novamente isto está de acordo com as regras do SQL para identificadores entre aspas. Por exemplo, \dt "FOO""BAR" mostra a tabela chamada FOO"BAR (não foo"bar). Diferentemente das regras normais para os nomes SQL, pode ser colocado um par de aspas em torno de apenas uma parte do padrão, por exemplo \dt FOO"FOO"BAR irá mostrar a tabela chamada fooFOObar.
Dentro do padrão, o caractere * corresponde a qualquer seqüência de caracteres (inclusive nenhum caractere), e o caractere ? corresponde a qualquer um único caractere (Esta notação é semelhante a do padrão para nomes de arquivos do interpretador de comandos do Unix). Por exemplo, \dt int* mostra todas as tabelas cujos nomes começam por int. Porém, entre aspas os caracteres * e ? perdem seus significados especiais sendo apenas correspondidos literalmente.
Um padrão contendo um ponto é 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 corresponderá apenas aos objetos visíveis no caminho de procura de esquemas corrente. Novamente, entre aspas o ponto perde seu significado especial sendo correspondido literalmente. Por exemplo: [9]
=> \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.
Os usuários avançados podem utilizar as notações de expressão regular como classes de caracteres como, por exemplo, [0-9] para corresponder a qualquer dígito. Todos os caracteres especiais de expressão regular funcionam conforme especificado na Seção 9.7.3, com exceção do . que é considerado como o separador mencionado acima, o * que é traduzido na notação de expressão regular .*, e o ? que é traduzido como .. Estes caracteres do padrão podem ser emulados, se for necessário, escrevendo ? no lugar do ., (R+|) no lugar de R*, ou (R|) no lugar de R?. Lembre-se que o padrão deve corresponder ao nome completo, diferentemente da interpretação usual das expressões regulares; deve ser escrito * no início e/ou no fim se não for desejado que o padrão fique ancorado. Deve ser observado que entre as aspas todos os caracteres especiais da expressão regular perdem seu significado especial e são correspondidos literalmente. Além disso, os caracteres especiais da expressão regular são correspondidos literalmente nos padrões de nome de operador (ou seja, o argumento do comando \do).
Sempre que o parâmetro padrão for inteiramente omitido, os comandos \d mostrarão todos os objetos visíveis no caminho de procura de esquemas corrente — é equivalente a utilizar o padrão *. Para mostrar todos os objetos do banco de dados, deve ser utilizado 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 comando \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 'alguma_coisa' 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 o comando \set for chamado sem o segundo argumento, a variável será 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, por indicarem certas definições de opção que podem ser mudadas em tempo de execução alterando o valor da variável, ou por representarem algum estado do aplicativo. 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 suas letras em maiúsculas (e possivelmente números e sublinhados). Para garantir a máxima compatibilidade futura, deve-se evitar usar estes nomes de variáveis para finalidades particulares. A seguir estão todas as variáveis com tratamento especial.
Quando está on (o padrão), cada comando SQL é automaticamente efetivado ao terminar bem-sucedido. Neste modo, para adiar a efetivação deve ser emitido o comando SQL BEGIN ou START TRANSACTION. Quando está off, ou não definido, os comandos SQL não são efetivados até ser emitido explicitamente o comando COMMIT ou END. O modo "autocommit-off" opera emitindo um comando BEGIN, implícito, logo antes de qualquer comando que não esteja dentro de um bloco de transação, e não seja o próprio BEGIN ou outro comando de controle de transação, nem um comando que não possa ser executado dentro de uma transação, (como o VACUUM).
Nota: No modo "autocommit-off" toda transação que não for bem-sucedida deve ser explicitamente abandonada submetendo ABORT ou ROLLBACK. Também deve-se ter em mente que, se a sessão for finalizada 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 global do sistema psqlrc, ou no arquivo do usuário ~/.psqlrc.
O exemplo abaixo mostra o valor da variável AUTOCOMMIT: [10]
=> \echo :AUTOCOMMIT on
O nome do banco de dados que se está conectado no momento. Definida toda vez que é feita a conexão com um banco de dados (inclusive na inicialização do programa), mas a definição pode ser removida.
O exemplo abaixo mostra o valor da variável DBNAME: [11]
=> \echo :DBNAME template1
Se for definida como "all" todas as linhas entradas pelo teclado, ou do script, serão escritas na saída padrão antes de serem analisadas ou executadas. Para selecionar este comportamento na inicialização do programa, deve ser usada a chave -a. Se for definida como "queries", o psql simplesmente mostrará todos os comandos à medida que forem enviados para o servidor. A chave para isto é -e.
Quando esta variável está definida, e um comando de contrabarra consulta o banco de dados, primeiro a consulta é mostrada. Por este meio pode-se estudar a parte interna do PostgreSQL e oferecer funcionalidades semelhantes nos próprios programas (Para selecionar este comportamento na inicialização do programa, deve ser usada a chave -E). Se esta variável for definida com o valor "noexec" os comandos serão apenas mostrados, não sendo enviados para o servidor para serem executados.
O exemplo abaixo define a variável ECHO_HIDDEN e executa o meta-comando \dn: [12]
=> \set ECHO_HIDDEN
=> \dn
******** CONSULTA ********
SELECT n.nspname AS "Nome",
r.rolname AS "Dono"
FROM pg_catalog.pg_namespace n JOIN pg_catalog.pg_roles r
ON n.nspowner=r.oid
WHERE (n.nspname !~ '^pg_temp_' OR
n.nspname = (pg_catalog.current_schemas(true))[1])
ORDER BY 1;
**************************
Lista de esquemas
Nome | Dono
--------------------+----------
information_schema | postgres
pg_catalog | postgres
pg_toast | postgres
public | postgres
(4 linhas)
A codificação corrente do conjunto de caracteres do cliente.
O exemplo abaixo mostra o valor da variável ENCODING: [13]
=> \echo :ENCODING LATIN1
Se esta variável estiver definida com um valor inteiro > 0, os resultados das consultas SELECT serão trazidos e mostrados em grupos com esta quantidade de linhas, em vez do comportamento padrão de trazer todo o conjunto de resultados antes de mostrá-lo. Portanto, só é utilizada uma quantidade limitada de memória, independentemente do tamanho do conjunto de resultados. Normalmente são utilizados valores de 100 a 1000 quando esta funcionalidade é ativada. Deve-se ter em mente que ao utilizar esta funcionalidade a consulta poderá falhar após terem sido exibidas algumas linhas.
Dica: Embora possa ser utilizado qualquer formato de saída com esta funcionalidade, o formato padrão alinhado tende a não ter uma boa aparência porque cada grupo de FETCH_COUNT linhas é formatado separadamente, ocasionando larguras de colunas diferentes entre os grupos de linhas. O formato não alinhado tem uma aparência melhor.
Se esta variável estiver definida como "ignorespace", as linhas começando por espaço não serão guardadas na lista de histórico. Se estiver definida como "ignoredups", as linhas idênticas à linha anterior do histórico não serão guardadas. O valor "ignoreboth" combina estas duas opções. Se esta variável não estiver definida, ou se estiver definida com um valor diferente dos acima, todas as linhas lidas no modo interativo serão guardadas na lista de histórico.
Nota: Esta funcionalidade foi desavergonhadamente plagiada do Bash.
O nome do arquivo a ser utilizado para armazenar a lista de histórico. O valor padrão é ~/.psql_history. Por exemplo, colocar
\set HISTFILE ~/.psql_history- :DBNAME
no arquivo ~/.psqlrc faz com que o psql mantenha um histórico separado para cada banco de dados.
Nota: Esta funcionalidade foi desavergonhadamente plagiada do Bash.
O número de comandos a serem guardados no histórico de comandos. O valor padrão é 500.
Nota: Esta funcionalidade foi desavergonhadamente plagiada do Bash.
O hospedeiro do servidor de banco de dados ao qual se está conectado. Esta variável é definida toda vez que é feita a conexão com um banco de dados (inclusive na inicialização do programa), mas a definição pode ser removida.
Se esta variável não estiver definida, o envio do caractere EOF (geralmente Control+ D) para uma sessão interativa do psql terminará o aplicativo. Se estiver definida com um valor numérico, será ignorada esta quantidade de caracteres EOF antes do aplicativo terminar. Se a variável estiver definida, mas não tiver um valor numérico, o padrão é 10.
Nota: Esta funcionalidade foi desavergonhadamente plagiada do Bash.
O valor do último OID afetado, conforme retornado por um comando INSERT ou lo_insert. Somente há garantia do valor desta variável ser válido até ser mostrado o resultado do próximo comando SQL.
Quando o valor desta variável for "on", se um comando em um bloco de transação gerar um erro, este erro será ignorado e a transação prosseguirá. Quando o valor for "interactive", os erros somente serão ignorados nas sessões interativas, e não ao ler de um arquivo de script. Quando o valor for "off" (o padrão), o comando do bloco de transação que gerar um erro vai interromper toda a transação. O modo on_error_rollback-on trabalha emitindo um comando SAVEPOINT implícito logo antes de cada comando do bloco de transação, e desfaz até o ponto de salvamento em caso de erro.
Por padrão, se um script não-interativo encontrar algum erro, como um comando SQL ou um meta-comando interno mal formado, o processamento continuará. 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 terminará imediatamente. Se o script tiver sido chamado por outro script este terminará da mesma maneira. Se o script mais externo não foi chamado a partir de uma sessão interativa do psql, mas usando a opção -f, o psql retornará o 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. Esta variável é definida toda vez que é feita a conexão com um banco de dados (inclusive na inicialização do programa), mas a definição pode ser removida.
Especificam como os prompts emitidos pelo psql devem se parecer. Consulte Prompt abaixo.
Esta variável equivale à opção de linha de comando -q. Provavelmente não tem muita utilidade no modo interativo.
Esta variável equivale à opção de linha de comando -S.
Esta variável equivale à opção de linha de comando -s.
O usuário do banco de dados como o qual se está conectado. Esta variável é definida toda vez que é feita a conexão com um banco de dados (inclusive na inicialização do programa), mas a definição pode ser removida.
Esta variável pode ser definida com os valores default, verbose ou terse (sucinto), para controlar a verbosidade dos relatórios de erro.
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. Não é realizada a interpolação de variáveis dentro de entidades SQL entre aspas ou apóstrofos. Por exemplo: [14]
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=10;
usename
----------
postgres
(1 linha)
testdb=> SELECT usename FROM ':tabela' WHERE usesysid=10;
ERRO: erro de sintaxe em ou próximo de "':tabela'"
LINHA 1: SELECT usename FROM ':tabela' WHERE usesysid=1;
^
testdb=> SELECT usename FROM ":tabela" WHERE usesysid=10;
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 acima.
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 receber escape 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` ''''
Se estiverem sendo utilizadas cadeias de caracteres que não estão em conformidade com o padrão, então também será necessário dobrar as contrabarras. Isto é um pouco ardiloso:
testdb=> \set conteudo '''' `sed -e "s/'/''/g" -e 's/\\/\\\\/g' < meu_arquivo.txt` ''''
Deve ser observada a utilização de convenções diferentes para a delimitação no interpretador de comandos, para que nem os apóstrofos nem as contrabarras sejam especiais para o interpretador de comandos. Entretanto, as contrabarras ainda são especiais para o sed sendo, portanto, necessário duplicá-las (Talvez em algum ponto tenha se pensado que era ótimo todos os comandos do Unix utilizarem o mesmo caractere de escape).
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. De qualquer maneira, sempre pode ser feito o escape dos dois-pontos com uma contrabarra para protegê-lo da substituição (A sintaxe com dois-pontos para as variáveis é padrão SQL para linguagens de comandos incorporadas, 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 se espera mais entrada, porque o comando não foi terminado por um ponto-e-vírgula, ou um apóstrofo ou aspa 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 é encontrado um sinal de percentagem (%). Dependendo do caractere seguinte, certos outros textos são colocados em seu lugar. 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 [local:/dir/nome], 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 no primeiro ponto, ou [local] se a conexão for através de um soquete do domínio Unix.
O número da porta onde o servidor de banco de dados está atendendo.
O nome do usuário da sessão de banco de dados (A expansão deste valor pode mudar durante a sessão de banco de dados como resultado do comando SET SESSION AUTHORIZATION).
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 da sessão for um superusuário do banco de dados então #, senão > (A expansão deste valor pode mudar durante a sessão de banco de dados como resultado do comando SET SESSION AUTHORIZATION)
No prompt 1 normalmente "=", mas "^" se estiver no modo de linha-única, e "!" se a sessão estiver desconectada do banco de dados (o que pode acontecer se \connect não for bem-sucedido). No prompt 2 a seqüência é substituída por "-", "*", apóstrofo, aspas ou "$", dependendo se o psql está aguardando mais entrada devido ao comando não ter terminado ainda, porque está dentro de um comentário /* ... */, ou porque está dentro de uma cadeia de caracteres envolta por apóstrofos, aspas ou cifrão. No prompt 3 a seqüência não se transforma em nada.
Status da transação: uma cadeia de caracteres vazia quando não estiver dentro de um bloco de transação, ou * quando estiver dentro de um bloco de transação, ou ! quando estiver em um bloco de transação que falhou, ou ? quando o estado da transação for indeterminado (por exemplo, porque não há conexão).
O caractere com o código numérico indicado é substituído.
O valor da variável do psql nome. Para obter detalhes deve ser consultada a seção Variáveis.
A saída do comando, semelhante à substituição de "crase" normal.
Os prompts podem conter caracteres de controle do terminal os quais, por exemplo, mudam a cor da letra e do fundo e o estilo do texto do prompt, ou o título da janela do terminal. Para que as funcionalidades de edição de linha do Readline funcionem de forma apropriada, estes caracteres de controle não imprimíveis devem ser projetados como sendo invisíveis envolvendo-os por %[ e %]. Podem existir vários pares iguais a este dentro do prompt. Por exemplo,
testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '
resulta em um prompt negrito (1;) amarelo-sobre-preto (33;40) em um terminal colorido compatível com o VT100.
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 de comando é salvo automaticamente quando o psql termina, e é recarregado quando o psql inicia. Completar com a tecla de tabulação também é suportado, embora a lógica da funcionalidade 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 esta funcionalidade 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).
Se o resultado do comando não couber na tela, então será mostrado por meio deste comando. Os valores típicos são more e less. O padrão depende da plataforma. O uso do paginador pode ser desativado por meio do comando \pset.
Banco de dados padrão para conectar.
Parâmetros de conexão padrão.
Editor utilizado pelo comando \e. As variáveis são examinadas na ordem listada; a primeira que estiver definida será utilizada.
Comando executado pelo meta-comando \!.
Diretório para armazenar os arquivos temporários. O padrão é /tmp.
Como o psql utiliza a biblioteca libpq internamente, todas as variáveis de ambiente utilizadas pela libpq também são válidas no psql. Para ver a lista completa destas variáveis deve ser consultada a Seção 29.12.
Antes de iniciar, o psql tenta ler e executar os comandos do arquivo global do sistema psqlrc, e o arquivo do usuário ~/.psqlrc (No Windows, o arquivo de inicialização do usuário chama-se %APPDATA%\postgresql\psqlrc.conf). Veja em PREFIXO/share/psqlrc.sample as informações sobre como definir o arquivo global do sistema. Pode ser usado para configurar o cliente ou o servidor conforme se deseje (usando os comandos \set e SET).
Tanto o arquivo global do sistema, psqlrc, quanto o arquivo do usuário, ~/.psqlrc, podem ser tornados específicos para uma versão anexando um hífen e o número da versão do PostgreSQL como, por exemplo, ~/.psqlrc-8.2.0. O arquivo correspondendo à versão específica terá preferência sobre o arquivo que não é específico da versão.
O histórico de linha de comando é armazenado no arquivo ~/.psql_history, ou no arquivo %APPDATA%\postgresql\psql_history no Windows.
Nas versões iniciais, o psql permitia o primeiro argumento de um comando de contrabarra de uma única letra começar logo após o comando, sem o espaço separador. Por motivo de compatibilidade isto ainda é suportado de alguma forma, que não será explicado em detalhes porque seu uso é desencorajado, mas se forem recebidas mensagens estranhas tenha isso em mente. Por exemplo
testdb=> \foo O separador de campos é "oo".
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 imediatamente, mas podem acontecer problemas sutis, e nem tão sutis. Os comandos de contrabarra são os mais propensos a não serem bem-sucedidos se o servidor for de uma versão diferente.
O psql é construído como um "aplicativo console". Como as janelas de console do Windows utilizam uma página de código diferente do restante do sistema, deve-se tomar um cuidado especial quando são utilizados caracteres de 8 bits no psql. Se o psql detectar uma página de código da console problemática, emitirá uma advertência na inicialização. Para mudar a página de código da console são necessárias duas coisas:
Definir a página de código executando cmd.exe /c chcp 1252 ( 1252 é a página de código apropriada para o Português do Brasil; se for necessário deve ser utilizado outro código de página). Se estiver sendo utilizado o Cygwin, este comando poderá ser colocado em /etc/profile.
Definir a fonte da console como "Lucida Console", porque a fonte mapa de bits (raster) não trabalha com páginas de código ANSI.
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(> primeiro INTEGER NOT NULL DEFAULT 0, testdb(> segundo TEXT) testdb-> ; CREATE TABLE
Abaixo está mostrada a definição da tabela:
testdb=> \d minha_tabela
Tabela "public.minha_tabela"
Coluna | Tipo | Modificadores
----------+---------+--------------------
primeiro | integer | not null default 0
segundo | text |
Agora o prompt será mudado para algo mais interessante:
testdb=> \set PROMPT1 '%n@%m %~%R%# ' peter@localhost testdb=>
Assumindo que a tabela já esteja com dados e queremos vê-los:
peter@localhost testdb=> SELECT * FROM minha_tabela;
primeiro | segundo
----------+---------
1 | UM
2 | DOIS
3 | TRÊS
4 | QUATRO
(4 linhas)
As tabelas podem ser mostradas de forma diferente usando o comando \pset:
peter@localhost testdb=> \pset border 2
O estilo da borda é 2.
peter@localhost testdb=> SELECT * FROM minha_tabela;
+----------+---------+
| primeiro | segundo |
+----------+---------+
| 1 | UM |
| 2 | DOIS |
| 3 | TRÊS |
| 4 | QUATRO |
+----------+---------+
(4 linhas)
peter@localhost testdb=> \pset border 0
O estilo da borda é 0.
peter@localhost testdb=> SELECT * FROM minha_tabela;
primeiro segundo
-------- -------
1 UM
2 DOIS
3 TRÊS
4 QUATRO
(4 linhas)
peter@localhost testdb=> \pset border 1
O estilo da borda é 1.
peter@localhost testdb=> \pset format unaligned
O formato de saída é não alinhado.
peter@localhost testdb=> \pset fieldsep ','
O separador de campos é ",".
peter@localhost testdb=> \pset tuples_only
Mostrando apenas tuplas.
peter@localhost testdb=> SELECT segundo, primeiro FROM minha_tabela;
UM,1
DOIS,2
TRÊS,3
QUATRO,4
Como alternativa, podem ser usados os comandos curtos:
peter@localhost testdb=> \a \t \x O formato de saída é alinhado. Mostrar somente tuplas está desativado. A exibição expandida está ativada. peter@localhost testdb=> SELECT * FROM minha_tabela; -[ RECORD 1 ]---- primeiro | 1 segundo | UM -[ RECORD 2 ]---- primeiro | 2 segundo | DOIS -[ RECORD 3 ]---- primeiro | 3 segundo | TRÊS -[ RECORD 4 ]---- primeiro | 4 segundo | QUATRO
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 é possível utilizar em \dt. [15]
=> 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""
=> 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] |
Os comandos date e hostname são executados na estação cliente onde o psql está executando. Portanto, as informações mostradas são da estação cliente e não do servidor, a não ser que o psql esteja executando na mesma máquina que o servidor. (N. do T.) |
| [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. |
| [11] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
| [12] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
| [13] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
| [14] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
| [15] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |
