Manual de Referncia do PostgreSQL

7.3.2

The PostgreSQL Global Development Group

Manual de Referncia do PostgreSQL 7.3.2

por The PostgreSQL Global Development Group
Copyright 1996-2002 The PostgreSQL Global Development Group
Legal Notice
PostgreSQL is Copyright 1996-2002 by the PostgreSQL Global Development Group and is distributed under the terms of the license of the
University of California below.
Postgres95 is Copyright 1994-5 by the Regents of the University of California.
Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written
agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all
copies.
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL,
INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE
AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN AS-IS BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

ndice
Prefcio ....................................................................................................................................................................i
I. Comandos SQL................................................................................................................................................... 1
ABORT........................................................................................................................................................... 1
ALTER DATABASE ...................................................................................................................................... 1
ALTER GROUP ............................................................................................................................................. 1
ALTER TABLE.............................................................................................................................................. 1
ALTER TRIGGER ......................................................................................................................................... 1
ALTER USER ................................................................................................................................................ 1
ANALYZE...................................................................................................................................................... 1
BEGIN............................................................................................................................................................ 1
CHECKPOINT............................................................................................................................................... 1
CLOSE ........................................................................................................................................................... 1
CLUSTER ...................................................................................................................................................... 1
COMMENT ................................................................................................................................................... 1
COMMIT ....................................................................................................................................................... 1
COPY ............................................................................................................................................................. 1
CREATE AGGREGATE ................................................................................................................................ 1
CREATE CAST.............................................................................................................................................. 1
CREATE CONSTRAINT TRIGGER ............................................................................................................ 1
CREATE CONVERSION .............................................................................................................................. 1
CREATE DATABASE.................................................................................................................................... 1
CREATE DOMAIN ....................................................................................................................................... 1
CREATE FUNCTION.................................................................................................................................... 1
CREATE GROUP .......................................................................................................................................... 1
CREATE INDEX ........................................................................................................................................... 1
CREATE LANGUAGE.................................................................................................................................. 1
CREATE OPERATOR ................................................................................................................................... 1
CREATE OPERATOR CLASS...................................................................................................................... 1
CREATE RULE.............................................................................................................................................. 1
CREATE SCHEMA ....................................................................................................................................... 1
CREATE SEQUENCE ................................................................................................................................... 1
CREATE TABLE ........................................................................................................................................... 1
CREATE TABLE AS ..................................................................................................................................... 1
CREATE TRIGGER ...................................................................................................................................... 1
CREATE TYPE.............................................................................................................................................. 1
CREATE USER.............................................................................................................................................. 1
CREATE VIEW ............................................................................................................................................. 1
DEALLOCATE .............................................................................................................................................. 1
DECLARE ..................................................................................................................................................... 1
DELETE......................................................................................................................................................... 1
DROP AGGREGATE..................................................................................................................................... 1
DROP CAST .................................................................................................................................................. 1
DROP CONVERSION................................................................................................................................... 1
DROP DATABASE ........................................................................................................................................ 1
DROP DOMAIN ............................................................................................................................................ 1
DROP FUNCTION ........................................................................................................................................ 1
DROP GROUP ............................................................................................................................................... 1
DROP INDEX ................................................................................................................................................ 1
DROP LANGUAGE ...................................................................................................................................... 1

iii

DROP OPERATOR........................................................................................................................................ 1
DROP OPERATOR CLASS .......................................................................................................................... 1
DROP RULE .................................................................................................................................................. 1
DROP SCHEMA............................................................................................................................................ 1
DROP SEQUENCE........................................................................................................................................ 1
DROP TABLE................................................................................................................................................ 1
DROP TRIGGER ........................................................................................................................................... 1
DROP TYPE .................................................................................................................................................. 1
DROP USER .................................................................................................................................................. 1
DROP VIEW .................................................................................................................................................. 1
END................................................................................................................................................................ 1
EXECUTE...................................................................................................................................................... 1
EXPLAIN....................................................................................................................................................... 1
FETCH ........................................................................................................................................................... 1
GRANT .......................................................................................................................................................... 1
INSERT .......................................................................................................................................................... 1
LISTEN .......................................................................................................................................................... 1
LOAD ............................................................................................................................................................. 1
LOCK ............................................................................................................................................................. 1
MOVE ............................................................................................................................................................ 1
NOTIFY ......................................................................................................................................................... 1
PREPARE....................................................................................................................................................... 1
REINDEX ...................................................................................................................................................... 1
RESET............................................................................................................................................................ 1
REVOKE........................................................................................................................................................ 1
ROLLBACK................................................................................................................................................... 1
SELECT ......................................................................................................................................................... 1
SELECT INTO............................................................................................................................................... 1
SET................................................................................................................................................................. 1
SET CONSTRAINTS .................................................................................................................................... 1
SET SESSION AUTHORIZATION .............................................................................................................. 1
SET TRANSACTION.................................................................................................................................... 1
SHOW ............................................................................................................................................................ 1
START TRANSACTION............................................................................................................................... 1
TRUNCATE ................................................................................................................................................... 1
UNLISTEN .................................................................................................................................................... 1
UPDATE......................................................................................................................................................... 1
VACUUM....................................................................................................................................................... 1
II. Aplicativos para a estao cliente do PostgreSQL ......................................................................................... 4
clusterdb ......................................................................................................................................................... 5
createdb .......................................................................................................................................................... 8
createlang ..................................................................................................................................................... 11
createuser...................................................................................................................................................... 14
dropdb........................................................................................................................................................... 18
droplang........................................................................................................................................................ 21
dropuser ........................................................................................................................................................ 24
ecpg .............................................................................................................................................................. 27
pg_config...................................................................................................................................................... 29
pg_dump....................................................................................................................................................... 31
pg_dumpall................................................................................................................................................... 38
pg_restore ..................................................................................................................................................... 41

iv

psql ............................................................................................................................................................... 48
pgtclsh .......................................................................................................................................................... 70
pgtksh ........................................................................................................................................................... 71
vacuumdb ..................................................................................................................................................... 72
III. Aplicativos para o servidor do PostgreSQL................................................................................................ 75
initdb............................................................................................................................................................. 76
initlocation.................................................................................................................................................... 79
ipcclean......................................................................................................................................................... 80
pg_ctl............................................................................................................................................................ 81
pg_controldata .............................................................................................................................................. 85
pg_resetxlog ................................................................................................................................................. 86
postgres......................................................................................................................................................... 88
postmaster..................................................................................................................................................... 92

Prefcio
As entradas deste Manual de Referncia se propem a fornecer um resumo completo e formal dos respectivos
assuntos. Mais informaes sobre a utilizao do PostgreSQL, sob forma narrativa, de tutorial, ou de exemplos,
podem ser encontradas em outras partes do conjunto de documentos do PostgreSQL. Veja as referncias cruzadas
listadas em cada pgina de referncia.
As informaes contidas no Manual de Referncia tambm esto disponveis no formato man pages do Unix.
Projeto PostgreSQL Br1 - O centro de informaes para os usurios brasileiros.

Traduzido por Halley Pacheco de Oliveira2 - Cmara Municipal do Rio de Janeiro.

Revisado por Diogo de Oliveira Biazus3 - Ikono

1.
2.
3.

http://pgsqlbr.querencialivre.rs.gov.br
mailto:[email protected]
mailto:[email protected]

I. Comandos SQL
Esta parte contm informaes de referncia para os comandos SQL suportados pelo PostgreSQL. Por SQL
entenda-se a linguagem SQL de modo geral; informaes sobre a conformidade e a compatibilidade de cada
comando com relao ao padro podem ser encontradas nas respectivas pginas de referncia.

ABORT
Nome
ABORT aborta a transao corrente

Sinopse
ABORT [ WORK | TRANSACTION ]

Entradas
Nenhuma.

Sadas
ROLLBACK

Mensagem retornada se o comando for executado com sucesso.

WARNING: ROLLBACK: no transaction in progress

Se no houver nenhuma transao sendo executada.

Descrio
O comando ABORT desfaz a transao corrente, fazendo com que todas as modificaes realizadas pela transao
sejam rejeitadas. Este comando possui um comportamento idntico ao do comando ROLLBACK do SQL92, estando
presente apenas por razes histricas.

Notas
Use o comando COMMIT para terminar uma transao com sucesso.

Utilizao
Para abortar todas as modificaes:
ABORT WORK;

ABORT

Compatibilidade
SQL92
Este comando uma extenso do PostgreSQL presente apenas por razes histricas. O comando equivalente do
SQL92 o ROLLBACK.

ALTER DATABASE
Nome
ALTER DATABASE altera um banco de dados

Sinopse
ALTER DATABASE nome SET varivel { TO | = } { valor | DEFAULT }
ALTER DATABASE nome RESET varivel

Descrio
O comando ALTER DATABASE utilizado para mudar o valor padro de uma varivel de configurao de tempo
de execuo, para a sesso em um banco de dados do PostgreSQL. Sempre que uma nova sesso for iniciada neste
banco de dados, o valor especificado se torna o padro para a sesso. O padro especfico para o banco de dados
prevalece sobre qualquer outra definio presente no arquivo postgresql.conf, ou que tenha sido recebida do
postmaster.
Somente um superusuro, ou o dono do banco de dados, podem mudar os padres para a sesso de um banco de
dados.

Parmetros
nome
O nome do banco de dados cujo padro para a sesso est sendo alterado.
varivel
valor
Define, para a sesso do banco de dados, o valor padro da varivel de configurao especificada como
o valor fornecido. Se valor for DEFAULT ou, de forma equivalente, se RESET for usado, a definio da
varivel para o banco de dados especfico removida, e o valor padro global do sistema ser herdado para
as novas sesses do banco de dados. Use RESET ALL para apagar todas as definies.
Consulte o comando SET e o Guia do Administrador para obter mais informaes sobre os nomes e valores
permitidos para as variveis.

Diagnsticos
ALTER DATABASE

Mensagem retornada se a alterao for realizada com sucesso.

ALTER DATABASE
ERROR: database "nome_bd" does not exist

Mensagem de erro rertornada se o banco de dados especificado no existir no sistema.

Notes
Utilizando-se o comando ALTER USER, tambm possvel associar a um usurio especfico, em vez de associar
a um banco de dados, o valor padro para a sesso. Definies especficas para o usurio prevalecem sobre
definies especficas para o banco de dados no caso de haver conflito.

Exemplos
Para desabilitar a varedura de ndices por padro no banco banco de dados: test:
ALTER DATABASE teste SET enable_indexscan TO off;

Compatibilidade
O comando ALTER DATABASE uma extenso do PostgreSQL.

Consulte tambm
ALTER USER, CREATE DATABASE, DROP DATABASE, SET

ALTER GROUP
Nome
ALTER GROUP inclui ou exclui usurios em um grupo

Sinopse
ALTER GROUP nome ADD USER nome_do_usurio [, ... ]
ALTER GROUP nome DROP USER nome_do_usurio [, ... ]

Entradas
nome
O nome do grupo a ser modificado.
nome_do_usurio
Os usurios a serem includos ou excludos no grupo. Os nomes dos usurios devem existir.

Sadas
ALTER GROUP

Mensagem retornada se a alterao for realizada com sucesso.

Descrio
O comando ALTER GROUP utilizado para incluir ou excluir usurios em um grupo. Somente os superusurios do
banco de dados podem utilizar este comando. Incluir um usurio em um grupo no cria o usurio. Analogamente,
excluir um usurio de um grupo no exclui o usurio do banco de dados.
Use o CREATE GROUP para criar um novo grupo, e o DROP GROUP para remover um grupo.

Utilizao
Incluir usurios em um grupo:
ALTER GROUP arquitetura ADD USER joana, alberto;

Excluir um usurio de um grupo:

ALTER GROUP
ALTER GROUP engenharia DROP USER margarida;

Compatibilidade
SQL92
No existe o comando ALTER GROUP no SQL92. O conceito de roles similar ao de grupos.

ALTER TABLE
Nome
ALTER TABLE altera a definio de uma tabela

Sinopse
ALTER TABLE [ ONLY ] tabela [ * ]
ADD [ COLUMN ] column tipo [ restrio_de_coluna [ ... ] ]
ALTER TABLE [ ONLY ] tabela [ * ]
DROP [ COLUMN ] coluna [ RESTRICT | CASCADE ]
ALTER TABLE [ ONLY ] tabela [ * ]
ALTER [ COLUMN ] coluna { SET DEFAULT valor | DROP DEFAULT }
ALTER TABLE [ ONLY ] tabela [ * ]
ALTER [ COLUMN ] coluna { SET | DROP } NOT NULL
ALTER TABLE [ ONLY ] tabela [ * ]
ALTER [ COLUMN ] coluna SET STATISTICS inteiro
ALTER TABLE [ ONLY ] tabela [ * ]
ALTER [ COLUMN ] coluna SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }
ALTER TABLE [ ONLY ] tabela [ * ]
RENAME [ COLUMN ] coluna TO novo_nome_da_coluna
ALTER TABLE tabela
RENAME TO novo_nome_da_tabela
ALTER TABLE [ ONLY ] tabela [ * ]
ADD definio_de_restrio_de_tabela
ALTER TABLE [ ONLY ] tabela [ * ]
DROP CONSTRAINT nome_da_restrio [ RESTRICT | CASCADE ]
ALTER TABLE tabela
OWNER TO novo_dono

Entradas
tabela
O nome (opcionalmente qualificado pelo esquema) da tabela existente a ser alterada. Se ONLY for especificado, somente esta tabela alterada. Se ONLY no for especificado, a tabela e todas as suas tabelas descendentes (se existirem) sero alteradas. O * pode ser apensado ao nome da tabela para indicar que as tabelas
descendentes devem ser varridas, mas na verso atual este comportamento padro (Nas verses anteriores
a 7.1 ONLY era o comportamento padro). O padro pode ser alterado mudando-se a opo de configurao
SQL_INHERITANCE.
coluna
O nome de uma coluna nova ou existente.
tipo
O tipo da nova coluna.
novo_nome_da_coluna
O novo nome para a coluna existente.

ALTER TABLE
novo_nome_da_tabela
O novo nome para a tabela.
definio_de_restrio_de_tabela
A nova restrio de tabela (table constraint) para a tabela.
nome_da_restrio
O nome da restrio existente a ser excluda.
novo_dono
O nome de usurio do novo dono da tabela.
CASCADE
Exclui, automaticamente, os objetos que dependem da coluna ou restrio excluda (por exemplo, vises que
fazem referncia coluna).
RESTRICT
Recusa excluir a coluna ou a restrio se existirem objetos dependentes. Este o comportamento padro.

Sadas
ALTER TABLE

Mensagem retornada se o nome da coluna ou da tabela for alterado com sucesso.

ERROR

Mensagem retornada se a tabela ou a coluna no existir.

Descrio
O comando ALTER TABLE altera a definio de uma tabela existente. Existem vrias formas alternativas:
ADD COLUMN
Esta forma adiciona uma nova coluna tabela usando a mesma sintaxe do comando CREATE TABLE.
DROP COLUMN
Esta forma exclui uma coluna da tabela. Note que os ndices e as restries da tabela que referenciam a
coluna tambm sero automaticamente excludos. Ser necessrio especificar CASCADE se algum objeto fora
da tabela depender da coluna --- por exemplo, chaves estrangeiras, vises, etc...
SET/DROP DEFAULT
Estas formas definem ou removem o valor padro para a coluna. Note que o valor padro somente se aplica
aos prximos comandos INSERT; as linhas existentes na tabela no so modificadas. Os valores padro
tambm podem ser criados para as vises e, neste caso, so inseridos pelo comando INSERT antes da regra
ON INSERT da viso ser aplicada.

ALTER TABLE
SET/DROP NOT NULL
Estas formas mudam a definio da coluna para permitir valores nulos ou para rejeitar valores nulos. A forma
SET NOT NULL somente pode ser usada quando no existem valores nulos na coluna.
SET STATISTICS
Esta forma permite controlar a coleta de estatsticas para os comandos ANALYZE posteriores. O valor pode
ser definido no intervalo de 0 a 1000; como alternativa, pode ser definido como -1 para utilizar o valor padro
do sistema para as estatsticas.
SET STORAGE
Esta forma define o modo de armazenamento para a coluna. Controla se a coluna armazenada junto com
as outras ou em uma tabela suplementar, e se os dados devem ser comprimidos ou no. PLAIN deve ser
usado para valores de tamanho fixo como o INTEGER, sendo mantidos junto e no comprimido. MAIN
usado para dados mantidos juntos que podem ser comprimidos. EXTERNAL usado para dados externos e
no comprimidos, e EXTENDED usado para dados externos comprimidos. EXTENDED o padro para todos
os tipos de dados que o suportam. A utilizao de EXTERNAL faz com que as operaes de substring em
uma coluna TEXT sejam mais rpidas, embora o espao para armazenamento aumente.
RENAME
A forma RENAME muda o nome de uma tabela (um ndice, uma seqncia ou uma viso) ou o nome de uma
coluna da tabela. No produz efeito sobre os dados armazenados.
ADD definio_de_restrio_de_tabela
Esta forma adiciona uma nova restrio para a tabela usando a mesma sintaxe do comando CREATE TABLE.
DROP CONSTRAINT
Esta forma exclui a restrio da tabela. Atualmente as restries de tabela no necessitam ter nomes nicos,
portanto pode haver mais de uma restrio correspondendo ao nome especificado. Todas estas restries
sero excludas.
OWNER
Esta forma muda o dono da tabela, ndice, seqncia ou viso para o usurio especificado.

necessrio ser o dono da tabela para executar o comando ALTER TABLE, exceto para a forma ALTER TABLE
OWNER que somente pode ser executada por um superusurio.

Notas
A palavra chave COLUMN apenas informativa podendo ser omitida.
Na atual implementao de ADD COLUMN, as clusulas valor padro e NOT NULL no so suportadas para a nova
coluna. A nova coluna sempre criada com todos os valores nulos. Pode ser usada a forma SET DEFAULT do
comando ALTER TABLE para definir o valor padro mais tarde. (Os valores atuais das linhas existentes podero
ser atualizados, posteriormente, para o novo valor padro usando o comando UPDATE.) If you want to mark the
column non-null, use the SET NOT NULL form after youve entered non-null values for the column in all rows.
O comando DROP COLUMN no remove fisicamente a coluna, simplemente torna a coluna invisvel para as operaes SQL. As prximas incluses e atualizaes na tabela armazenam nulo para a coluna. Portanto, excluir uma
coluna rpido mas no reduz imediatamente o espao em disco da tabela, uma vez que o espao ocupado pela
coluna excluda no reorganizado. O espao reorganizado ao longo do tempo quando as linhas existentes vo
sendo atualizadas. Para reorganizar o espao de uma vez deve-se fazer uma atualizao fictcia de todas as linhas
e depois executar o comando VACUUM, como em:

ALTER TABLE
UPDATE tabela SET coluna = coluna;
VACUUM FULL tabela;

Se a tabela possuir tabelas descendentes, no permitido adicionar ou mudar o nome da coluna na tabela ancestral
sem fazer o mesmo nas tabelas descendentes --- ou seja, ALTER TABLE ONLY rejeitado. Isto garante que as
tabelas descendentes sempre possuem colunas que correspondem as da tabela ancestral.
Uma operao DROP COLUMN recursiva remove a coluna da tabela descendente somente se a tabela descendente no herda esta coluna de outros ancestrais e nunca pussuiu uma definio independente para a coluna. Uma
operao DROP COLUMN no recursiva (ou seja, ALTER TABLE ONLY ... DROP COLUMN) nunca remove
qualquer coluna descendente mas, em vez disto, marca estas colunas como definidas independentemente em vez
de herdada.
Mudar qualquer parte do esquema do catlogo do sistema no permitido.
Consulte o comando CREATE TABLE para obter uma descrio detalhada dos argumentos vlidos. O Guia do
Usurio do PostgreSQL contm mais informaes sobre herana.

Utilizao
Para adicionar uma coluna do tipo varchar em uma tabela:
ALTER TABLE distribuidores ADD COLUMN endereco VARCHAR(30);

Para excluir uma coluna de uma tabela:

ALTER TABLE distribuidores DROP COLUMN endereco RESTRICT;

Para mudar o nome de uma coluna existente:

ALTER TABLE distribuidores RENAME COLUMN endereco TO cidade;

Para mudar o nome de uma tabela existente:

ALTER TABLE distribuidores RENAME TO fornecedores;

Para adicionar uma restrio NOT NULL a uma coluna:

ALTER TABLE distribuidores ALTER COLUMN logradouro SET NOT NULL;

Para remover a restrio NOT NULL da coluna:

ALTER TABLE distribuidores ALTER COLUMN logradouro DROP NOT NULL;

ALTER TABLE

Para adicionar uma restrio de verificao (check) a uma tabela:

ALTER TABLE distribuidores ADD CONSTRAINT chk_cep CHECK (char_length(cod_cep) = 8);

Para remover uma restrio de verificao de uma tabela e de todas as suas descendentes:
ALTER TABLE distribuidores DROP CONSTRAINT chk_cep;

Para adicionar uma restrio de chave estrangeira a uma tabela:

ALTER TABLE distribuidores ADD CONSTRAINT fk_dist FOREIGN KEY (endereco) REFERENCES enderecos

Para adicionar uma restrio de unicidade (multi-coluna) tabela:

ALTER TABLE distribuidores ADD CONSTRAINT unq_dist_id_cod_cep UNIQUE (dist_id, cod_cep);

Para adicionar uma restrio de chave primria a uma tabela com o nome gerado automaticamente, observando-se
que a tabela somente pode possuir uma nica chave primria:
ALTER TABLE distribuidores ADD PRIMARY KEY (dist_id);

Compatibilidade
SQL92
A forma ADD COLUMN est em conformidade, a no ser por no suportar valor padro e NOT NULL, conforme
foi explicado anteriormente. A forma ALTER COLUMN est em conformidade total.
As clusulas para mudar os nomes das tabelas, ndices e seqncias so extenses do PostgreSQL ao SQL92.

ALTER TRIGGER
Nome
ALTER TRIGGER altera a definio de um gatilho

Sinopse
ALTER TRIGGER gatilho ON tabela
RENAME TO novo_nome

Entradas
gatilho
O nome do gatilho que est sendo alterado.
tabela
O nome da tabela onde o gatilho atua.
novo_nome
O novo nome para o gatilho existente.

Sadas
ALTER TRIGGER

Mensagem retornada se o nome do gatilho for alterado com sucesso.

ERROR

Mensagem retornada se o gatilho no existir, ou se o nome novo for igual ao nome de outro gatilho existente
na tabela.

Descrio
O comando ALTER TRIGGER muda a definio de um gatilho existente. A clusula RENAME faz com que o nome
de um determinado gatilho de uma tabela mude sem mudar a definio do gatilho.
necessrio ser o dono da tabela em que o gatilho atua para poder mudar as suas propriedades.

ALTER TRIGGER

Notas
Consulte o comando CREATE TRIGGER para obter uma descrio detalhada dos argumentos vlidos.

Usage
Para mudar o nome de um gatilho existente:
ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs;

Compatibilidade
SQL92
A clusula para mudar o nome dos gatilhos uma extenso do PostgreSQL ao SQL92.

ALTER USER
Nome
ALTER USER altera a conta de um usurio do banco de dados

Sinopse
ALTER USER nome_do_usurio [ [ WITH ] opo [ ... ] ]
onde opo pode ser:
[ ENCRYPTED | UNENCRYPTED ] PASSWORD senha
| CREATEDB | NOCREATEDB
| CREATEUSER | NOCREATEUSER
| VALID UNTIL data_hora
ALTER USER nome_do_usurio SET varivel { TO | = } { valor | DEFAULT }
ALTER USER nome_do_usurio RESET varivel

Descrio
O comando ALTER USER utilizado para mudar os atributos da conta de um usurio do PostgreSQL. Os atributos
no mencionados no comando permanecem com os seus valores inalterados.
A primeira forma deste comando mostrada na sinopse muda certos privilgios globais do usurio e definies
de autenticao (Veja abaixo para obter detalhes). Somente um superusurio do banco de dados pode alterar os
privilgios e a expirao da senha com este comando. Os usurios comuns somente podem alterar as suas prprias
senhas.
A segunda e a terceira formas mudam o valor padro da varivel de configurao indicada para a sesso do
usurio. Sempre que o usurio iniciar uma nova sesso o valor especificado se tornar o padro para a sesso,
substituindo qualquer definio que esteja presente no arquivo postgresql.conf, ou que tenha sido recebida
do postmaster. Usurios comuns podem mudar os valores padro para a sua prpria sesso. Superusurios
podem mudar os valores padro para a sesso de qualquer usurio.

Parmetros
nome_do_usurio
O nome do usurio cujos atributos esto sendo alterados.
senha
A nova senha a ser utilizada para esta conta.
ENCRYPTED
UNENCRYPTED

Estas palavras chave controlam se a senha armazenada criptografada, ou no, em pg_shadow (Consulte o
comando CREATE USER para obter mais informaes sobre esta opo).

ALTER USER
CREATEDB
NOCREATEDB

Estas clusulas definem a permisso para o usurio criar bancos de dados. Se CREATEDB for especificado, o usurio sendo alterado ter permisso para criar seus prprios bancos de dados. Especificando-se
NOCREATEDB a permisso para criar bancos de dados negada ao usurio.
CREATEUSER
NOCREATEUSER

Estas clusulas definem a permisso para o usurio criar novos usurios. Esta opo tambm torna o usurio
um superusurio, que pode mudar todas as restries de acesso.
data_hora
A data (e, opcionalmente, a hora) de expirao da senha do usurio.
varivel
valor
Define, para a sesso do usurio, o valor padro da varivel de configurao especificada como o valor
fornecido. Se valor for DEFAULT ou, de forma equivalente, se RESET for usado, a definio da varivel
para o usurio especfico removida, e o valor padro global do sistema ser herdado para as novas sesses
do usurio. Use RESET ALL para apagar todas as definies.
Consulte o comando SET e o Guia do Administrador para obter mais informaes sobre os nomes e valores
permitidos para as variveis.

Diagnsticos
ALTER USER

Mensagem retornada se a alterao for realizada com sucesso.

ERROR: ALTER USER: user "nome_do_usurio" does not exist

Mensagem retornada quando o usurio especificado no existir no banco de dados.

Notas
Use o comando CREATE USER para criar um novo usurio, e o comando DROP USER para remover um usurio.
O comando ALTER USER no pode mudar a participao do usurio nos grupos. Use o comando ALTER GROUP
para realizar esta operao.
Utilizando-se o comando ALTER DATABASE tambm possvel associar a um banco de dados especfico, em vez
de associar a um usurio, o valor padro para a sesso.

ALTER USER

Exemplos
Mudar a senha do usurio:
ALTER USER marcos WITH PASSWORD hu8jmn3;

Mudar a data de expirao da senha do usurio:

ALTER USER manuel VALID UNTIL Jan 31 2030;

Mudar a data de expirao da senha do usurio, especificando que sua autorizao expira ao meio dia de 4 de
maio de 1998, usando uma zona horria uma hora adiante da UTC:
ALTER USER cristina VALID UNTIL May 4 12:00:00 1998 +1;

Dar ao usurio poderes para criar outros usurios e novos bancos de dados:
ALTER USER marcela CREATEUSER CREATEDB;

Compatibilidade
O comando ALTER USER uma extenso do PostgreSQL. O padro deixa a definio dos usurios para a implementao.

Consulte tambm
CREATE USER, DROP USER, SET

ANALYZE
Nome
ANALYZE coleta estatsticas sobre um banco de dados

Sinopse
ANALYZE [ VERBOSE ] [ tabela [ (coluna [, ...] ) ] ]

Entradas
VERBOSE
Ativa a exibio de mensagens de progresso.
tabela
O nome (opcionalmente qualificado pelo esquema) de uma tabela especfica a ser analisada. Por padro todas
as tabelas.
coluna
O nome de uma coluna especfica a ser analisada. Por padro todas as colunas.

Sadas
ANALYZE

O comando est concludo.

Descrio
O comando ANALYZE coleta estatsticas sobre o contedo das tabelas do PostgreSQL, e armazena os resultados
na tabela do sistema pg_statistic. Posteriormente, o otimizador de consultas utiliza estas estatsticas para
auxiliar na determinao do plano de execuo mais eficiente para as consultas.
Sem nenhum parmetro, o comando ANALYZE analisa todas as tabelas do banco de dados em uso. Com parmetro,
o comando ANALYZE analisa somente uma tabela. possvel ainda fornecer uma relao de nomes de colunas e,
neste caso, somente as estatsticas para estas colunas so atualizadas.

ANALYZE

Notas
Aconselha-se executar o comando ANALYZE periodicamente, ou logo aps realizar uma alterao significativa
no contedo de uma tabela. Estatsticas precisas auxiliam o otimizador na escolha do plano de consulta mais
apropriado e, portanto, a melhorar o tempo do processamento da consulta. Uma estratgia habitual executar
VACUUM e ANALYZE uma vez por dia em perodos de pouca carga.
Ao contrrio do comando VACUUM FULL, o comando ANALYZE requer somente um bloqueio de leitura na tabela
podendo, portanto, ser executado em conjunto com outras atividades na tabela.
Para tabelas grandes, o comando ANALYZE pega amostras aleatrias do contedo da tabela, em vez de examinar
todas as linhas. Esta estratgia permite que mesmo tabelas muito grandes sejam analisadas em curto espao de
tempo. Observe, entretanto, que as estatsticas so apenas aproximadas e vo ser um pouco diferentes cada vez que
o comando ANALYZE for executado, mesmo que o contedo da tabela no se altere, podendo ocasionar pequenas
mudanas no custo estimado pelo otimizador mostrado no comando EXPLAIN.
As estatsticas coletadas geralmente incluem a relao dos valores com maior incidncia de cada coluna e um histograma mostrando a distribuio aproximada dos dados de cada coluna. Um, ou ambos, podem ser omitidos se o
comando ANALYZE consider-los irrelevantes (por exemplo, em uma coluna com chave nica no existem valores
repetidos) ou se o tipo de dado da coluna no suportar os operadores apropriados. Existem mais informaes
sobre as estatsticas no Guia do Usurio.
A extenso da anlise pode ser controlada ajustando-se o valor de default_statistics_target, ou coluna
por coluna atravs do comando ALTER TABLE ALTER COLUMN SET STATISTICS (consulte o comando ALTER
TABLE). O valor especificado define o nmero mximo de entradas presentes na lista de valores com maior
incidncia, e o nmero mximo de barras no histograma. O valor padro 10, mas pode ser ajustado para mais,
ou para menos, para balancear a preciso das estimativas do otimizador contra o tempo gasto para a execuo do
comando ANALYZE e a quantidade de espao ocupado pela tabela pg_statistic. Em particular, especificandose o valor zero desativa a coleta de estatsticas para a coluna, podendo ser til para colunas que nunca so usadas
como parte das clusulas WHERE, GROUP BY ou ORDER BY das consultas, porque as estatsticas destas
colunas no tm utilidade para o otimizador.
O maior nmero de estatsticas, entre as colunas sendo analisadas, determina o nmero de linhas amostradas
para preparar as estatsticas. Aumentando o nmero de estatsticas por coluna causa um aumento proporcional no
tempo e espao necessrio para executar o comando ANALYZE.

Compatibilidade
SQL92
No existe o comando ANALYZE no SQL92.

BEGIN
Nome
BEGIN inicia um bloco de transao

Sinopse
BEGIN [ WORK | TRANSACTION ]

Entradas
WORK
TRANSACTION
Palavras chave opcionais. No produzem nenhum efeito.

Sadas
BEGIN

Significa que uma nova transao comeou.

WARNING: BEGIN: already a transaction in progress

Indica que uma transao est sendo executada. A transao corrente no afetada.

Descrio
Por padro, o PostgreSQL executa as transaes em modo no encadeado (tambm conhecido por autocommit
[auto-efetivao] em outros sistemas de banco de dados). Em outras palavras, cada comando executado em
sua prpria transao e uma efetivao implicitamente realizada ao final do comando (se a execuo terminar
com sucesso, seno um rollback realizado). O comando BEGIN inicia uma transao no modo encadeado, ou
seja, todas as declaraes aps o comando BEGIN so executadas como sendo uma nica transao, at que seja
encontrado um comando explcito COMMIT ou ROLLBACK. Os comandos so executados mais rpido no modo
encadeado, porque cada incio/efetivao de transao requer uma atividade significativa de CPU e de disco. A
execuo de vrios comandos em uma nica transao tambm requerida por motivo de consistncia, quando
vrias tabelas relacionadas so modificadas: os outros usurios no enxergam os estados intermedirios enquanto
todas as atualizaes relacionadas no estiverem terminadas.
O nvel de isolamento padro da transao no PostgreSQL READ COMMITTED, onde os comandos dentro
de uma transao enxergam apenas as mudanas efetivadas antes da execuo do comando. Por esse motivo

BEGIN
deve-se utilizar SET TRANSACTION ISOLATION LEVEL SERIALIZABLE logo aps o comando BEGIN se for
necessrio um nvel de isolamento mais rigoroso para a transao (como alternativa, pode-se mudar o nvel de
isolamento padro da transao; consulte o Guia do Administrador do PostgreSQL para obter detalhes). No modo
SERIALIZABLE os comandos enxergam apenas as modificaes efetivadas antes do incio da transao (na
verdade, antes da execuo do primeiro comando DML da transao).
As transaes possuem as propriedades ACID (atomicidade, consistncia, isolamento e durabilidade) padro.

Notas
O comando START TRANSACTION possui a mesma funcionalidade do BEGIN.
Use o comando COMMIT ou o comando ROLLBACK para terminar uma transao.
Consulte o comando LOCK para obter mais informaes sobre o bloqueio de tabelas dentro de uma transao.
Se o modo autocommit (auto-efetivao) for acionado, ento o comando BEGIN no necessrio: todo comando
SQL inicia automaticamente uma transao.

Utilizao
Para iniciar uma transao:
BEGIN WORK;

Compatibilidade
SQL92
O comando BEGIN uma extenso do PostgreSQL linguagem. No existe o comando BEGIN explcito no
SQL92; o incio da transao sempre implcito, terminando pelo comando COMMIT ou pelo comando ROLLBACK.

Nota: Muitos sistemas de banco de dados relacionais oferecem a funcionalidade de auto-efetivao (autocommit) por convenincia.

Observe que a palavra chave BEGIN utilizada para uma finalidade diferente no SQL embutido. Deve-se ter muito
cuidado com relao semntica da transao ao se portar aplicativos de banco de dados.
O SQL92 requer que SERIALIZABLE seja o nvel de isolamento padro das transaes.

CHECKPOINT
Nome
CHECKPOINT fora um ponto de controle no log de transao

Sinopse
CHECKPOINT

Descrio
A gravao prvia do registro no log (Write-Ahead Logging/WAL) coloca periodicamente um ponto de controle
(checkpoint) no log de transao (Para ajustar o intervalo automtico do ponto de controle, consulte as opes
de configurao em tempo de execuo CHECKPOINT_SEGMENTS e CHECKPOINT_TIMEOUT). O comando
CHECKPOINT fora um ponto de controle imediato ao ser executado, sem aguardar o ponto de controle prdefinido.
Um ponto de controle um ponto na seqncia do log de transao no qual todos os arquivos de dados foram atualizados para refletir a informao no log. Todos os dados so escritos no disco. Consulte o Guia do Administrador
do PostgreSQL para obter mais informaes sobre o WAL.
Somente os superusurios podem executar o comando CHECKPOINT. A utilizao deste comando durante uma
operao normal no esperada .

Consulte tambm
Guia do Administrador do PostgreSQL

Compatibilidade
O comando CHECKPOINT uma extenso do PostgreSQL linguagem.

CLOSE
Nome
CLOSE fecha o cursor

Sinopse
CLOSE cursor

Entradas
cursor
O nome do cursor aberto a ser fechado.

Sadas
CLOSE CURSOR

Mensagem retornada se o cursor for fechado com sucesso.

WARNING: PerformPortalClose: portal "cursor" not found

Esta advertncia exibida quando o cursor no est declarado ou se j tiver sido fechado.

Descrio
O comando CLOSE libera os recursos associados a um cursor aberto. Aps o cursor ser fechado, no permitida
nenhuma operao posterior sobre o mesmo. O cursor deve ser fechado quando no for mais necessrio.
Um fechamento implcito executado para todos os cursores abertos quando a transao terminada pelo comando COMMIT ou pelo comando ROLLBACK.

Notas
O PostgreSQL no possui um comando explcito OPEN cursor; o cursor considerado aberto ao ser declarado.
Use o comando DECLARE para declarar um cursor.

CLOSE

Utilizao
Fechar o cursor cur_emp:
CLOSE cur_emp;

Compatibilidade
SQL92
O comando CLOSE totalmente compatvel com o SQL92.

CLUSTER
Nome
CLUSTER agrupa uma tabela de acordo com um ndice

Sinopse
CLUSTER nome_do_ndice ON nome_da_tabela

Entradas
nome_do_ndice
O nome de um ndice.
nome_da_tabela
O nome (opcionalmente qualificado pelo esquema) de uma tabela.

Sadas
CLUSTER

O agrupamento foi realizado com sucesso.

Descrio
O comando CLUSTER instrui o PostgreSQL para agrupar a tabela especificada por nome_da_tabela baseado
no ndice especificado por nome_do_ndice. necessrio que o ndice tenha sido criado anteriormente na
tabela nome_da_tabela.
Quando a tabela agrupada, ela fisicamente reordenada baseado na informao do ndice. O agrupamento
uma operao nica: nas prximas vezes em que a tabela for atualizada, as modificaes no sero agrupadas, ou
seja, nenhuma tentativa feita para manter as tuplas novas ou atualizadas na ordem do ndice. Se for desejado, a
tabela pode ser reagrupada periodicamente executando-se este comando novamente.

Notas
No caso de se estar acessando uma nica linha da tabela aleatoriamente, a ordem fsica dos dados da tabela no
importante. Entretanto, havendo uma tendncia para acessar alguns dados mais do que outros, se existir um ndice
que agrupa estes dados haver benefcio se o comando CLUSTER for utilizado.
Outra situao em que o comando CLUSTER til so os casos em que se usa o ndice para acessar vrias linhas
da tabela. Se for solicitada uma faixa de valores indexados de uma tabela, ou um nico valor indexado possuindo

CLUSTER
muitas linhas que correspondam a este valor, o comando CLUSTER ajuda porque quando o ndice identifica a
pgina da primeira linha todas as outras linhas estaro provavelmente nesta mesma pgina, reduzindo o acesso ao
disco e acelerando a consulta.
Durante a operao de agrupamento, uma cpia temporria da tabela criada para conter os dados da tabela na
ordem do ndice. Tambm so criadas cpias temporrias de cada ndice da tabela. Portanto, necessrio um
espao livre em disco pelo menos igual soma do tamanho da tabela mais os tamanhos dos ndices.
O comando CLUSTER preserva as concesses (GRANT), herana, ndices, chaves estrangeiras e outras propriedades relacionadas tabela.
Uma vez que o otimizador registra estatsticas sobre a ordem das tabelas, aconselhvel executar o comando
ANALYZE na tabela recm agrupada, seno o otimizador poder fazer escolhas ruins no planejamento das consultas.
Existe outra maneira de se agrupar os dados. O comando CLUSTER reordena a tabela original na ordem do ndice
especificado. Este procedimento pode ser lento para tabelas grandes porque as linhas so lidas da tabela na ordem
do ndice e, se a tabela no estiver ordenada, as linhas estaro em pginas aleatrias, fazendo uma pgina do disco
ser lida para cada linha movida. O PostgreSQL possui um cache, mas a maioria das tabelas grandes no cabem
no cache. A outra maneira de se agrupar a tabela usar
SELECT lista_de_colunas INTO TABLE nova_tabela
FROM nome_da_tabela ORDER BY lista_de_colunas

que usa o cdigo de ordenao do PostgreSQL da clusula ORDER BY para criar a ordem desejada, o que geralmente muito mais rpido do que a varredura do ndice para dados no ordenados. Em seguida a tabela original deve
ser removida, o comando ALTER TABLE...RENAME deve ser utilizado para mudar o nome da nova_tabela
para o nome da tabela original, e os ndices da tabela devem ser recriados. Entretanto, esta maneira no preserva
os OIDs, restries, chaves estrangeiras, privilgios concedidos e outras propriedades relacionadas tabela --todos estes itens devero ser recriados manualmente.

Utilizao
Agrupar a relao empregados baseado no atributo ID:
CLUSTER emp_ind ON emp;

Compatibilidade
SQL92
No existe o comando CLUSTER no SQL92.

COMMENT
Nome
COMMENT guarda ou muda um comentrio sobre um objeto

Sinopse
COMMENT ON
[
TABLE nome_do_objeto |
COLUMN nome_da_tabela.nome_da_coluna |
AGGREGATE nome_da_agregao (tipo_da_agregao) |
CONSTRAINT nome_da_restrio ON nome_da_tabela |
DATABASE nome_do_objeto |
DOMAIN nome_do_objeto |
FUNCTION nome_da_funo (arg1_type, tipo_arg2, ...) |
INDEX nome_do_objeto |
OPERATOR op (tipo_operando_esq, tipo_operando_dir) |
RULE nome_da_regra ON nome_da_tabela |
SCHEMA nome_do_objeto |
SEQUENCE nome_do_objeto |
TRIGGER nome_do_gatilho ON nome_da_tabela |
TYPE nome_do_objeto |
VIEW nome_do_objeto
] IS texto

Entradas
nome_do_objeto, nome_da_tabela.nome_da_coluna, nome_da_agregao,
nome_da_restrio, nome_da_funo, op, nome_da_regra e nome_do_gatilho
O nome do objeto ao qual o comentrio se refere. Os nomes das tabelas, agregaes, domnios, funes,
ndices, operadores, seqncias, tipos e vises podem se qualificados pelo esquema.
texto
O comentrio a ser adicionado.

Sadas
COMMENT

Mensagem retornada se o comentrio for adicionado com sucesso.

COMMENT

Descrio
O comando COMMENT guarda um comentrio sobre um objeto do banco de dados. Os comentrios podem ser
facilmente acessados atravs dos comandos \dd, \d+ e \l+ do psql. Outras interfaces de usurio podem acessar os comentrios utilizando as mesmas funes nativas usadas pelo psql, que so: obj_description() e
col_description().
Para modificar um comentrio basta executar novamente o comando COMMENT para o mesmo objeto. Somente um
nico comentrio armazenado para cada objeto. Para excluir um comentrio escreva NULL no lugar do texto. O
comentrio automaticamente excludo quando o objeto excludo.
Nota: No existe atualmente nenhum mecanismo de segurana para os comentrios: qualquer usurio
conectado ao banco de dados pode ver todos os comentrios dos objetos do banco de dados (embora
somente um superusurio possa modificar comentrios de objetos que no lhe pertencem). Portanto, no
coloque informaes confidenciais nos comentrios.

Utilizao
Adicionar um comentrio tabela minha_tabela:
COMMENT ON TABLE minha_tabela IS Esta tabela minha.;

Remover o comentrio:
COMMENT ON TABLE minha_tabela IS NULL;

Alguns outros exemplos:

COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT
COMMENT

ON
ON
ON
ON
ON
ON
ON
ON
ON
ON
ON
ON
ON
ON
ON

AGGREGATE minha_agregacao (double precision) IS Calcula a varincia da amostra;

COLUMN minha_tabela.meu_campo IS Nmero de identificao do empregado;
DATABASE meu_bd IS Banco de dados de desenvolvimento;
DOMAIN meu_dominio IS Domnio de endereo de correio eletrnico;
FUNCTION minha_funcao (timestamp) IS Retorna o nmero em algarismos romanos;
INDEX my_index IS Enforces uniqueness on employee id;
OPERATOR ^ (text, text) IS Realiza a interseo de dois textos;
OPERATOR ^ (NONE, text) IS Este um operador de prefixo no texto;
RULE minha_regra ON minha_tabela IS Registra as atualizales dos registros dos e
SCHEMA meu_esquema IS Dados departamentais;
SEQUENCE minha_sequencia IS Usado para gerar as chaves primrias;
TABLE meu_esquema.minha_tabela IS Informaes dos empregados;
TRIGGER meu_gatilho ON minha_tabela IS Usado para a integridade referencial;
TYPE complex IS Tipo de dado de nmero complexo;
VIEW minha_viso IS Viso dos custos departamentais;

COMMENT

Compatibilidade
SQL92
No existe o comando COMMENT no SQL92.

COMMIT
Nome
COMMIT efetiva a transao corrente

Sinopse
COMMIT [ WORK | TRANSACTION ]

Entradas
WORK
TRANSACTION
Palavras chave opcionais. No produzem nenhum efeito.

Sadas
COMMIT

Mensagem retornada se a transao for efetivada com sucesso.

WARNING: COMMIT: no transaction in progress

Se no houver nenhuma transao sendo executada.

Descrio
O comando COMMIT efetiva a transao sendo executada. Todas as modificaes efetuadas pela transao se
tornam visveis para os outros, e existe a garantia de permanecerem se uma falha ocorrer.

Notas
As palavras chave WORK e TRANSACTION so informativas podendo ser omitidas.
Use o ROLLBACK para desfazer a transao.

COMMIT

Utilizao
Para tornar todas as modificaes permanentes:
COMMIT WORK;

Compatibilidade
SQL92
O SQL92 somente especifica as duas formas COMMIT e COMMIT WORK. Fora isso a compatibilidade total.

COPY
Nome
COPY copia dados entre arquivos e tabelas

Sinopse
COPY tabela [ ( coluna [, ...] ) ]
FROM { nome_do_arquivo | stdin }
[ [ WITH ]
[ BINARY ]
[ OIDS ]
[ DELIMITER [ AS ] delimitador ]
[ NULL [ AS ] cadeia de caracteres nula ] ]
COPY tabela [ ( coluna [, ...] ) ]
TO { nome_do_arquivo | stdout }
[ [ WITH ]
[ BINARY ]
[ OIDS ]
[ DELIMITER [ AS ] delimitador ]
[ NULL [ AS ] cadeia de caracteres nula ] ]

Entradas
table
O nome (opcionalmente qualificado pelo esquema) de uma tabela existente.
coluna
Uma relao opcional das colunas a serem copiadas. Se nenhuma relao for fornecida, so usadas todas as
colunas.
nome_do_arquivo
O nome do arquivo de entrada ou de sada no Unix, junto com o caminho absoluto.
stdin

Especifica que a entrada vem do aplicativo cliente.

stdout

Especifica que a sada vai para o aplicativo cliente.

BINARY
Altera o comportamento da formatao dos campos, fazendo todos os dados serem escritos ou lidos no
formato binrio em vez de texto. No podem ser especificados DELIMITER e NULL no modo binrio.
OIDS
Especifica a cpia do identificador interno do objeto (OID) de cada linha.
delimitador
O caractere nico que separa os campos dentro de cada linha do arquivo.

COPY
cadeia de caracteres nula
A cadeia de caracteres que representa o valor nulo. O padro \N (contrabarra-N). Pode-se preferir uma
cadeia de caracteres vazia, por exemplo.
Nota: Durante a leitura, qualquer item de dado que corresponda a esta cadeia de caracteres armazenado com o valor nulo, portanto deve-se ter certeza de estar usando para ler a mesma cadeia de
caracteres que foi usada para escrever.

Sadas
COPY

A cpia terminou com sucesso.

ERROR: razo

A cpia falhou pela razo mostrada na mensagem de erro.

Descrio
O comando COPY copia dados entre tabelas do PostgreSQL e arquivos do sistema operacional. O comando COPY
TO copia o contedo de uma tabela para um arquivo, enquanto o comando COPY FROM copia os dados de um
arquivo para uma tabela (adicionando os dados aos existentes na tabela).
Se uma relao de colunas for especificada, o comando COPY somente copia os dados das colunas especificadas
de ou para o arquivo. Havendo alguma coluna na tabela que no esteja na relao de colunas, o comando COPY
FROM insere o valor padro desta coluna.
O comando COPY com um nome de arquivo instrui o servidor PostgreSQL a ler ou escrever diretamente no
arquivo. O arquivo deve ser acessvel ao servidor e o nome deve ser especificado sob o ponto de vista do servidor.
Quando stdin ou stdout so especificados, os dados fluem entre o cliente e o servidor.
Dica: No confunda o comando COPY com a instruo \copy do psql. O \copy executa COPY FROM stdin ou
COPY TO stdout e, ento, l/grava os dados em um arquivo acessvel ao cliente psql. Portanto, a acessibilidade e os direitos de acesso dependem do cliente e no do servidor, quando o \copy utilizado.

Notas
O comando COPY s pode ser utilizado em tabelas, no pode ser utilizado em vises.

COPY
A palavra chave BINARY fora todos os dados serem escritos/lidos no formato binrio em vez de texto. um
pouco mais rpido do que a cpia normal, mas o arquivo binrio produzido no portvel entre mquinas com
arquiteturas diferentes.
Por padro, a cpia no formato texto usa o caractere de tabulao ("\t") como delimitador de campos. O delimitador de campo pode ser mudado para qualquer outro caractere nico usando a palavra chave DELIMITER. Os
caracteres nos campos de dados que forem idnticos ao caractere delimitador sero precedidos por uma contrabarra.
necessrio possuir permisso de leitura em todas as tabelas cujos valores so lidos pelo COPY TO, e permisso para inserir em uma tabela onde valores so inseridos pelo COPY FROM. O servidor tambm necessita de
permisses apropriadas no Unix para todos os arquivos lidos ou escritos pelo COPY.
O comando COPY FROM invoca os gatilhos e as restries de verificao da tabela de destino. Entretanto, no
invoca as regras.
O COPY pra de executar no primeiro erro, o que no deve acarretar problemas para o COPY TO, mas a tabela
de destino j vai ter recebido linhas no caso do COPY FROM. Estas linhas no so visveis nem acessveis, mas
ocupam espao em disco, podendo ocasionar o desperdcio de uma grande quantidade de espao em disco se
o erro ocorrer durante a cpia de uma grande quantidade de dados. Deve-se executar o comando VACUUM para
recuperar o espao desperdiado.
Os arquivos declarados no comando COPY so lidos ou escritos diretamente pelo servidor, e no pelo aplicativo
cliente. Portanto, devem residir ou serem acessveis pela mquina servidora de banco de dados, e no pela estao
cliente. Os arquivos devem ser acessveis e poder ser lidos ou escritos pelo usurio do PostgreSQL (o ID do usurio
sob o qual O servidor processa), e no pelo cliente. O COPY com nome de arquivo s permitido aos superusurios
do banco de dados, porque permite ler e escrever em qualquer arquivo que o servidor possua privilgio de acesso.

Dica: A instruo \copy do psql l e escreve arquivos na estao cliente usando as permisses do cliente,
portanto no restrita aos superusurios.

Recomenda-se que os nomes dos arquivos usados no comando COPY sejam sempre especificados como um caminho absoluto, sendo exigido pelo servidor no caso do COPY TO, mas para COPY FROM existe a opo de ler um
arquivo especificado pelo caminho relativo. O caminho interpretado como sendo relativo ao diretrio de trabalho
do servidor (algum lugar abaixo de $PGDATA), e no relativo ao diretrio de trabalho do cliente.

Formatos dos Arquivo

Formato Texto
Quando o comando COPY utilizado sem a opo BINARY, o arquivo lido ou escrito um arquivo de texto com
uma linha para cada linha da tabela. As colunas (atributos) so separadas na linha pelo caractere delimitador. Os
valores dos atributos so cadeias de caracteres geradas pela funo de sada, ou aceitveis pela funo de entrada,
para cada tipo de dado de atributo. A cadeia de caracteres nula especificada utilizada no lugar dos atributos
que so nulos. O comando COPY FROM ocasiona um erro se alguma linha do arquivo de entrada possuir mais ou
menos colunas do que o esperado.
Se OIDS for especificado, o OID lido ou escrito como a primeira coluna, precedendo as colunas de dado do
usurio (Vai acontecer um erro se OIDS for especificado para uma tabela que no possua OIDs).

COPY
O fim dos dados pode ser representado por uma nica linha contendo apenas contrabarra-ponto (\.). Um marcador
de fim de dados no necessrio ao se ler de um arquivo Unix, porque o fim de arquivo serve perfeitamente bem;
mas um marcador de fim dos dados deve ser fornecido para copiar os dados de ou para um aplicativo cliente.
O caractere contrabarra (\) pode ser usado nos dados do comando COPY para evitar que caracteres dos dados
sejam interpretados como delimitadores de linha ou de coluna. Em particular, os seguintes caracteres devem ser
precedidos por uma contrabarra se aparecerem como parte do valor de um atributo: a prpria contrabarra, a novalinha e o caractere delimitador corrente.
As seguintes seqncias especiais de contrabarra so reconhecidas pelo comando COPY FROM:
Seqncia

Representa

\b

Backspace (ASCII 8)

\f

Avano de pgina (ASCII 12)

\n

Nova-linha (ASCII 10)

\r

Retorno do carro (ASCII 13)

\t

Tabulao (ASCII 9)

\v

Tabulao Vertical (ASCII 11)

\dgitos

A contrabarra seguida por um a trs dgitos octais

especifica o caractere com este cdigo numrico

Atualmente o COPY TO nunca gera uma seqncia contrabarra-dgitos-octais, mas as outras seqncias de contrabarra listadas acima so utilizadas para estes caracteres de controle.
Nunca coloque uma contrabarra antes dos caracteres de dado N ou ponto (.), seno os dois sero interpretados,
erroneamente, como a cadeia de caracteres nula padro e o marcador de fim dos dados, respectivamente. Qualquer
outro caractere no mencionado na tabela acima interpretado como representando a si prprio.
fortemente recomendado que os aplicativos que geram dados para o COPY convertam os caracteres de novalinha e de retorno-de-carro presentes nos dados em seqncias \n e \r respectivamente. No presente momento
(PostgreSQL 7.2 e verses mais antigas) possvel se representar um retorno-de-carro nos dados sem nenhuma
seqncia especial, e representar a nova-linha nos dados por uma contrabarra seguida por um caractere de novalinha. Entretanto, estas representaes no sero aceitas por padro nas verses futuras.
Observe que o fim de cada linha marcado por um caractere de nova-linha no estilo Unix (\n). Atualmente, o
COPY FROM no se comporta de forma adequada quando o arquivo especificado contm o fim de linha no estilo
MS-DOS ou Mac. Espera-se que isto mude em verses futuras.

Formato Binrio
O formato do arquivo usado pelo COPY BINARY mudou no PostgreSQL v7.1. O novo formato do arquivo consiste
em um cabealho, zero ou mais tuplas e um rodap.
Cabealho do Arquivo
O cabealho do arquivo consiste de 24 bytes para campos fixos, seguidos por uma rea de extenso do cabealho
de tamanho varivel. Os campos fixos so:
Assinatura
A seqncia de 12 bytes PGBCOPY\n\377\r\n\0 --- observe que o nulo uma parte requerida da assinatura
(A assinatura foi projetada para permitir a fcil identificao de arquivos corrompidos por uma transferncia
no apropriada. Esta assinatura modificada por filtros de traduo de nova-linha, nulos suprimidos, bits
altos suprimidos, ou mudanas de paridade).

COPY
Campo de disposio de inteiro
Constante int32 0x01020304 na ordem dos bytes da origem. Se uma ordem errada dos bytes for detectada
aqui, o leitor poder se envolver em uma mudana na ordem dos bytes dos campos posteriores.
Campo de sinalizadores
Mscara de bits int32 usada para caracterizar aspectos importantes do formato do arquivo. Os bits so numerados de 0 (LSB) at 31 (MSB) --- observe que este campo armazenado na ordem dos bytes da plataforma
de origem, assim como todos os campos inteiro posteriores. Os bits 16-31 so reservados para caracterizar
questes crticas do formato do arquivo; o leitor deve abortar se for encontrado um bit no esperado neste intervalo. Os bits 0-15 so reservados para sinalizar questes de formato precedente-compatveis; o leitor deve
simplesmente ignorar qualquer bit no esperado neste intervalo. Atualmente somente um bit sinalizador est
definido, os outros devem ser zero:
Bit 16
Se for igual a 1 os OIDs esto includos no arquivo; 0 caso contrrio.

Comprimento da rea de extenso do cabealho

Valor int32 do comprimento em bytes do restante do cabealho, no se incluindo. Na verso inicial ser
zero, com a primeira tupla vindo a seguir. Mudanas futuras no formato podem permitir a presena de
dados adicionais no cabealho. O leitor deve simplesmente desprezar qualquer dado da rea de extenso do
cabealho que no souber o que fazer com a mesma.

A rea de extenso do cabealho imaginada como contendo uma seqncia de blocos auto-identificantes. O
campo de sinalizadores no tem por finalidade informar os leitores o que existe na rea de extenso. O projeto
especfico do contedo da rea de extenso do cabealho foi deixado para uma verso futura.
Este projeto permite tanto adies de cabealho precedente-compatveis (adicionar blocos de extenso de
cabealho, ou sinalizar com bits de baixa-ordem) e mudanas no precedente-compatveis (usar bits de
alta-ordem para sinalizar estas mudanas, e adicionar dados de apoio para a rea de extenso se for necessrio).

Tuplas
Cada tupla comea com um contador (int16) do nmero de campos na tupla (atualmente todas as tuplas da tabela
possuem o mesmo contador, mas isto pode no ser verdade para sempre). Ento, repetido para cada campo da
tupla, existe uma palavra tipo-comprimento (typlen, int16) possivelmente seguida por um campo de dados. O
campo tipo-comprimento interpretado como:
Zero
O campo nulo. Nenhum dado segue.
>0
O campo possui um tipo de dado de comprimento fixo. Exatamente N bytes de dados seguem a palavra
tipo-comprimento (typlen).
-1
O campo possui um tipo de dado de comprimento varivel (varlena). Os prximos quatro bytes so o
cabealho, que contm o valor do comprimento total incluindo a si prprio.

COPY
< -1
Reservado para uso futuro.

Para campos no nulos, o leitor pode verificar se o tipo-comprimento (typlen) corresponde ao tipo-comprimento
esperado para a coluna de destino, fornecendo uma maneira simples, mas muito til, de verificar se o dado est
como o esperado.
No existe nenhum preenchimento de alinhamento ou qualquer dado extra entre os campos. Tambm observe que
o formato no distingue se um tipo de dado passado por referncia ou passado por valor. Estas duas disposies
so deliberadas: elas ajudam a melhorar a portabilidade dos arquivos (embora problemas relacionados com a
ordem dos bytes ou o formato do ponto flutuante podem impedir a troca de arquivos binrios entre computadores).
Se os OIDs so includos no arquivo, o campo OID segue imediatamente a palavra contador-de-campos. um
campo normal, exceto que no est includo no contador-de-campos. Em particular possui um tipo-comprimento
--- isto permite tratar OIDs de 4 bytes versus 8 bytes sem muita dificuldade, e permite os OIDs serem mostrados
como NULL se por acaso for desejado.

Rodap do Arquivo
O rodap do arquivo consiste em uma palavra int16 contendo -1, sendo facilmente distinguvel da palavra
contador-de-campos da tupla.
O leitor deve relatar um erro se a palavra contador-de-campos no for -1 nem o nmero esperado de colunas,
fornecendo uma verificao extra com relao a perda de sincronizao com os dados.

Utilizao
O exemplo a seguir copia uma tabela para a sada padro, usando a barra vertical (|) como delimitador de campo:
COPY paises TO stdout WITH DELIMITER |;

Para copiar dados de um arquivo Unix para a tabela paises:

COPY paises FROM /usr1/proj/bray/sql/paises.txt;

Abaixo est um exemplo de dados apropriados para se copiar para a tabela a partir de stdin (por isso possui a
seqncia de terminao na ltima linha):
AF
AL
DZ
ZM
ZW
\.

AFGHANISTAN
ALBANIA
ALGERIA
ZAMBIA
ZIMBABWE

Observe que os espaos em branco em cada linha so, na verdade, o caractere de tabulao.

COPY
Abaixo so os mesmos dados, escritos no formato binrio em uma mquina Linux/i586. Os dados mostrados
foram filtrados atravs do utilitrio do Unix od -c. A tabela possui trs campos: o primeiro char(2); o segundo
text; o terceiro integer. Todas as linhas possuem um valor nulo no terceiro campo.
0000000
P
G
B
C
O
P
0000020 \0 \0 \0 \0 \0 \0
0000040
A
F 377 377 017 \0
0000060
T
A
N \0 \0 003
0000100 377 \v \0 \0 \0
A
0000120 377 377 006 \0 \0 \0
0000140
G
E
R
I
A \0
0000160
M 377 377 \n \0 \0
0000200 \0 377 377 006 \0 \0
0000220
I
M
B
A
B
W

Y \n 377 \r \n \0 004 003 002 001

\0 \0 003 \0 377 377 006 \0 \0 \0
\0 \0
A
F
G
H
A
N
I
S
\0 377 377 006 \0 \0 \0
A
L 377
L
B
A
N
I
A \0 \0 003 \0
D
Z 377 377 \v \0 \0 \0
A
L
\0 003 \0 377 377 006 \0 \0 \0
Z
\0
Z
A
M
B
I
A \0 \0 003
\0
Z
W 377 377 \f \0 \0 \0
Z
E \0 \0 377 377

Compatibilidade
SQL92
No existe o comando COPY no SQL92.
A sintaxe mostrada abaixo era utilizada nas verses anteriores a 7.3 e ainda aceita:
COPY [ BINARY ] tabela [ WITH OIDS ]
FROM { nome_do_arquivo | stdin }
[ [USING] DELIMITERS delimitador ]
[ WITH NULL AS cadeia de caracteres nula ]
COPY [ BINARY ] tabela [ WITH OIDS ]
TO { nome_do_arquivo | stdout }
[ [USING] DELIMITERS delimitador ]
[ WITH NULL AS cadeia de caracteres nula ]

CREATE AGGREGATE
Nome
CREATE AGGREGATE cria uma funo de agregao

Sinopse
CREATE AGGREGATE nome ( BASETYPE = tipo_dado_entrada,
SFUNC = func_trans_estado, STYPE = tipo_dado_estado
[ , FINALFUNC = func_final ]
[ , INITCOND = cond_inicial ] )

Entradas
name
O nome (opcionalmente qualificado pelo esquema) da funo de agregao a ser criada.
tipo_dado_entrada
O tipo do dado de entrada sobre o qual esta funo de agregao opera. Pode ser especificado como "ANY"
para uma funo de agregao que no examina seus valores de entrada (um exemplo a funo count(*)).
func_trans_estado
O nome da funo de transio de estado a ser chamada para cada valor dos dados da entrada. Normalmente
esta uma funo com dois argumentos, o primeiro sendo do tipo tipo_dado_estado e o segundo do
tipo tipo_dado_entrada. Outra possibilidade, para uma funo de agregao que no examina seus
valores de entrada, a funo possuir apenas um argumento do tipo tipo_dado_estado. Em qualquer
um dos casos a funo deve retornar um valor do tipo tipo_dado_estado. Esta funo recebe o valor
atual do estado e o item atual de dado da entrada, e retorna o valor do prximo estado.
tipo_dado_estado
O tipo de dado do valor do estado da agregao.
func_final
O nome da funo final chamada para calcular o resultado da agregao aps todos os dados da entrada
terem sido percorridos. A funo deve possuir um nico argumento do tipo tipo_dado_estado. O tipo
de dado do valor da agregao definido pelo tipo do valor retornado por esta funo. Se func_final no
for especificado, ento o valor do estado final utilizado como sendo o resultado da agregao, e o tipo da
sada fica sendo o tipo_dado_estado.
cond_inicial
A atribuio inicial para o valor do estado. Deve ser uma constante literal na forma aceita pelo tipo de dado
tipo_dado_estado. Se no for especificado, o valor do estado comea com NULL.

CREATE AGGREGATE

Sadas
CREATE AGGREGATE

Mensagem retornada se o comando for executado com sucesso.

Descrio
O comando CREATE AGGREGATE permite ao usurio ou ao programador estender as funcionalidades do
PostgreSQL criando novas funes de agregao. Algumas funes de agregao para tipos base, como
min(integer) e avg(double precision) esto presentes na distribuio base. Se forem criados tipos
novos, ou se houver a necessidade de uma funo de agregao que no esteja presente, ento o comando
CREATE AGGREGATE pode ser utilizado para criar as funcionalidades desejadas.
Se o nome do esquema for fornecido (por exemplo, CREATE AGGREGATE meu_esquema.minha_agregacao
...) ento a funo de agregao criada no esquema especificado, seno criada no esquema corrente (aquele
na frente do caminho de procura; consulte o CURRENT_SCHEMA()).
Uma funo de agregao identificada pelo seu nome e pelo tipo de dado da entrada. Duas funes de agregao
no mesmo esquema podem possuir o mesmo nome no caso de operarem sobre dados de entrada de tipos diferentes.
O nome e o tipo de dado da entrada de uma funo de agregao tambm deve ser diferente do do nome e do tipo
de dado da entrada de todas as funes comuns no mesmo esquema.
Uma funo de agregao constituda de uma ou duas funes comuns: uma funo de transio de estado
func_trans_estado, e outra funo, opcional, para a realizao dos clculos finais func_final. Estas
funes so utilizadas da seguinte maneira:
func_trans_estado( estado-interno, prximo-item-dado ) ---> prximo-estado-interno
func_final( estado-interno ) ---> valor-da-agregao

O PostgreSQL cria uma varivel temporria do tipo tipo_dado_estado para armazenar o estado interno
atual da agregao. Para cada item de dado da entrada, a funo de transio de estado chamada para calcular
o novo valor do estado interno. Aps todos os dados terem sido processados, a funo final chamada uma vez
para calcular o valor de sada da agregao. Se no houver nenhuma funo final, ento o valor do estado final
retornado.
A funo de agregao pode possuir uma condio inicial, ou seja, um valor inicial para o valor de estado interno.
Este valor especificado e armazenado no banco de dados em um campo do tipo text, mas deve possuir uma
representao externa vlida de uma constante do tipo de dado do estado. Se no for especificado, ento o valor
do estado comea com NULL.
Se a funo de transio de estado for declarada como strict, ento no poder ser chamada com valores da
entrada nulos. Para este tipo de funo de transio, a execuo da agregao realizada da seguinte maneira.
Valores da entrada nulos so ignorados (a funo no chamada e o valor do estado anterior permanece). Se o
valor do estado inicial for nulo, ento o primeiro valor de entrada que no for nulo substitui o valor do estado,
e a funo de transio chamada a partir do segundo valor de entrada que no for nulo. Este procedimento
til para implementar funes de agregao como max. Note que este comportamento somente est disponvel
quando o tipo_dado_estado for do mesmo tipo do tipo_dado_entrada. Quando estes tipos de dado

CREATE AGGREGATE
forem diferentes, dever ser fornecido um valor no nulo para a condio inicial, ou utilizar uma funo de
transio que no seja estrita.
Se a funo de transio de estado no for estrita ento ser chamada, incondicionalmente, para cada valor da
entrada, devendo ser capaz de lidar com valores nulos da entrada e valores nulos de transio. Esta opo permite
ao autor da funo de agregao ter pleno controle sobre os valores nulos.
Se a funo final for declarada strict, esto no ser chamada quando o valor do estado final for nulo; em vez
disso, um resultado nulo ser produzido automaticamente ( claro que este apenas o comportamento normal de
funes estritas). De qualquer forma, a funo final tem sempre a opo de retornar nulo. Por exemplo, a funo
final para avg retorna nulo quando no h nenhum valor de entrada.

Notes
Use o comando DROP AGGREGATE para excluir funes de agregao.
Os parmetros do comando CREATE AGGREGATE podem ser escritos em qualquer ordem, e no apenas na ordem
mostrada acima.

Utilizao
Consulte o captulo sobre funes de agregao no Guia do Programador do PostgreSQL para ver exemplos
completos sobre a sua utilizao.

Compatibilidade
SQL92
O comando CREATE AGGREGATE uma extenso do PostgreSQL linguagem. No existe o comando CREATE
AGGREGATE no SQL92.

CREATE CAST
Nome
CREATE CAST cria uma transformao definida pelo usurio

Sinopse
CREATE CAST (tipo_de_origem AS tipo_de_destino)
WITH FUNCTION nome_da_funo (tipo_do_argumento)
[ AS ASSIGNMENT | AS IMPLICIT ]
CREATE CAST (tipo_de_origem AS tipo_de_destino)
WITHOUT FUNCTION
[ AS ASSIGNMENT | AS IMPLICIT ]

Descrio
O comando CREATE CAST cria uma nova transformao. A transformao especifica como realizar a converso
entre dois tipos de dados. Por exemplo,
SELECT CAST(42 AS text);

converte a constante inteira 42 para o tipo text chamando uma funo especificada previamente, neste caso
text(int4) (Se nenhuma transformao adequada existir a converso falha).
Dois tipos de dado podem ser binariamente compatveis, significando que podem ser convertidos um no outro
livremente, sem chamar qualquer funo. Requer que os valores correspondentes utilizem a mesma representao interna. Por exemplo, os tipos text e varchar so binariamente compatveis.
Por padro, a transformao pode ser chamada somente por uma chamada explcita, ou seja, uma construo
explcita CAST(x AS nome_do_tipo), x ::nome_do_tipo, ou nome_do_tipo(x).
Se a transformao for marcada como AS ASSIGNMENT ento pode ser chamada implicitamente quando for
atribudo um valor uma coluna com o tipo de dado de destino. Por exemplo, supondo-se que foo.f1 seja
uma coluna do tipo text, ento a atribuio
INSERT INTO foo(f1) VALUES(42);

somente permitida se a transformao do tipo integer para o tipo text estiver marcada como AS
ASSIGNMENT, seno a atribuio no permitida. (Geralmente utilizado o termo transformao de atribuio
[assignment cast] para descrever este tipo de transformao).
Se a transformao estiver maracada como AS IMPLICIT ento pode ser chamada implicitamente em qualquer
contexto, seja em uma atribuio ou internamente em uma expresso. Por exemplo, uma vez que || recebe
argumentos do tipo text, ento a expresso
SELECT Data e hora || now();

somente permitida se a transformao do tipo timestamp para o tipo text estiver marcada como AS
IMPLICIT, seno necessrio escrever a transformao explicitamente, como em
SELECT Data e hora || CAST(now() AS text);

CREATE CAST
(Geralmente utilizado o termo transformao implcita [implicit cast] para descrever este tipo de transformao).
aconselhvel ser conservador com relao a marcar as transformaes como implcitas. Uma abundncia de
possibilidades de transformaes implcitas pode fazer com que o PostgreSQL interprete o comando de forma
surpreendente, ou que no seja capaz de executar o comando devido existncia de vrias interpretaes possveis. Um boa regra bsica tornar as transformaes chamadas implicitamente disponveis apenas para as transformaes que preservam as informaes entre tipos da mesma categoria geral. Por exemplo, a transformao
de int2 em int4 pode ser implcita, mas uma transformao de float8 em int4 provavelmente s deve ser
permitida para atribuio. As transformaes entre tipos diferentes, como text em int4, melhor que sejam
somente explcitas.
Para poder criar uma transformao deve-se ser o dono do tipo de dado de origem ou de destino. Para criar
uma transformao binariamente compatvel necessrio ser um superusurio (esta restrio feita porque uma
transformao binariamente compatvel pode facilmente derrubar o servidor).

Parmetros
tipo_de_origem
O nome do tipo de dado de origem da transformao.
tipo_de_destino
O nome do tipo de dado de destino da transformao.
nome_da_funo(tipo_do_argumento)
A funo utilizada para realizar a transformao. O nome da funo pode ser qualificado pelo esquema. Se
no for, a funo ser procurada no caminho. O tipo do argumento deve ser idntico ao tipo da origem, e o
tipo do resultado deve corresponder ao tipo de destino da transformao.
WITHOUT FUNCTION

Indica que o tipo de dado de origem e o tipo de dado de destino so binariamente compatveis, e por isso
nenhuma funo necessria para realizar a transformao.
AS ASSIGNMENT

Indica que a transformao pode ser chamada implicitamente em contextos de atribuio.

AS IMPLICIT

Indica que a transformao pode ser chamada implicitamente em qualquer contexto.

Notas
Use o comando DROP CAST para remover as transformaes criadas pelo usurio.
Para ser possvel a converso de tipos nas duas direes necessrio declarar transformaes para as duas direes
explicitamente.
Antes do PostgreSQL 7.3 toda funo que possuia o mesmo nome de um tipo de dado, retornava este tipo de dado,
e recebia um argumento de um tipo diferente era automaticamente uma funo de transformao. Esta conveno
foi abandonada devido introduo dos esquemas e da capacidade de representar transformaes binariamente
compatveis nos catlogos (As funes de transformao primitivas ainda seguem esta nomenclatura, mas devem
ser mostradas como transformaes em pg_cast).

CREATE CAST

Exemplos
Para criar uma transformao do tipo text para o tipo int4 usando a funo int4(text):
CREATE CAST (text AS int4) WITH FUNCTION int4(text);

(Esta transformao j pr-existente no sistema).

Compatibilidade
O comando CREATE CAST est em conformidade com o SQL99, exceto que o SQL99 no prev os tipos binariamente compatveis. A clusula AS IMPLICIT tambm uma extenso do PostgreSQL.

Consulte tambm
CREATE FUNCTION, CREATE TYPE, DROP CAST, Guia do Programador do PostgreSQL

CREATE CONSTRAINT TRIGGER

Nome
CREATE CONSTRAINT TRIGGER cria um gatilho de restrio

Sinopse
CREATE CONSTRAINT TRIGGER nome
AFTER eventos ON
relao restrio atributos
FOR EACH ROW EXECUTE PROCEDURE funo ( args )

Entradas
nome
O nome do gatilho de restrio.
eventos
As categorias dos eventos para as quais este gatilho deve ser disparado.
relao
O nome (opcionalmente qualificado pelo esquema) da relao cujos eventos disparam o gatilho.
restrio
Especificao da restrio.
atributos
Atributos da restrio.
funo(args)
Funo a ser chamada como parte do processamento do gatilho.

Sadas
CREATE TRIGGER

Mensagem retornada se o comando for executado com sucesso.

CREATE CONSTRAINT TRIGGER

Descrio
O comando CREATE CONSTRAINT TRIGGER utilizado dentro do comando CREATE/ALTER TABLE e pelo
pg_dump para criar gatilhos especiais para a integridade referencial.
No h a inteno de ser para uso geral.

CREATE CONVERSION
Nome
CREATE CONVERSION cria uma converso definida pelo usurio

Sinopse
CREATE [DEFAULT] CONVERSION nome_da_converso
FOR codificao_de_origem TO codificao_de_destino FROM nome_da_funo

Descrio
O comando CREATE CONVERSION cria uma nova converso de codificao. Os nomes das converses podem
ser usados na funo CONVERT() para especificar uma converso de codificao em particular. Alm disso, as
converses que so marcadas como DEFAULT podem ser usadas para fazer a converso automtica de codificao
entre o cliente e o servidor. Para esta finalidade duas converses de codificao devem existir, de A para B e de B
para A.
Para poder criar uma converso, deve-se possuir o direito de executar a funo e o direito de criar no esquema de
destino.

Parmetros
DEFAULT

A clusula DEFAULT indica que esta a converso padro para o caso destas codificaes de origem e de
destino em particular. Deve existir apenas uma converso padro para um determinado par de codificaes
em um esquema.
nome_da_converso
O nome da converso. O nome da converso pode ser qualificado pelo esquema. Se no for, a converso
criada no esquema corrente. O nome da converso deve ser inico no esquema.
codificao_de_origem
O nome da codificao de origem.
codificao_de_destino
O nome da codificao de destino.
nome_da_funo
A funo utilizada para realizar a converso. O nome da funo pode ser qualificado pelo esquema. Se no
for, a funo procurada no caminho.
A funo deve possuir a seguinte assinatura:
funcao_de_conversao(
INTEGER, -- identificador da codificao de origem
INTEGER, -- identificador da codificao de destino
CSTRING, -- cadeia de caracteres de origem (cadeia de caracteres C terminada por nulo)
CSTRING, -- cadeia de caracteres de destino (cadeia de caracteres C terminada por nulo)
INTEGER -- comprimento da cadeia de caracteres de origem
) returns VOID;

CREATE CONVERSION

Notas
Use o comando DROP CONVERSION para remover as converses definidas pelo usurio.
Os privilgios necessrios para criar uma converso podem ser alterados em um verso futura.

Exemplos
Para criar uma converso da codificao UNICODE para LATIN1 utilizando minha_funcao:
CREATE CONVERSION minha_conversao FOR UNICODE TO LATIN1 FROM minha_funcao;

Compatibilidade
O comando CREATE CONVERSION uma extenso do PostgreSQL. No existe o comando CREATE CONVERSION
no SQL99.

Consulte tambm
CREATE FUNCTION, DROP CONVERSION, Guia do Programador do PostgreSQL

CREATE DATABASE
Nome
CREATE DATABASE cria um banco de dados

Sinopse
CREATE DATABASE nome
[ [ WITH ] [ OWNER [=] dono_bd ]
[ LOCATION [=] caminho_bd ]
[ TEMPLATE [=] gabarito ]
[ ENCODING [=] codificao ] ]

Entradas
nome
O nome do banco de dados a ser criado.
dono_bd
O nome do usurio do banco de dados que ser o dono do novo banco de dados, ou DEFAULT para usar o
padro (ou seja, o usurio que est executando o comando).
caminho_bd
Um local alternativo no sistema de arquivos onde ser armazenado o banco de dados, especificado como uma
cadeia de caracteres; ou DEFAULT para utilizar o local padro.
gabarito
Nome do banco de dados a ser usado como gabarito para a criao do novo banco de dados, ou DEFAULT
para utilizar o banco de dados de gabarito padro (template1).
codificao
Mtodo de codificao multibyte a ser utilizado no novo banco de dados. Especifique o nome como uma
cadeia de caracteres (por exemplo, SQL_ASCII), ou o nmero inteiro da codificao, ou DEFAULT para
utilizar a codificao padro.

Sadas
CREATE DATABASE

Mensagem retornada se o comando for executado com sucesso.

ERROR: user nome_do_usurio is not allowed to create/drop databases

necessrio possuir o privilgio especial CREATEDB para criar bancos de dados. Consulte o comando CREATE USER.

CREATE DATABASE
ERROR: createdb: database "nome" already exists

Esta mensagem ocorre se o banco de dados com o nome especificado j existir.

ERROR: database path may not contain single quotes

O local do banco de dados especificado em caminho no pode conter apstrofos (). Isto necessrio para
que o interpretador de comandos, que vai criar o diretrio do banco de dados, possa executar com segurana.
ERROR: CREATE DATABASE: may not be called in a transaction block

Havendo um bloco de transao explcito sendo executado no possvel utilizar o comando CREATE
DATABASE. Primeiro a transao deve terminar.
ERROR: Unable to create database directory caminho_bd.
ERROR: Could not initialize database directory.

Estas mensagens esto relacionadas com a falta de permisso no diretrio de dados, o disco estar cheio, ou
outro problema no sistema de arquivos. O usurio, sob o qual o servidor de banco de dados est processando,
deve ter permisso para o local.

Descrio
O comando CREATE DATABASE cria um banco de dados novo no PostgreSQL.
Normalmente, o criador se torna o dono do novo banco de dados. Os superusurios podem criar bancos de dados
cujos donos so outros usurios utilizando a clusula OWNER e, at mesmo, criar bancos de dados cujos donos so
usurios sem nenhum privilgio especial. Usurios comuns com o privilgio de CREATEDB somente podem criar
bancos de dados cujos donos so eles mesmos.
Um local alternativo pode ser especificado com a finalidade de, por exemplo, armazenar o banco de dados em um
disco diferente. O caminho deve ter sido preparado anteriormente com o comando initlocation.
Se o nome do caminho no possuir uma barra (/) interpretado como sendo o nome de uma varivel de ambiente,
a qual deve ser conhecida pelo servidor. Desta maneira, o administrador do banco de dados pode exercer controle
sobre os locais onde os bancos de dados podem ser criados (Uma escolha usual , por exemplo, PGDATA2). Se o
servidor for compilado com ALLOW_ABSOLUTE_DBPATHS (o que no feito por padro), nomes de caminhos absolutos, identificados por uma barra inicial (por exemplo, /usr/local/pgsql/data), tambm so permitidos.
Por padro, o novo banco de dados ser criado clonando o banco de dados padro do sistema template1.
Um gabarito diferente pode ser especificado escrevendo-se TEMPLATE = nome. Em particular, escrevendo-se
TEMPLATE = template0, pode ser criado um banco de dados bsico contendo apenas os objetos padro predefinidos pela verso do PostgreSQL sendo utilizada. Esta forma til quando se deseja evitar a cpia de qualquer
objeto da instalao local que possa ter sido adicionado ao template1.
O parmetro opcional de codificao permite a escolha de uma codificao para o banco de dados, se o servidor
em uso foi compilado com suporte codificao multibyte. Quando este parmetro no especificado, o padro
utilizar a mesma codificao do banco de dados usado como gabarito.
Os parmetros opcionais podem ser escritos em qualquer ordem, e no apenas na ordem mostrada acima.

Notas
O comando CREATE DATABASE uma extenso da linguagem do PostgreSQL.
Use o comando DROP DATABASE para excluir um banco de dados.

CREATE DATABASE
O aplicativo createdb um script envoltrio criado em torno deste comando, fornecido por convenincia.
Existem questes associadas segurana e integridade dos dados envolvidas na utilizao de locais alternativos
para os bancos de dados especificados por caminhos absolutos. Por isso, pelo padro, somente uma varivel de
ambiente conhecida pelo gerenciador de banco de dados pode ser especificada para um local alternativo. Consulte
o Guia do Administrador do PostgreSQL para obter mais informaes.
Embora seja possvel copiar outros bancos de dados alm do template1 especificando-se seu nome como gabarito, no se pretende (pelo menos ainda) que seja uma funcionalidade para COPY DATABASE de uso geral.
recomendado que os bancos de dados utilizados como gabarito sejam tratados como se fossem apenas de leitura.
Consulte o Guia do Administrador do PostgreSQL para obter mais informaes.

Utilizao
Para criar um banco de dados novo:
silva=> create database lusiadas;

Para criar um banco de dados novo na rea alternativa ~/bd_privado:

$ mkdir bd_privado
$ initlocation ~/bd_privado
The location will be initialized with username "silva".
This user will own all the files and must also own the server process.
Creating directory /home/silva/bd_privado
Creating directory /home/silva/bd_privado/base
initlocation is complete.

$ psql silva
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

silva=>

CREATE DATABASE outro_lugar WITH LOCATION = /home/silva/bd_privado;

CREATE DATABASE

CREATE DATABASE

Compatibilidade
SQL92
No existe o comando CREATE DATABASE no SQL92. Os bancos de dados so equivalentes aos catlogos cuja
criao definidas pela implementao.

CREATE DOMAIN
Nome
CREATE DOMAIN cria um domnio

Sinopse
CREATE DOMAIN nome_do_domnio [AS] tipo_de_dado
[ DEFAULT expresso_padro ]
[ restrio [, ... ] ]
onde restrio :
[ CONSTRAINT nome_da_restrio ]
{ NOT NULL | NULL }

Parmetros
nome_do_domnio
O nome (opcionalmente qualificado pelo esquema) do domnio sendo criado.
tipo_de_dado
O tipo de dado subjacente do domnio, podendo incluir especificadores de matrizes (arrays). Consulte o
Guia do Usurio para obter mais informaes sobre tipos de dados e matrizes (arrays).
DEFAULT expresso_padro

A clusula DEFAULT especifica o valor padro para as colunas com o tipo de dado do domnio. O valor
qualquer expresso varivel livre (mas as subconsultas no so permitidas). O tipo de dado da expresso
padro deve corresponder ao tipo de dado do domnio.
A expresso padro usada em toda operao de incluso que no especifica o valor da coluna. Se no
houver valor padro para o domnio, o padro NULL.
Nota: Se o valor padro for especificado para uma determinada coluna, este valor padro prevalece
sobre qualquer valor padro associado com o domnio. Por sua vez, o padro do domnio prevalece
sobre qualquer padro associado ao o tipo de dado subjacente.

CONSTRAINT nome_da_restrio

Um nome opcional para a restrio. Se no for especificado, o sistema gera um nome.

NOT NULL

Os valores para este domnio no podem ser nulos.

NULL

Os valores para este domnio podem ser nulos. Este o padro.

Esta clusula est disponvel somente para manter a compatibilidade com os bancos de dados SQL fora do
padro. Seu uso desaconselhado nos novos aplicativos.

CREATE DOMAIN

Sadas
CREATE DOMAIN

Mensagem retornada se o domnio for criado com sucesso.

Descrio
O comando CREATE DOMAIN permite ao usurio registrar um novo domnio de dados no PostgreSQL para ser
usado no banco de dados corrente. O usurio que cria o domnio se torna o seu dono.
Se o nome do esquema for fornecido (por exemplo, CREATE DOMAIN meu_esquema.meu_dominio ...) ento
o domnio criado no esquema especificado, seno criado no esquema corrente (aquele na frente do caminho de
procura; consulte o CURRENT_SCHEMA()). O nome do domnio deve ser nico entre os tipos e domnios existentes
em seu esquema.
Os domnios so teis para abstrair campos comuns entre tabelas em um nico lugar para manuteno. Uma
coluna de endereo de correio eletrnico pode ser usada em vrias tabelas, sempre com as mesmas propriedades.
Pode-se criar um domnio e us-lo em vez de especificar as restries em cada tabela individualmente.

Exemplos
Este exemplo cria o tipo de dado cod_nacao (cdigo da nao) usando-o em seguida na especificao da tabela:
CREATE DOMAIN cod_nacao char(2) NOT NULL;
CREATE TABLE tbl_nacao (id INT4, nacao cod_nacao);

Compatibilidade
O padro SQL99 define o comando CREATE DOMAIN, mas especifica que o nico tipo de restrio permitido
o de verificao (CHECK). As restries de verificao para os domnios ainda no so aceitas pelo PostgreSQL.

Consulte tambm
DROP DOMAIN, Guia do Programador do PostgreSQL

CREATE FUNCTION
Nome
CREATE FUNCTION cria uma funo

Sinopse
CREATE [ OR REPLACE ] FUNCTION nome ( [ tipo_do_argumento [, ...] ] )
RETURNS tipo_retornado
{ LANGUAGE nome_da_linguagem
| IMMUTABLE | STABLE | VOLATILE
| CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
| [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER
| AS definio
| AS arquivo_objeto, smbolo_de_ligao
} ...
[ WITH ( atributo [, ...] ) ]

Descrio
O comando CREATE FUNCTION cria uma nova funo. O comando CREATE OR REPLACE FUNCTION tanto cria
uma nova funo, quanto substitui uma funo existente.
O usurio que cria a funo se torna o seu dono.

Parmetros
nome
O nome da funo a ser criada. Se o nome do esquema for includo ento a funo criada no esquema
especificado, seno criada no esquema corrente (aquele na frente do caminho de procura; consulte
CURRENT_SCHEMA()). O nome da nova funo no deve ser igual ao de qualquer outra funo existente no
mesmo esquema, que tenha os mesmos tipos de argumentos. Entretanto, funes com argumentos de tipos
diferentes podem ter o mesmo nome, o que chamado de sobrecarga (overloading).
tipo_do_argumento
Os tipos dos argumentos da funo, caso existam. Os tipos de dado da entrada podem ser o tipo base, complexo, de domnio, ou o mesmo tipo de uma coluna existente. O tipo de dado da coluna referenciado
escrevendo-se nome_da_tabela.nome_da_coluna%TYPE; utilizando-se esta notao ajuda a funo
se tornar independente das mudanas ocorridas na estrutura da tabela. Dependendo da linguagem de implementao tambm pode ser permitido especificar pseudo-tipos, como cstring. Pseudo-tipos indicam que
o tipo do argumento no est completamente especificado, ou que est fora do conjunto usual de tipos de
dado do SQL.
tipo_retornado
O tipo do dado retornado. O tipo de dado retornado pode ser especificado como um tipo base, complexo,
de domnio, ou o mesmo tipo tipo de uma coluna existente. Dependendo da linguagem de implementao
tambm pode ser permitido especificar pseudo-tipos, como cstring. O modificador setof indica que a
funo retorna um conjunto de itens, em vez de um nico item.

CREATE FUNCTION
nome_da_linguagem
O nome da linguagem em que a funo est implementada. Pode ser SQL, C, internal, ou o nome de
uma linguagem procedural criada pelo usurio (Consulte tambm o aplicativo createlang). Para manter a
compatibilidade com as verses anteriores, o nome pode estar entre apstrofos ().
IMMUTABLE
STABLE
VOLATILE
Estes atributos informam ao sistema se seguro substituir vrias chamadas funo por uma nica chamada,
para otimizar o tempo de execuo. Deve ser especificado no mximo um dos trs atributos. Se nenhum deles
for especificado, o padro utilizar VOLATILE.
O atributo IMMUTABLE indica que a funo sempre retorna o mesmo resultado, quando so fornecidos os
mesmos valores para os argumentos, ou seja, no faz consultas a bancos de dados ou de alguma outra forma
utiliza informaes que no estejam diretamente presentes nos parmetros. Se este atributo for usado, qualquer chamada funo com os mesmos argumentos pode ser imediatamente substituda pelo resultado da
funo.
O atributo STABLE indica que dentro da mesma varredura da tabela a funo retorna o mesmo resultado para
os mesmos valores dos argumentos, mas que este resultado pode variar entre comandos SQL. Esta a seleo
apropriada para as funes cujos resultados dependem de consultas a bancos de dados, valores de parmetros
(como a zona horria corrente), etc... Observe tambm que a famlia de funes CURRENT_TIMESTAMP se
qualifica como estvel, uma vez que seus valores no mudam dentro de uma transao.
O atributo VOLATILE indica que o valor do resultado da funo pode mudar mesmo dentro da mesma
varredura da tabela, e portanto nenhuma otimizao pode ser feita. Bem poucas funes de banco de dados
so volteis neste sentido; alguns exemplos so random(), currval() e timeofday(). Observe que toda
funo que possua efeito colateral deve ser classificada como voltil, mesmo que o resultado seja bastante
previsvel, para previnir que as chamadas sejam otimizadas; um exemplo setval().
CALLED ON NULL INPUT
RETURNS NULL ON NULL INPUT
STRICT
CALLED ON NULL INPUT (o padro) indica que a funo chamada normalmente mesmo quando algum

de seus argumentos nulo. Portanto, responsabilidade do autor da funo verificar a presena de valores
nulos se for necessrio, e responder de forma apropriada.
RETURNS NULL ON NULL INPUT ou STRICT indica que a funo sempre retorna NULL quando qualquer

um de seus argumentos for NULL. Se este parmetro for especificado a funo no ser executada quando
existir argumento NULL; em vez disto um resultado NULL assumido automaticamente.
[EXTERNAL] SECURITY INVOKER
[EXTERNAL] SECURITY DEFINER
SECURITY INVOKER indica que a funo deve ser executada com os privilgios do usurio que faz a
chamada. Este o padro. SECURITY DEFINER especifica que a funo deve ser executada com os priv-

ilgios do usurio que a criou.

A palavra chave EXTERNAL est presente para manter a compatibilidade com o SQL, mas opcional uma
vez que, diferentemente do SQL, esta funcionalidade no se aplica somente s funes externas.
definio
Uma cadeia de caracteres contendo a definio da funo; o significado depende da linguagem. Pode ser o
nome de uma funo interna, o caminho para um arquivo objeto, uma consulta SQL, ou um texto escrito em
uma linguagem procedural.

CREATE FUNCTION
arquivo_objeto, simbolo_de_ligao
Esta forma da clusula AS usada para funes escritas na linguagem C, ligadas dinamicamente, quando
o nome da funo no cdigo fonte da linguagem C no o mesmo nome da funo SQL. A cadeia de
caracteres arquivo_objeto o nome do arquivo contendo o objeto carregado dinamicamente, e
simbolo_de_ligao o smbolo de ligao do objeto, ou seja, o nome da funo no cdigo fonte
escrito na linguagem C.
atributo
A forma histrica de se especificar informaes opcionais sobre a funo. Os seguintes atributos podem ser
utilizados:
isStrict

Equivalente ao STRICT ou ao RETURNS NULL ON NULL INPUT

isCachable
isCachable uma forma obsoleta equivalente ao IMMUTABLE; ainda aceito por motivo de compati-

bilidade com as verses anteriores.

No so diferenciadas letras minsculas de maisculas nos nomes dos atributos.

Notas
Consulte o captulo do Guia do Programador do PostgreSQL relativo extenso do PostgreSQL atravs de
funes para obter mais informaes sobre como escrever funes externas.
A sintaxe completa do SQL permitida para os argumentos de entrada e o valor retornado. Entretanto, alguns
detalhes da especificao do tipo (por exemplo, a preciso para tipos numeric) so responsabilidade da implementao da funo subjacente sendo silenciosamente aceitos pelo comando CREATE FUNCTION (ou seja, no
so reconhecidos ou exigidos).
O PostgreSQL permite a sobrecarga de funo, ou seja, o mesmo nome pode ser usado por vrias funes diferentes desde que possuam argumentos com tipos diferentes. Entretanto, esta funcionalidade deve ser usada com
cuidado para as funes internas e para as funes escritas na linguagem C.
Duas funes internal no podem possuir o mesmo nome no cdigo C sem causar erros durante a fase de
ligao. Para contornar este problema deve-se dar nomes diferentes no cdigo C (por exemplo, usar os tipos dos
argumentos como parte do nome no cdigo C), ento especificar este nome na clusula AS do comando CREATE
FUNCTION. Se a clusula AS for omitida, ento CREATE FUNCTION assume que o nome da funo no cdigo C
tem o mesmo nome do SQL.
Analogamente, ao se sobrecarregar o nome das funes SQL atravs de vrias funes escritas na linguagem C,
deve ser dado a cada instncia da funo na linguagem C um nome distinto e, ento, usar a forma alternativa da
clusula AS na sintaxe do CREATE FUNCTION para selecionar a implementao apropriada na linguagem C de
cada funo SQL sobrecarregada.
Quando chamadas repetidas ao comando CREATE FUNCTION fazem referncia ao mesmo arquivo objeto, o arquivo s carregado uma vez. Para descarregar e carregar o arquivo (talvez durante a fase de desenvolvimento),
use o comando LOAD.
Use o comando DROP FUNCTION para remover as funes definidas pelo usurio.
Para atualizar a definio de uma funo existente use o comando CREATE OR REPLACE FUNCTION. Observe
que no possvel mudar o nome ou os tipos dos argumentos da funo desta forma (se for tentado, ser criada

CREATE FUNCTION
uma nova funo distinta). O comando CREATE OR REPLACE FUNCTION tambm no permite que se mude o
tipo do valor retornado de uma funo existente. Para fazer isto, a funo deve ser removida e recriada.
Se a funo for removida e recriada, a nova funo no mais a mesma entidade que era antes; ficaro invlidas
as regras, vises, gatilhos, etc... existentes que faziam referncia antiga funo. Use o comando CREATE OR
REPLACE FUNCTION para mudar a definio de uma funo, sem invalidar os objetos que fazem referncia
funo.
Para poder criar uma funo o usurio deve possuir o privilgio USAGE na linguagem.
Por padro, somente o dono (criador) da funo possui o direito de execut-la. Aos outros usurios deve ser
concedido o privilgio EXECUTE na funo para que possam execut-la.

Exemplos
Para criar uma funo SQL simples:
CREATE FUNCTION um() RETURNS integer
AS SELECT 1 AS RESULTADO;
LANGUAGE SQL;
SELECT um() AS resposta;
resposta
---------1

Este exemplo cria uma funo C chamando a rotina de uma biblioteca compartilhada criada pelo usurio chamada
funcs.so (a extenso pode variar entre plataformas). O arquivo contendo a biblioteca compartilhada procurado no caminho de procura de biblioteca compartilhada do servidor. Esta rotina em particular calcula o dgito
verificador e retorna TRUE se o dgito verificador dos parmetros da funo est correto. A inteno utilizar
esta funo numa restrio de verificao (CHECK).
CREATE FUNCTION ean_checkdigit(char, char) RETURNS boolean
AS funcs LANGUAGE C;
CREATE TABLE product (
id
char(8) PRIMARY KEY,
eanprefix char(8) CHECK (eanprefix ~ [0-9]{2}-[0-9]{5})
REFERENCES brandname(ean_prefix),
eancode
char(6) CHECK (eancode ~ [0-9]{6}),
CONSTRAINT ean
CHECK (ean_checkdigit(eanprefix, eancode))
);

No prximo exemplo criada uma funo que faz a converso de tipo, do tipo complexo definido pelo usurio
e o tipo nativo point. A funo implementada por um objeto carregado dinamicamente que foi compilado a
partir de um fonte C (est ilustrada a alternativa obsoleta de se especificar o caminho absoluto para o arquivo
contendo o objeto compartilhado). Para o PostgreSQL encontrar a funo de converso de tipo automaticamente,
a funo SQL deve ter o mesmo nome do tipo retornado, e por isso a sobrecarga inevitvel. O nome da funo
sobrecarregado utilizando-se a segunda forma da clusula AS na definio SQL:
CREATE FUNCTION point(complex) RETURNS point
AS /home/bernie/pgsql/lib/complex.so, complex_to_point
LANGUAGE C STRICT;

CREATE FUNCTION
A declarao em C da funo poderia ser:
Point * complex_to_point (Complex *z)
{
Point *p;
p = (Point *) palloc(sizeof(Point));
p->x = z->x;
p->y = z->y;
return p;
}

Note que a funo est marcada como strict, o que evita verificar a entrada nula no corpo da funo.

Compatibilidade
O comando CREATE FUNCTION definido no SQL99. A verso do PostgreSQL similar mas no totalmente
compatvel. Os atributos no so portveis, nem as diferentes linguagens disponveis o so.

Consulte tambm
DROP FUNCTION, GRANT, LOAD, REVOKE, createlang, Guia do Programador do PostgreSQL

CREATE GROUP
Nome
CREATE GROUP cria um grupo de usurios

Sinopse
CREATE GROUP nome [ [ WITH ] opo [ ... ] ]
onde opo pode ser:
SYSID gid
| USER nome_usurio [, ...]

Entradas
nome
O nome do grupo.
gid
A clusula SYSID pode ser utilizada para escolher o identificador do novo grupo no PostgreSQL. Entretanto,
no h necessidade de ser utilizada.
Se esta clusula no for especificada, o valor do identificador mais alto atribudo a um grupo, acrescido de
um, comeando por 1, ser utilizado por padro.
nome_usurio
A relao dos usurios a serem includos no grupo. Os usurios devem existir.

Sadas
CREATE GROUP

Mensagem retornada se o comando for executado com sucesso.

Descrio
O comando CREATE GROUP cria um novo grupo na instalao de banco de dados. Consulte o Guia do Administrador do PostgreSQL para obter mais informaes sobre a utilizao de grupos para autenticao. necessrio
ser um superusurio do banco de dados para executar este comando.

CREATE GROUP
Use o ALTER GROUP para incluir ou excluir usurios no grupo, e o DROP GROUP para excluir um grupo.

Utilizao
Criar um grupo vazio:
CREATE GROUP engenharia;

Criar um grupo com membros:

CREATE GROUP vendas WITH USER jonas, marcela;

Compatibilidade
SQL92
No existe o comando CREATE GROUP no SQL92. O conceito de roles similar ao de grupos.

CREATE INDEX
Nome
CREATE INDEX cria um ndice

Sinopse
CREATE [ UNIQUE ] INDEX nome_do_ndice ON tabela
[ USING mtodo_de_acesso ] ( coluna [ nome_do_operador ] [, ...] )
[ WHERE predicado ]
CREATE [ UNIQUE ] INDEX nome_do_ndice ON tabela
[ USING mtodo_de_acesso ] ( nome_da_funo( coluna [, ... ]) [ nome_do_operador ] )
[ WHERE predicado ]

Entradas
UNIQUE
Faz com que o sistema procure por valores duplicados na tabela quando o ndice criado, se existirem dados
na tabela, e sempre que novos dados forem adicionados. A tentativa de inserir ou de atualizar dados, que
produza um valor duplicado, gera um erro.
nome_do_ndice
O nome do ndice a ser criado. O nome do esquema no pode ser includo aqui; o ndice sempre criado no
mesmo esquema da tabela a que pertence.
tabela
O nome (opcionalmente qualificado pelo esquema) da tabela a ser indexada.
mtodo_de_acesso
O nome do mtodo de acesso a ser utilizado pelo o ndice. O mtodo de acesso padro BTREE. O PostgreSQL implementa quatro mtodos de acesso para os ndices:
BTREE

uma implementao das B-trees de alta concorrncia de Lehman-Yao.

RTREE

implementa R-trees padro, utilizando o algoritmo de partio quadrtica de Guttman.

HASH

uma implementao das disperses lineares de Litwin.

GIST

Generalized Index Search Trees (rvores de Procura de ndice Generalizadas).

coluna
O nome de uma coluna da tabela.

CREATE INDEX
ops_name
Uma classe de operador associada. Veja abaixo para obter mais detalhes.
nome_da_funo
Uma funo que retorna um valor que pode ser indexado.
predicado
Define a expresso da restrio (constraint) para o ndice parcial.

Sadas
CREATE INDEX

Mensagem retornada se o ndice for criado com sucesso.

ERROR: Cannot create index: nome_do_ndice already exists.

Este erro ocorre se for impossvel criar o ndice.

Descrio
O comando CREATE INDEX constri o ndice nome_do_ndice na tabela especificada.
Dica: Os ndices so utilizados, principalmente, para melhorar o desempenho do banco de dados, mas a
utilizao no apropriada causa uma degradao do desempenho.

Na primeira sintaxe exibida acima, os campos chave para o ndice so especificados como nomes de coluna.
Vrios campos podem ser especificados, se o mtodo de acesso do ndice suportar ndices com mltiplas colunas.
Na segunda sintaxe exibida acima, o ndice criado usando o resultado da funo definida pelo usurio
nome_da_funo aplicada sobre uma ou mais colunas de uma nica tabela. Estes ndices funcionais podem
ser utilizados para obter acesso rpido aos dados baseado em operadores que normalmente iriam requerer alguma
transformao para aplic-los aos dados base. Por exemplo, um ndice funcional em upper(col) permite que a
clusula WHERE upper(col) = JIM use um ndice.
O PostgreSQL implementa os mtodos de acesso B-tree, R-tree, hash e GiST para os ndices. O mtodo
de acesso B-tree uma implementao das B-trees de alta concorrncia de Lehman-Yao. O mtodo de acesso
R-tree implementa R-trees padro utilizando o algoritmo de partio quadrtica de Guttman. O mtodo de
acesso hash uma implementao das disperses lineares de Litwin. Os algoritmos utilizados so mencionados apenas para informar que todos estes mtodos de acesso so inteiramente dinmicos, no necessitando de
otimizao peridica (como no caso de, por exemplo, mtodos de acesso hash estticos).
Quando a clusula WHERE est presente, um ndice parcial criado. Um ndice parcial um ndice que contm
entradas apenas para uma parte da tabela, geralmente uma parte mais interessante do que o resto da tabela.

CREATE INDEX
Por exemplo, havendo uma tabela contendo tanto pedidos faturados quanto no faturados, onde os pedidos no
faturados ocupam uma pequena frao da tabela, mas a parte mais consultada, o desempenho pode ser melhorado
criando-se um ndice apenas para esta poro da tabela. Uma outra aplicao possvel a utilizao da clusula
WHERE junto com UNIQUE para exigir a unicidade de um subconjunto dos dados da tabela.
A expresso utilizada na clusula WHERE pode referenciar apenas as colunas da tabela subjacente (mas pode referenciar qualquer coluna, e no apenas as que esto sendo indexadas). Na forma atual, subconsultas e expresses
de agregao no so permitidas na clusula WHERE.
Todas as funes e operadores utilizados por um ndice devem ser imutveis (immutable), ou seja, seus resultados
devem depender apenas de seus argumentos de entrada e nunca de uma influncia externa (como o contedo de
outra tabela ou a hora atual). Esta restrio garante que o comportamento do ndice bem preciso. Para utilizar
uma funo definida pelo usurio em um ndice deve ser utilizado o atributo immutable na clusula WITH.
Use o DROP INDEX para excluir um ndice.

Notas
O otimizador de consultas do PostgreSQL vai considerar o uso de um ndice B-tree sempre que um atributo
indexado estiver envolvido em uma comparao utilizando um dos seguintes operadores: <, <=, =, >=, >
O otimizador de consultas do PostgreSQL vai considerar o uso de um ndice R-tree sempre que um atributo
indexado estiver envolvido em uma comparao utilizando um dos seguintes operadores: <<, &<, &>, >>, @,
~=, &&
O otimizador de consultas do PostgreSQL vai considerar o uso de um ndice hash sempre que um atributo
indexado estiver envolvido em uma comparao utilizando o operador =.
Os testes mostraram que os ndices hash do PostgreSQLs so semelhantes ou mais lentos do que os ndices
B-tree, e que o tamanho do ndice e o tempo para gerar os ndices hash so muito piores. Os ndices hash
tambm tm seu desempenho degradado sob alta concorrncia. Por estes motivos, a utilizao dos ndices hash
desaconselhada.
Atualmente somente os mtodos de acesso B-tree e Gist suportam ndices com mais de uma coluna. Por
padro, at 32 chaves podem ser especificadas (este limite pode ser alterado na gerao do PostgreSQL). Na
implementao atual, somente o B-tree suporta ndices nicos.
Uma classe de operador pode ser especificada para cada coluna de um ndice. A classe de operador identifica os
operadores a serem utilizados pelo ndice desta coluna. Por exemplo, um ndice B-tree sobre inteiros de quatro
bytes vai utilizar a classe de operadores int4_ops; esta classe de operadores inclui funes de comparao para
inteiros de quatro bytes. Na prtica, a classe de operadores padro para o tipo de dado do campo normalmente
suficiente. O ponto principal em haver classes de operadores que, para alguns tipos de dado, pode haver mais de
uma ordenao que faa sentido. Por exemplo, pode se desejar ordenar o tipo de dado do nmero complexo tanto
pelo valor absoluto, quanto pela parte real, o que pode ser feito definindo-se duas classes de operadores para o
tipo de dado e, ento, selecionando-se a classe apropriada para a construo do ndice. Tambm existem algumas
classes de operadores com finalidades especiais:

As duas classes de operadores box_ops e bigbox_ops suportam ndices R-tree para o tipo de dado box. A
diferena entre as duas que bigbox_ops ajusta as coordenadas da caixa para baixo, evitando excees de
ponto flutuante ao executar multiplicao, adio e subtrao de coordenadas com nmeros de ponto flutuante
muito grande (Nota: isto era verdade h algum tempo atrs, mas atualmente as duas classes de operadores
utilizam ponto flutuante e so efetivamente idnticas).

A seguinte consulta exibe todas as classes de operadores:

SELECT am.amname AS metodo_de_acesso,

CREATE INDEX
opc.opcname AS nome_do_operador
FROM pg_am am, pg_opclass opc
WHERE opc.opcamid = am.oid
ORDER BY acc_method, ops_name;

Utilizao
Para criar um ndice B-tree para a coluna titulo na tabela filmes:
CREATE UNIQUE INDEX unq_titulo
ON filmes (titulo);

Compatibilidade
SQL92
O comando CREATE INDEX uma extenso do PostgreSQL linguagem.
No existe o comando CREATE INDEX no SQL92.

CREATE LANGUAGE
Nome
CREATE LANGUAGE cria uma linguagem procedural

Sinopse
CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE nome_da_linguagem
HANDLER tratador_de_chamadas [ VALIDATOR funo_de_validao ]

Descrio
Atravs do comando CREATE LANGUAGE, um usurio do PostgreSQL pode registrar uma nova linguagem procedural em um banco de dados do PostgreSQL. Depois, podem ser definidos funes e procedimentos de gatilhos
nesta nova linguagem. O usurio deve possuir o privilgio de superusurio do PostgreSQL para poder registrar
uma nova linguagem.
O comando CREATE LANGUAGE associa o nome da linguagem com o tratador de chamadas (call handler) que
responsvel por executar as funes escritas nesta linguagem. Consulte o Guia do Programador para obter mais
informaes sobre os tratadores de chamadas das linguagens.
Observe que as linguagens procedurais so locais a cada bancos de dados. Para tornar uma linguagem disponvel
a todos os bancos de dados por padro, esta linguagem deve ser instalada no banco de dados template1.

Parmetros
TRUSTED
TRUSTED especifica que o tratador de chamadas para a linguagem seguro, ou seja, no oferece a um usurio

sem privilgios qualquer funcionalidade para contornar as restries de acesso. Se esta palavra chave for
omitida ao registrar a linguagem, somente usurios do PostgreSQL com privilgio de superusurio vo poder
usar esta linguagem para criar novas funes.
PROCEDURAL

Apenas informativo.
nome_da_linguagem
O nome da nova linguagem procedural. No existe distino entre letras minsculas e maisculas. Uma
linguagem procedural no pode substituir uma das linguagens nativas do PostgreSQL.
Por compatibilidade com as verses anteriores, o nome pode ser escrito entre apstrofos ().
HANDLER tratador_de_chamadas

O tratador_de_chamadas o nome de uma funo, previamente registrada, que vai ser chamada
para executar as funes escritas nesta linguagem procedural. O tratador de chamadas para a linguagem
procedural deve ser escrito em uma linguagem compilada (como C), com a conveno de chamadas verso
1, registrada no PostgreSQL como uma funo que no recebe nenhum argumento e com retorno do tipo
language_handler, que um tipo usado apenas para identificar a funo como tratadora de chamadas.

CREATE LANGUAGE
VALIDATOR funo_de_validao

funo_de_validao nome de uma funo registrada previamente que ser chamada sempre que
for criada uma nova funo nesta linguagem, para validar a nova funo. Se nenhuma funo validadora for
especificada, ento a nova funo no ser verificada ao ser criada. A funo validadora deve receber um
argumento do tipo oid, que o OID (identificador do objeto) da funo a ser criada, retornando usualmente
void.
A funo validadora tipicamente inspeciona o corpo da funo para verificar se a sintaxe est correta, mas
tambm pode verificar outras propriedades da funo como, por exemplo, certos tipos de argumentos que a
linguagem no pode tratar. Para sinalizar um erro, a funo validadora deve usar a funo elog(). O valor
retornado pela funo ignorado.

Diagnsticos
CREATE LANGUAGE

Mensagem retornada se a linguagem for criada com sucesso.

ERROR:

PL handler function nome_da_funo() doesnt exist

Este erro ocorre quando a funo nome_da_funo() no for encontrada.

Notas
Normalmente, este comando no deve ser executado diretamente pelos usurios. Para as linguagens procedurais
fornecidas juntamente com a distribuio do PostgreSQL o aplicativo createlang deve ser utilizado, porque este
aplicativo tambm instala o tratador de chamadas correto (O aplicativo createlang chama o CREATE LANGUAGE
internamente).
Nas verses do PostgreSQL anteriores a 7.3, era necessrio declarar uma funo tratadora como retornando o
tipo opaque, em vez de language_handler. Para permitir a carga de cpias de segurana antigas, o comando
CREATE LANGUAGE vai aceitar as funes declaradas como retornando opaque, mas vai emitir uma mensagem
NOTICE e mudar o tipo retornado declarado por language_handler.
Use o comando CREATE FUNCTION para criar uma nova funo.
Use o comando DROP LANGUAGE, ou melhor ainda, o aplicativo droplang, para excluir linguagens procedurais.
O catlogo do sistema pg_language registra informaes sobre as linguagens procedurais atualmente instaladas.
Table "pg_language"
Attribute
|
Type
| Modifier
---------------+-----------+----------

CREATE LANGUAGE
lanname
lanispl
lanpltrusted
lanplcallfoid
lanvalidator
lanacl

|
|
|
|
|
|

name
boolean
boolean
oid
oid
aclitem[]

|
|
|
|
|
|

lanname
| lanispl | lanpltrusted | lanplcallfoid | lanvalidator | lanacl
-------------+---------+--------------+---------------+--------------+-------internal
| f
| f
|
0 |
2246 |
c
| f
| f
|
0 |
2247 |
sql
| f
| t
|
0 |
2248 | {=U}

Atualmente, com exceo das permisses, a definio de uma linguagem procedural no pode ser mudada aps
ter sido criada.
Para poder utilizar uma linguagem procedural, deve ser concedido o privilgio USAGE para o usurio. O aplicativo
createlang concede automaticamente permisso para todos se a linguagem for reconhecida como trusted.

Exemplos
Os dois comandos mostrados abaixo, executados em seqncia, registram uma nova linguagem procedural e o
tratador de chamadas associado:
CREATE FUNCTION minha_pl_trata_chamada () RETURNS language_handler
AS $libdir/minha_pl
LANGUAGE C;
CREATE LANGUAGE minha_pl
HANDLER minha_pl_trata_chamada;

Compatibilidade
O comando CREATE LANGUAGE uma extenso do PostgreSQL linguagem.

Histrico
O comando CREATE LANGUAGE apareceu pela primeira vez no PostgreSQL 6.3.

Consulte tambm
createlang, CREATE FUNCTION, droplang, DROP LANGUAGE, GRANT, REVOKE, Guia do Programador do
PostgreSQL

CREATE OPERATOR
Nome
CREATE OPERATOR cria um operador

Sinopse
CREATE OPERATOR nome ( PROCEDURE = nome_da_funo
[, LEFTARG = tipo_esquerdo
] [, RIGHTARG = tipo_direito ]
[, COMMUTATOR = op_comutador ] [, NEGATOR = op_negador ]
[, RESTRICT = proc_restr ] [, JOIN = proc_juncao ]
[, HASHES ] [, MERGES ]
[, SORT1 = op_ord_esq ] [, SORT2 = op_ord_dir ]
[, LTCMP = op_menor_que ] [, GTCMP = op_maior_que ] )

Entradas
name
O operador a ser definido. Veja abaixo os caracteres permitidos. O nome pode ser qualificado pelo esquema
como, por exemplo, CREATE OPERATOR meu_esquema.+ (...).
nome_da_funo
A funo utilizada para implementar este operador.
tipo_esquerdo
O tipo do argumento do lado esquerdo do operador, se houver. Esta opo omitida em um operador unrio
esquerdo.
tipo_direito
O tipo do argumento do lado direito do operador, se houver. Esta opo omitida em um operador unrio
direito.
op_comutador
O comutador deste operador.
op_negador
O negador deste operador.
proc_restr
A funo estimadora de seletividade de restrio para este operador.
proc_juncao
A funo estimadora de seletividade de juno para este operador.
HASHES
Indica que este operador pode suportar uma juno por hash.
MERGES
Indica que este operador pode suportar uma juno por mesclagem.

CREATE OPERATOR
op_ord_esq
Se este operador pode suportar uma juno por mesclagem, o operador menor-que que ordena o tipo de dado
do lado esquerdo deste operador.
op_ord_dir
Se este operador pode suportar uma juno por mesclagem, o operador maior-que que ordena o tipo de dado
do lado direito deste operador.
op_menor_que
Se este operador pode suportar uma juno por mesclagem, o operador menor_que que compara os tipos de
dado de entrada deste operador.
op_maior_que
Se este operador pode suportar uma juno por mesclagem, o operador maior_que que compara os tipos de
dado de entrada deste operador.

Sadas
CREATE OPERATOR

Mensagem retornada se o operador for criado com sucesso.

Descrio
O comando CREATE OPERATOR define um novo operador nome. O usurio que define um operador se torna seu
dono.
Se o nome do esquema for fornecido, ento o operador ser criado no esquema especificado, seno ser criado no
esquema corrente (aquele na frente do caminho de procura; consulte CURRENT_SCHEMA()).
Dois operadores no mesmo esquema podem ter o mesmo nome se operarem sobre tipos de dado diferentes, o que
chamado de sobrecarga (overloading). O sistema tenta pegar o operador apropriado baseado nos tipos de
dado da entrada quando existe ambigidade.
O operador nome uma seqncia de at NAMEDATALEN-1 (63 por padro) caracteres da seguinte lista:
+-*/<>=~!@#%^&|?$

Existem algumas restries na escolha do nome:

O $ no pode ser definido como um operador de um nico caractere, embora possa fazer parte do nome de um
operador multi-caractere.

CREATE OPERATOR

As seqncias -- e /* no podem aparecer em nenhum lugar do nome do operador, porque ser considerado
incio de comentrio.

Um nome de operador multi-caractere no pode terminar por + ou por -, a menos que o nome tambm contenha
pelo menos um dos seguintes caracteres:
~!@#%^&|?$
Por exemplo, @- um nome de operador permitido, mas *- no . Esta restrio permite ao PostgreSQL
analisar consultas em conformidade com o SQL sem requerer espaos entre elementos (tokens).
Nota: Ao se trabalhar com nomes de operadores que no sejam padro SQL, usualmente necessrio usar
espaos entre os operadores adjacentes para evitar ambigidade. Por exemplo, definindo-se um operador
unrio esquerdo chamado @, no se pode escrever X*@Y; deve-se escrever X* @Y para garantir que o PostgreSQL leia dois nomes de operadores e no um.

O operador != mapeado para <> na entrada, portanto estes dois nomes so sempre equivalentes.
Pelo menos um entre LEFTARG e RIGHTARG deve ser definido. Para operadores binrios os dois devem ser
definidos. Para operadores unrios direito somente o LEFTARG deve ser definido, enquanto que para operadores
unrios esquerdo somente o RIGHTARG deve ser definido.
O procedimento nome_da_funo deve ser previamente definido utilizando o comando CREATE FUNCTION,
e deve estar definido para aceitar o nmero correto de argumentos (um ou dois) dos tipos indicados.
O operador comutador deve ser identificado, se existir, para que o PostgreSQL possa reverter a ordem dos operandos se desejar. Por exemplo, o operador area-menor-do-que, <<<, provavelmente teria o operador comutador
area-maior-do-que, >>>. Com isso, o otimizador de consultas poderia livremente converter:
caixa ((0,0), (1,1))

>>> minhas_caixas.descricao

em
minhas_caixas.descricao <<< caixa ((0,0), (1,1))

Isto permite o cdigo de execuo sempre utilizar a ltima representao e simplifica um pouco o otimizador de
consultas.
Analogamente, se existir um operador negador ento este deve ser identificado. Suponha que exista um operador area-igual, ===, assim como um area-diferente, !==. A ligao negador permite ao otimizador de consultas
simplificar
NOT minhas_caixas.descricao === caixa ((0,0), (1,1))

para
minhas_caixas.descricao !== caixa ((0,0), (1,1))

CREATE OPERATOR
Se for fornecido o nome de um operador comutador, o PostgreSQL procura-o no catlogo. Se encontr-lo, e
este ainda no tiver um comutador prprio, ento a entrada do comutador atualizada para ter o novo operador
criado como sendo o seu comutador. Aplica-se igualmente ao negador. Isto serve para permitir a definio de
dois operadores que so o comutador ou o negador um do outro. O primeiro operador deve ser definido sem um
comutador ou negador (conforme apropriado). Quando o segundo operador for definido, este nomear o primeiro
como seu comutador ou negador. O primeiro ser atualizado como efeito colateral (A partir do PostgreSQL 6.5,
isto tambm funciona para se ter apenas dois operadores referindo um ao outro).
As opes HASHES, MERGES, SORT1, SORT2, LTCMP e GTCMP esto presentes para apoiar o otimizador de consultas na realizao de junes. O PostgreSQL sempre pode avaliar uma juno (ou seja, processar uma clusula
com duas variveis tuplas separadas por um operador que retorna um booleano) por substituio interativa. Adicionalmente, o PostgreSQL pode usar um algoritmo juno-hash; entretanto, necessita saber se esta estratgia
pode ser aplicada. O algoritmo atual de juno-hash correto apenas para operadores que representam testes
de igualdade; alm disso, a igualdade do tipo de dado deve significar igualdade bit a bit da representao do tipo
(Por exemplo, um tipo de dado que contm bits no utilizados, que no fazem diferena nos testes de igualdade,
no pode utilizar juno-hash). O sinalizador HASHES indica ao otimizador de consultas que a juno-hash
pode ser usada com segurana com este operador.
De forma similar, o sinalizador MERGES indica se uma ordenao-mesclagem uma estratgia de juno possvel
de ser utilizada para este operador. Um juno de mesclagem requer que os dois tipos de dados de entrada possuam
ordenao consistentes, e que o operador de juno-mesclagem se comporte como o operador de igualdade com
relao ordenao. Por exemplo, possvel uma igualdade juno-mesclagem entre uma varivel inteira e uma
de ponto flutuante, ordenando-se as duas entradas na ordem numrica normal. A execuo de uma juno de
mesclagem requer que o sistema possa identificar quatro operadores relacionados com o operador igualdade
juno-mesclagem: comparao menor-que para o tipo de dado de entrada esquerda, comparao menor-que
para o tipo de dado de entrada direita, comparao menor-que entre os dois tipos de dado, e comparao maiorque entre os dois tipos de dado. possvel fazer estas especificaes pelo nome, com as opes SORT1, SORT2,
LTCMP e GTCMP respectivamente. O sistema usa os nomes padro <, <, <, > respectivamente quando um deles
omitido na especificao do MERGES. Tambm, assumido que MERGES est envolvido quando uma destas quatro
opes de operador aparece.
Se forem descobertas outras estratgias de juno consideradas prticas, o PostgreSQL mudar o otimizador
e o sistema de execuo para us-las, demandando especificao adicional quando um operador for definido.
Felizmente, a comunidade de pesquisa no inventa novas estratgias de juno freqentemente, e a generalidade
adicionada por estratgias de juno definidas pelo usurio no foram consideradas como valendo a complexidade
envolvida.
As opes RESTRICT e JOIN ajudam o otimizador de consultas a estimar o tamanho dos resultados. Se uma
clusula da forma:
minhas_caixas.descricao <<< caixa ((0,0), (1,1))

estiver presente na qualificao, ento o PostgreSQL poder ter que estimar a frao das instncias de
minhas_caixas que satisfazem a clusula. A funo proc_restr deve ser uma funo registrada (o que
significa ter sido definida usando o comando CREATE FUNCTION) que aceita argumentos do tipo de dado correto
e que retorna um nmero de ponto flutuante. O otimizador de consultas simplesmente chama esta funo,
passando o parmetro ((0,0), (1,1)) e multiplica o resultado pelo tamanho da relao para obter o nmero
esperado de instncias.
Analogamente, quando os dois operandos do operador contm variveis instncias, o otimizador deve estimar
o tamanho da juno resultante. A funo proc_juncao retornar outro nmero de ponto flutuante que ser
multiplicado pelas cardinalidades das duas tabelas envolvidas para calcular o tamanho esperado do resultado.
A diferena entre a funo
meu_procedimento_1 (minhas_caixas.descricao, caixa ((0,0), (1,1)))

CREATE OPERATOR

e o operador
minhas_caixas.descricao === caixa ((0,0), (1,1))

que o PostgreSQL tenta otimizar operadores e pode decidir usar um ndice para restringir o espao de procura
quando operadores esto envolvidos. Entretanto, no existe tentativa de otimizar funes, que so executadas pela
fora bruta. Mais ainda, as funes podem possuir qualquer nmero de argumentos, enquanto os operadores esto
restritos a um ou dois.

Notas
Consulte o captulo sobre operadores no Guia do Usurio do PostgreSQL para obter mais informaes. Consulte
o comando DROP OPERATOR para excluir do banco de dados um operador definido pelo usurio.
To give a schema-qualified operator name in com_op or the other optional arguments, use the OPERATOR()
syntax, for example
COMMUTATOR = OPERATOR(myschema.===) ,

Utilizao
The following command defines a new operator, area-equality, for the BOX data type:
CREATE OPERATOR === (
LEFTARG = caixa,
RIGHTARG = caixa,
PROCEDURE = area_igual_procedimento,
COMMUTATOR = ===,
NEGATOR = !==,
RESTRICT = area_restricao_procedimento,
JOIN = area_juncao_procedimento,
HASHES,
SORT1 = <<<,
SORT2 = <<<
-- Uma vez que os operadores de ordfenao foram fornecidos, MERGES est implcito.
-- assume-se que LTCMP e GTCMP sejam < e > respectivamente
);

Compatibilidade
SQL92
O comando CREATE OPERATOR uma extenso do PostgreSQL linguagem. No existe o comando CREATE
OPERATOR no SQL92.

CREATE OPERATOR CLASS

Nome
CREATE OPERATOR CLASS cria uma classe de operadores para ndices

Sinopse
CREATE OPERATOR CLASS nome [ DEFAULT ] FOR TYPE tipo_de_dado USING mtodo_de_acesso AS
{ OPERATOR nmero_da_estratgia identificador_do_operador [ ( tipo, tipo ) ] [ RECHECK ]
| FUNCTION nmero_de_suporte nome_da_funo ( tipos_dos_parmetros )
| STORAGE tipo_de_armazenamento
} [, ... ]

Entradas
nome
O nome da classe de operadores a ser criada. O nome pode ser qualificado pelo esquema.
DEFAULT

Se estiver presente, a classe de operadores se tornar a classe de operadores padro do ndice para o seu tipo
de dado. No mximo uma classe de operadores pode ser padro para um determinado tipo de dado e mtodo
de acesso.
tipo_de_dado
O tipo de dado da coluna que esta classe de operadores se aplica.
mtodo_de_acesso
O nome do mtodo de acesso do ndice que esta classe de operadores se destina.
nmero_da_estratgia
O nmero de estratgia do mtodo de acesso para um operador associado com a classe de operadores.
identificador_do_operador
O identificador (opcionalmente qualificado pelo esquema) de um operador associado com a classe de operadores.
tipo
O(s) tipo(s) de dado de entrada de um operador, ou NONE significando um operador unrio-esquerdo ou
unrio-direito. Os tipos de dado de entrada podem ser omitidos no caso normal, onde so idnticos ao tipo
de dado da classe de operadores.
RECHECK

Se estiver presente, o ndice lossy para este operador e, portanto, as tuplas buscadas usando o ndice deve
ser verificadas novamente para garantir que realmente satisfazem a clusula de qualificao envolvendo este
operador.
nmero_de_suporte
O nmero do procedimento de suporte do mtodo de acesso do ndice para a funo associada com a classe
de operadores.

CREATE OPERATOR CLASS

nome_da_funo
O nome (opcionalmente qualificado pelo esquema) da funo que o procedimento de suporte do mtodo
de acesso do ndice para a classe de operadores.
tipos_dos_parmetros
Os tipos de dado dos parmetros da funo.
tipo_de_armazenamento
O tipo de dado realmente armazenado no ndice. Normalmente o mesmo tipo de dado da coluna, mas alguns
mtodos de acesso de ndice (somente GIST nesta data) permitem que seja diferente. A clusula STORAGE
deve ser omitida a menos que o mtodo de acesso do ndice permita o uso de um tipo diferente.

Sadas
CREATE OPERATOR CLASS

Mensagem retornada se a classe de operadores for criada com sucesso.

Descrio
O comando CREATE OPERATOR CLASS define a nova classe de operadores, nome.
Uma classe de operadores define como um tipo de dado especfico pode ser usado com um ndice. A classe de
operadores especifica que certos operadores iro preencher papis particulares ou estratgias para este tipo de
dados e este mtodo de acesso. A classe de operadores tambm especifica os procedimentos de apoio a serem
usados pelo mtodo de acesso do ndice quando a classe de operadores selecionada para uma coluna do ndice.
Todos os operadores e funes utilizadas por uma classe de operadores devem ser definidas anstes da classe de
operadores ser criada.
Se o nome do esquema for fornecido, ento a classe de operadores criada no esquema especificado, seno
criada no esquema corrente (aquele na frente do caminho de procura; consulte CURRENT_SCHEMA()). Duas
classes de operadores no mesmo esquema podem ter o mesmo nome somente se forem para mtodos de acesso
diferentes do ndice.
O usurio que cria a classe de operadores se torna o seu dono. Atualmente para poder criar necessrio ser um
superusurio (Esta restrio feita porque uma definio errada de uma clase de operadores pode confundir ou
mesmo derrubar o servidor).
CREATE OPERATOR CLASS does not presently check whether the class definition includes all the operators and

functions required by the index access method. It is the users responsibility to define a valid operator class.
Consulte o captulo sobre extenses de interfaceamento para ndices no Guia do Programador do PostgreSQL
para obter mais informaes.

CREATE OPERATOR CLASS

Notas
Consulte o DROP OPERATOR CLASS para excluir uma classe de operadores definida pelo usurio do banco de
dados.

Utilizao
O exemplo mostrado abaixo define uma classe de operadores para um ndice GiST para o tipo de dado _int4
(matriz de int4). Consulte contrib/intarray/ para ver o exemplo completo.
CREATE OPERATOR CLASS gist__int_ops
DEFAULT FOR TYPE _int4 USING gist AS
OPERATOR
3
&&,
OPERATOR
6
=
RECHECK,
OPERATOR
7
@,
OPERATOR
8
~,
OPERATOR
20
@@ (_int4, query_int),
FUNCTION
1
g_int_consistent (internal, _int4, int4),
FUNCTION
2
g_int_union (bytea, internal),
FUNCTION
3
g_int_compress (internal),
FUNCTION
4
g_int_decompress (internal),
FUNCTION
5
g_int_penalty (internal, internal, internal),
FUNCTION
6
g_int_picksplit (internal, internal),
FUNCTION
7
g_int_same (_int4, _int4, internal);

As clusula OPERATOR, FUNCTION e STORAGE podem aparecer em qualquer ordem.

Compatibilidade
SQL92
O comando CREATE OPERATOR CLASS uma extenso do PostgreSQL. No existe o comando CREATE
OPERATOR CLASS no SQL92.

CREATE RULE
Nome
CREATE RULE cria uma regra

Sinopse
CREATE [ OR REPLACE ] RULE nome AS ON evento
TO tabela [ WHERE condio ]
DO [ INSTEAD ] ao
onde ao pode ser:
NOTHING
| consulta
| ( consulta ; consulta ... )

Entradas
nome
O nome da regra a ser criada. Deve ser diferente do nome de qualquer outra regra para a mesma tabela.
evento
Evento um entre SELECT, UPDATE, DELETE e INSERT.
tabela
O nome (opcionalmente qualificado pelo esquema) da tabela ou da viso qual a regra se aplica.
condio
Qualquer expresso condicional SQL (retornando booleano). A expresso condicional no pode fazer referncia a nenhuma tabela, exceto new e old, e no pode conter funes de agregao.
consulta
A consulta (ou consultas) causadora da ao pode ser um dos comandos SQL SELECT, INSERT, UPDATE,
DELETE ou NOTIFY.

Dentro da condio e da ao os nomes especiais de tabela new e old podem ser usados para fazer referncia
aos valores da tabela referenciada. O new vlido nas regras ON INSERT e ON UPDATE para se referir nova
linha sendo inserida ou atualizada. O old vlido nas regras ON UPDATE e ON DELETE para se referir linha
existente sendo atualizada ou excluda.

CREATE RULE

Sadas
CREATE RULE

Mensagem retornada se a regra for criada com sucesso.

Descrio
O comando CREATE RULE cria uma nova regra a ser aplicada tabela ou viso especificada. O comando CREATE
OR REPLACE RULE cria uma nova regra, ou substitui uma regra existente para a mesma tabela que tenha o mesmo
nome.
O sistema de regras do PostgreSQL permite a definio de uma ao alternativa a ser realizada para as incluses,
atualizaes ou excluses nas tabelas do banco de dados. As regras tambm so utilizadas para implementar as
vises das tabelas.
A semntica de uma regra que, no instante em que uma instncia individual (linha) acessada, includa, atualizada ou excluda, existe uma instncia antiga (para consultas, atualizaes e excluses) e uma instncia nova
(para incluses e atualizaes). Toda as regras para o tipo de evento indicado na tabela de destino indicada so examinadas sucessivamente (na ordem dos nomes). Se a condio especificada na clusula WHERE (caso exista)
for verdadeira, a parte ao da regra executada. A ao executada em vez da consulta original se INSTEAD
for especificado; seno executada aps a consulta original no caso de ON INSERT, ou antes da consulta original
nos casos de ON UPDATE e ON DELETE. Dentro da condio e da ao, os valores dos campos da instncia
antiga e/ou da instncia nova so substitudos por old.nome_do_atributo e new.nome_do_atributo.
A parte ao da regra pode ser composta por uma ou mais consultas. Para escrever vrias consultas deve-se
coloc-las entre parnteses. Estas consultas sero realizadas na ordem especificada. A ao tambm pode ser
NOTHING indicando nenhuma ao. Portanto, a regra DO INSTEAD NOTHING suprime a execuo da consulta
original (quando sua condio for verdadeira); uma regra DO NOTHING no tem utilidade.
A parte ao da regra executa com o mesmo identificador do comando e da transao do comando do usurio
que causou sua ativao.
importante que se tenha em mente que uma regra na verdade um mecanismo de transformao de consultas,
ou uma macro de consultas. Toda a consulta processada para que seja convertida em uma srie de consultas que incluam as aes das regras, o que ocorre antes do incio da avaliao da consulta. Portanto, as regras
condicionais so tratadas pela adio da condio da regra clusula WHERE das aes derivadas da regra. A
descrio anterior de uma regra como uma operao que executada para cada linha portanto enganosa. Se for
desejada uma operao que dispare independentemente de cada linha fsica, provavelmente o que se deseja um
gatilho e no uma regra. As regras so mais teis nas situaes em que se deseja transformar toda a consulta,
independentemente dos dados especficos sendo tratados.

Regras e Vises
Atualmente, as regras ON SELECT devem ser regras incondicionais INSTEAD e devem possuir aes compostas
por uma nica consulta SELECT. Portanto, uma regra ON SELECT torna efetivamente a tabela objeto em uma
viso, cujo contedo visvel so as linhas retornadas pela consulta SELECT da regra em vez de qualquer outra
coisa que tenha sido armazenada na tabela (se houver). Escrever um comando CREATE VIEW considerado um
estilo melhor do que criar uma tabela de verdade e definir uma regra ON SELECT para esta tabela.

CREATE RULE
O comando CREATE VIEW cria uma tabela fictcia (sem armazenamento subjacente) e associa uma regra ON
SELECT a esta tabela. O sistema no permite atualizaes na viso, porque sabe que no existe uma tabela
real. Pode ser criada a iluso de uma viso atualizvel definindo-se regras para ON INSERT, ON UPDATE e
ON DELETE (ou qualquer subconjunto destes comandos que for suficiente para atender as necessidades) para
substituir as aes de atualizao na viso por atualizaes apropriadas em outras tabelas.
Existe um problema quando se tenta utilizar regras condicionais para a atualizao das vises: obrigatrio haver
uma regra incondicional INSTEAD para cada ao que se deseja permitir na viso. Se a regra for condicional, ou
no for INSTEAD, ento o sistema continuar rejeitando as tentativas de realizar uma ao de atualizao, porque
poder tentar realizar a ao sobre a tabela fictcia em alguns casos. Se for desejado tratar todos os casos vlidos
atravs de regras condicionais, pode-se simplesmente adicionar uma regra incondicional DO INSTEAD NOTHING para garantir que o sistema sabe que nunca ser chamado para atualizar a tabela fictcia. Em seguida devem
ser criadas as regras condicionais como no INSTEAD; nos casos em que forem disparadas, vo se adicionar s
aes padro INSTEAD NOTHING.

Notas
necessrio possuir uma concesso para definio de regras na tabela para poder definir uma regra para a tabela.
Use o comando GRANT e REVOKE para conceder e revogar as permisses.
muito importante tomar cuidado para evitar as regras circulares. Por exemplo, embora qualquer uma destas
duas definies de regra seja aceita pelo PostgreSQL, a consulta vai fazer com que o PostgreSQL retorne um erro
porque a consulta vai circular muitas vezes:
CREATE RULE "_RETURN" AS
ON SELECT TO emp
DO INSTEAD
SELECT * FROM toyemp;
CREATE RULE "_RETURN" AS
ON SELECT TO toyemp
DO INSTEAD
SELECT * FROM emp;

A tentativa de consultar a tabela EMP faz com que o PostgreSQL emita um erro porque a consulta vai circular
muitas vezes:
SELECT * FROM emp;

Atualmente, se uma regra possui uma consulta NOTIFY, o NOTIFY ser executado incondicionalmente --- ou
seja, a notificao ser emitida mesmo que no haja linhas onde a regra possa ser aplicada. Por exemplo, em
CREATE RULE me_notifique AS ON UPDATE TO minha_tabela DO NOTIFY minha_tabela;
UPDATE minha_tabela SET nome = foo WHERE id = 42;

um evento de notificao (NOTIFY) ser emitido durante a atualizao (UPDATE), haja ou no haja alguma linha
com id = 42. Esta uma restrio da implementao que dever estar corrigida em verses futuras.

CREATE RULE

Compatibilidade
SQL92
O comando CREATE RULE uma extenso do PostgreSQL linguagem. No existe o comando CREATE RULE
no SQL92.

CREATE SCHEMA
Nome
CREATE SCHEMA cria um esquema

Sinopse

CREATE SCHEMA nome_do_esquema [ AUTHORIZATION nome_do_usurio ] [ elemento_do_esquema [ ... ]

CREATE SCHEMA AUTHORIZATION nome_do_usurio [ elemento_do_esquema [ ... ] ]

Entradas
nome_do_esquema
O nome do esquemam a ser criado. Se for omitido, o nome do usurio ser usado como o nome do esquema.
nome_do_usurio
O nome do usurio que ser o dono do esquema. Se for omitido, ser usado por padro o nome do usurio
executando o comando. Somente os superusurios podem criar esquemas que pertenam a outros usurios.
elemento_do_esquema
Um comando SQL definindo um objeto a ser criado no esquema. Atualmente somente CREATE TABLE,
CREATE VIEW e GRANT so aceitos como clusulas do comando CREATE SCHEMA. Os outros tipos de objetos
podem ser criados atravs de comandos prprios aps o esquema ter sido criado.

Sadas
CREATE SCHEMA

Mensagem retornada se o comando for executado com sucesso.

ERROR: namespace "nome_do_esquema" already exists

Se o esquema especificado j existir.

Descrio
O comando CREATE SCHEMA cria um novo esquema no banco de dados corrente. O nome do esquema deve ser
diferente do nome de qualquer outro esquema existente no banco de dados corrente.
O esquema essencialmente um espao de nomes: contm objetos nomeados (tabelas, tipos de dado, funes e
operadores) cujos nomes podem duplicar os nomes de outros objetos existentes em outros esquemas. Os objetos

CREATE SCHEMA
nomeados so acessados qualificando-se seus nomes usando o nome do esquema como prefixo, ou definindo um
caminho de procura que inclua o(s) esquema(s) desejado(s). Os objetos no qualificados so criados no esquema
corrente (quele na frente do caminho de procura; consulte CURRENT_SCHEMA()).
Opcionalmente, o comando CREATE SCHEMA pode incluir subcomandos para criar objetos no novo esquema.
Estes subcomandos so tratados essencialmente da mesma forma que os outros comandos executados aps a
criao do esquema exceto que, se a clusula AUTHORIZATION for usada, todos os objetos criados pertencero a
este usurio.

Notas
Para criar um esquema, o usurio deve possuir o privilgio CREATE no banco de dados corrente ( claro que os
superusurios no so afetados por esta exigncia).
Use o comando DROP SCHEMA para remover um esquema.

Exemplos
Criar um esquema:
CREATE SCHEMA meu_esquema;

Criar um esquema para o usurio antonio --- o esquema tambm se chamar antonio:
CREATE SCHEMA AUTHORIZATION antonio;

Criar um esquema e criar uma tabela e uma viso nele:

CREATE SCHEMA hollywood
CREATE TABLE filmes (titulo text, lancamento date, premios text[])
CREATE VIEW premiados AS
SELECT titulo, lancamento FROM filmes WHERE premios IS NOT NULL;

Deve-se perceber que os comandos individuais no terminam por ponto-e-vrgula.

Abaixo est mostrada uma forma equivalente para se obter o mesmo resultado:
CREATE SCHEMA hollywood;
CREATE TABLE hollywood.filmes (titulo text, lancamento date, premios text[])
CREATE VIEW hollywood.premiados AS
SELECT titulo, lancamento FROM hollywood.filmes WHERE premios IS NOT NULL;

CREATE SCHEMA

Compatibilidade
SQL92
O SQL92 permite a clusula DEFAULT CHARACTER SET no comando CREATE SCHEMA, bem como mais tipos
de subcomandos do que os atualmente aceitos pelo PostgreSQL.
O SQL92 especifica que os subcomandos presentes em CREATE SCHEMA podem aparecer em qualquer ordem.
Na implementao atual do PostgreSQL no so tratados todos os casos de referncias frente nos subcomandos;
pode ser que seja necessrio reordenar os subcomandos para evitar referncias frente.
No SQL92 o dono do esquema sempre possui todos os objetos que este contm. O PostgreSQL permite que os
esquemas contenham objetos que pertenam a outros usurios alm do dono do esquema, o que somente acontece
se o dono do esquema conceder o privilgio CREATE para outro usurio.

CREATE SEQUENCE
Nome
CREATE SEQUENCE cria um gerador de seqncia

Sinopse
CREATE [ TEMPORARY | TEMP ] SEQUENCE nome_seq [ INCREMENT incremento ]
[ MINVALUE valor_min ] [ MAXVALUE valor_max ]
[ START incio ] [ CACHE cache ] [ CYCLE ]

Entradas
TEMPORARY ou TEMP
Se for especificado, o objeto de seqncia criado somente para esta sesso, e automaticamente eliminado
ao trmino da sesso. Uma seqncia permanente com o mesmo nome, caso exista, no ser visvel nesta
sesso enquanto a seqncia temporria existir, a menos que seja referenciada por um nome qualificado pelo
esquema.
nome_seq
O nome (opcionalmente qualificado pelo esquema) da seqncia a ser criada.
incremento
A clusula INCREMENT incremento opcional. Um valor positivo cria uma seqncia ascendente, enquanto um valor negativo cria uma seqncia descendente. O valor padro um (1).
valor_min
A clusula opcional MINVALUE valor_min determina o valor mnimo que a seqncia pode gerar. Por
padro 1 e -2^63-1 para seqncias ascendentes e descendentes, respectivamente.
valor_max
A clusula opcional MAXVALUE valor_max determina o valor mximo para a seqncia. Por padro 2^63-1
e -1 para seqncias ascendentes e descendentes, respectivamente.
incio
A clusula opcional START incio permite a seqncia iniciar com qualquer valor. Por padro, o valor
inicial igual a valor_min para seqncias ascendentes, e igual a valor_max para seqncias descendentes.
cache
A opo CACHE cache permite que os nmeros da seqncia sejam prviamente alocados e armazenados
em memria para acesso mais rpido. O valor mnimo 1 (somente um valor pode ser gerado de cada vez,
ou seja, sem armazenamento em memria) e este tambm o valor padro.
CYCLE
A palavra chave opcional CYCLE pode ser utilizada para permitir a seqncia reiniciar quando o
valor_max ou o valor_min for atingido pela seqncia ascendente ou descendente, respectivamente.
Se o limite for atingido, o prximo nmero gerado ser valor_min ou valor_max, respectivamente.
Sem a clusula CYCLE, aps o limite ser atingido as chamadas funo nextval retornam um erro.

CREATE SEQUENCE

Sadas
CREATE SEQUENCE

Mensagem retornada se o comando for executado com sucesso.

ERROR: Relation nome_seq already exists

A seqncia especificada j existe.

ERROR: DefineSequence: MINVALUE (incio) cant be >= MAXVALUE (max)

O valor especificado para o incio da seqncia est fora do intervalo.

ERROR: DefineSequence: START value (incio) cant be < MINVALUE (min)

O valor especificado para o incio da seqncia est fora do intervalo.

ERROR: DefineSequence: MINVALUE (min) cant be >= MAXVALUE (max)

Os valores mnimo e mximo esto inconsistentes.

Description
O comando CREATE SEQUENCE cria um novo gerador de nmeros seqenciais no banco de dados em uso. Este
comando envolve a criao e a inicializao de uma tabela nova com uma nica linha com o nome nome_seq.
O usurio que executa o comando se torna o dono do gerador.
Se um nome de esquema for fornecido ento a seqncia criada no esquema especificado, seno criada no
esquema corrente (aquele na frente do caminho de procura; consulte o CURRENT_SCHEMA()). As seqncias
TEMP existem em um esquema especial, portanto o nome do esquema no pode ser fornecido ao se criar uma
seqncia TEMP. O nome da seqncia deve ser diferente do nome de qualquer outra seqncia, tabela, ndice ou
viso no mesmo esquema.
Aps a seqncia ser criada, podem ser utilizadas as funes nextval, currval e setval para trabalhar com a
seqncia. Estas funes esto documentadas no Guia do Usurio.
Embora no seja possvel atualizar uma seqncia diretamente, possvel realizar uma consulta do tipo
SELECT * FROM nome_seq;

para conhecer os parmetros e o estado atual da seqncia. Em particular, o campo last_value da seqncia
mostra o ltimo valor alocado por qualquer processo servidor ( claro que este valor pode estar obsoleto na hora
em que for exibido, se outros processos estiverem chamando a funo nextval).

CREATE SEQUENCE

Cuidado
Podem ocorrer resultados no esperados ao se especificar um valor maior do que 1 para cache em
um objeto de seqncia utilizado ao mesmo tempo por vrios servidores (backends). Cada servidor
aloca e armazena em memria valores sucessivos da seqncia ao fazer um nico acesso ao objeto
de seqncia e incrementa o ltimo valor (last_value) na forma correspondente. Ento, a prxima utilizao de cache-1 da funo nextval neste servidor, simplesmente retorna os valores pr-alocados,
sem tocar no objeto compartilhado. Desta forma, todos os valores alocados nesta sesso, mas no utilizados, so perdidos ao final da sesso. Alm disso, embora seja garantido que os diversos servidores
alocam valores distintos da seqncia, os valores podem ser gerados fora de seqncia quando so
levados em conta todos os servidores. (Por exemplo, com um cache de 10, o servidor A pode reservar
os valores de 1 a 10 e usar o prximo valor igual a 1, ento o servidor B pode reservar os valores de
11 a 20 e usar o prximo valor igual a 11 antes do servidor A ter usado o prximo valor igual a 2).
Assim, com um valor para cache igual a 1 seguro assumir que os valores da funo nextval so
gerados seqencialmente; com um valor para cache maior do que 1 pode-se assumir que os valores
da funo nextval so todos distintos, mas no que sejam gerados de forma puramente seqencial.
Alm disso, o valor do campo last_value reflete o ltimo valor reservado por qualquer servidor, independentemente de ter sido ou no retornado por uma chamada funo nextval. Outra considerao
a ser feita, que a funo setval executada neste tipo de seqncia no vai fazer efeito em outro
servidor at que este tenha utilizado todos os valores pr-alocados em memria.

Notas
Use o comando DROP SEQUENCE para excluir uma seqncia.
As seqncias so baseadas em aritmtica de tipo bigint, por isso a faixa de valores no pode ultrapassar a faixa
permitida para nmeros inteiros de 8 bytes (-9223372036854775808 a 9223372036854775807). Em algumas
plataformas mais antigas pode no haver suporte do compilador para nmeros inteiros de 8 bytes e, neste caso, as
seqncias utilizam aritmtica para o tipo regular integer (faixa de valores de -2147483648 a +2147483647).
Quando o valor para cache maior do que 1, cada servidor utiliza sua prpria memria para armazenar os
nmeros prviamente alocados. Os nmeros armazenados em memria, mas no utilizados pela sesso atual, so
perdidos, ocasionando uma seqncia cheia de buracos.

Utilizao
Criar uma seqncia ascendente chamada serial, comeando por 101:
CREATE SEQUENCE serial START 101;

Selecionar o prximo valor desta seqncia:

SELECT nextval(serial);
nextval
------114

Utilizar esta seqncia em um comando INSERT:

INSERT INTO distribuidores VALUES (nextval(serial), nada);

CREATE SEQUENCE

Atualizar o valor da seqncia aps executar o comando COPY FROM:

BEGIN;
COPY distribuidores FROM arquivo_entrada;
SELECT setval(serial, max(id)) FROM distribuidores;
END;

Compatibilidade
SQL92
O comando CREATE SEQUENCE uma extenso do PostgreSQL linguagem. No existe o comando CREATE
SEQUENCE no SQL92.

CREATE TABLE
Nome
CREATE TABLE cria uma tabela

Sinopse

CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE nome_da_tabela (

{ nome_da_coluna tipo_de_dado [ DEFAULT expresso_padro ] [ restrio_de_coluna [, ... ]
| restrio_de_tabela } [, ... ]
)
[ INHERITS ( tabela_ascendente [, ... ] ) ]
[ WITH OIDS | WITHOUT OIDS ]
onde restrio_de_coluna :
[ CONSTRAINT nome_da_restrio ]
{ NOT NULL | NULL | UNIQUE | PRIMARY KEY |
CHECK (expresso) |
REFERENCES tabela_referenciada [ ( coluna_referenciada ) ] [ MATCH FULL | MATCH PARTIAL ]
[ ON DELETE ao ] [ ON UPDATE ao ] }
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
e restrio_de_tabela :

[ CONSTRAINT nome_da_restrio ]
{ UNIQUE ( nome_da_coluna [, ... ] ) |
PRIMARY KEY ( nome_da_coluna [, ... ] ) |
CHECK ( expresso ) |
FOREIGN KEY ( nome_da_coluna [, ... ] ) REFERENCES tabela_referenciada [ ( coluna_referenci
[ MATCH FULL | MATCH PARTIAL ] [ ON DELETE ao ] [ ON UPDATE ao ] }
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]

Descrio
O comando CREATE TABLE cria uma tabela nova, inicialmente vazia, no banco de dados atual. O usurio que
executa o comando torna-se o dono da tabela.
Se o nome do esquema for fornecido (por exemplo, CREATE TABLE meu_esquema.minha_tabela ...) ento
a tabela criada no esquema especificado, seno criada no esquema corrente (aquele na frente do caminho de
procura; consulte CURRENT_SCHEMA()). As tabelas TEMP so criadas em um esquema especial, portanto o nome
do esquema no pode ser fornecido para as tabelas temporrias. O nome da tabela deve ser diferente do nome de
qualquer outra tabela, seqncia, ndice ou viso no mesmo esquema.
O comando CREATE TABLE tambm cria, automaticamente, um tipo de dado que representa o tipo da tupla (tipo
estrutura) correspondente a uma linha da tabela. Portanto, uma tabela no pode ter o mesmo nome de um tipo de
dado existente no mesmo esquema.
Uma tabela no pode possuir mais de 1600 colunas (Na prtica, o limite efetivo menor, devido restrio do
comprimento das tuplas).
As clusulas opcionais de restrio especificam as restries (ou testes) que as linhas novas ou modificadas devem
satisfazer para a operao de incluso ou de alterao ser completada. Uma restrio uma regra com nome: um

CREATE TABLE
objeto SQL que ajuda a definir conjuntos vlidos de valores, estabelecendo limites nos resultados das operaes
de incluso, excluso e atualizao realizadas na tabela.
Existem duas formas para definir restries: restries de tabela e restries de coluna. A restrio de coluna
definida como parte da definio da coluna. A restrio de tabela no est presa a uma coluna em particular,
podendo abranger mais de uma coluna. Toda restrio de coluna tambm pode ser escrita como uma restrio de
tabela; a restrio de coluna somente uma notao conveniente, no caso da restrio afetar apenas uma coluna.

Parmetros
[LOCAL] TEMPORARY ou [LOCAL] TEMP

Se for especificado, a tabela criada como uma tabela temporria. Tabelas temporrias so automaticamente
eliminadas no final da sesso. Uma tabela permanente com o mesmo nome, caso exista, no ser visvel na
sesso corrente enquanto a tabela temporria existir, a menos que seja referenciada por um nome qualificado
pelo esquema. Todo ndice criado em tabela temporria tambm temporrio.
A palavra LOCAL opcional. Veja sob Compatibilidade.
nome_da_tabela
O nome (opcionalmente qualificado pelo esquema) da tabela a ser criada.
nome_da_coluna
O nome da coluna a ser criada na nova tabela.
tipo_de_dado
O tipo de dado da coluna. Pode incluir especificador de matriz (array). Consulte o Guia do Usurio para
obter mais informaes sobre tipos de dado e sobre matrizes.
DEFAULT expresso_padro

A clusula DEFAULT atribui um valor padro para o dado da coluna em cuja definio est presente. O valor
pode ser qualquer expresso (subconsultas e referncias cruzadas para outras colunas da mesma tabela no
so permitidas). O tipo de dado da expresso padro deve corresponder ao tipo de dado da coluna.
A expresso utilizada em todas as operaes de incluso que no especificam valor para a coluna. No
havendo valor padro para a coluna, ento NULL torna-se o valor padro.
INHERITS ( tabela_ascendente [, ... ] )

A clusula opcional INHERITS (herda) especifica uma lista de tabelas das quais a nova tabela herda, automaticamente, todas as colunas. Se o mesmo nome de coluna existir em mais de uma tabela ascendente um
erro gerado, a menos que o tipo de dado das colunas seja o mesmo em todas as tabelas ascendentes. Se no
houver conflito, ento as colunas duplicadas so mescladas para formar uma nica coluna da nova tabela. Se
a lista de nomes de colunas da nova tabela contm uma coluna que tambm herdada, da mesma forma o
tipo de dado deve ser o mesmo das colunas herdadas, e a definio das colunas ser mesclada em uma nica
coluna. Entretanto, declaraes de colunas novas e herdadas com o mesmo nome no precisam especificar
restries idnticas: todas as restries fornecidas em qualquer uma das declaraes so mescladas, sendo
todas aplicadas nova tabela. Se a nova tabela especificar, explicitamente, um valor padro para a coluna,
este valor padro substitui qualquer valor padro das declaraes herdadas. Fora isso, toda tabela ascendente
que especificar um valor padro para a coluna deve especificar o mesmo valor, ou um erro ser gerado.
WITH OIDS ou WITHOUT OIDS

Esta clusula opcional especifica se as linhas da nova tabela devem possuir OIDs (identificadores do objeto).
O padro possuir OIDs (Se a nova tabela herdar de qualquer tabela que possua OIDs, ento a clusula WITH
OIDS forada mesmo que no comando esteja especificado WITHOUT OIDS).

CREATE TABLE
A especificao de WITHOUT OIDS permite ao usurio suprimir a gerao dos OIDs para as linhas da tabela.
Este procedimento pode ser interessante em tabelas grandes, porque reduz o consumo de OIDs e, portanto,
adia o recomeo deste contador de 32 bits. Quando o contador recomea, no mais possvel assumir a sua
unicidade, o que reduz muito a sua utilidade.
CONSTRAINT nome_da_restrio

Um nome opcional para a restrio da coluna ou da tabela. Se no for especificado, o nome ser gerado pelo
sistema.
NOT NULL

Valores nulos no so permitidos na coluna.

NULL

Valores nulos so permitidos na coluna. Este o padro.

Esta clusula s est disponvel por compatibilidade com bancos de dados SQL fora do padro. Sua utiizao
desestimulada em novas aplicaes.
UNIQUE (restrio da coluna)
UNIQUE ( column_name [, ... ] ) (restrio da tabela)

A restrio UNIQUE especifica a regra onde um grupo de uma ou mais colunas distintas de uma tabela podem
conter apenas valores nicos. O comportamento da restrio de unicidade para tabelas o mesmo da restrio
de unicidade para colunas, porm com a capacidade adicional de abranger vrias colunas.
Para a finalidade da restrio de unicidade, valores nulos no so considerados iguais.
Cada restrio de unicidade da tabela deve abranger um conjunto de colunas diferente do conjunto de colunas
abrangido por qualquer outra restrio de unicidade e da chave primria definida para a tabela (Seno, seria
apenas a mesma restrio declarada duas vezes).
PRIMARY KEY (restrio da coluna)
PRIMARY KEY ( column_name [, ... ] ) (restrio da tabela)

A restrio de chave primria especifica que a coluna, ou colunas, da tabela pode conter apenas valores
nicos (no duplicados) e no nulos. Tecnicamente a chave primria (PRIMARY KEY) simplesmente uma
combinao de unicidade (UNIQUE) com no nulo (NOT NULL), mas identificar um conjunto de colunas como
chave primria tambm fornece metadados sobre o projeto do esquema, porque chaves primrias indicam que
outras tabelas podem depender deste conjunto de colunas como um identificador nico para linhas.
Somente uma chave primria pode ser especificada para uma tabela, seja como uma restrio de coluna ou
como uma restrio de tabela.
A restrio de chave primria deve abranger um conjunto de colunas que seja diferente de outro conjunto de
colunas abrangido por uma restrio de unicidade definida para a mesma tabela.
CHECK (expresso)

A clusula CHECK especifica restries de integridade, ou testes, que as linhas novas ou atualizadas devem
atender para que uma operao de insero ou de atualizao complete. Cada restrio deve ser uma expresso que produza um resultado booleano. Uma condio declarada na definio da coluna deve fazer
referncia apenas ao valor desta coluna, enquanto uma condio declarada como uma restrio da tabela
pode fazer referncia a vrias colunas.
Atualmente, as expreses de CHECK no podem conter subconsultas, nem fazer referncia a variveis que
no sejam colunas da linha atual.

CREATE TABLE
REFERENCES reftable [ ( refcolumn ) ] [ MATCH matchtype ] [ ON DELETE action ] [ ON
UPDATE action ] (restrio da coluna)
FOREIGN KEY ( nome_da_coluna [, ... ] ) REFERENCES tabela_referenciada [ (
coluna_referenciada [, ... ] ) ] [ MATCH tipo_corresp ] [ ON DELETE ao ] [ ON
UPDATE ao ] (restrio da tabela)

A restrio REFERENCES especifica que um grupo de uma ou mais colunas da nova tabela deve conter somente valores correspondentes aos valores das colunas referenciadas coluna_referenciada da tabela
referenciada tabela_referenciada. Se a coluna_referenciada for omitida, a chave primria da
tabela_referenciada utilizada. As colunas referenciadas devem pertencer a uma restrio de chave
primria ou de unicidade da tabela referenciada.
Os valores adicionados a estas colunas so comparados com os valores das colunas referenciadas da tabela
referenciada utilizando o tipo de comparao. Existem 3 tipos de comparao: MATCH FULL, MATCH
PARTIAL e o tipo de comparao padro se nada for especificado. MATCH FULL no permite que uma
coluna de uma chave estrangeira com vrias colunas seja nula, a menos que todas as colunas da chave
estrangeira sejam nulas. O tipo de comparao padro permite que algumas colunas da chave estrangeira
sejam nulas enquanto outras colunas da chave estrangeira no so nulas. MATCH PARTIAL ainda no est
implementado.
Adicionalmente, quando os dados das colunas referenciadas so modificados, certas aes so realizadas nos
dados das colunas desta tabela. A clusula ON DELETE especifica a ao a ser executada quando uma linha
referenciada da tabela referenciada excluda. Da mesma maneira, a clusula ON UPDATE especifica a ao a
ser executada quando uma coluna referenciada da tabela referenciada muda de valor. Se a linha atualizada,
mas a coluna referenciada no muda de valor, nenhuma ao executada. So possveis as seguintes aes
para cada clusula:
NO ACTION

Gera um erro indicando que a excluso ou a atualizao criaria uma violao de chave estrangeira. Esta
a ao padro.
RESTRICT

O mesmo que NO ACTION.

CASCADE

Exclui qualquer linha que faa referncia linha excluda, ou atualiza o valor da coluna que faz referncia usando o novo valor da coluna referenciada, respectivamente.
SET NULL

Atribui nulo aos valores das colunas que fazem referncia.

SET DEFAULT

Atribui o valor padro s colunas que fazem referncia.

Se a coluna da chave primria atualizada freqentemente, pode ser til adicionar um ndice s colunas
da clusula REFERENCES, para que as aes NO ACTION e CASCADE associadas s colunas da clusula
REFERENCES sejam executadas mais rapidamente.
DEFERRABLE ou NOT DEFERRABLE

Estas clusulas controlam se as restries podem ser postergadas. Uma restrio que no pode ser postergada
verificada imediatamente aps cada comando. A verificao das restries que so postergveis pode ser
adiada para o final da transao (usando o comando SET CONSTRAINTS). O padro NOT DEFERRABLE.

CREATE TABLE
Somente restries de chave estrangeira aceitam esta clusula no momento. Todos os outros tipos de restrio
no so postergveis.
INITIALLY IMMEDIATE ou INITIALLY DEFERRED

Se uma restrio postergvel, esta clusula especifica o momento padro para verificar a restrio. Se a restrio INITIALLY IMMEDIATE, ento verificada aps cada declarao. Este o padro. Se a declarao
INITIALLY DEFERRED, ento verificada apenas no final da transao. O momento de verificao da
restrio pode ser alterado pelo comando SET CONSTRAINTS.

Diagnsticos
CREATE TABLE

Mensagem retornada se a tabela for criada com sucesso.

ERROR

Mensagem retornada se a criao da tabela falhar. Esta mensagem normalmente acompanhada por algum
texto descritivo, como: ERROR: Relation nome_da_tabela already exists, que ocorre quando
a tabela especificada existe no banco de dados.

Notas

Sempre que uma aplicao faz uso dos OIDs para identificar linhas especficas de uma tabela, recomendado
criar uma restrio de unicidade para a coluna oid da tabela, para garantir que os OIDs na tabela realmente
identificam unicamente uma linha, mesmo aps o contador recomear. Evite assumir que os OIDs so nicos
entre tabelas; se for necessrio um identificador nico para todo o banco de dados, use uma combinao do
tableoid (OID da tabela) com o OID da linha para esta finalidade ( provvel que nas verses futuras do
PostgreSQL existam contadores OID separados para cada tabela, ento ser necessrio, e no opcional, incluir
o tableoid para ter-se um identificador nico para todo o banco de dados).
Dica: O uso de WITHOUT OIDS no recomendado para tabelas sem chave primria porque sem um OID,
e sem uma chave de dados nica, fica difcil identificar uma linha especfica.

O PostgreSQL cria, automaticamente, um ndice para cada restrio de unicidade e de chave primria para
garantir a sua unicidade. Portanto, no necessrio criar um ndice explcito para as colunas da chave primria.
(Consulte o comando CREATE INDEX para obter mais informaes)

CREATE TABLE

O padro SQL92 especifica que as restries CHECK de colunas podem referenciar apenas a coluna qual se
aplica; somente restries CHECK de tabelas podem fazer referncias a vrias colunas. O PostgreSQL no impe
esta restrio; as restries de tabela e de colunas so tratadas da mesma maneira.

As restries de unicidade e de chave primria no so herdadas na implementao atual, tornando o comportamento da combinao de herana com restrio de unicidade diferente do esperado.

Examplos
Criar a tabela filmes e a tabela distribuidores:
CREATE TABLE filmes (
cod
CHARACTER(5) CONSTRAINT pk_filmes PRIMARY KEY,
titulo
CHARACTER VARYING(40) NOT NULL,
did
DECIMAL(3) NOT NULL,
data_prod
DATE,
tipo
CHAR(10),
duracao
INTERVAL HOUR TO MINUTE
);
CREATE TABLE distribuidores (
did
DECIMAL(3) PRIMARY KEY DEFAULT NEXTVAL(serial),
nome
VARCHAR(40) NOT NULL CHECK (nome <> )
);

Criar uma tabela com uma matriz de 2 dimenses

CREATE TABLE matriz2d (
matriz INT[][]
);

Definir uma restrio de unicidade para a tabela filmes. Restries de unicidade de tabela podem ser definidas
usando uma ou mais colunas da tabela:
CREATE TABLE filmes (
cod
CHAR(5),
titulo
VARCHAR(40),
did
DECIMAL(3),
data_prod
DATE,
tipo
VARCHAR(10),
duracao
INTERVAL HOUR TO MINUTE,
CONSTRAINT producao UNIQUE(data_prod)
);

Definir uma restrio de coluna para verificao:

CREATE TABLE distribuidores (
did
DECIMAL(3) CHECK (did > 100),
nome
VARCHAR(40)
);

CREATE TABLE
Definir uma restrio de tabela para verificao:
CREATE TABLE distribuidores (
did
DECIMAL(3),
nome
VARCHAR(40)
CONSTRAINT chk_dist CHECK (did > 100 AND nome <> )
);

Definir uma restrio de chave primria para a tabela filmes. Restries de chave primria da tabela podem ser
definidas usando uma ou mais colunas da tabela.
CREATE TABLE filmes (
cod
CHAR(5),
titulo
VARCHAR(40),
did
DECIMAL(3),
data_prod
DATE,
tipo
VARCHAR(10),
duracao
INTERVAL HOUR TO MINUTE,
CONSTRAINT pk_filmes PRIMARY KEY(cod,titulo)
);

Definir a restrio de chave primria para a tabela distribuidores. Os dois exemplos abaixo so equivalentes,
o primeiro utiliza a sintaxe de restrio de tabela, e o segundo utiliza a notao de restrio de coluna.
CREATE TABLE distribuidores (
did
DECIMAL(3),
nome
CHAR VARYING(40),
PRIMARY KEY(did)
);
CREATE TABLE distribuidores (
did
DECIMAL(3) PRIMARY KEY,
nome
VARCHAR(40)
);

O comando abaixo especifica uma constante literal como valor padro da coluna nome; faz com que o valor
padro da coluna did seja gerado como o prximo valor de um objeto de seqncia; faz com que o valor padro
da coluna data_ins seja a data e hora em que a linha inserida.
CREATE TABLE distribuidores (
nome
VARCHAR(40) DEFAULT luso filmes,
did
INTEGER DEFAULT NEXTVAL(seq_distribuidores),
data_ins TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Definir duas restries de coluna NOT NULL na tabela distribuidores, sendo que uma delas recebe um nome
explicito:
CREATE TABLE distribuidores (
did
DECIMAL(3) CONSTRAINT nao_nulo NOT NULL,
nome
VARCHAR(40) NOT NULL
);

CREATE TABLE

Definir uma restrio de unicidade para a coluna nome:

CREATE TABLE distribuidores (
did
DECIMAL(3),
nome
VARCHAR(40) UNIQUE
);

O comando acima equivalente ao mostrado abaixo, especificado atravs de uma restriao de tabela:
CREATE TABLE distribuidores (
did
DECIMAL(3),
nome
VARCHAR(40),
UNIQUE(nome)
);

Compatibilidade
O comando CREATE TABLE est em conformidade com o SQL92 Intermedirio e com um subconjunto do
SQL99, com excees listadas abaixo e nas descries acima.

Tabelas temporrias
Alm da tabela temporria local, o SQL92 tambm define a declarao CREATE GLOBAL TEMPORARY TABLE.
Tabelas temporrias globais tambm so visveis por outras sesses.
Para as tabelas temporrias existe uma clusula opcional ON COMMIT:

CREATE { GLOBAL | LOCAL } TEMPORARY TABLE nome_da_tabela ( ... ) [ ON COMMIT { DELETE | PRESE

A clusula ON COMMIT especifica se a tabela temporria deve ou no ser esvaziada quando o comando COMMIT
executado. Se a clusula ON COMMIT for omitida, o SQL92 especifica como padro ON COMMIT DELETE ROWS.
Entretanto, o comportamento do PostgreSQL sempre ON COMMIT PRESERVE ROWS.

Restrio NULL
A restrio NULL (na verdade uma no restrio) uma extenso do PostgreSQL ao SQL92, includa para
manter a compatibilidade com alguns outros SGBDRs (e por simetria com a restrio NOT NULL). Sendo que este
o padro para qualquer coluna, sua presena simplesmente informativa.

Asseres
Uma assero (assertion) um tipo especial de restrio de integridade e compartilha o mesmo espao de nomes
como outras restries. Entretanto, uma assero no necessriamente dependente de uma tabela em particular
como as retries so, por isso o SQL92 fornece a declarao CREATE ASSERTION como uma forma alternativa
para definir restries:
CREATE ASSERTION nome CHECK ( condio )

CREATE TABLE
O PostgreSQL no implementa asseres atualmente.

Herana
Heranas mltiplas atravs da clusula INHERITS uma extenso da linguagem do PostgreSQL. O SQL99 (mas
no o SQL92) define herana nica utilizando uma sintaxe diferente e semnticas diferente. O estilo de herana
do SQL99 ainda no suportado pelo PostgreSQL.

Identificadores do Objeto (Object IDs)

O conceito de OIDs (identificadores de objeto) do PostgreSQL no padro.

Consulte tambm
ALTER TABLE, DROP TABLE

CREATE TABLE AS
Nome
CREATE TABLE AS cria uma tabela a partir do resultado de uma consulta

Sinopse
CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE nome_da_tabela [ (nome_da_coluna [, ...] ) ]
AS consulta

Descrio
O comando CREATE TABLE AS cria e carrega uma tabela com dados produzidos pelo comando SELECT. As
colunas da tabela possuem os nomes e tipos de dado associados s colunas da sada produzida pelo comando
SELECT (exceto que possvel substituir os nomes das colunas fornecendo-se uma lista explcita de novos nomes
de colunas).
O comando CREATE TABLE AS exibe alguma semelhana com a criao de uma viso, mas na realidade bastante diferente: este comando cria a nova tabela e executa a consulta apenas uma vez para fazer a carga inicial
dos dados da nova tabela. A nova tabela no vai ter conhecimento das prximas mudanas ocorridas na tabela de
origem da consulta. Contrastando com este comportamento, uma viso executa novamente o comando SELECT
sempre que consultada.

Parmetros
[LOCAL] TEMPORARY ou [LOCAL] TEMP

Se for especificado, a tabela criada como uma tabela temporria. Consulte o comando CREATE TABLE
para obter mais detalhes.
nome_da_tabela
O nome (opcionalmente qualificado pelo esquema) da tabela a ser criada.
nome_da_coluna
O nome da coluna da nova tabela. Vrios nomes de colunas podem ser especificados utilizando uma lista
de nomes separados por vrgula. Se os nomes das colunas no forem fornecidos, sero obtidos a partir dos
nomes das colunas produzidas pela consulta.
consulta
Uma declarao de consulta (ou seja, um comando SELECT). Consulte o comando SELECT para obter a
descrio da sintaxe permitida.

Diagnsticos
Consulte os comandos CREATE TABLE e SELECT para obter um sumrio das possveis mensagens de sada.

CREATE TABLE AS

Notas
Este comando funcionalmente equivalente ao SELECT INTO mas prefervel, porque menos propenso a ser
confundido com outros usos da sintaxe do comando SELECT ... INTO.

Compatibilidade
Este comando baseado em uma funcionalidade do Oracle. No existe nenhum comando com funcionalidade
equivalente no SQL92 nem no SQL99. Entretanto, uma combinao de CREATE TABLE com INSERT ...
SELECT pode ser utilizada para produzir o mesmo resultado com um pouco mais de esforo.

Histrico
O comando CREATE TABLE AS est disponvel desde o PostgreSQL 6.3.

Consulte tambm
CREATE TABLE, CREATE VIEW, SELECT, SELECT INTO

CREATE TRIGGER
Nome
CREATE TRIGGER cria um gatilho

Sinopse
CREATE TRIGGER nome { BEFORE | AFTER } { evento [OR ...] }
ON tabela FOR EACH { ROW | STATEMENT }
EXECUTE PROCEDURE funo ( argumentos )

Entradas
nome
O nome a ser dado ao novo gatilho. Deve ser diferente do nome de qualquer outro gatilho para a mesma
tabela.
evento
Um entre INSERT, DELETE e UPDATE.
tabela
O nome (opcionalmente qualificado pelo esquema) da tabela em que o gatilho atua.
func
Uma funo fornecida pelo usurio, declarada como no recebendo nenhum argumento e com retorno do
tipo trigger.
argumentos
Uma relao opcional de argumentos, separados por vrgula, a serem fornecidos funo junto com os
dados usuais dos gatilhos, como os contedos novo e antigo das tuplas, quando o gatilho for disparado. Os
argumentos so constantes literais na forma de cadeias de caracteres. Nomes simples e constantes numricas
podem ser escritas tambm, mas sero convertidos em cadeias de caracteres.

Sadas
CREATE TRIGGER

Mensagem retornada se o gatilho for criado com sucesso.

CREATE TRIGGER

Descrio
O comando CREATE TRIGGER introduz um novo gatilho no banco de dados atual. O gatilho fica associado com
a relao tabela e executa a funo especificada funo.
O gatilho pode ser especificado para disparar antes (BEFORE) da operao ser realizada na tupla (antes das
restries serem verificadas e o INSERT, UPDATE ou DELETE serem efetuados), ou aps (AFTER) a operao
ser realizada (ou seja, aps as restries serem verificadas e o INSERT, UPDATE ou DELETE ter completado).
Se o gatilho disparar antes do evento, o gatilho pode evitar a operao para a tupla atual, ou modificar a tupla
sendo inserida (para as operaes de INSERT e UPDATE somente). Se o gatilho disparar aps o evento todas as
modificaes, incluindo a ltima insero, atualizao ou excluso, so visveis para o gatilho.
Se vrios gatilhos do mesmo tipo estiverem definidos para o mesmo evento, ento sero disparados na ordem
alfabtica de seus nomes.
O SELECT no modifica nenhuma linha, portanto no possvel criar gatilhos para SELECT. Regras e vises so
mais apropriadas para este caso.
Consulte os captulos sobre SPI (Interface de Programao do Servidor) e Gatilhos no Guia do Programador do
PostgreSQL para obter mais informaes.

Notas
Para criar um gatilho em uma tabela, o usurio deve possuir o privilgio TRIGGER na tabela.
Nas verses anteriores a 7.3 do PostgreSQL, era necessrio declarar as funes dos gatilhos com retorno do tipo
opaque em vez de trigger. Para permitir a carga das cpias de segurana antigas, o comando CREATE TRIGGER
vai aceitar funes declaradas como retornando opaque, mas vai exibir uma NOTICE e mudar o tipo declarado
de retorno da funo para trigger.
Na verso atual, gatilhos de declarao (STATEMENT triggers) no esto implementados.
Consulte o comando DROP TRIGGER para obter informaes sobre como remover gatilhos.

Exemplos
Antes de inserir ou atualizar uma linha da tabela filmes, verificar se o cdigo do distribuidor existe na tabela de
distribuidores:
CREATE TRIGGER se_dist_existe
BEFORE INSERT OR UPDATE ON filmes FOR EACH ROW
EXECUTE PROCEDURE verificar_chave_primaria (did, distribuidores, did);

Antes de remover um distribuidor, ou de atualizar o seu cdigo, remover todas as referncias na tabela filmes:
CREATE TRIGGER se_filme_existe
BEFORE DELETE OR UPDATE ON distribuidores FOR EACH ROW
EXECUTE PROCEDURE verificar_chave_primaria (1, CASCADE, did, filmes, did);

O segundo exemplo tambm pode ser implementado usando uma chave estrangeira, como em:
CREATE TABLE distribuidores (
did
DECIMAL(3),
nome
VARCHAR(40),

CREATE TRIGGER
CONSTRAINT se_filme_existe
FOREIGN KEY(did) REFERENCES filmes
ON UPDATE CASCADE ON DELETE CASCADE
);

Compatibilidade
SQL92
No existe o comando CREATE TRIGGER no SQL92.
SQL99
O comando CREATE TRIGGER do PostgreSQL implementa um subconjunto do padro SQL99. As seguintes
funcionalidades esto faltando:

O SQL99 permite os gatilhos dispararem quando da atualizao de colunas especficas (por exemplo,
AFTER UPDATE OF col1, col2).

O SQL99 permite definir alis para as linhas ou tabelas velha e nova para uso na definio das
aes do gatilho (por exemplo, CREATE TRIGGER ... ON nome_tabela REFERENCING OLD ROW
AS algum_nome NEW ROW AS outro_nome ...). Como o PostgreSQL permite que os procedimentos
dos gatilhos sejam escritos em qualquer linguagem definida pelo usurio, o acesso aos dados realizado
na forma especfica da linguagem.

O PostgreSQL somente possui gatilhos no nvel de linha, no possuindo gatilhos no nvel de declarao.

O PostgreSQL somente permite a execuo de procedimentos armazenados para a ao do gatilho. O

SQL99 permite a execuo de vrios outros comandos SQL, como o CREATE TABLE, para a ao de
um gatilho. Esta limitao no difcil de ser contornada criando-se um procedimento armazenado que
execute estes comandos.

O SQL99 especifica que mltiplos gatilhos devem ser disparados na ordem da data de criao. O PostgreSQL
usa a ordem dos nomes, que foi julgada mais conveniente para se trabalhar.

Consulte tambm
CREATE FUNCTION, ALTER TRIGGER, DROP TRIGGER, Guia do Programador do PostgreSQL

CREATE TYPE
Nome
CREATE TYPE cria um tipo de dado

Sinopse
CREATE TYPE nome_do_tipo ( INPUT = input_function, OUTPUT = funo_de_sada
, INTERNALLENGTH = { comprimento_interno | VARIABLE }
[ , DEFAULT = padro ]
[ , ELEMENT = elemento ] [ , DELIMITER = delimitador ]
[ , PASSEDBYVALUE ]
[ , ALIGNMENT = alinhamento ]
[ , STORAGE = armazenamento ]
)
CREATE TYPE nome_do_tipo AS
( nome_da_coluna tipo_de_dado [, ... ] )

Entradas
nome_do_tipo
O nome (opcionalmente qualificado pelo esquema) do tipo a ser criado.
comprimento_interno
Um valor literal, especificando o comprimento interno do novo tipo.
funo_de_entrada
O nome da funo criada pelo comando CREATE FUNCTION que converte os dados da forma externa para a
forma interna do tipo.
funo_de_sada
O nome da funo criada pelo comando CREATE FUNCTION que converte os dados da forma interna numa
forma adequada para ser exibida.
elemento
O tipo sendo criado uma matriz (array); especifica o tipo dos elementos da matriz.
delimitador
O caractere delimitador a ser usado entre os valores das matrizes (arrays) deste tipo.
padro
O valor padro para o tipo de dado. Usualmente omitido, fazendo com que NULL seja o padro.
alinhamento
Alinhamento de armazenamento requerido por este tipo de dado. Se for especificado, deve ser char, int2,
int4 ou double; o padro int4.

CREATE TYPE
armazenamento
Tcnica de armazenamento para este tipo de dado. Se for especificado, deve ser plain, external,
extended ou main; o padro plain.

nome_da_coluna
O nome de uma coluna do tipo composto.
tipo_de_dado
O nome de um tipo de dado existente.

Sadas
CREATE TYPE

Mensagem retornada se o tipo for criado com sucesso.

Descrio
O comando CREATE TYPE permite ao usurio registrar um novo tipo de dado do usurio no PostgreSQL, para ser
usado no banco de dados corrente. O usurio que define o tipo se torna o seu dono.
Se o nome do esquema for fornecido, ento o tipo ser criado no esquema especificado, seno ser criado no
esquema corrente (aquele na frente do caminho de procura; consulte CURRENT_SCHEMA()). O nome do tipo
deve ser diferente do nome de qualquer tipo ou domnio existente no mesmo esquema (uma vez que as tabelas
possuem tipos de dado associados, os nomes dos tipos tambm no podem ser iguais aos nomes das tabelas no
mesmo esquema).

Tipos Base
A primeira forma do comando CREATE TYPE cria um novo tipo base (tipo escalar). Requer o registro de duas
funes (usando CREATE FUNCTION) antes de definir o tipo. A representao do novo tipo base determinada
pela funo_de_entrada, que converte a representao externa do tipo na representao interna utilizvel
pelos operadores e funes definidas para o tipo. Naturalmente a funo_de_sada realiza a transformao
inversa. A funo de entrada pode ser declarada como recebendo um argumento do tipo cstring, ou como
recebendo trs argumentos dos tipos cstring, OID e int4. (O primeiro argumento o texto de entrada na forma
de uma cadeia de caracteres C, o segundo argumento o tipo do elemento no caso de ser uma matriz (array),
e o terceiro o typmod da coluna de destino, se for conhecido). Deve retornar um valor prprio tipo de dado.
A funo de sada pode ser declarada como recebendo um argumento do novo tipo de dado, ou recebendo dois
argumentos dos quais o segundo do tipo OID. (O segundo argumento novamente o tipo do elemento da matriz
para tipos array). A funo de sada deve retornar o tipo cstring.
Podemos estar nos perguntando neste ponto como as funes de entrada e de sada podem ser declaradas como
possuindo resultados ou entradas do novo tipo, se elas devem ser criadas antes do novo tipo ser criado. A resposta
que a funo de entrada deve ser criada primeiro, depois a funo de sada e depois o tipo de dado. O PostgreSQL
primeiramente ver o nome do novo tipo de dado como o tipo retornado pela funo de entrada, vai criar um tipo

CREATE TYPE
de abrigo, que simplesmente uma entrada na tabela pg_type, e vai ligar a definio da funo de entrada ao
tipo de abrigo. Analogamente, a funo de sada vai ser ligada ao (agora j existente) tipo de abrigo. Finalmente,
o CREATE TYPE substitui a entrada de abrigo com a definio completa do tipo, e o novo tipo poder ser usado.
Nota: Nas verses do PostgreSQL anteriores a 7.3, era comum evitar a criao do tipo de abrigo substituindo
as referncias frente das funes ao nome do tipo usando o pseudo-tipo OPAQUE. AS entradas e resultados
cstring tambm deviam ser declarados como OPAQUE antes da 7.3. Para permitir a carga de cpias de
segurana antigas, o CREATE TYPE vai aceitar as funes declaradas usando opaque, mas vai gerar uma
NOTICE e mudar a declarao da funo para usar o tipo correto.

Novos tipos de dado base podem ser de comprimento fixo e, neste caso, o comprimento_interno um
inteiro positivo, ou podem ser de comprimento varivel indicado por fazer comprimento_interno igual a
VARIABLE (Internamente representado definindo typlen como -1). A representao interna de todos os tipos
de comprimento varivel devem comear por um nmero inteiro indicando o comprimento total deste valor do
tipo.
Para indicar que o tipo uma matriz (array), especifica-se o tipo dos elementos da matriz usando a palavra chave
ELEMENT. Por exemplo, para definir uma matriz de inteiros de 4 bytes ("int4"), especifica-se
ELEMENT = int4

Mais detalhes sobre os tipos matriz so mostrados abaixo.

Para indicar o delimitador a ser usado entre os valores na representao externa das matrizes (arrays) deste tipo,
o delimitador pode ser especificado como um caractere especfico. O delimitador padro a vrgula, (,).
Observe que o delimitador est associado com o tipo de elemento da matriz, e no com a prpria matriz.
Um valor padro pode ser especificado quando o usurio desejar que as colunas com este tipo de dado tenham um
valor padro diferente de NULL. Especifica-se o padro com a palavra chave DEFAULT (Este tipo de padro pode
ser substitudo por um clusula DEFAULT explcita declarada na coluna).
O sinalizador opcional PASSEDBYVALUE indica que os valores deste tipo de dado so passados por valor, e no
por referncia. Observe que no se pode passar por valor os tipos cuja representao interna maior do que o
comprimento do tipo Datum (quatro bytes na maioria das mquinas, oito bytes em algumas).
A palavra chave alinhamento especifica o alinhamento do armazenamento requerido por este tipo de dado.
Os valores permitidos igualam-se ao alinhamento das fronteiras de 1, 2, 4 ou 8 bytes. Observe que os tipos de
tamanho varivel devem ter um alinhamento de pelo menos 4, porque contm necessariamente um int4 como
seu primeiro componente.
A palavra chave armazenamento permite selecionar estratgias de armazenamento para tipos de dado de comprimento varivel (somente plain permitido para os tipos de comprimento fixo). O plain desativa TOAST
para o tipo de dado: ser sempre armazenado em linha e no comprimido. O extended permite toda a capacidade
do TOAST: o sistema primeiro tenta comprimir um valor longo do dado, movendo o valor para fora da tabela principal se ainda continuar muito longo. O external permite que o valor seja movido para fora da tabela principal,
mas o sistema no vai tentar comprimi-lo. O main permite a compresso, mas desencoraja mover o valor para
fora da tabela principal (Os itens de dado com este mtodo de armazenamento ainda podem ser movidos para fora
da tabela principal se no houver outro meio para fazer o ajuste da linha, mas ser mantido na tabela principal
com preferncia maior que os itens extended e external).

Tipos Compostos
A segunda forma do CREATE TYPE cria um tipo composto. O tipo composto especificado por uma relao de
nomes de colunas e tipos de dado. essencialmente o mesmo que o tipo de uma linha de uma tabela, mas usando-

CREATE TYPE
se CREATE TYPE evita a necessidade de se criar uma tabela real quando tudo o que se deseja definir um tipo.
Um tipo composto autnomo til como o tipo de retorno de uma funo.

Tipos matriciais
Sempre que criado um tipo de dado definido pelo usurio, o PostgreSQL automaticamente cria um tipo matriz
(array) associado, cujo nome consiste do nome do tipo base prefixado por um caractere sublinhado. O analisador
compreende esta conveno de nome e traduz as requisies para colunas do tipo foo[] em requisies do tipo
_foo. O tipo matriz criado implicitamente de comprimento varivel e usa as funes de entrada e sada nativas
array_in e array_out.
Pode-se perguntar com razo porque existe a opo ELEMENT, se o sistema produz o tipo matriz correto automaticamente? O nico caso em que til utilizar ELEMENT quando se constri um tipo de comprimento fixo
que internamente uma matriz de N componentes idnticos, e deseja-se que estes N componentes sejam acessados diretamente por ndices em adio a qualquer outra operao que se planeje fornecer para este tipo como
um todo. Por exemplo, o tipo name permite que seus chars constituintes sejam acessados desta forma. Um tipo
point 2-D pode permitir que seus dois componentes sejam acessados como point[0] e point[1]. Observe
que esta facilidade somente funciona para tipos de comprimento fixo cuja forma interna seja exatamente uma
seqncia de N campos de tamanho fixo idnticos. Um tipo de comprimento varivel, para permitir ndices deve
possuir a representao interna generalizada usada por array_in e array_out. Por razes histricas (ou seja,
claramente errado mas muito tarde para mudar) os ndices das matrizes de comprimento fixo comeam em zero,
enquanto ndices das matrizes de comprimento varivel comeam em um.

Notas
Os nomes dos tipos definidos pelo usurio no podem comear pelo caractere sublinhado (_) e podem ter o
comprimento de apenas 62 caracteres (ou, de uma maneira geral, NAMEDATALEN-2 em vez dos NAMEDATALEN-1
caracteres permitidos para os outros nomes). Os nomes de tipo comeados por sublinhado so reservados para os
nomes dos tipos matriz criados internamente.

Exemplos
Este exemplo cria o tipo de dado caixa e, em seguida, usa o tipo na definio de uma tabela:
CREATE TYPE caixa (INTERNALLENGTH = 16,
INPUT = meu_procedimento_1, OUTPUT = meu_procedimento_2);
CREATE TABLE tbl_caixa (id INT4, descricao caixa);

Se a estrutura interna de caixa fosse uma matriz contendo quatro float4, poderamos escrever
CREATE TYPE caixa (INTERNALLENGTH = 16,
INPUT = meu_procedimento_1, OUTPUT = meu_procedimento_2,
ELEMENT = float4);

o que permitiria o valor de um componente da caixa ser acessado atravs do ndice. Fora isso o tipo se comporta
da mesma maneira que o anterior.
Este exemplo cria um tipo de objeto grande e o utiliza na definio de uma tabela:
CREATE TYPE objeto_grande (INPUT = lo_filein, OUTPUT = lo_fileout,

CREATE TYPE
INTERNALLENGTH = VARIABLE);
CREATE TABLE tbl_grandes_objetos (id int4, obj objeto_grande);

This example creates a composite type and uses it in a table function definition:

CREATE TYPE compfoo AS (f1 int, f2 text);

CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS SELECT fooid, fooname FROM foo LANGUAGE S

Compatibilidade
Este comando CREATE TYPE uma extenso do PostgreSQL. Existe um comando CREATE TYPE no SQL99 que
bastante diferente nos detalhes.

Consulte tambm
CREATE FUNCTION, DROP TYPE, Guia do Programador do PostgreSQL

CREATE USER
Nome
CREATE USER cria uma conta de usurio do banco de dados

Sinopse
CREATE USER nome_do_usurio [ [ WITH ] opo [ ... ] ]
onde opo pode ser:

|
|
|
|
|

SYSID uid
[ ENCRYPTED | UNENCRYPTED ] PASSWORD senha
CREATEDB | NOCREATEDB
CREATEUSER | NOCREATEUSER
IN GROUP nome_do_grupo [, ...]
VALID UNTIL data_hora

Descrio
O comando CREATE USER inclui um novo usurio em uma instncia do PostgreSQL. Consulte o Guia do Administrador para obter mais informaes sobre o gerenciamento de usurios e autenticao. Apenas os superusurios
do banco de dados podem usar este comando.

Parmetros
nome_do_usurio
O nome do usurio.
uid
A clusula SYSID pode ser utilizada para especificar o identificador do usurio sendo criado no PostgreSQL.
No , de forma alguma, necessrio que este identificador corresponda ao identificador do usurio no UNIX,
mas algumas pessoas optam por manter o mesmo nmero.
Se no for especificado, ser utilizado por padro o maior valor atribudo a um identificador de usurio
acrescido de 1 (com mnimo de 100).
senha
Define a senha do usurio. Se no se planeja utilizar autenticao por senha pode-se omitir esta opo, mas
o usurio no ser capaz de se conectar a um servidor autenticado por senha. A senha pode ser definida ou
alterada posteriormente atravs do comando ALTER USER.
ENCRYPTED
UNENCRYPTED

Estas palavras chave controlam se a senha armazenada criptografada, ou no, na tabela pg_shadow
(Se nenhuma das duas for especificada, o comportamento padro determinado pelo parmetro
PASSWORD_ENCRYPTION do servidor). Se a cadeia de caracteres apresentada j estiver criptografada
no formato MD5, ento esta cadeia de caracteres armazenada como est, independentemente de

CREATE USER
ENCRYPTED ou UNENCRYPTED ser especificado. Esta funcionalidade permite a restaurao das senhas
criptografadas efetuadas por uma operao de dump/restore.
Consulte o captulo sobre autenticao de cliente no Guia do Administrador para obter mais detalhes sobre
como configurar os mecanismos de autenticao. Observe que os clientes antigos podem no possuir suporte
ao mecanismo de autenticao para o MD5, que necessrio para trabalhar com as senhas armazenadas
criptografadas.
CREATEDB
NOCREATEDB

Estas clusulas definem a permisso para o usurio criar bancos de dados. Se CREATEDB for especificado, o
usurio sendo definido ter permisso para criar seus prprios bancos de dados. Se NOCREATEDB for especificado, nega-se ao usurio a permisso para criar bancos de dados. Se esta clusula for omitida, NOCREATEDB
ser utilizado por padro.
CREATEUSER
NOCREATEUSER

Estas clusulas determinam se permitido ou no o usurio criar novos usurios. Esta opo tambm torna
o usurio um superusurio, que pode modificar todas as restries de acesso. Se esta clusula for omitida, o
valor deste atributo para o usurio ser NOCREATEUSER.
nome_do_grupo
O nome do grupo onde o usurio ser includo como um novo membro. Nomes de vrios grupos podem estar
presentes.
data_hora
A clusula VALID UNTIL define uma data e hora aps a qual a senha do usurio no mais vlida. Se esta
clusula for omitida, a conta ser vlida para sempre.

Diagnsticos
CREATE USER

Mensagem retornada se o comando for executado com sucesso.

Notas
Use o comando ALTER USER para mudar os atributos do usurio e DROP USER para remover o usurio. Use
ALTER GROUP para incluir ou remover o usurio em grupos. O PostgreSQL possui o aplicativo createuser que
tem a mesma funcionalidade deste comando (na verdade, chama este comando), mas que pode ser executado a
partir da linha de comando.

CREATE USER

Exemplos
Criar um usurio sem senha:
CREATE USER jonas;

Criar um usurio com senha:

CREATE USER manuel WITH PASSWORD jw8s0F4;

Criar um usurio com senha, cuja conta seja vlida at o fim de 2001. Observe que no primeiro instante de 2002
esta conta no ser mais vlida:
CREATE USER miriam WITH PASSWORD jw8s0F4 VALID UNTIL Jan 1 2002;

Criar uma conta onde o usurio pode criar bancos de dados:

CREATE USER manuel WITH PASSWORD jw8s0F4 CREATEDB;

Compatibilidade
O comando CREATE USER uma extenso do PostgreSQL. O padro SQL deixa a criao dos usurios por conta
da implementao.

Consulte tambm
ALTER USER, DROP USER, createuser

CREATE VIEW
Nome
CREATE VIEW cria uma viso

Sinopse
CREATE [ OR REPLACE ] VIEW viso [ ( nomes_de_colunas ) ] AS SELECT consulta

Entradas
viso
O nome (opcionalmente qualificado pelo esquema) da viso a ser criada.
nomes_de_colunas
Uma relao opcional de nomes a serem usados para as colunas da viso. Quando fornecidos, estes nomes
substituem os nomes inferidos a partir da consulta SQL.
consulta
Uma consulta SQL (ou seja, um comando SELECT) que gera as colunas e as linhas da viso.
Consulte o comando SELECT para obter mais informaes sobre os argumentos vlidos.

Sadas
CREATE VIEW

Mensagem retornada se a viso for criada com sucesso.

ERROR: Relation viso already exists

Este erro ocorre se a viso especificada j existir no banco de dados.

WARNING: Attribute nome_da_coluna has an unknown type

A viso ser criada possuindo uma coluna de tipo desconhecido se no for especificado. Por exemplo, o
seguinte comando gera esta advertncia:
CREATE VIEW vista AS SELECT Al Mundo

enquanto o comando abaixo no gera esta advertncia:

CREATE VIEW vista AS SELECT text Al Mundo

CREATE VIEW

Descrio
O comando CREATE VIEW cria uma viso. A viso no fisicamente materializada. Em vez disso, uma regra
automaticamente criada (uma regra ON SELECT) para realizar as operaes de SELECT na viso.
O comando CREATE OR REPLACE VIEW semelhante, mas se uma viso com o mesmo nome existir ento
substituda. Somente pode ser substituda uma viso por outra que produza um conjunto idntico de colunas (ou
seja, colunas com os mesmos nomes e os mesmos tipos de dado).
Se o nome do esquema for fornecido (por exemplo, CREATE VIEW meu_esquema.minha_visao ...) ento a
viso ser criada no esquema especificado, seno ser criada no esquema corrente (aquele na frente do caminho
de procura; consulte CURRENT_SCHEMA()). O nome da viso deve ser diferente do nome de qualquer outra viso,
tabela, seqncia ou ndice no mesmo esquema.

Notas
Atualmente, as vises so apenas para leitura: o sistema no permite incluso, atualizao ou excluso em uma
viso. possvel obter o efeito de uma viso atualizvel criando-se regras que troquem as incluses, ... na viso
por aes apropriadas em outras tabelas. Para mais informaes consulte o comando CREATE RULE.
Use o comando DROP VIEW para excluir uma viso.

Utilizao
Criar uma viso consistindo de todos os filmes de comdia:
CREATE VIEW comedias AS
SELECT *
FROM filmes
WHERE tipo = Comdia;
SELECT * FROM comedias;
cod
|
titulo
| did | data_prod | tipo
| duracao
-------+---------------------------+-----+------------+---------+-------UA502 | Bananas
| 105 | 1971-07-13 | Comdia | 01:22
C_701 | Theres a Girl in my Soup | 107 | 1970-06-11 | Comdia | 01:36
(2 rows)

Compatibilidade
SQL92
O SQL92 especifica algumas funcionalidades adicionais para o comando CREATE VIEW:
CREATE VIEW viso [ coluna [, ...] ]
AS SELECT expresso [ AS nome_da_coluna ] [, ...]
FROM tabela [ WHERE condio ]
[ WITH [ CASCADE | LOCAL ] CHECK OPTION ]

CREATE VIEW
As clusulas opcionais para o comando SQL92 completo so:
CHECK OPTION
Esta opo est relacionada com as vises atualizveis. Todos os comandos INSERT e UPDATE em uma viso
sero verificados para garantir que os dados satisfazem as condies que definem a viso. Se no satisfizer,
a atualizao ser rejeitada.
LOCAL
Verifica a integridade nesta viso.
CASCADE
Verifica a integridade nesta viso e em todas as vises dependentes. CASCADE assumido se nem CASCADE nem LOCAL forem especificados.

O comando CREATE OR REPLACE VIEW uma extenso do PostgreSQL linguagem.

DEALLOCATE
Nome
DEALLOCATE remove uma consulta preparada

Sinopse
DEALLOCATE [ PREPARE ] nome

Entradas
PREPARE
Esta palavra chave ignorada.
nome
O nome da consulta preparada a ser removida.

Sadas
DEALLOCATE

A consulta preparada foi removida com sucesso.

Descrio
O comando DEALLOCATE utilizado para remover uma consulta preparada anteriormente. Se uma consulta
preparada no for removida por um comando DEALLOCATE explcito, ento ser removida no trmino da sesso.
Para obter mais informaes sobre as consultas preparada consulte o comando PREPARE.

Compatibilidade
SQL92
O SQL92 inclui o comando DEALLOCATE, mas apenas para ser usado no SQL embutido nos clientes.

DECLARE
Nome
DECLARE define um cursor

Sinopse
DECLARE nome_do_cursor [ BINARY ] [ INSENSITIVE ] [ SCROLL ]
CURSOR FOR consulta
[ FOR { READ ONLY | UPDATE [ OF coluna [, ...] ] ]

Entradas
nome_do_cursor
O nome do cursor a ser utilizado nas operaes de busca (FETCH) posteriores.
BINARY
Faz com que o cursor busque os dados no formato binrio em vez do formato texto.
INSENSITIVE
Palavra chave do SQL92 indicando que os dados buscados pelo cursor no devem ser afetados pelas atualizaes feitas por outros processos ou cursores. Como as operaes do cursor ocorrem dentro de uma transao
no PostgreSQL, este sempre o caso. Esta palavra chave no provoca qualquer efeito.
SCROLL
Palavra chave do SQL92 indicando que vrias linhas de dados devem ser trazidas em cada operao de busca
(FETCH). Como sempre permitido pelo PostgreSQL, esta palavra chave no provoca qualquer efeito.
consulta
Uma consulta SQL que fornece as linhas a serem controladas pelo cursor. Consulte o comando SELECT
para obter mais informaes sobre os argumentos vlidos.
READ ONLY
Palavra chave do SQL92 indicando que o cursor ser usado no modo apenas para leitura. Como este o
nico modo de acesso do cursor disponvel no PostgreSQL, esta palavra chave no provoca qualquer efeito.
UPDATE
Palavra chave do SQL92 indicando que o cursor ser usado para atualizar tabelas. Como as atualizaes
pelo cursor no so suportadas no momento pelo PostgreSQL, esta palavra chave provoca uma mensagem
informando o erro.
coluna
Coluna(s) a serem atualizadas. Como as atualizaes pelo cursor no so suportadas no momento pelo PostgreSQL, a clusula UPDATE provoca uma mensagem informando o erro.

DECLARE

Sadas
DECLARE CURSOR

Mensagem retornada se o SELECT for executado com sucesso.

WARNING: Closing pre-existing portal "nome_do_cursor"

Esta mensagem exibida se o mesmo nome de cursor j estiver declarado no bloco de transao corrente. A
definio anterior descartada.
ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks

Este erro ocorre quando o cursor no declarado dentro de um bloco de transao.

Descrio
O comando DECLARE permite ao usurio criar cursores, os quais podem ser usados para buscar de cada vez um
pequeno nmero de linhas de uma consulta grande. Os cursores podem retornar dados tanto no formato texto
quanto binrio usando o comando FETCH.
Os cursores normais retornam os dados no formato texto, em ASCII ou outro esquema de codificao dependendo de como o servidor PostgreSQL foi compilado. Como os dados so armazenados nativamente no formato
binrio, o sistema necessita fazer uma converso para produzir o formato texto. Adicionalmente, o formato texto
geralmente possui um tamanho maior do que o formato binrio correspondente. Quando a informao retorna na
forma de texto, o aplicativo cliente pode precisar converter para o formato binrio para manipul-la. Os cursores
binrios retornam os dados na representao binria nativa.
Por exemplo, se uma consulta retornar o valor um de uma coluna inteira, ser recebida a cadeia de caracteres 1
com o cursor padro, enquanto que o cursor binrio retornaria um valor de 4 bytes igual a control-A (^A).
Os cursores binrios devem ser usados com cuidado. Aplicativos do usurio, como o psql, no esto atentos a
cursores binrios, esperando que os dados cheguem no formato texto.
A representao da cadeia de caracteres arquiteturalmente neutra, enquanto que a representao binria pode ser
diferente entre mquinas com arquiteturas diferentes. O PostgreSQL no soluciona a ordem dos bytes ou outros
problemas de representao para os cursores binrios. Portanto, se a mquina cliente e a mquina servidora usam
representaes diferentes, (por exemplo, big-endian versus little-endian), provavelmente no vai ser desejado
que os dados retornem no formato binrio. Entretanto, os cursores binrios podem ser um pouco mais eficientes
porque existe menos sobrecarga de converso na transferncia de dados do servidor para o cliente.
Dica: Se a inteno for mostrar os dados em ASCII, buscar os dados em ASCII reduz o esforo realizado
pelo cliente.

Notas
Os cursores s esto disponveis nas transaes. Use os comando BEGIN, COMMIT e ROLLBACK para definir
um bloco de transao.

DECLARE
No SQL92 os cursores somente esto disponveis nos aplicativos com SQL embutido (ESQL). O servidor PostgreSQL no implementa o comando OPEN cursor explcito; o cursor considerado aberto ao ser declarado.
Entretanto, o ecpg, o pr-processador SQL embutido do PostgreSQL, suporta as convenes de cursor do SQL92,
incluindo as que envolvem os comandos DECLARE e OPEN.

Utilizao
Para declarar um cursor:
DECLARE liahona CURSOR
FOR SELECT * FROM filmes;

Compatibilidade
SQL92
O SQL92 permite cursores somente no SQL embutido e em mdulos. O PostgreSQL permite que o cursor seja
usado interativamente. O SQL92 permite aos cursores embutidos ou modulares atualizar as informaes no banco
de dados. Todos os cursores do PostgreSQL so apenas para leitura. A palavra chave BINARY uma extenso do
PostgreSQL.

DELETE
Nome
DELETE exclui linhas de uma tabela

Sinopse
DELETE FROM [ ONLY ] tabela [ WHERE condio ]

Entradas
tabela
O nome (opcionalmente qualificado pelo esquema) de uma tabela existente.
condio
Uma condio de consulta do SQL que retorna as linhas a serem excludas.
Consulte o comando SELECT para obter mais informaes sobre a clusula WHERE.

Sadas
DELETE contador

Mensagem retornada se as linhas foram excludas com sucesso. O contador representa o nmero de linhas
excludas.
Se contador for 0, ento nenhuma linha foi excluda.

Descrio
O comando DELETE exclui as linhas que satisfazem a clusula WHERE na tabela especificada.
Se a condio (clusula WHERE) estiver ausente, o efeito a excluso de todas as linhas da tabela. O resultado
vai ser uma tabela vlida, porm vazia.
Dica: O comando TRUNCATE uma extenso do PostgreSQL que fornece um mecanismo rpido para excluir
todas as linhas de uma tabela.

DELETE
Por padro o DELETE exclui as linhas da tabela especificada e de todas as suas filhas. Para atualizar somente a
tabela especificada deve ser utilizada a clusula ONLY.
necessrio possuir acesso de escrita a uma tabela para poder modific-la, assim como acesso de leitura em todas
as tabelas cujos valores so lidos na condio da clusula WHERE.

Utilizao
Remover todos os filmes, exceto os musicais:
DELETE FROM filmes WHERE tipo <> Musical;
SELECT * FROM filmes;
cod
|
titulo
| did | data_prod | tipo
| duracao
-------+---------------------------+-----+------------+---------+--------UA501 | West Side Story
| 105 | 1961-01-03 | Musical | 02:32
TC901 | The King and I
| 109 | 1956-08-11 | Musical | 02:13
WD101 | Bed Knobs and Broomsticks | 111 |
| Musical | 01:57
(3 rows)

Esvaziar a tabela filmes:

DELETE FROM filmes;
SELECT * FROM filmes;
cod | titulo | did | data_prod | tipo | duracao
------+--------+-----+-----------+------+--------(0 rows)

Compatibilidade
SQL92
O SQL92 permite uma declarao DELETE posicionada:
DELETE FROM tabela WHERE
CURRENT OF cursor

onde cursor identifica um cursor aberto. Cursores interativos no PostgreSQL so apenas para leitura.

DROP AGGREGATE
Nome
DROP AGGREGATE remove uma funo de agregao definida pelo usurio

Sinopse
DROP AGGREGATE nome ( tipo ) [ CASCADE | RESTRICT ]

Entradas
nome
O nome (opcionalmente qualificado pelo esquema) de uma funo de agregao existente.
tipo
O tipo de dado de entrada da funo de agregao, ou * se a funo aceita qualquer tipo de dado de entrada
(Consulte o Guia do Usurio do PostgreSQL para obter mais informaes sobre tipos de dado).
CASCADE
Exclui automaticamente os objetos que dependem da funo de agregao.
RESTRICT
No exclui a funo de agregao se existirem objetos dependentes. Este o padro.

Sadas
DROP AGGREGATE

Mensagem retornada se o comando for executado com sucesso.

ERROR: RemoveAggregate: aggregate nome for type tipo does not exist

Esta mensagem ocorre quando a funo de agregao especificada no existe no banco de dados.

Descrio
O comando DROP AGGREGATE remove a definio da funo de agregao. Para executar este comando o usurio
corrente deve ser o dono da funo de agregao.

DROP AGGREGATE

Notas
Utilize o comando CREATE AGGREGATE para criar funes de agregao.

Utilizao
Para remover a funo de agregao minha_media para o tipo de dado int4:
DROP AGGREGATE minha_media(int4);

Compatibilidade
SQL92
No existe o comando CREATE AGGREGATE no SQL92. O comando CREATE AGGREGATE uma extenso do
PostgreSQL linguagem.

DROP CAST
Nome
DROP CAST remove uma transformao definida pelo usurio

Sinopse
DROP CAST (tipo_de_origem AS tipo_de_destino)
[ CASCADE | RESTRICT ]

Descrio
O comando DROP CAST remove uma transformao previamente definida.
Para poder remover uma transformao, deve-se ser o dono do tipo de dado de origem ou de destino. Estes so os
mesmos privilgios necessrios para criar uma transformao.

Parmetros
tipo_de_origem
O nome do tipo de dado de origem da transformao.
tipo_de_destino
O nome do tipo de dado de destino da transformao.
CASCADE
RESTRICT

Estas palavras chave no possuem nenhum efeito, uma vez que no existem dependncias para as converses.

Notas
Use o comando CREATE CAST para criar uma transformao definida pelo usurio.

Exemplos
Para remover a transformao do tipo text para o tipo int:
DROP CAST (text AS int4);

Compatibilidade
O comando DROP CAST est em conformidade com o SQL99.

DROP CAST

Consulte tambm
CREATE CAST

DROP CONVERSION
Nome
DROP CONVERSION remove uma converso definida pelo usurio

Sinopse
DROP CONVERSION nome_da_converso
[ CASCADE | RESTRICT ]

Descrio
O comando DROP CONVERSION remove uma converso definida anteriormente.
Para ser possvel remover uma converso necessrio ser o dono da converso.

Parmetros
nome_da_converso
O nome da converso. O nome da converso pode ser qualificado pelo esquema.
CASCADE
RESTRICT

Estas palavras chave no produzem nenhum efeito, uma vez que no h dependncias em converses.

Notas
Use o comando CREATE CONVERSION para criar uma converso definida pelo usurio.
Os privilgios exigidos para remover uma converso podem mudar em verses futuras.

Exemplos
Para remover a converso chamada minha_conversao:
DROP CONVERSION minha_conversao;

Compatibilidade
O comando DROP CONVERSION uma extenso do PostgreSQL. No existe o comando DROP CONVERSION no
SQL99.

DROP CONVERSION

Consulte tambm
CREATE CONVERSION

DROP DATABASE
Nome
DROP DATABASE remove um banco de dados

Sinopse
DROP DATABASE nome

Entradas
nome
O nome do banco de dados existente a ser removido

Sadas
DROP DATABASE

Mensagem retornada se o comando for executado com sucesso.

DROP DATABASE: cannot be executed on the currently open database

No possvel estar conectado ao banco de dados que se deseja remover. Conecte-se ao banco de dados
template1, ou a qualquer outro banco de dados, e execute este comando novamente.
DROP DATABASE: may not be called in a transaction block

Antes de executar este comando deve-se concluir a transao em andamento.

Descrio
O comando DROP DATABASE remove as entradas do catlogo para um banco de dados existente e remove o
diretrio contendo os dados. Somente pode ser executado pelo dono do banco de dados (normalmente o usurio
que o criou).
O comando DROP DATABASE no pode ser desfeito. Use com prudncia!

Notas
Este comando no pode ser executado enquanto conectado ao banco de dados de destino. Portanto, mais conveniente utilizar o script dropdb, que uma envoltria em torno deste comando.

DROP DATABASE
Consulte o comando CREATE DATABASE para obter informaes sobre como criar bancos de dados.

Compatibilidade
SQL92
O comando DROP DATABASE uma extenso do PostgreSQL linguagem. No existe este comando no SQL92.

DROP DOMAIN
Nome
DROP DOMAIN remove um domnio definido pelo usurio

Sinopse
DROP DOMAIN nome_do_domnio [, ...]

[ CASCADE | RESTRICT ]

Entradas
nome_do_domnio
O nome (opcionalmente qualificado pelo esquema) de um domnio existente.
CASCADE

Remove automaticamente os objetos que dependem do domnio (como colunas de tabelas).

RESTRICT

Recusa excluir o domnio se existirem objetos dependentes. Este o padro.

Sadas
DROP DOMAIN

Mensagem retornada se o comando for executado com sucesso.

ERROR: RemoveDomain: type nome_do_domnio does not exist

Esta mensagem ocorre quando o domnio especificado (ou tipo) no encontrado.

Descrio
O comando DROP DOMAIN remove um domnio do usurio dos catlogos do sistema.
Somente o dono pode remover o domnio.

DROP DOMAIN

Exemplos
Para remover o domnio caixa:
DROP DOMAIN caixa;

Compatibilidade
SQL92

Consulte tambm
CREATE DOMAIN

DROP FUNCTION
Nome
DROP FUNCTION remove uma funo definida pelo usurio

Sinopse
DROP FUNCTION nome ( [ tipo [, ...] ] ) [ CASCADE | RESTRICT ]

Entradas
nome
O nome (opcionalmente qualificado pelo esquema) de uma funo existente.
tipo
O tipo de um parmetro da funo.
CASCADE
Remove automaticamente os objetos que dependem da funo (como operadores e gatilhos).
RESTRICT
Recusa remover a funo se existirem objetos dependentes. Este o padro.

Sadas
DROP FUNCTION

Mensagem retornada se o comando for executado com sucesso.

WARNING: RemoveFunction: Function "nome" ("tipo") does not exist

Esta mensagem retornada quando a funo especificada no existe no banco de dados corrente.

Descrio
O comando DROP FUNCTION remove a definio de uma funo existente. Para executar este comando o
usurio deve ser o dono da funo. Os tipos de dado dos argumentos de entrada da funo devem ser especificados,
porque vrias funes diferentes podem existir com o mesmo nome, mas com argumentos diferentes.

DROP FUNCTION

Notas
Consulte o comando CREATE FUNCTION para obter informaes sobre como criar funes.

Exemplos
Este comando remove a funo que calcula a raiz quadrada:
DROP FUNCTION sqrt(integer);

Compatibilidade
O comando DROP FUNCTION definido no SQL99. Uma de suas sintaxes similar do PostgreSQL.

Consulte tambm
CREATE FUNCTION

DROP GROUP
Nome
DROP GROUP remove um grupo de usurios

Sinopse
DROP GROUP nome

Entradas
nome
O nome de um grupo existente.

Sadas
DROP GROUP

Mensagem retornada se o grupo for removido com sucesso.

Descrio
O comando DROP GROUP remove do banco de dados o grupo especificado. Os usurios cadastrados no grupo no
so removidos.
Use o CREATE GROUP para criar grupos novos, e o ALTER GROUP para gerenciar os membros do grupo.

Utilizao
Para eliminar um grupo:
DROP GROUP engenharia;

DROP GROUP

Compatibilidade
SQL92
No existe o comando DROP GROUP no SQL92.

DROP INDEX
Nome
DROP INDEX remove um ndice

Sinopse
DROP INDEX nome_do_ndice [, ...] [ CASCADE | RESTRICT ]

Entradas
nome_do_ndice
O nome (opcionalmente qualificado pelo esquema) do ndice a ser removido.
CASCADE
Remove automaticamente os objetos que dependem do ndice.
RESTRICT
Recusa remover o ndice se existirem objetos dependente. Este o padro.

Sadas
DROP INDEX

Mensagem retornada se o comando for executado com sucesso.

ERROR: index "nome_do_ndice" does not exist

Esta mensagem ocorre se nome_do_ndice no for um ndice no banco de dados.

Descrio
O comando DROP INDEX remove um ndice existente no sistema de banco de dados. Para executar este comando
necessrio ser o dono do ndice.

Notas
O comando DROP INDEX uma extenso da linguagem do PostgreSQL.
Consulte o comando CREATE INDEX para obter informaes sobre como criar ndices.

DROP INDEX

Utilizao
Remover o ndice titulo_idx:
DROP INDEX titulo_idx;

Compatibilidade
SQL92
O SQL92 define comandos atravs dos quais um banco de dados relacional genrico pode ser acessado. O ndice
uma funcionalidade dependente da implementao e portanto no existe comando especfico para ndice ou a
sua definio na linguagem SQL92.

DROP LANGUAGE
Nome
DROP LANGUAGE remove uma linguagem procedural definida pelo usurio

Sinopse
DROP [ PROCEDURAL ] LANGUAGE nome [ CASCADE | RESTRICT ]

Entradas
nome
O nome de uma linguagem procedural existente. Para manter a compatibilidade com as verses anteriores o
nome pode estar entre apstrofos ().
CASCADE
Remove automaticamente os objetos que dependem da linguagem (como as funes escritas nesta linguagem).
RESTRICT
Recusa remover a linguagem se existirem objetos dependentes. Este o padro.

Sadas
DROP LANGUAGE

Mensagem retornada se a linguagem for removida com sucesso.

ERROR: Language "nome" doesnt exist

Esta mensagem ocorre quando a linguagem chamada nome no encontrada no banco de dados.

Descrio
O comando DROP PROCEDURAL LANGUAGE remove a definio da linguagem procedural registrada anteriormente chamada nome.

DROP LANGUAGE

Notas
O comando DROP PROCEDURAL LANGUAGE uma extenso do PostgreSQL linguagem.
Consulte o comando CREATE LANGUAGE para obter informaes sobre como criar linguagens procedurais.

Utilizao
Remover a linguagem PL/Sample:
DROP LANGUAGE plsample;

Compatibilidade
SQL92
No existe o comando DROP PROCEDURAL LANGUAGE no SQL92.

DROP OPERATOR
Nome
DROP OPERATOR remove um operador definido pelo usurio

Sinopse
DROP OPERATOR id ( tipo_esquerdo | NONE , tipo_direito | NONE ) [ CASCADE | RESTRICT ]

Entradas
id
O identificador (opcionalmente qualificado pelo esquema) de um operador existente.
tipo_esquerdo
O tipo do argumento do lado esquerdo do operador; deve ser escrito NONE se o operador no possuir argumento do lado esquerdo.
tipo_direito
O tipo do argumento do lado direito do operador; deve ser escrito NONE se o operador no possuir argumento
do lado direito.
CASCADE
Remove automaticamente os objetos que dependem do operador.
RESTRICT
Recusa remover o operador se existirem objetos dependentes. Este o padro.

Sadas
DROP OPERATOR

Mensagem retornada se o comando for executado com sucesso.

ERROR: RemoveOperator: binary operator operador taking tipo_esquerdo and
tipo_direito does not exist

Esta mensagem ocorre quando o operador binrio especificado no existe.

ERROR: RemoveOperator: left unary operator opererador taking tipo_esquerdo does
not exist

Esta mensagem ocorre quando o operador unrio esquerdo especificado no existe.

DROP OPERATOR
ERROR: RemoveOperator: right unary operator operador taking tipo_direito does
not exist

Esta mensagem ocorre quando o operador unrio direito especificado no existe.

Descrio
O comando DROP OPERATOR remove um operador existente do banco de dados. Para executar este comando
necessrio ser o dono do operador.
O tipo do lado esquerdo ou direito de um operador unrio esquerdo ou direito, respectivamente, deve ser especificado como NONE.

Notas
O comando DROP OPERATOR uma extenso da linguagem do PostgreSQL.
Consulte o comando CREATE OPERATOR para obter informaes sobre como criar operadores.

Utilizao
Remover o operador de potncia a^n para int4:
DROP OPERATOR ^ (int4, int4);

Remover o operador de negao unrio esquerdo (! b) para booleano:

DROP OPERATOR ! (none, bool);

Remover o operador de fatorial unrio direito (i !) para int4:

DROP OPERATOR ! (int4, none);

Compatibilidade
SQL92
No existe o comando DROP OPERATOR no SQL92.

DROP OPERATOR CLASS

Nome
DROP OPERATOR CLASS remove uma classe de operadores definida pelo usurio

Sinopse
DROP OPERATOR CLASS nome USING mtodo_de_acesso [ CASCADE | RESTRICT ]

Entradas
name
O nome (opcionalmente qualificado pelo esquema) de uma classe de operadores existente.
mtodo_de_acesso
O nome do mtodo de acesso do ndice para o qual a classe de operadores se destina.
CASCADE
Remove automaticamente os objetos dependentes da classe de operadores.
RESTRICT
Recusa excluir a classe de operadores se existirem objetos dependentes. Este o comportamento padro.

Sadas
DROP OPERATOR CLASS

Mensagem retornada se o comando for executado com sucesso.

Descrio
O comando DROP OPERATOR CLASS remove do banco de dados uma classe de operadores existente. Para executar este comando deve-se ser o dono da classe de operadores.

Notas
O comando DROP OPERATOR CLASS uma extenso do PostgreSQL linguagem.
Consulte o comando CREATE OPERATOR CLASS para obter informaes sobre como criar classes de operadores.

DROP OPERATOR CLASS

Utilizao
Remover a classe de operadores B-treechamada widget_ops:
DROP OPERATOR CLASS widget_ops USING btree;

Este comando no executa quando existe algum ndice dependente da classe de operadores. Deve-se especificar
CASCADE para remover estes ndices junto com a classe de operadores.

Compatibilidade
SQL92
No existe o comando DROP OPERATOR CLASS no SQL92.

DROP RULE
Nome
DROP RULE remove uma regra

Sinopse
DROP RULE nome ON relao [ CASCADE | RESTRICT ]

Entradas
nome
O nome de uma regra existente a ser removida.
relao
O nome (opcionalmente qualificado pelo esquema) da relao qual a regra se aplica.
CASCADE
Remove automaticamente os objetos que dependem da regra.
RESTRICT
Recusa remover a regra se existirem objetos dependentes. Este o padro.

Sadas
DROP RULE

Mensagem retornada se o comando for executado com sucesso.

ERROR: Rule "nome" not found

Esta mensagem ocorre quando a regra especificada no existe.

Descrio
O comando DROP RULE remove uma regra do conjunto de regras do PostgreSQL. O PostgreSQL pra imediatamente de imp-la e remove sua definio dos catlogos do sistema.

DROP RULE

Notas
O comando DROP RULE uma extenso do PostgreSQL linguagem.
Consulte o comando CREATE RULE para obter informaes sobre como criar regras.

Utilizao
Para remover a regra nova_regra:
DROP RULE nova_regra ON minha_tabela;

Compatibilidade
SQL92
No existe o comando DROP RULE no SQL92.

DROP SCHEMA
Nome
DROP SCHEMA remove um esquema

Sinopse
DROP SCHEMA nome [, ...] [ CASCADE | RESTRICT ]

Entradas
nome
O nome do esquema.
CASCADE
Remove automaticamente os objetos (tabelas, funes, etc...) que esto contidos no esquema.
RESTRICT
Recusa remover o esquema se este contiver algum objeto. Este o padro.

Sadas
DROP SCHEMA

Mensagem retornada se o esquema for excludo com sucesso.

ERROR: Schema "nome" does not exist

Esta mensagem ocorre quando o esquema especificado no existe.

Descrio
DROP SCHEMA remove esquemas de um banco de dados.

Um esquema somente pode ser removido por seu dono ou por um superusurio. Observe que o dono pode remover
o esquema (e, portanto, todos os objetos que este contm) mesmo que no seja o dono de alguns dos objetos
contidos no esquema.

DROP SCHEMA

Notas
Consulte o comando CREATE SCHEMA para obter informaes sobre como criar um esquema.

Utilizao
Para remover do banco de dados o esquema meu_esquema junto com todos os objetos que esto contidos:
DROP SCHEMA meu_esquema CASCADE;

Compatibilidade
SQL92
O comando DROP SCHEMA totalmente compatvel com o SQL92, exceto que o padro permite apenas um esquema ser removido por comando.

DROP SEQUENCE
Nome
DROP SEQUENCE remove uma seqncia

Sinopse
DROP SEQUENCE nome [, ...] [ CASCADE | RESTRICT ]

Entradas
nome
O nome (opcionalmente qualificado pelo esquema) da seqncia.
CASCADE
Remove automaticamente os objetos que dependem da seqncia.
RESTRICT
Recusa remover a seqncia se existirem objetos dependentes. Este o padro.

Sadas
DROP SEQUENCE

Mensagem retornada se a seqncia for removida com sucesso.

ERROR: sequence "nome" does not exist

Esta mensagem ocorre quando a seqncia especificada no existe.

Descrio
O comando DROP SEQUENCE remove do banco de dados o gerador de nmeros seqenciais. Na implementao atual das seqncias como tabelas especiais, este comando funciona de maneira anloga ao comando DROP TABLE.

DROP SEQUENCE

Notas
O comando DROP SEQUENCE uma extenso do PostgreSQL linguagem.
Consulte o comando CREATE SEQUENCE para obter informaes sobre como criar seqncias.

Utilizao
Para remover do banco de dados a seqncia serial:
DROP SEQUENCE serial;

Compatibilidade
SQL92
No existe o comando DROP SEQUENCE no SQL92.

DROP TABLE
Nome
DROP TABLE remove uma tabela

Sinopse
DROP TABLE nome [, ...] [ CASCADE | RESTRICT ]

Entradas
nome
O nome (opcionalmente qualificado pelo esquema) de uma tabela existente a ser removida.
CASCADE
Remove automaticamente os objetos que dependem da tabela (como vises).
RESTRICT
Recusa remover a tabela se existirem objetos dependentes. Este o padro.

Sadas
DROP TABLE

Mensagem retornada se o comando for executado com sucesso.

ERROR: table "nome" does not exist

Se a tabela especificada no existe no banco de dados.

Descrio
O comando DROP TABLE remove tabelas do banco de dados. Somente o criador pode remover a tabela. A tabela
poder ficar sem linhas, mas no ser removida, usando o comando DELETE.
O comando DROP TABLE sempre remove todos os ndices, regras, gatilhos e restries existentes na tabela. Entretanto, para remover uma tabela que referenciada por uma restrio de chave estrangeira de outra tabela, o
CASCADE deve ser especificado (O CASCADE remove a restrio de chave restrangeira, e no a tabela).

DROP TABLE

Notas
Consulte os comandos CREATE TABLE e ALTER TABLE para obter informaes sobre como criar e modificar
tabelas.

Utilizao
Destruir as tabelas filmes e distribuidores:
DROP TABLE filmes, distribuidores;

Compatibilidade
SQL92

DROP TRIGGER
Nome
DROP TRIGGER remove um gatilho

Sinopse
DROP TRIGGER nome ON tabela [ CASCADE | RESTRICT ]

Entradas
nome
O nome de um gatilho existente.
tabela
O nome (opcionalmente qualificado pelo esquema) de uma tabela.
CASCADE
Remove automaticamente os objetos que dependem do gatilho.
RESTRICT
Recusa remover se existirem objetos dependentes. Este o padro.

Sadas
DROP TRIGGER

Mensagem retornada se o gatilho for removido com sucesso.

ERROR: DropTrigger: there is no trigger nome on relation "tabela"

Esta mensagem ocorre quando o gatilho especificado no existe.

Descrio
O comando DROP TRIGGER remove uma definio de gatilho existente. Para executar este comando o usurio
corrente deve ser o dono da tabela para a qual o gatilho est definido.

DROP TRIGGER

Exemplos
Remover o gatilho se_dist_existe da tabela filmes:
DROP TRIGGER se_dist_existe ON filmes;

Compatibilidade
SQL92
No existe o comando DROP TRIGGER no SQL92.
SQL99
O comando DROP TRIGGER do PostgreSQL no compatvel com o SQL99. No SQL99 os nomes dos
gatilhos no so locais s tabelas, portanto o comando simplesmente DROP TRIGGER nome.

Consulte tambm
CREATE TRIGGER

DROP TYPE
Nome
DROP TYPE remove um tipo de dado definido pelo usurio

Sinopse
DROP TYPE nome_do_tipo [, ...] [ CASCADE | RESTRICT ]

Entradas
nome_do_tipo
O nome (opcionalmente qualificado pelo esquema) de um tipo existente.
CASCADE
Remove automaticamente os objetos que dependem do tipo (como colunas de tabelas, funes, operadores,
etc..).
RESTRICT
Recusa remover o tipo se existirem objetos dependentes. Este o padro.

Sadas
DROP TYPE

Mensagem retornada se o comando for executado com sucesso.

ERROR: RemoveType: type nome_do_tipo does not exist

Esta mensagem ocorre quando o tipo especificado no encontrado.

Descrio
O comando DROP TYPE remove um tipo do usurio dos catlogos do sistema.
Somente o dono do tipo pode remov-lo.

DROP TYPE

Exemplos
Para remover o tipo caixa:
DROP TYPE caixa;

Compatibilidade
Observe que o comando CREATE TYPE e os mecanismos de extenso de tipo do PostgreSQL so diferentes do
SQL99.

Consulte tambm
CREATE TYPE

DROP USER
Nome
DROP USER remove uma conta de usurio do banco de dados

Sinopse
DROP USER nome

Descrio
O comando DROP USER remove o usurio especificado do banco de dados. No remove tabelas, vises ou outros
objetos de propriedade do usurio. Se o usurio possuir algum banco de dados uma mensagem de erro gerada.

Parmetros
nome
O nome de um usurio existente.

Diagnsticos
DROP USER

Mensagem retornada se o usurio for excludo com sucesso.

ERROR: DROP USER: user "nome" does not exist

Mensagem retornada se o nome do usurio no for encontrado.

DROP USER: user "nome" owns database "nome", cannot be removed

Primeiro o banco de dados deve ser excludo ou mudar de dono.

Notas
Use o comando CREATE USER para adicionar novos usurios, e o ALTER USER para mudar seus atributos. O
PostgreSQL tem o aplicativo dropuser que possui a mesma funcionalidade deste comando (na verdade, chama
este comando), mas que pode ser executado a partir da linha de comandos.

DROP USER

Exemplos
Para remover uma conta de usurio:
DROP USER josias;

Compatibilidade
O comando DROP USER uma extenso do PostgreSQL linguagem. O padro SQL deixa a definio dos
usurios para a implementao

See Also
CREATE USER, ALTER USER, dropuser

DROP VIEW
Nome
DROP VIEW remove uma viso

Sinopse
DROP VIEW nome [, ...] [ CASCADE | RESTRICT ]

Entradas
nome
O nome (opcionalmente qualificado pelo esquema) de uma viso existente.
CASCADE
Remove automaticamente os objetos que dependem da viso (como outras vises).
RESTRICT
Recusa remover a viso se existirem objetos dependentes. Este o padro.

Sadas
DROP VIEW

Mensagem retornada se o comando for executado com sucesso.

ERROR: view nome does not exist

Esta mensagem ocorre quando a viso especificada no existe no banco de dados.

Descrio
O comando DROP VIEW remove do banco de dados uma viso existente. Para executar este comando necessrio
ser o dono da viso.

Notas
Consulte o comando CREATE VIEW para obter informaes sobre como criar vises.

DROP VIEW

Utilizao
Remover a viso chamada tipos:
DROP VIEW tipos;

Compatibilidade
SQL92

END
Nome
END efetiva a transao corrente

Sinopse
END [ WORK | TRANSACTION ]

Entradas
WORK
TRANSACTION
Palavras chave opcionais. No produzem nenhum efeito.

Sadas
COMMIT

Mensagem retornada se a transao for efetivada com sucesso.

WARNING: COMMIT: no transaction in progress

Se no houver nenhuma transao sendo executada.

Descrio
O comando END uma extenso do PostgreSQL. um sinnimo para o comando COMMIT compatvel com o
SQL92.

Notas
As palavras chave WORK e TRANSACTION so informativas podendo ser omitidas.
Use o ROLLBACK para desfazer a transao.

END

Utilizao
Para tornar todas as modificaes permanentes:
END WORK;

Compatibilidade
SQL92
O comando END uma extenso do PostgreSQL que fornece uma funcionalidade equivalente ao COMMIT.

EXECUTE
Nome
EXECUTE executa uma consulta preparada

Sinopse
EXECUTE nome [ (parmetro [, ...] ) ]

Entradas
nome
O nome da consulta preparada a ser executada.
parmetro
O valor real do parmetro da consulta preparada. Deve ser uma expresso que produza um valor com tipo
compatvel com o tipo de dado especificado para a posio deste parmetro no comando PREPARE que criou
a consulta preparada.

Descrio
O comando EXECUTE usado para executar uma consulta previamente preparada. Uma vez que as consultas
preparadas existem somente durante o tempo da sesso, a consulta preparada deve ter sido criada por um comando
PREPARE executado anteriormente na mesma sesso.
Se o comando PREPARE que criou a consulta especificar alguns parmetros, um conjunto compatvel de parmetros deve ser passado para o comando EXECUTE, seno um erro vai ser gerado. Observe que (diferentemente das
funes) as consultas preparadas no so sobrecarregadas baseado no tipo ou no nmero de seus parmetros: o
nome de uma consulta preparada deve ser nico para uma sesso.
Para obter mais informaes sobre a criao e a utilizao de consultas preparadas consulte o comando PREPARE.

Compatibidade
SQL92
O SQL92 inclui um comando EXECUTE, mas apenas para ser usado no SQL embutido nos clientes. O comando
EXECUTE implementado pelo PostgreSQL tambm usa uma sintaxe um pouco diferente.

EXPLAIN
Nome
EXPLAIN mostra o plano de execuo de uma instruo

Sinopse
EXPLAIN [ ANALYZE ] [ VERBOSE ] consulta

Entradas
ANALYZE
Sinalizador para executar a consulta e mostrar os tempos reais de execuo.
VERBOSE
Sinalizador para mostrar o plano de execuo detalhado.
consulta
Qualquer consulta.

Sadas
Query plan
Plano de execuo explcito do planejador do PostgreSQL.

Nota: Antes do PostgreSQL 7.3, o plano da consulta era exibido na forma de uma mensagem tipo NOTICE.
Agora exibida na forma do resultado de uma consulta (formatado como uma tabela de uma nica coluna
do tipo texto).

Descrio
Este comando mostra o plano de execuo que o planejador do PostgreSQL gera para a consulta fornecida.
O plano de execuo mostra como a(s) tabela(s) referenciada pela consulta ser varrida --- por uma varredura
seqencial, varredura do ndice, etc. --- e, se vrias tabelas forem referenciadas, quais algoritmos de juno sero
usados para unir as tuplas requisitadas de cada tabela de entrada.

EXPLAIN
A parte mais crtica exibida o custo estimado da execuo da consulta, que a estimativa feita pelo planejador
sobre a durao da execuo da consulta (medida em unidade de acesso s pginas do disco). Na verdade dois
nmeros so mostrados: o tempo inicial anterior primeira tupla poder ser retornada, e o tempo total para retornar
todas as tuplas. Para a maioria das consultas o tempo total o que interessa, mas em contextos como os das
subconsultas EXISTS o planejador escolhe o menor tempo inicial em vez do menor tempo total (porque o executor
pra aps ter obtido uma linha). Alm disso, se for limitado o nmero de tuplas a serem retornadas usando a
clusula LIMIT, o planejador efetua uma interpolao apropriada com relao aos custos finais para saber qual
plano realmente o de menor custo.
A opo ANALYZE faz com que a consulta seja realmente executada, e no apenas planejada. O tempo total de
durao gasto dentro de cada parte do plano (em milissegundos) e o nmero total de linhas realmente retornadas
so adicionados ao que normalmente mostrado. Esta opo til para ver se as estimativas do planejador esto
prximas da realidade.

Cuidado
Tenha em mente que a consulta realmente executada quando a opo ANALYZE usada. Embora o
EXPLAIN despreze qualquer sada que o SELECT possa produzir, os outros efeitos colaterais da consulta acontecem na forma usual. Para usar EXPLAIN ANALYZE em um INSERT, UPDATE, ou DELETE
sem deixar que os dados sejam afetados, utilize o seguinte procedimento:
BEGIN;
EXPLAIN ANALYZE ...;
ROLLBACK;

A opo VERBOSE fornece a representao interna completa da rvore do plano, em vez de apenas o seu
sumrio. Geralmente esta opo til apenas para fazer o debug do prprio PostgreSQL. A sada produzida
pela opo VERBOSE pode ser formatada para ser facilmente lida ou no, dependendo do que for especificado
para o parmetro de configurao EXPLAIN_PRETTY_PRINT.

Notas
Existem apenas informaes esparsas sobre a utilizao do otimizador na documentao do PostgreSQL. Consulte
o Guia do Usurio e o Guia do Programador para obter mais informaes.

Utilizao
Para mostrar o plano da consulta para uma consulta simples em uma tabela com uma nica coluna int4 e 10.000
linhas:
EXPLAIN SELECT * FROM foo;
QUERY PLAN
--------------------------------------------------------Seq Scan on foo (cost=0.00..155.00 rows=10000 width=4)
(1 row)

Havendo um ndice, e se for feita uma consulta com uma condio WHERE indexvel, o EXPLAIN mostra um
plano diferente:

EXPLAIN
EXPLAIN SELECT * FROM foo WHERE i = 4;
QUERY PLAN
-------------------------------------------------------------Index Scan using fi on foo (cost=0.00..5.98 rows=1 width=4)
Index Cond: (i = 4)
(2 rows)

O exemplo abaixo mostra um plano para uma consulta que contm uma funo de agregao:
EXPLAIN SELECT sum(i) FROM foo WHERE i < 10;
QUERY PLAN
--------------------------------------------------------------------Aggregate (cost=23.93..23.93 rows=1 width=4)
-> Index Scan using fi on foo (cost=0.00..23.92 rows=6 width=4)
Index Cond: (i < 10)
(3 rows)

Observe que os nmeros especficos mostrados, e mesmo a estratgia selecionada para a consulta, pode variar
entre verses do PostgreSQL devido a melhorias no planejador.

Compatibilidade
SQL92
No existe o comando EXPLAIN no SQL92.

FETCH
Nome
FETCH busca linhas de uma tabela usando um cursor

Sinopse
FETCH [ direo ] [ contador ] { IN | FROM } cursor
FETCH [ FORWARD | BACKWARD | RELATIVE ] [ # | ALL | NEXT | PRIOR ]
{ IN | FROM } cursor

Entradas
direo
Um seletor definindo a direo da busca. Pode ser um dos seguintes:
FORWARD
busca a(s) prxima(s) linha(s). Este o padro quando o seletor for omitido.
BACKWARD
busca a(s) linha(s) anterior(es).
RELATIVE
Somente por compatibilidade com o SQL92.

contador
O contador determina quantas linhas sero buscadas. Pode ser um dos seguintes:
#
Um nmero inteiro com sinal que especifica quantas linhas sero buscadas. Note que um nmero negativo equivalente a mudar o sentido de FORWARD e de BACKWARD.
ALL
Busca todas as linhas remanescentes.
NEXT
Equivalente a especificar um contador igual a 1.
PRIOR
Equivalente a especificar um contador igual a -1.

FETCH
cursor
O nome de um cursor aberto.

Sadas
O comando FETCH retorna o resultado da consulta definida pelo cursor especificado. As seguintes mensagens
retornam quando a consulta falha:
WARNING: PerformPortalFetch: portal "cursor" not found

Se o cursor no tiver sido previamente declarado. O cursor deve ser declarado dentro do bloco da
transao.
WARNING: FETCH/ABSOLUTE not supported, using RELATIVE

O PostgreSQL no suporta o posicionamento absoluto do cursor.

ERROR: FETCH/RELATIVE at current position is not supported

O SQL92 permite buscar repetitivamente o cursor em sua posio corrente usando a sintaxe
FETCH RELATIVE 0 FROM cursor.

O PostgreSQL atualmente no suporta esta noo; na verdade o valor zero reservado para indicar que todas
as linhas devem ser buscadas, equivalendo a especificar a palavra chave ALL. Se a palavra chave RELATIVE
for usada, o PostgreSQL assume que o usurio deseja o comportamento do SQL92 e retorna esta mensagem
de erro.

Descrio
O comando FETCH permite o usurio buscar linhas usando um cursor. O nmero de linhas buscadas especificado
pelo #. Se o nmero de linhas remanescentes no cursor for menor do que #, ento somente as linhas disponveis
so buscadas. Colocando-se a palavra chave ALL no lugar do nmero faz com que todas as linhas restantes no
cursor sejam buscadas. As instncias podem ser buscadas para frente (FORWARD) e para trs (BACKWARD) O
padro para frente.
Dica: permitido especificar nmeros negativos para o contador de linhas. Um nmero negativo equivale a
inverter o sentido das palavras chave FORWARD e BACKWARD. Por exemplo, FORWARD -1 o mesmo que
BACKWARD 1.

FETCH

Notas
Note que as palavras chave FORWARD e BACKWARD so extenses do PostgreSQL. A sintaxe do SQL92 tambm suportada, especificando-se a segunda forma do comando. Veja abaixo para obter detalhes sobre questes
de compatibilidade.
A atualizao de dados pelo cursor no suportada pelo PostgreSQL, porque mapear as atualizaes do cursor
de volta para as tabelas base geralmente no possvel, como no caso das atualizaes nas vises. Conseqentemente, os usurios devem executar um comando UPDATE explcito para atualizar os dados.
Os cursores somente podem ser usados dentro de transaes, porque os dados por eles armazenados estendem-se
por muitas consultas dos usurios.
Use o comando MOVE para mudar a posio do cursor. O comando DECLARE define um cursor. Consulte os
comando BEGIN, COMMIT, e ROLLBACK para obter mais detalhes sobre transaes.

Utilizao
O exemplo a seguir acessa uma tabela usando um cursor.
-- Definir e usar o cursor:
BEGIN WORK;
DECLARE liahona CURSOR FOR SELECT * FROM filmes;
-- Buscar as 5 primeiras linhas do cursor liahona:
FETCH FORWARD 5 IN liahona;
cod
|
titulo
| did | data_prod | tipo
| duracao
-------+-------------------------+-----+------------+----------+--------BL101 | The Third Man
| 101 | 1949-12-23 | Drama
| 01:44
BL102 | The African Queen
| 101 | 1951-08-11 | Romance | 01:43
JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romance | 01:25
P_301 | Vertigo
| 103 | 1958-11-14 | Ao
| 02:08
P_302 | Becket
| 103 | 1964-02-03 | Drama
| 02:28

-- Buscar a linha anterior:

FETCH BACKWARD 1 IN liahona;
cod
| titulo | did | data_prod | tipo
| duracao
-------+---------+-----+------------+--------+--------P_301 | Vertigo | 103 | 1958-11-14 | Ao
| 02:08

-- fechar a consulta e efetivar o trabalho:

CLOSE liahona;
COMMIT WORK;

FETCH

Compatibilidade
SQL92
Nota: O uso no embutido de cursores uma extenso do PostgreSQL. A sintaxe e a utilizao dos cursores
est sendo comparada com relao forma embutida dos cursores definida no SQL92.

O SQL92 permite o posicionamento absoluto de cursores para a busca (FETCH), e permite armazenar os resultados em variveis explicitadas:
FETCH ABSOLUTE #
FROM cursor
INTO :varivel [, ...]

ABSOLUTE
O cursor deve ser posicionado na linha especificada pelo nmero absoluto. Todos os nmeros de linhas no
PostgreSQL so nmeros relativos, portanto esta funcionalidade no suportada.
:varivel
Varivel do programa.

GRANT
Nome
GRANT concede privilgios de acesso

Sinopse
GRANT { { SELECT | INSERT | UPDATE | DELETE | RULE | REFERENCES | TRIGGER }
[,...] | ALL [ PRIVILEGES ] }
ON [ TABLE ] nome_da_tabela [, ...]
TO { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]
GRANT { { CREATE | TEMPORARY | TEMP } [,...] | ALL [ PRIVILEGES ] }
ON DATABASE nome_bd [, ...]
TO { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]
GRANT { EXECUTE | ALL [ PRIVILEGES ] }
ON FUNCTION nome_da_funo ([tipo, ...]) [, ...]
TO { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]
GRANT { USAGE | ALL [ PRIVILEGES ] }
ON LANGUAGE nome_da_linguagem [, ...]
TO { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]
GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
ON SCHEMA nome_do_esquema [, ...]
TO { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]

Descrio
O comando GRANT concede permisses especficas no objeto (tabela, viso, seqncia, banco de dados, funo,
linguagem procedural ou esquema) para um ou mais usurios ou grupos de usurio. Estas permisses so adicionadas s j concedidas, caso existam.
A palavra chave PUBLIC indica que o privilgio deve ser concedido para todos os usurios, inclusive aos que
vierem a ser criado posteriormente. PUBLIC pode ser considerado como um grupo implicitamente definido que
sempre inclui todos os usurios. Observe que qualquer usurio em particular possui a soma dos privilgios concedidos diretamente para o mesmo, mais os privilgios concedidos para qualquer grupo do qual seja membro, mais
os privilgios concedidos para PUBLIC.
No existe nenhuma necessidade de se conceder privilgios ao criador do objeto, porque o criador possui todos os
privilgios por padro (O criador pode, entretanto, decidir revogar alguns de seus prprios privilgios por motivo
de segurana). Observe que esta capacidade de conceder e revogar privilgios inerente ao criador, no podendo
ser perdida. O direito de eliminar o objeto, ou alter-lo de outra maneira no descrita nos direitos que podem ser
concedidos, da mesma forma inerente ao criador, no podendo ser concedido ou revogado.
Dependendo do tipo do objeto, o padro pode incluir a concesso de alguns privilgios para PUBLIC nos privilgios iniciais. O padro : no permitir o acesso pblico s tabelas e esquemas; privilgio de criao de tabela
TEMP para bancos de dados; privilgio EXECUTE para funes; e o privilgio USAGE para linguagens. O criador
do objeto pode, claro, revogar estes privilgios (para mxima segurana, deve ser executado o comando REVOKE
na mesma transao que criar o objeto, fazendo com que no haja um intervalo de tempo em que outro usurio
possa acessar o objeto).

GRANT
Os privilgios possveis so:
SELECT
Permite consultar qualquer coluna (SELECT) da tabela, viso ou seqncia especificada. Tambm permite
utilizar o comando COPY TO. Para as seqncias, este privilgiotambm permite o uso da funo currval.
INSERT
Permite incluir novas linhas (INSERT) na tabela especificada. Tambm permite utilizar o comando COPY
FROM.
UPDATE
Permite modificar os dados de qualquer coluna (UPDATE) da tabela especificada. O comando SELECT ...
FOR UPDATE tambm requer este privilgio (alm do privilgio SELECT). Para as seqncias, este privilgio
permite o uso das funes nextval e setval.
DELETE
Permite excluir linhas (DELETE) da tabela especificada.
RULE
Permite criar regras para a tabela ou para a viso (Consulte o comando CREATE RULE ).
REFERENCES
Para criar uma restrio de chave estrangeira necessrio possuir este privilgio tanto na tabela que faz
referncia quanto na que referenciada.
TRIGGER
Permite criar gatilhos na tabela especificada (Consulte o comando CREATE TRIGGER).
CREATE
Para banco de dados, permite que novos esquemas sejam criados dentro do mesmo.
Para esquema, permite que novos objetos sejam criados dentro do mesmo. Para mudar o nome de um objeto
existente, necessrio ser o dono do objeto e possuir este privilgio no esquema que o contm.
TEMPORARY
TEMP
Permite criar tabelas temporrias enquanto estiver usando o banco de dados.
EXECUTE
Permite usar a funo especificada e utilizar qualquer operador que seja implementado usando a funo. Este
o nico tipo de privilgio aplicvel s funes (Esta sintaxe tambm funciona para as funes de agregao,
da mesma maneira).
USAGE
Para as linguagens procedurais, permite a utilizao da linguagem especificada para a criao de funes
nesta linguagem. Este o nico tipo de privilgio aplicvel s linguagens procedurais.
Para os esquemas, permite o acesso aos objetos contidos no esquema especificado (assumindo-se que os privilgios necessrios nos prprios objetos esto atendidos). Permite, essencialmente, quem recebe a concesso
enxergar os objetos contidos no esquema.
ALL PRIVILEGES
Concede todos os privilgios aplicveis ao objeto de uma s vez. A palavra chave PRIVILEGES opcional
no PostgreSQL, entretanto requerida pelo SQL estrito.

GRANT
Os privilgios requeridos pelos outros comandos esto listados nas pginas de referncia dos respectivos comandos.

Notas
O comando REVOKE utilizado para revogar os privilgios de acesso.
Deve-se observar que os superusurios do banco de dados podem acessar todos os objetos a despeito dos privilgios definidos. Este comportamento pode ser comparado aos direitos do usurio root no sistema operacional
Unix. Assim como no caso do root, no aconselhvel operar como um superusurio a no ser que seja absolutamente necessrio.
Atualmente para se conceder privilgios somente para algumas colunas no PostgreSQL, deve-se criar uma viso
possuindo as colunas desejadas e conceder os privilgios nesta viso.
Deve ser usado o comando \dp do psql para obter informaes sobre os privilgios concedidos. Por exemplo:
lusitania=> \dp mytable
Access privileges for database "lusitania"
Schema | Table |
Access privileges
--------+---------+--------------------------------------public | mytable | {=r,miriam=arwdRxt,"group todos=arw"}
(1 row)

As informaes mostradas pelo comando \dp so interpretadas da seguinte forma:

=xxxx -- privilgios concedidos para PUBLIC
uname=xxxx -- privilgios concedidos para o usurio
group gname=xxxx -- privilgios concedidos para o grupo
r
w
a
d
R
x
t
X
U
C
T
arwdRxt

-------------

SELECT ("leitura")
UPDATE ("escrita")
INSERT ("incluso")
DELETE
RULE
REFERENCES
TRIGGER
EXECUTE
USAGE
CREATE
TEMPORARY
ALL PRIVILEGES (para tabelas)

O exemplo acima seria visto pela usuria miriam aps esta ter criado a tabela mytable e executado:
GRANT SELECT ON mytable TO PUBLIC;
GRANT SELECT,UPDATE,INSERT ON mytable TO GROUP todos;

Se a coluna Access privileges estiver vazia para um dado objeto, significa que o objeto possui os privilgios
padro (ou seja, seu campo de privilgios contm NULL). Os privilgios padro sempre incluem todos os privilgios para o dono, e podem incluir alguns privilgios para PUBLIC dependendo do tipo do objeto, como foi
explicado acima. O primeiro comando GRANT ou REVOKE em um objeto gera uma instncia dos privilgios padro

GRANT
(produzindo, por exemplo, {=,miriam=arwdRxt}) e, em seguida, modifica esta instncia de acordo com a requisio solicitada.

Exemplos
Conceder, para todos os usurios, o privilgio de inserir na tabela filmes:
GRANT INSERT ON filmes TO PUBLIC;

Conceder todos os privilgios na viso tipos para o usurio manuel:

GRANT ALL PRIVILEGES ON tipos TO manuel;

Compatibilidade
SQL92
A palavra chave PRIVILEGES em ALL PRIVILEGES requerida. O SQL no aceita a concesso de privilgios
em mais de uma tabela no mesmo comando.
A sintaxe do SQL92 para o comando GRANT permite conceder privilgios individuais para as colunas da tabela,
e permite conceder o privilgio de conceder o mesmo privilgio para outros:
GRANT privilgio [, ...]
ON objeto [ ( coluna [, ...] ) ] [, ...]
TO { PUBLIC | nome_do_usurio [, ...] } [ WITH GRANT OPTION ]

O SQL permite conceder o privilgio USAGE em outros tipos de objeto: CHARACTER SET, COLLATION,
TRANSLATION, DOMAIN.
O privilgio TRIGGER foi introduzido no SQL99. O privilgio RULE uma extenso do PostgreSQL.

Consulte tambm
REVOKE

INSERT
Nome
INSERT cria novas linhas em uma tabela

Sinopse
INSERT INTO tabela [ ( coluna [, ...] ) ]
{ DEFAULT VALUES | VALUES ( { expresso | DEFAULT } [, ...] ) | SELECT consulta }

Entradas
tabela
O nome (opcionalmente qualificado pelo esquema) de uma tabela existente.
coluna
O nome de uma coluna da tabela.
DEFAULT VALUES
Todas as colunas so preenchidas com nulo, ou pelos valores especificados quando a tabela criada usando
a clusula DEFAULT.
expresso
Uma expresso ou valor vlido a ser atribudo coluna.
DEFAULT
Esta coluna ser preenchida pela clusula DEFAULT da coluna, ou NULL se um valor padro no estiver
definido.
consulta
Uma consulta vlida. Consulte o comando SELECT para obter uma descrio mais detalhada dos argumentos
vlidos.

Sadas
INSERT oid 1

Mensagem retornada se apenas uma linha for includa. O identificador do objeto oid o OID numrico da
linha includa.
INSERT 0 #

Mensagem retornada se mais de uma linha for includa. O # representa o nmero de linhas includas.

INSERT

Descrio
O comando INSERT permite a incluso de novas linhas na tabela. Pode ser includa uma linha de cada vez, ou
vrias linhas resultantes de uma consulta. As colunas da lista de insero podem estar em qualquer ordem.
As colunas que no aparecem na lista de insero so includas utilizando o valor padro, seja o valor DEFAULT
declarado, ou nulo. O PostgreSQL rejeita a nova coluna se um valor nulo for includo em uma coluna declarada
como NOT NULL.
Se a expresso para cada coluna no for do tipo de dado correto, ser tentada uma transformao automtica de
tipo.
necessrio possuir o privilgio INSERT na tabela para inserir linhas, assim como o privilgio SELECT nas
tabelas especificadas na clusula WHERE.

Utilizao
Inserir uma nica linha na tabela filmes:
INSERT INTO filmes VALUES
(UA502,Bananas,105,1971-07-13,Comdia,INTERVAL 82 minute);

No segundo exemplo, mostrado abaixo, a ltima coluna duracao foi omitida e, portanto, vai receber o valor
padro NULL:
INSERT INTO filmes (codigo, titulo, did, data_prod, tipo)
VALUES (T_601, Yojimbo, 106, DATE 1961-06-16, Drama);

No terceiro exemplo, mostrado abaixo, utilizado o valor DEFAULT para a coluna de data em vez de especificar
um valor.
INSERT INTO filmes VALUES
(UA502,Bananas,105,DEFAULT,Comdia,INTERVAL 82 minute);
INSERT INTO films (codigo, titulo, did, data_prod, tipo)
VALUES (T_601, Yojimbo, 106, DEFAULT, Drama);

Inserir uma nica linha na tabela distribuidores; observe que somente a coluna nome est especificada, portanto
vai ser atribudo o valor padro para a coluna did que foi omitida:
INSERT INTO distribuidores (nome) VALUES (Entrega Rpida);

Inserir vrias linhas na tabela filmes a partir da tabela tmp:

INSERT INTO filmes SELECT * FROM tmp;

INSERT
Incluso em matrizes (arrays) (Consulte o Guia do Usurio do PostgreSQL para obter mais informaes sobre
matrizes):
-- Criar um tabuleiro vazio de 3x3 posies para o Jogo da Velha
-- (todos 3 comandos criam o mesmo atributo do tabuleiro)
INSERT INTO tictactoe (game, board[1:3][1:3])
VALUES (1,{{"","",""},{},{"",""}});
INSERT INTO tictactoe (game, board[3][3])
VALUES (2,{});
INSERT INTO tictactoe (game, board)
VALUES (3,{{},{},{}});

Compatibilidade
SQL92
O comando INSERT totalmente compatvel com o SQL92. As possveis limitaes nas funcionalidades da
clusula de consulta esto documentadas no comando SELECT.

LISTEN
Nome
LISTEN escuta uma notificao

Sinopse
LISTEN nome

Entradas
name
O nome da condio de notificao.

Sada
LISTEN

Mensagem retornada se a notificao for registrada com sucesso.

WARNING: Async_Listen: We are already listening on nome

Este processo servidor j est registrado para esta condio de notificao.

Descrio
O comando LISTEN registra o processo servidor corrente do PostgreSQL para escutar a condio de notificao
nome.
Sempre que o comando NOTIFY nome executado, tanto por este processo servidor quanto por qualquer outro
conectado ao mesmo banco de dados, todos os processos servidores escutando esta condio de notificao neste
instante so notificados, e cada um por sua vez notifica o aplicativo cliente ao qual est conectado. Consulte a
discusso do comando NOTIFY para obter mais informaes.
Um processo servidor pode cancelar seu registro para uma dada condio de notificao usando o comando
UNLISTEN. Os registros de escuta de um processo servidor so automaticamente removidos quando o processo
servidor encerra sua execuo.
O mtodo que o aplicativo cliente deve usar para detectar eventos de notificao depende da interface de programao de aplicativos (API) do PostgreSQL sendo usada. Usando a biblioteca libpq bsica, o aplicativo executa o
comando LISTEN como um comando SQL comum e depois passa a chamar periodicamente a rotina PQnotifies
para descobrir se algum evento de notificao foi recebido. Outras interfaces, como a libpgtcl, fornecem mtodos

LISTEN
de nvel mais alto para tratar os eventos de notificao; na verdade, usando a libpgtcl o programador do aplicativo
no precisa nem executar o comando LISTEN ou UNLISTEN diretamente. Consulte a documentao da biblioteca
sendo usada para obter mais detalhes.
O comando NOTIFY contm uma discusso mais extensa da utilizao do comando LISTEN e do comando
NOTIFY.

Notas
nome pode ser qualquer cadeia de caracteres vlida como um nome; no precisa corresponder ao nome de qualquer tabela existente. Se nome_notificao estiver entre aspas ("), no necessrio nem que seja um nome
com uma sintaxe vlida; pode ser qualquer cadeia de caracteres com at 63 caracteres.
Em algumas verses anteriores do PostgreSQL, o nome tinha que vir entre aspas quando no correspondia a
nenhum nome de tabela existente, mesmo que sintaticamente fosse um nome vlido, mas no mais necessrio.

Utilizao
Configurar e executar a seqncia escutar/notificar usando o psql:
LISTEN virtual;
NOTIFY virtual;
Asynchronous NOTIFY virtual from backend with pid 8448 received.

Compatibilidade
SQL92
No existe o comando LISTEN no SQL92.

LOAD
Nome
LOAD carrega ou recarrega um arquivo de biblioteca compartilhada

Sinopse
LOAD nome_arquivo

Descrio
Carrega um arquivo de biblioteca compartilhada no espao de endereamento do servidor PostgreSQL. Se o
arquivo tiver sido carregado anteriormente, o mesmo descarregado primeiramente. Este comando til para
descarregar e recarregar um arquivo de biblioteca compartilhada que foi mudado aps ter sido carregado pelo
servidor. Para usar a biblioteca compartilhada suas funes devem ser declaradas pelo comando CREATE FUNCTION.
O nome do arquivo especificado da mesma forma que os nomes das bibliotecas compartilhadas no comando
CREATE FUNCTION; em particular, pode-se confiar no caminho de procura e na adio automtica das extenses
de nomes de arquivos das bibliotecas compartilhadas do sistema padro. Consulte o Guia do Programador para
obter mais detalhes.

Compatibilidade
O comando LOAD uma extenso do PostgreSQL.

Consulte tambm
CREATE FUNCTION, Guia do Programador do PostgreSQL

LOCK
Nome
LOCK bloqueia explicitamente uma tabela

Sinopse
LOCK [ TABLE ] nome [, ...]
LOCK [ TABLE ] nome [, ...] IN modo_de_bloqueio MODE
onde modo_de_bloqueio um entre:
ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE |
SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE

Entradas
nome
O nome (opcionalmente qualificado pelo esquema) de uma tabela existente a ser bloqueada.
ACCESS SHARE MODE
Este o modo de bloqueio menos restritivo. Somente conflita com o modo ACCESS EXCLUSIVE. utilizado para proteger a tabela de ser modificada por um comando ALTER TABLE, DROP TABLE ou VACUUM
FULL concorrente.
Nota: O comando SELECT obtm um bloqueio neste modo nas tabelas referenciadas. Em geral, qualquer
comando que somente leia a tabela sem modific-la ir obter este modo de bloqueio.

ROW SHARE MODE

Conflita com os modos de bloqueio EXCLUSIVE e ACCESS EXCLUSIVE.
Nota: O comando SELECT FOR UPDATE obtm um bloqueio neste modo na tabela(s) a ser modificada
(alm de bloqueio no modo ACCESS SHARE nas outras tabelas que so referenciadas, mas que no so
selecionadas como FOR UPDATE).

ROW EXCLUSIVE MODE

Conflita com os modos de bloqueio SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE e ACCESS EXCLUSIVE.
Nota: Os comandos UPDATE, DELETE e INSERT obtm este modo de bloqueio na tabela de destino (alm
do bloqueio ACCESS SHARE nas outras tabelas que so referenciadas). Em geral, este modo de bloqueio
obtido por todo comando que modifica os dados da tabela.

LOCK
SHARE UPDATE EXCLUSIVE MODE
Conflita com os modos de bloqueio SHARE UPDATE EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE e ACCESS EXCLUSIVE. Este modo de bloqueio protege a tabela contra alteraes
concorrentes do esquema e a execuo do comando VACUUM.
Nota: Obtido pelo comando VACUUM (sem a opo FULL).

SHARE MODE
Conflita com os modos de bloqueio ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE ROW
EXCLUSIVE, EXCLUSIVE e ACCESS EXCLUSIVE. Este modo de bloqueio protege a tabela contra a
modificao concorrente dos dados.
Nota: Obtido pelo comando CREATE INDEX.

SHARE ROW EXCLUSIVE MODE

Conflita com os modos de bloqueio ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE, SHARE
ROW EXCLUSIVE, EXCLUSIVE e ACCESS EXCLUSIVE.
Nota: Este modo no obtido automaticamente por nenhum comando do PostgreSQL.

EXCLUSIVE MODE
Conflita com os modos de bloqueio ROW SHARE, ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE,
SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE e ACCESS EXCLUSIVE. Este modo de bloqueio
permite somente o ACCESS SHARE concorrente, ou seja, somente leituras na tabela podem ocorrer em
paralelo a uma transao que obteve este tipo de bloqueio.
Nota: Este modo no obtido automaticamente por nenhum comando do PostgreSQL.

ACCESS EXCLUSIVE MODE

Conflita com todos os outros modos de bloqueio. Este modo garante que a transao que o obteve a nica
com qualquer forma com acesso tabela.
Nota: Obtido pelos comandos ALTER TABLE, DROP TABLE e VACUUM FULL. Este tambm o modo de
bloqueio padro do comando LOCK TABLE quando o modo no especificado explicitamente.

LOCK

Sadas
LOCK TABLE

Mensagem retornada se o bloqueio for obtido com sucesso.

ERROR nome: Table does not exist.

Mensagem retornada se nome no existir.

Descrio
O comando LOCK TABLE obtm um bloqueio no nvel de tabela aguardando, se for necessrio, qualquer bloqueio
conflitante ser liberado. Uma vez obtido, o bloqueio mantido pelo restante da transao corrente (No existe o
comando UNLOCK TABLE; os bloqueios so sempre liberados no final da transao).
Ao obter automaticamente um bloqueio para os comandos que fazem referncia a tabelas, o PostgreSQL sempre utiliza o modo de bloqueio menos restritivo possvel. O comando LOCK TABLE usado nos casos onde
necessrio um modo de bloqueio mais restritivo.
Por exemplo, supondo-se que um aplicativo processe uma transao no nvel de isolamento READ COMMITTED, e precise garantir que os dados da tabela permaneam os mesmos durante a transao. Para conseguir
esta permanncia, pode ser obtido o bloqueio da tabela no modo SHARE antes de realizar a consulta. Este procedimento impede a alterao concorrente dos dados e garante que as prximas operaes de leitura na tabela
enxergam uma situao estvel de dados efetivados, porque o modo de bloqueio SHARE conflita com qualquer
modo de bloqueio ROW EXCLUSIVE necessrio para escrever. O comando LOCK TABLE nome IN SHARE
MODE aguarda at que todas as transaes que obtiveram um bloqueio no modo ROW EXCLUSIVE terminem,
efetivando ou desfazendo suas modificaes. Portanto, quando este bloqueio obtido, no existe nenhuma operao de escrita sendo executada; alm disso, nenhuma transao pode comear enquanto o bloqueio no for
liberado.
Nota: Para obter um efeito semelhante ao executar uma transao no nvel de isolamento SERIALIZABLE,
necessrio executar o comando LOCK TABLE antes de executar qualquer comando da DML. A viso dos
dados em uma transao serializvel congelada no momento em que o primeiro comando da DML comea
a executar. Um comando LOCK posterior impede a escrita simultnea --- mas no garante que o que lido
pela transao corresponde aos ltimos valores efetivados.

Se uma transao deste tipo altera os dados da tabela, ento deve ser usado o modo de bloqueio SHARE ROW
EXCLUSIVE em vez do modo SHARE, garantindo que somente uma transao deste tipo executa de cada vez.
Sem isto, possvel a ocorrncia de um impasase (deadlock): duas transaes podem obter um bloqueio no
modo SHARE, e depois ficarem impossibilitadas de obter o bloqueio no modo ROW EXCLUSIVE para realizar
as modificaes (Observe que os bloqueios obtidos pela prpria transao nunca entram em conflito, portanto
a transao pode obter o modo ROW EXCLUSIVE aps obter o modo SHARE --- mas no se outra transao
estiver com o modo SHARE).
Duas regras gerais devem ser seguidas para evitar a condio de impasse:

As transaes tm que obter o bloqueio dos mesmos objetos na mesma ordem.

LOCK
Por exemplo, se um aplicativo atualiza a linha R1 e depois atualiza a linha R2 (na mesma transao), ento um
segundo aplicativo no deve atualizar a linha R2 se for atualizar a linha R1 em seguida (na mesma transao).
Em vez disto, o segundo aplicativo deve atualizar as linha R1 e R2 na mesma ordem do primeiro aplicativo.

Se diversos modos de bloqueio esto envolvidos para um mesmo objeto, ento as transaes devem sempre
obter primeiro o modo mais restritivo.
Um exemplo desta regra foi dado anteriormente ao se discutir o uso do modo SHARE ROW EXCLUSIVE em
vez do modo SHARE.

O PostgreSQL detecta impasses (deadlocks) e desfaz pelo menos uma das transaes em espera para resolver
o impasse. Se na prtica no for possvel codificar um aplicativo que siga estritamente as regras mostradas acima,
uma soluo alternativa se preparar para tentar novamente as transaes que forem abortadas devido a impasse.
Ao se bloquear vrias tabelas, o comando LOCK a, b; equivalente a LOCK a; LOCK b;. As tabelas so
bloqueadas uma por uma na ordem especificada pelo comando LOCK.

Notas
O comando LOCK ... IN ACCESS SHARE MODE requer o privilgio SELECT na tabela especificada. Todas as
outras formas de LOCK requerem os privilgios UPDATE e/ou DELETE.
O comando LOCK til apenas dentro de um bloco de transao (BEGIN...COMMIT), porque o bloqueio liberado
quando a transao termina. Um comando LOCK aparecendo fora de um bloco de transao forma uma transao
auto-contida e, portanto, o bloqueio liberado logo aps ser obtido.
Os bloqueios efetuados pelos RDBMS (Sistemas Gerenciadores de Banco de Dados Relacionais) seguem a
seguinte terminologia padro:
EXCLUSIVE
Um bloqueio exclusivo impede a concesso de outros bloqueios do mesmo tipo.
SHARE
Um bloqueio compartilhado permite que outros tambm obtenham o mesmo tipo de bloqueio, mas impede
que o bloqueio EXCLUSIVE correspondente seja concedido.
ACCESS
Bloqueia o esquema da tabela.
ROW
Bloqueia linhas individualmente.

O PostgreSQL no segue esta terminologia exatamente. O LOCK TABLE trata somente de bloqueios no nvel de
tabela e, portanto, os nomes dos modos envolvendo linhas (ROW) so todos incorretos. Os nomes destes modos
geralmente devem ser lidos como indicando a inteno de se obter um bloqueio no nvel de linha dentro de um
bloqueio de tabela. Tambm, o modo ROW EXCLUSIVE no segue esta conveno de nomes de forma exata,
uma vez que um bloqueio compartilhado de tabela. Deve-se ter em mente que todos estes modos de bloqueio
possuem semntica idntica no que diz respeito ao LOCK TABLE, diferindo apenas nas regras sobre quais modos
conflitam com quais modos.

LOCK

Utilizao
Obter o bloqueio no modo SHARE da tabela que contm a chave primria, antes de fazer uma insero na tabela
que contm a chave estrangeira:
BEGIN WORK;
LOCK TABLE filmes IN SHARE MODE;
SELECT id FROM filmes
WHERE nome = Star Wars: Episode I - The Phantom Menace;
-- Fazer o ROLLBACK se a linha no for encontrada
INSERT INTO filmes_comentarios VALUES
(_id_, Maravilhoso! Eu estava aguardando por isto h muito tempo!);
COMMIT WORK;

Obter o bloqueio no modo SHARE ROW EXCLUSIVE da tabela que contm a chave primria antes de realizar
a operao de excluso:
BEGIN WORK;
LOCK TABLE filmes IN SHARE ROW EXCLUSIVE MODE;
DELETE FROM filmes_comentarios WHERE id IN
(SELECT id FROM filmes WHERE avaliacao < 5);
DELETE FROM filmes WHERE avaliacao < 5;
COMMIT WORK;

Compatibilidade
SQL92
No existe o comando LOCK TABLE no SQL92, que em seu lugar usa o comando SET TRANSACTION para especificar os nveis de concorrncia das transaes. O PostgreSQL tambm suporta esta funcionalidade; Consulte
o comando SET TRANSACTION para obter mais detalhes.
Exceto pelos modos de bloqueio ACCESS SHARE, ACCESS EXCLUSIVE e SHARE UPDATE EXCLUSIVE,
os modos de bloqueio do PostgreSQL e a sintaxe do comando LOCK TABLE so compatveis com as presentes no
Oracle(TM).

MOVE
Nome
MOVE posiciona o cursor em uma determinada linha da tabela

Sinopse
MOVE [ direo ] [ contador ]
{ IN | FROM } cursor

Descrio
O comando MOVE permite ao usurio mover a posio do cursor o nmero especificado de linhas. O comando
MOVE trabalha como o comando FETCH, porm somente posiciona o cursor sem retornar as linhas.
Consulte o comando FETCH para obter detalhes sobre a sintaxe e a utilizao.

Notas
O comando MOVE uma extenso da linguagem do PostgreSQL.
Consulte o comando FETCH para obter uma descrio dos argumentos vlidos. Consulte o comando DECLARE
para definir o cursor. Consulte os comandos BEGIN, COMMIT, e ROLLBACK para obter mais informaes sobre
as transaes.

Utilizao
Criar e usar um cursor:
BEGIN WORK;
DECLARE liahona CURSOR FOR SELECT * FROM filmes;
-- Saltar as primeiras 5 linhas:
MOVE FORWARD 5 IN liahona;
MOVE

-- Ler a sexta linha no cursor liahona:

FETCH 1 IN liahona;
FETCH
cod
| titulo | did | data_prod | tipo | duracao
-------+--------+-----+-----------+------+--------P_303 | 48 Hrs | 103 | 1982-10-22| Ao | 01:37
(1 row)

-- fechar o cursor liahona e efetivar a transao:

CLOSE liahona;
COMMIT WORK;

MOVE

Compatibilidade
SQL92
No existe o comando MOVE no SQL92. Em vez disto, o SQL92 permite usar o comando FETCH para buscar uma
linha na posio absoluta do cursor, movendo implicitamente o cursor para a posio correta.

NOTIFY
Nome
NOTIFY gera uma notificao

Sinopse
NOTIFY nome

Entradas
nome_da_notificao
Condio de notificao a ser sinalizada.

Sadas
NOTIFY

Mostra que o comando NOTIFY foi executado.

Notify events
Os eventos so enviados para os clientes escutando; se, e como, cada aplicativo cliente reage depende da sua
programao.

Descrio
O comando NOTIFY envia um evento de notificao para cada aplicativo cliente que tenha executado anteriormente o comando LISTEN nome_da_notificao para a condio de notificao especificada, no banco de
dados corrente.
A notificao passada para o cliente por um evento de notificao inclui o nome da condio de notificao e o
PID do processo servidor que est notificando. Fica por conta do projetista do banco de dados definir os nomes
das condies que sero utilizadas em um determinado banco de dados e o significado de cada uma delas.
Usualmente, o nome da condio de notificao o mesmo nome de uma tabela do banco de dados, e o evento de
notificao essencialmente diz Eu modifiquei a tabela, d uma olhada nela e veja o que h de novo. Porm, este
tipo de associao no exigida pelos comandos NOTIFY e LISTEN. Por exemplo, o projetista do banco de dados
pode usar vrios nomes diferentes de condio para sinalizar diferentes tipos de mudana em uma nica tabela.
O comando NOTIFY fornece uma forma de sinal simples, ou mecanismo de IPC (comunicao entre processos),
para um conjunto de processos acessando o mesmo banco de dados do PostgreSQL. Podem ser construdos

NOTIFY
mecanismos de nvel mais alto usando-se tabelas no banco de dados para passar informaes adicionais (alm do
mero nome da condio) do notificador para o(s) ouvinte(s).
Quando o NOTIFY utilizado para sinalizar a ocorrncia de mudanas em uma tabela em particular, uma tcnica
de programao til colocar o NOTIFY em uma regra que disparada pela atualizao da tabela. Deste modo, a
notificao acontece automaticamente quando a tabela modificada, e o programador do aplicativo no vai poder
acidentalmente esquecer de faz-la.
O NOTIFY interage com as transaes SQL de forma importante. Em primeiro lugar, se um NOTIFY for executado
dentro de uma transao, o evento de notificao no enviado at que, e a menos que, a transao seja efetivada.
Isto apropriado porque, se a transao for abortada, deseja-se que nenhum de seus comandos tenha surtido
efeito, incluindo o NOTIFY. Mas isto pode ser desconcertante se for esperado que os eventos de notificao sejam
enviados imediatamente. Em segundo lugar, se um processo servidor na escuta recebe um sinal de notificao
enquanto est executando uma transao, o evento de notificao no ser enviado ao cliente conectado antes
da transao ser completada (seja efetivada ou abortada). Novamente o raciocnio que se a notificao for
enviada dentro de uma transao que for abortada posteriormente, vai se desejar que a notificao seja desfeita
de alguma maneira --- mas o processo servidor no pode pegar de volta uma notificao aps envi-la para o
cliente. Portanto, os eventos de notificao somente so enviados entre transaes. O resultado final disto que os
aplicativos que utilizam o NOTIFY para sinalizao de tempo real devem tentar manter as suas transaes curtas.
O NOTIFY se comporta como os sinais do Unix em um aspecto importante: se o mesmo nome de condio for
sinalizado diversas vezes em uma sucesso rpida, os ouvintes podem receber somente um evento de notificao
para vrias execues do NOTIFY. Portanto, uma m idia depender do nmero de notificaes recebidas. Em
vez disso, use o NOTIFY para acordar os aplicativos que devam prestar ateno em algo, e use um objeto do banco
de dados (como uma seqncia) para registrar o que aconteceu ou quantas vezes aconteceu.
comum para um cliente que executa o NOTIFY estar escutando o mesmo nome de notificao. Neste caso vai ser
recebido de volta o evento de notificao da mesma maneira que todos os outros clientes na escuta. Dependendo
da lgica do aplicativo, isto pode resultar em um trabalho sem utilidade --- por exemplo, a releitura da tabela
do banco de dados para encontrar as mesmas atualizaes que foram feitas. No PostgreSQL 6.4, e nas verses
posteriores, possvel evitar este trabalho extra verificando se o PID do processo servidor que fez a notificao
(fornecido na mensagem do evento de notificao) o mesmo PID do seu processo servidor (disponvel pela
libpq). Quando forem idnticos, o evento de notificao o seu prprio trabalho retornando, podendo ser ignorado
(A despeito do que foi dito no pargrafo precedente, esta uma tcnica segura. O PostgreSQL mantm as autonotificaes separadas das notificaes vindas de outros processos servidores, portanto no possvel perder-se
uma notificao externa ignorando-se as prprias notificaes).

Notas
nome pode ser qualquer cadeia de caracteres vlida como um nome; no necessrio que corresponda ao nome
de qualquer tabela existente. Se nome estiver entre aspas ("), no necessrio nem que seja um nome com uma
sintaxe vlida; pode ser qualquer cadeia de caracteres com at 63 caracteres.
Em algumas verses anteriores do PostgreSQL, o nome tinha que vir entre aspas quando no correspondia a
nenhum nome de tabela existente, mesmo que sintaticamente fosse um nome vlido, mas no mais necessrio.
Nas verses do PostgreSQL anteriores a 6.4, o PID do processo servidor que enviou a mensagem de notificao
era sempre o PID do processo servidor do prprio cliente. Ento no era possvel distinguir entre as prprias
notificaes e as notificaes dos outros clientes nestas verses antigas.

NOTIFY

Utilizao
Configurar e executar a seqncia escutar/notificar usando o psql:
LISTEN virtual;
NOTIFY virtual;
Asynchronous NOTIFY virtual from backend with pid 8448 received.

Compatibilidade
SQL92
No existe o comando NOTIFY no SQL92.

PREPARE
Nome
PREPARE cria uma consulta preparada

Sinopse
PREPARE nome [ (tipo_de_dado [, ...] ) ] AS consulta

Inputs
nome
Um nome arbitrrio dado para esta consulta preparada. Deve ser nico dentro da mesma sesso, sendo usado
para executar ou remover uma consulta preparada anteriormente.
tipo_de_dado
O tipo de dado do parmetro da consulta preparada. Para fazer referncia aos parmetros na prpria consulta
preparada usa-se $1, $2, etc...

Sadas
PREPARE

A consulta foi preparada com sucesso.

Descrio
O comando PREPARE cria uma consulta preparada. Uma consulta preparada um objeto no lado do servidor que
pode ser usado para otimizar o desempenho. Quando o comando PREPARE executado, a consulta preparada
analisada, reescrita e planejada. Quando um comando EXECUTEposterior emitido, a consulta preparada necessita
apenas ser executada. Portanto, os estgios de anlise, reescrita e planejamento so realizados apenas uma vez, e
no todas as vezes que a consulta for executada.
As consultas preparadas podem receber parmetros: valores que so substitudos na consulta quando executada.
Para especificar os parmetros da consulta preparada, deve-se incluir uma relao de tipos de dado no comando
PREPARE. Na prpria consulta os parmetros podem ser referenciados atravs da sua posio utilizando $1, $2,
etc... Ao executar a consulta, especifica-se os valores reais dos parmetros no comando EXECUTE -- consulte o
comando EXECUTE para obter mais informaes.

PREPARE
As consultas preparadas so armazenadas localmente (no processo servidor corrente), e somente vo existir enquanto durar a sesso do banco de dados. Quando o cliente termina a sesso a consulta preparada esquecida
sendo, portanto, necessrio recriar a consulta antes de us-la novamente. Significa, tambm, que uma nica consulta preparada no pode ser usada por vrios clientes simultneos do banco de dados; entretanto, cada cliente
pode criar e usar a sua prpria consulta preparada.
As consultas preparadas possuem desempenho mais vantajoso quando um nico processo servidor usado para
executar um grande nmero de consultas similares. A diferena no desempenho ser particularmente significante,
se as consultas possuirem um planejamento ou uma reescrita complexos. Por exemplo, quando uma consulta
envolve uma juno de muitas tabelas ou requer a aplicao de vrias regras. Se a consulta for relativamente
simples de ser planejada e reescrita, mas relativamente dispendiosa para ser executada, a vantagem no desempenho
das consultas preparadas fica mais difcil de ser notada.

Notas
Em algumas situaes, o planejamento da consulta produzido pelo PostgreSQL para uma consulta preparada,
pode ser inferior ao plano produzido quando a consulta submetida e executada normalmente. Isto se deve ao
fato de que quando a consulta planejada (e o otimizador tenta determinar o plano timo para a consulta), os
valores reais dos parmetros especificados na consulta no esto disponveis. O PostgreSQL coleta estatsticas
da distribuio dos dados na tabela, e pode usar valores constantes na consulta para fazer suposies sobre o
resultado esperado ao executar a consulta. Uma vez que estes dados no esto disponveis no planejamento das
consultas preparadas com parmetros, o plano escolhido pode ser inferior ao timo.
Para obter mais informaes sobre o planejamento de consultas e estatsticas coletadas pelo PostgreSQL com a
finalidade de otimizar consultas, veja a documentao do comando ANALYZE.

Compatibilidade
SQL92
O SQL92 inclui o comando PREPARE, mas apenas para ser usado no SQL embutido nos clientes. O comando
PREPARE implementado pelo PostgreSQL tambm usa uma sintaxe um pouco diferente.

REINDEX
Nome
REINDEX reconstri ndices corrompidos

Sinopse
REINDEX { TABLE | DATABASE | INDEX } nome [ FORCE ]

Entradas
TABLE
Reconstri todos os ndices da tabela especificada.
DATABASE
Reconstri todos os ndices do sistema do banco de dados especificado (Os ndices das tabelas dos usurios
no so includos).
INDEX
Reconstri o ndice especificado.
nome
O nome da tabela, banco de dados ou ndice a ser reindexado. O nome da tabela e do ndice podem ser
qualificados pelo esquema.
FORCE
Fora a reconstruo dos ndices do sistema. Sem esta palavra chave o comando REINDEX pula os ndices do
sistema que no esto marcados como invlidos. FORCE irrelevante para o comando REINDEX INDEX, ou
para reindexar ndices do usurio.

Sadas
REINDEX

Mensagem retornada se a tabela for reindexada com sucesso.

REINDEX

Descrio
O comando REINDEX utilizado para reconstruir ndices corrompidos. Embora teoricamente esta necessidade
nunca deva existir, na prtica os ndices podem se tornar corrompidos devido a erros de programao ou falhas
nos equipamentos. O comando REINDEX fornece um mtodo de recuperao.
O comando REINDEX tambm remove certas pginas mortas do ndice que no podem ser recuperadas de outra
maneira. Consulte a seo "Reindexao de Rotina" no manual para obter mais informaes.
Se houver a suspeita de que um ndice de uma tabela do usurio est corrompido, pode-se simplesmente reconstruir este ndice, ou todos os ndices da tabela, usando o comando REINDEX INDEX ou REINDEX TABLE.
Nota: Outra forma de tratar o problema de ndice corrompido em tabela do usurio simplesmente elimin-lo
e recri-lo. Pode-se preferir esta forma para manter alguma aparncia de uma operao normal em uma
tabela. O comando REINDEX obtm um bloqueio exclusivo da tabela, enquanto o comando CREATE INDEX
bloqueia a escrita mas no a leitura da tabela.

A situao se torna mais difcil quando necessrio recuperar um ndice corrompido de uma tabela do sistema.
Neste caso importante que o servidor efetuando a recuperao no esteja usando nenhum dos ndices suspeitos
(Sem dvida, neste tipo de cenrio pode acontecer do servidor estar caindo durante a inicializao por depender
do ndice corrompido). Para executar a recuperao segura, o postmaster deve ser parado e um servidor autnomo
(stand-alone) do PostgreSQL deve ser iniciado fornecendo-se as opes de linha de comando -O e -P (estas opes
permitem modificar as tabelas do sistema e faz com que os ndices do sistema no sejam utilizados, respectivamente). Ento se executa o comando REINDEX INDEX, REINDEX TABLE, ou REINDEX DATABASE dependendo
de quanto se deseja reconstruir. Na dvida deve ser utilizado o comando REINDEX DATABASE FORCE para forar
a reconstruo de todos os ndices do sistema no banco de dados. Em seguida o servidor autnomo deve ser parado
e o postmaster reiniciado.
Como esta provavelmente a nica situao em que a maioria das pessoas usa um servidor autnomo, algumas
observaes devem ser feitas:

Inicie o servidor com um comando como

postgres -D $PGDATA -O -P meu_banco_de_dados

Fornea o caminho correto para a rea de banco de dados na opo -D, ou assegure-se de que a varivel de
ambiente PGDATA est declarada. Tambm deve ser especificado o nome do banco de dados em particular em
que se deseja trabalhar.

Pode ser executado qualquer comando SQL e no apenas o REINDEX.

Tenha em mente que o servidor autnomo trata o caractere de nova-linha como trmino da entrada do comando;
no existe a inteligncia sobre o ponto-e-vrgula como existe no psql. Para um comando prosseguir atravs
de vrias linhas, deve-se digitar uma contrabarra precedendo cada caractere de nova-linha, exceto da ltima.
Tambm no existe nenhuma das convenincias da edio de linha de comando (no existe o histrico dos
comandos, por exemplo).

Para sair do servidor digite EOF (geralmente Control+D).

Consulte a pgina de referncia do postgres para obter mais informaes.

Utilizao
Reconstruir os ndices da tabela minha_tabela:
REINDEX TABLE minha_tabela;

REINDEX

Reconstruir um nico ndice:

REINDEX INDEX meu_indice;

Reconstruir todos os ndices do sistema (somente funciona utilizando um servidor autnomo):

REINDEX DATABASE meu_banco_de_dados FORCE;

Compatibilidade
SQL92
No existe o comando REINDEX no SQL92.

RESET
Nome
RESET atribui a parmetros de tempo de execuo o seu valor padro

Sinopse
RESET varivel

RESET ALL

Entradas
varivel
O nome de um parmetro de tempo de execuo. Consulte o comando SET para ver a relao.
ALL
Atribui a todos os parmetros de tempo de execuo, que podem ser alterados, o seu valor padro.

Descrio
O comando RESET atribui a parmetros de tempo de execuo o seu valor padro. Consulte o comando SET para
obter detalhes. O comando RESET uma forma alternativa para
SET varivel TO DEFAULT

O valor padro definido como sendo o valor que a varivel deveria ter, se nenhum comando SET tivesse sido
executado na sesso corrente. A origem deste valor pode ser um padro de compilao, o arquivo de configurao
do postmaster, as chaves de linha de comando, ou os valores definidos por banco de dados ou por usurio.
Consulte o Guia do Administrador para obter detalhes.
Consulte a pgina do manual relativa ao comando SET para obter detalhes sobre o comportamento em transaes
do comando RESET.

Diagnsticos
Consulte o comando SET.

RESET

Exemplos
Atribuir ao parmetro DateStyle o seu valor padro:
RESET DateStyle;

Atribuir ao parmetro Geqo o seu valor padro:

RESET GEQO;

Compatibilidade
O comando RESET uma extenso do PostgreSQL linguagem.

REVOKE
Nome
REVOKE revoga privilgios de acesso

Sinopse
REVOKE { { SELECT | INSERT | UPDATE | DELETE | RULE | REFERENCES | TRIGGER }
[,...] | ALL [ PRIVILEGES ] }
ON [ TABLE ] nome_da_tabela [, ...]
FROM { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]
REVOKE { { CREATE | TEMPORARY | TEMP } [,...] | ALL [ PRIVILEGES ] }
ON DATABASE nome_bd [, ...]
FROM { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]
REVOKE { EXECUTE | ALL [ PRIVILEGES ] }
ON FUNCTION nome_da_funo ([tipo, ...]) [, ...]
FROM { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]
REVOKE { USAGE | ALL [ PRIVILEGES ] }
ON LANGUAGE nome_da_linguagem [, ...]
FROM { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]
REVOKE { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
ON SCHEMA nome_do_esquema [, ...]
FROM { nome_do_usurio | GROUP nome_do_grupo | PUBLIC } [, ...]

Descrio
O comando REVOKE permite ao criador de um objeto revogar as permisses concedidas anteriormente a um ou
mais usurios ou grupos de usurios. A palavra chave PUBLIC refere-se ao grupo de todos os usurios definido
implicitamente.
Note que um usurio em particular possui a soma dos privilgios concedidos diretamente ao prprio usurio, com
os privilgios concedidos aos grupos de que for membro e com os privilgios concedidos a PUBLIC. Da, por
exemplo, revogar o privilgio de SELECT para PUBLIC no significa, necessariamente, que todos os usurios
perdem o privilgio de SELECT sobre o objeto: queles que receberam o privilgio diretamente, ou atravs de
um grupo, permanecem com o privilgio.
Consulte a descrio do comando GRANT para conhecer o significado dos tipos de privilgio.

Notas
Use o comando \z do psql para exibir os privilgios concedidos nos objetos existentes. Consulte tambm o
comando GRANT para obter informaes sobre o formato.

REVOKE

Exemplos
Revogar o privilgio de insero na tabela filmes concedido para todos os usurios:
REVOKE INSERT ON filmes FROM PUBLIC;

Revogar todos os privilgios concedidos ao usurio manuel sobre a viso vis_tipos:

REVOKE ALL PRIVILEGES ON vis_tipos FROM manuel;

Compatibilidade
SQL92
As notas sobre compatibilidade presentes no comando GRANT se aplicam de forma anloga ao comando REVOKE.
O sumrio da sintaxe :
REVOKE [ GRANT OPTION FOR ] { SELECT | INSERT | UPDATE | DELETE | REFERENCES }
ON objeto [ ( coluna [, ...] ) ]
FROM { PUBLIC | nome_do_usurio [, ...] }
{ RESTRICT | CASCADE }

Se user1 conceder um privilgio WITH GRANT OPTION para o user2, e user2 conced-lo para o user3, ento,
user1 pode revogar este privilgio em cascata utilizando a palavra chave CASCADE. Se user1 conceder um
privilgio WITH GRANT OPTION para o user2, e user2 conced-lo ao user3, ento, se user1 tentar revogar este
privilgio especificando a palavra chave RESTRICT o comando ir falhar.

Consulte tambm
GRANT

ROLLBACK
Nome
ROLLBACK aborta a transao corrente

Sinopse
ROLLBACK [ WORK | TRANSACTION ]

Entradas
Nenhuma.

Sadas
ROLLBACK

Mensagem retornada se o comando for executado com sucesso.

WARNING: ROLLBACK: no transaction in progress

Se no houver nenhuma transao sendo executada.

Descrio
O comando ROLLBACK desfaz a transao corrente, fazendo com que todas as modificaes realizadas pela
transao sejam rejeitadas.

Notas
Use o comando COMMIT para terminar uma transao com sucesso. O comando ABORT um sinnimo para o
comando ROLLBACK.

Utilizao
Para abortar todas as modificaes:
ROLLBACK WORK;

ROLLBACK

Compatibilidade
SQL92
O SQL92 somente especifica as duas formas ROLLBACK e ROLLBACK WORK. Fora isso totalmente compatvel.

SELECT
Nome
SELECT retorna linhas de uma tabela ou de uma viso

Sinopse
SELECT [ ALL | DISTINCT [ ON ( expresso [, ...] ) ] ]
* | expresso [ AS nome_de_sada ] [, ...]
[ FROM item_de [, ...] ]
[ WHERE condio ]
[ GROUP BY expresso [, ...] ]
[ HAVING condio [, ...] ]
[ { UNION | INTERSECT | EXCEPT } [ ALL ] select ]
[ ORDER BY expresso [ ASC | DESC | USING operador ] [, ...] ]
[ LIMIT { contador | ALL } ]
[ OFFSET incio ]
[ FOR UPDATE [ OF nome_da_tabela [, ...] ] ]
onde item_de pode ser:
[ ONLY ] nome_da_tabela [ * ]
[ [ AS ] alis [ ( lista_de_alis_de_coluna ) ] ]
|
( select )
[ AS ] alis [ ( lista_de_alis_de_coluna ) ]
|
nome_da_funo_de_tabela ( [ argumento [, ...] ] )
[ AS ] alis [ ( lista_de_alis_de_coluna | lista_de_definio_de_coluna ) ]
|
nome_da_funo_de_tabela ( [ argumento [, ...] ] )
AS ( lista_de_definio_de_coluna )
|
item_de [ NATURAL ] tipo_de_juno item_de
[ ON condio_de_juno | USING ( lista_de_coluna_de_juno ) ]

Entradas
expresso
O nome de uma coluna da tabela ou uma expresso.
nome_de_sada
Especifica um outro nome para a coluna retornada utilizando a clusula AS. Este nome utilizado, principalmente, como o ttulo da coluna exibida. Tambm pode ser utilizado para fazer referncia ao valor da coluna
nas clusulas ORDER BY e GROUP BY. Porm, o nome_de_sada no pode ser usado nas clusulas
WHERE e HAVING; nestes casos, a expresso deve ser escrita novamente.
item_de
A referncia a uma tabela, uma subconsulta, uma funo de tabela ou uma clusula de juno. Veja abaixo
para obter detalhes.

SELECT
condio
Uma expresso booleana produzindo um resultado falso ou verdadeiro. Veja a descrio das clusulas
WHERE e HAVING abaixo.
select
Um comando SELECT com todas as suas funcionalidades, exceto as clusulas ORDER BY, LIMIT/OFFSET
e FOR UPDATE (mesmo estas podem ser utilizadas quando o SELECT est entre parnteses).

Os itens da clusula FROM podem conter:

nome_da_tabela
O nome (opcionalmente qualificado pelo esquema) de uma tabela ou de uma viso existente. Se ONLY
for especificado, somente esta tabela consultada. Se ONLY no for especificado a tabela, e todas as suas
tabelas descendentes porventura existentes, sero consultadas. O * pode ser anexado ao nome da tabela para
indicar que as tabelas descendentes devem ser consultadas, mas na verso corrente este o comportamento
padro (Nas verses anteriores a 7.1 ONLY era o comportamento padro). O comportamento padro pode
ser mudado alterando-se a opo de configurao SQL_INHERITANCE.
alis
Um nome substituto para o item do FROM que contm o alis. Um alis utilizado para abreviar ou para
eliminar ambigidade em autojunes (onde a mesma tabela referenciada vrias vezes). Quando um alis
fornecido, este oculta completamente o nome verdadeiro da tabela ou da funo de tabela; por exemplo,
escrevendo-se FROM foo AS f o restante do comando SELECT deve fazer referncia este item do FROM
como f, e no foo. Se um alis for fornecido, uma relao de alis de coluna tambm pode ser escrito para
fornecer nomes substitutos para uma ou mais colunas da tabela.
select
Uma subconsulta pode aparecer na clusula FROM, agindo tal qual sua sada tivesse sido criada como uma
tabela temporria pela durao do comando SELECT. Observe que a subconsulta deve estar entre parnteses,
e que um alis deve ser fornecido para esta subconsulta.
funo_de_tabela
Uma funo de tabela pode aparecer na clusula FROM, agindo tal qual sua sada tivesse sido criada como
uma tabela temporria pela durao do comando SELECT. Um alis tambm pode ser usado. Se um alis for
fornecido, uma relao de alis de coluna tambm pode ser escrito para fornecer nomes substitutos para uma
ou mais colunas da funo de tabela. Se a funo de tabela for definida retornando o tipo de dado record,
deve estar presente um alis ou a palavra chave AS seguida por uma lista de definio de coluna na forma (
nome_de_coluna tipo_de_dado [, ... ] ). A lista de definio de coluna deve corresponder ao nmero
e tipos de dado das colunas retornadas pela funo.
tipo_de_juno
Um entre [ INNER ] JOIN, LEFT [ OUTER ] JOIN, RIGHT [ OUTER ] JOIN, FULL [ OUTER ]
JOIN e CROSS JOIN. Para os tipos de juno INNER e OUTER, exatamente um entre NATURAL, ON
condio_de_juno e USING ( lista_de_coluna_de_juno ) deve estar presente. Para o
CROSS JOIN, nenhum destes itens pode aparecer.
condio_de_juno
Uma condio de qualificao, similar condio WHERE, exceto que somente se aplica aos dois itens
sendo unidos por esta clusula JOIN.

SELECT
lista_de_coluna_de_juno
A condio USING lista de colunas ( a, b, ... ) uma forma abreviada da condio ON tabela_esquerda.a =
tabela_direita.a AND tabela_esquerda.b = tabela_direita.b ...

Sadas
Linhas
O conjunto completo das linhas resultantes da especificao da consulta.
contador
A quantidade de linhas retornadas pela consulta.

Descrio
O comando SELECT retorna linhas de uma ou mais tabelas. As linhas que satisfazem a condio WHERE so
candidatas para seleo; se WHERE for omitido, todas as linhas so candidatas (Veja A clusula WHERE).
Na verdade, as linhas retornadas no so as linhas produzidas pelas clusulas FROM/WHERE/GROUP
BY/HAVING diretamente; mais precisamente, as linhas da sada so formadas computando-se as expresses de
sada do SELECT para cada linha selecionada. O * pode ser escrito na lista de sada como uma abreviao
para todas as colunas das linhas selecionadas. Pode-se escrever tambm nome_da_tabela.* como uma
abreviao para as colunas provenientes de apenas uma tabela.
A opo DISTINCT elimina as linhas repetidas do resultado, enquanto que a opo ALL (o padro) retorna todas
as linhas candidatas, incluindo as repetidas.
DISTINCT ON elimina as linhas que correspondem a todas as expresses especificadas, mantendo apenas a

primeira linha de cada conjunto de linhas repetidas. As expresses do DISTINCT ON so interpretadas usando as
mesmas regras dos itens do ORDER BY; veja abaixo. Observe que a primeira linha de cada conjunto no pode
ser prevista, a menos que ORDER BY seja usado para garantir que a linha desejada aparea primeiro. Por exemplo,
SELECT DISTINCT ON (local) local, data, condicao
FROM tbl_condicao_climatica
ORDER BY local, data DESC;

exibe a condio climtica mais recente para cada local, mas se ORDER BY no tivesse sido usado para forar
uma ordem descendente dos valores da data para cada local, teria sido obtido um relatrio com datas aleatrias
para cada local.
A clusula GROUP BY permite dividir a tabela em grupos de linhas que correspondem a um ou mais valores
(Veja A clusula GROUP BY).
A clusula HAVING permite selecionar somente os grupos de linhas que atendem a uma condio especfica
(Veja A clusula HAVING).

SELECT
A clusula ORDER BY faz com que as linhas retornadas sejam classificadas na ordem especificada. Se ORDER
BY no for especificado, as linhas retornam na ordem que o sistema considera mais fcil de gerar (Veja A clusula
ORDER BY).
As consultas SELECT podem ser combinadas usando os operadores UNION, INTERSECT e EXCEPT. Use
parnteses, se for necessrio, para determinar a ordem destes operadores.
O operador UNION computa a coleo das linhas retornadas pelas consultas envolvidas. As linhas duplicadas so
eliminadas, a no ser que ALL seja especificado (Veja A clusula UNION).
O operador INTERSECT computa as linhas que so comuns s duas consultas (interseo). As linhas duplicadas
so eliminadas, a no ser que ALL seja especificado (Veja A clusula INTERSECT).
O operador EXCEPT computa as linhas que so retornadas pela primeira consulta, mas que no so retornadas
pela segunda consulta. As linhas duplicadas so eliminadas, a no ser que ALL seja especificado (Veja A clusula
EXCEPT).
A clusula LIMIT permite que retorne para o usurio apenas um subconjunto das linhas produzidas pela consulta
(Veja A clusula LIMIT).
A clusula FOR UPDATE faz com que o comando SELECT bloqueie as linhas selecionadas contra atualizaes
simultneas.
necessrio possuir o privilgio SELECT na tabela para poder ler seus valores (Consulte os comandos GRANT e
REVOKE). Para utilizar a clusula FOR UPDATE tambm necessrio possuir o privilgio UPDATE.

A clusula FROM
A clusula FROM especifica uma ou mais tabelas de origem para o SELECT. Se mltiplas tabelas de origem
forem especificadas o resultado ser, conceitualmente, o produto cartesiano de todas as linhas de todas estas
tabelas -- mas, geralmente, condies de qualificao so adicionadas para restringir as linhas retornadas a um
pequeno subconjunto do produto cartesiano.
Quando o item da clusula FROM simplesmente o nome de uma tabela, so includas implicitamente as linhas
das subtabelas desta tabela (descendentes que herdam). Especificando-se ONLY causa a supresso das linhas das
subtabelas da tabela. Antes do PostgreSQL 7.1 este era o comportamento padro, e a adio das subtabelas era
feita anexando-se um * ao nome da tabela. Este comportamento antigo est disponvel atravs do comando SET
SQL_Inheritance TO OFF

Um item da clusula FROM pode ser tambm uma subconsulta entre parnteses (note que uma clusula alis
exigida para a subconsulta!). Esta caracterstica extremamente til porque esta a nica maneira de se obter
mltiplos nveis de agrupamento, agregao ou ordenao em uma nica consulta.
Um item do FROM pode ser uma funo de tabela (tipicamente, uma funo que retorna vrias linhas e/ou colunas, embora na verdade qualquer funo possa ser utilizada). A funo chamada com os valores dos argumentos
fornecidos, e a sua sada varrida como se fosse uma tabela.
Em alguns casos til definir funes de tabela que possam retornar conjuntos diferentes de colunas dependendo
de como so chamadas. Para que isto seja possvel, a funo de tabela deve ser declarada como retornando o
pseudo-tipo record. Quando esta funo usada no FROM, deve ser seguida por um alis ou pela palavra
chave AS szinha, e depois por uma lista de nomes de coluna e tipos de dado entre parnteses. Isto fornece
uma definio de tipo composto em tempo de consulta. A definio de tipo composto deve corresponder ao tipo
composto retornado pela funo, ou um erro ser gerado em tempo de execuo.
Finalmente, um item da clusula FROM pode ser uma clusula JOIN, que combina dois itens do FROM (Use
parnteses, se for necessrio, para determinar a ordem de aninhamento).
O CROSS JOIN e o INNER JOIN so um produto cartesiano simples, o mesmo que seria obtido listando-se os
dois itens no nvel superior do FROM. O CROSS JOIN equivalente ao INNER JOIN ON (TRUE), ou seja,

SELECT
nenhuma linha removida pela qualificao. Estes tipos de juno so apenas uma notao conveniente, porque
no fazem nada que no poderia ser feito usando simplesmente o FROM e o WHERE.
O LEFT OUTER JOIN retorna todas as linhas do produto cartesiano qualificado (i.e., todas as linhas combinadas
que passam pela condio ON), mais uma cpia de cada linha da tabela esquerda para a qual no h uma linha da
tabela direita que tenha passado pela condio ON. Esta linha da tabela esquerda estendida por toda a largura
da tabela combinada inserindo-se nulos para as colunas da tabela direita. Observe que somente as condies
ON ou USING do prprio JOIN so consideradas na hora de decidir quais linhas possuem correspondncia. As
condies ON ou WHERE externas so aplicadas depois.
De forma inversa, o RIGHT OUTER JOIN retorna todas as linhas da juno, mais uma linha para cada linha da
tabela direita sem correspondncia (estendida com nulos na tabela esquerda). Isto apenas uma convenincia
da notao, porque poderia ser convertido em um LEFT OUTER JOIN trocando-se a tabela direita pela tabela
esquerda.
O FULL OUTER JOIN retorna todas as linhas da juno, mais uma linha para cada linha da tabela esquerda sem
correspondncia (estendida com nulos na tabela direita), mais uma linha da tabela direita sem correspondncia
(estendida com nulos na tabela esquerda)
Para todos os tipos de JOIN, exceto CROSS JOIN, deve-se escrever exatamente um entre ON
condio_de_juno, USING ( lista_de_coluna_de_juno ), ou NATURAL. A clusula ON o
caso mais geral: pode ser escrita qualquer expresso de qualificao envolvendo as duas tabelas da juno.
A forma USING lista de colunas ( a, b, ... ) uma abreviao para a condio ON tabela_esquerda.a =
tabela_direita.a AND tabela_esquerda.b = tabela_direita.b ... Alm disso, USING implica em que somente uma
coluna de cada par de colunas equivalentes ser includa na sada do JOIN, e no as duas. NATURAL uma
abreviao para USING quando a lista menciona todas as colunas das tabelas com mesmo nome.

A clusula WHERE
A condio opcional WHERE possui a forma geral:
WHERE expresso_booleana

A expresso_booleana pode ser qualquer expresso que retorna um valor booleano. Em muitos casos esta
expresso possui a forma:
expresso cond_op expr

ou
op_logico expr

onde op_condio pode ser um entre: =, <, <=, >, >= ou <>, um operador condicional como ALL, ANY,
IN, LIKE, ou um operador definido localmente, e op_logico pode ser um entre: AND, OR e NOT. O SELECT
ignora todas as linhas para as quais a condio WHERE no retorna TRUE.

A clusula GROUP BY
O GROUP BY especifica uma tabela agrupada derivada da aplicao desta clusula:
GROUP BY expresso [, ...]

SELECT

O GROUP BY condensa em uma nica linha todas as linhas selecionadas que compartilham os mesmos valores
para as colunas agrupadas. As funes de agregao, caso existam, so computadas atravs de todas as linhas que
pertencem a cada grupo, produzindo um valor separado para cada grupo (enquanto que sem GROUP BY, uma
funo de agregao produz um nico valor computado atravs de todas as linhas selecionadas). Quando GROUP
BY est presente, no vlido uma expresso de sada do SELECT fazer referncia a uma coluna no agrupada,
exceto dentro de uma funo de agregao, porque pode haver mais de um valor possvel retornado para uma
coluna no agrupada.
Um item do GROUP BY pode ser o nome de uma coluna da entrada, o nome ou o nmero ordinal de uma coluna
da sada (expresso SELECT), ou pode ser uma expresso arbitrria formada pelos valores das colunas da entrada.
No caso de haver ambigidade, o nome no GROUP BY vai ser interpretado como o sendo o nome de uma coluna
da entrada, e no como o nome de uma coluna da sada.

A clusula HAVING
A condio opcional HAVING possui a forma geral:
HAVING expresso_booleana

onde expreso_booleana a mesma que foi especificada para a clusula WHERE.

HAVING especifica uma tabela agrupada derivada pela eliminao das linhas agrupadas que no satisfazem a
expresso_booleana. HAVING diferente de WHERE: WHERE filtra individualmente as linhas antes da
aplicao do GROUP BY, enquanto HAVING filtra os grupos de linhas criados pelo GROUP BY.
Cada coluna referenciada na expresso_booleana deve referenciar, sem ambigidade, uma coluna de agrupamento, a menos que a referncia aparea dentro de uma funo de agregao.

A clusula ORDER BY
ORDER BY expresso [ ASC | DESC | USING operator ] [, ...]

Um item do ORDER BY pode ser o nome ou o nmero ordinal de uma coluna da sada (expresso SELECT), ou
pode ser uma expresso arbitrria formada por valores da coluna de entrada. No caso de haver ambigidade, o
nome no ORDER BY ser interpretado como o nome de uma coluna da sada.
O nmero ordinal refere-se posio ordinal (da esquerda para a direita) da coluna do resultado. Esta caracterstica
torna possvel definir uma ordenao baseada em uma coluna que no possui um nome nico. Nunca isto
absolutamente necessrio, porque sempre possvel atribuir um nome a uma coluna do resultado usando a clusula
AS, como no exemplo abaixo:
SELECT titulo, data_prod + 1 AS newlen FROM filmes ORDER BY newlen;

Tambm possvel efetuar um ORDER BY por expresses arbitrrias (uma extenso ao SQL92), incluindo campos que no aparecem na lista de resultados do SELECT. Portanto, o seguinte comando vlido:
SELECT nome FROM distribuidores ORDER BY cod;

SELECT

Uma limitao desta funcionalidade que uma clusula ORDER BY aplicada ao resultado de uma consulta com
UNION, INTERSECT, ou EXCEPT pode apenas especificar um nome ou um nmero de coluna, mas no uma
expresso.
Observe que se um item do ORDER BY for um nome simples que corresponda tanto ao nome de uma coluna
do resultado quanto ao nome de uma coluna da entrada, o ORDER BY vai interpretar como sendo o nome da
coluna do resultado. Esta opo oposta a que feita pelo GROUP BY na mesma situao. Esta inconsistncia
determinada pelo padro SQL92.
Opcionalmente pode ser utilizada a palavra chave DESC (descendente) ou ASC (ascendente) aps cada nome de
coluna na clusula ORDER BY. Se nada for especificado, ASC assumido por padro. Como alternativa, um nome
de operador de ordenao especfico pode ser especificado. ASC equivalente a USING < e DESC equivalente a
USING >.
O valor nulo possui uma posio de ordenao superior a de qualquer outro valor do domnio. Em outras palavras,
na ordenao ascendente os valores nulos aparecem no final, e na ordenao descendente os valores nulos aparecem no incio.
Os dados dos tipos caractere so ordenados de acordo com locale-specific collation order that was established
when the database cluster was initialized.

A clusula UNION
tabela_consulta UNION [ ALL ] tabela_consulta
[ ORDER BY expresso [ ASC | DESC | USING operador ] [, ...] ]
[ LIMIT { contador | ALL } ]
[ OFFSET incio ]

onde tabela_consulta especifica qualquer expresso de seleo sem as clusulas ORDER BY, LIMIT ou
FOR UPDATE (ORDER BY e LIMIT podem aparecer na subexpresso se estiver entre parnteses. Sem os parnteses estas clusulas se aplicam ao resultado da UNION, e no na sua expresso de entrada da direita).
O operador UNION computa a coleo (conjunto unio) das linhas retornadas pelas consultas envolvidas. Os
dois comandos SELECT que representam os operandos diretos do UNION devem produzir o mesmo nmero de
colunas, e as colunas correspondentes devem possuir tipos de dado compatveis.
O resultado de uma UNION no contm nenhuma linha repetida, a menos que a opo ALL all seja especificada.
ALL impede a eliminao das linhas repetidas.
Quando existem vrios operadores UNION no mesmo comando SELECT, estes so processados da esquerda para
a direita, a menos que outra ordem seja definida pelo uso de parnteses.
Atualmente, FOR UPDATE no deve ser especificado nem no resultado nem nas entradas de uma UNION.

A clusula INTERSECT
tabela_consulta INTERSECT [ ALL ] tabela_consulta
[ ORDER BY expresso [ ASC | DESC | USING operador ] [, ...] ]
[ LIMIT { contador | ALL } ]
[ OFFSET incio ]

SELECT
onde tabela_consulta especifica qualquer expresso de seleo sem as clusulas ORDER BY, LIMIT, ou
FOR UPDATE.
INTERSECT semelhante a UNION, exceto que retorna somente as linhas presentes nas sadas das duas consultas, em vez de todas as linhas presentes nas duas consultas.
O resultado do INTERSECT no possui nenhuma linha repetida, a menos que a opo ALL seja especificada.
Com ALL, uma linha que possui m repeties em L e n repeties em R aparece min(m,n) vezes.
Quando existem vrios operadores INTERSECT no mesmo comando SELECT, estes so processados da esquerda
para a direita, a menos que os parnteses estabeleam outra ordem. INTERSECT tem prevalncia sobre UNION
--- ou seja, A UNION B INTERSECT C processado como A UNION (B INTERSECT C), a menos que outra
ordem seja estabelecida pelo uso de parnteses..

A clusula EXCEPT
tabela_consulta EXCEPT [ ALL ] tabela_consulta
[ ORDER BY expresso [ ASC | DESC | USING operador ] [, ...] ]
[ LIMIT { contador | ALL } ]
[ OFFSET incio ]

onde tabela_consulta especifica qualquer expresso de seleo sem as clusulas ORDER BY, LIMIT, ou
FOR UPDATE.
EXCEPT semelhante a UNION, exceto que retorna somente as linhas presentes na sada da consulta esquerda,
mas que no esto presentes na sada da consulta direita.
O resultado do EXCEPT no possui nenhuma linha repetida, a menos que a opo ALL seja especificada. Com
ALL, uma linha que possui m repeties em L e n repeties em R aparece max(m-n,0) vezes.
Quando existem vrios operadores EXCEPT no mesmo comando SELECT, estes so processados da esquerda
para a direita, a menos que os parnteses estabeleam outra ordem. EXCEPT possui o mesmo nvel de precedncia
de UNION.

A clusula LIMIT
LIMIT { contador | ALL }
OFFSET incio

onde contador especifica o nmero mximo de linhas retornadas, e incio especifica o nmero de linhas a
serem saltadas antes de comear a retornar as linhas.
O contador LIMIT permite que seja retornada apenas uma parte das linhas que so geradas pelo resultado da
consulta. Se um contador limite for fornecido, no ser retornado mais do que este nmero de linhas. Se um
deslocamento for especificado, este nmero de linhas ser saltado antes de comear o retorno das linhas.
Quando LIMIT usado, aconselha-se utilizar a clusula ORDER BY para colocar as linhas do resultado dentro de
uma ordem nica. De outra maneira, ser obtido um subconjunto das linhas da consulta impossvel de ser previsto
--- pode-se estar querendo obter da dcima a vigsima linha, mas da dcima a vigsima linha de qual ordenao?
No possvel saber qual ser a ordenao, a menos que ORDER BY seja especificado.
A partir do PostgreSQL 7.0, o otimizador de consultas leva LIMIT em considerao ao gerar o plano para
a consulta, ento muito provvel que sejam obtidos planos diferentes (resultando em ordenaes diferentes
das linhas) dependendo do que seja fornecido para LIMIT e OFFSET. Portanto, utilizar valores diferentes para

SELECT
LIMIT/OFFSET para selecionar subconjuntos diferentes do resultado de uma consulta vai produzir resultados
inconsistentes, a menos que seja exigida uma ordenao previsvel dos resultados utilizando ORDER BY. Isto
no um erro (bug), isto uma conseqncia do fato de que o SQL no retorna os resultados de uma consulta em
nenhuma ordem especfica, a no ser que ORDER BY seja utilizado para definir esta ordem.

A clusula FOR UPDATE

FOR UPDATE [ OF nome_da_tabela [, ...] ]

A clusula FOR UPDATE faz com que as linhas retornadas pela consulta sejam bloqueadas para atualizao
impedindo, desta forma, que sejam modificadas ou excludas por outras transaes at que a transao corrente
termine; ou seja, as outras transaes que tentarem executar um UPDATE, DELETE ou SELECT FOR UPDATE
nestas linhas sero bloqueadas at que a transao corrente termine. Tambm, se um UPDATE, DELETE ou
SELECT FOR UPDATE de alguma outra transao j tiver efetuado o bloqueio de uma ou mais linhas, o SELECT
FOR UPDATE ir aguardar at que a outra transao termine, e ento ir bloquear e retornar a linha atualizada (ou
nenhuma linha, se a linha for excluda). Para uma discusso mais detalhada consulte o captulo sobre concorrncia
no Guia do Usurio.
Se forem especificados nomes de tabelas na clusula FOR UPDATE, ento somente as linhas provenientes destas
tabela so bloqueadas; todas as outras tabelas presentes no SELECT so simplesmente lidas da forma usual.
A clusula FOR UPDATE no pode ser usada nos contextos onde as linha retornadas no podem ser claramente
relacionadas com as linhas das tabelas; por exemplo, no pode ser usado em uma agregao.
A clusula FOR UPDATE pode vir antes da clusula LIMIT para manter a compatibilidade com aplicativos pr7.3. Entretanto, como ser executada aps a clusula LIMIT recomenda-se que seja escrita aps esta clsula.

Utilizao
Para efetuar a juno da tabela filmes com a tabela distribuidores:
SELECT f.titulo, f.did, d.nome, f.data_prod, f.tipo
FROM distribuidores d, filmes f
WHERE f.did = d.did
titulo
| did |
nome
| data_prod | tipo
---------------------------+-----+------------------+------------+---------The Third Man
| 101 | British Lion
| 1949-12-23 | Drama
The African Queen
| 101 | British Lion
| 1951-08-11 | Romance
Une Femme est une Femme
| 102 | Jean Luc Godard | 1961-03-12 | Romance
Vertigo
| 103 | Paramount
| 1958-11-14 | Ao
Becket
| 103 | Paramount
| 1964-02-03 | Drama
48 Hrs
| 103 | Paramount
| 1982-10-22 | Ao
War and Peace
| 104 | Mosfilm
| 1967-02-12 | Drama
West Side Story
| 105 | United Artists
| 1961-01-03 | Musical
Bananas
| 105 | United Artists
| 1971-07-13 | Comdia
Yojimbo
| 106 | Toho
| 1961-06-16 | Drama
Theres a Girl in my Soup | 107 | Columbia
| 1970-06-11 | Comdia
Taxi Driver
| 107 | Columbia
| 1975-05-15 | Ao
Absence of Malice
| 107 | Columbia
| 1981-11-15 | Ao
Storia di una donna
| 108 | Westward
| 1970-08-15 | Romance

SELECT
The King and I
| 109 | 20th Century Fox | 1956-08-11 | Musical
Das Boot
| 110 | Bavaria Atelier | 1981-11-11 | Drama
Bed Knobs and Broomsticks | 111 | Walt Disney
|
| Musical
(17 rows)

Obter soma da coluna duracao de todos os filmes, agrupando os resultados por tipo:
SELECT tipo, SUM(duracao) AS total FROM filmes GROUP BY tipo;
tipo
| total
----------+------Ao
| 07:34
Comdia | 02:58
Drama
| 14:28
Musical | 06:42
Romance | 04:38
(5 rows)

Obter a soma da coluna duracao de todos os filmes, agrupando os resultados por tipo, mostrando apenas os
grupos com total inferior a 5 horas:
SELECT tipo, SUM(duracao) AS total
FROM filmes
GROUP BY tipo
HAVING SUM(duracao) < INTERVAL 5 hour;
tipo
| total
----------+------Comdia | 02:58
Romance | 04:38
(2 rows)

Os dois exemplos mostrados abaixo so formas idnticas de ordenao dos resultados de acordo com o contedo
da segunda coluna (nome):
SELECT * FROM distribuidores ORDER BY nome;
SELECT * FROM distribuidores ORDER BY 2;
id |
nome
-----+-----------------109 | 20th Century Fox
110 | Bavaria Atelier
101 | British Lion
107 | Columbia
102 | Jean Luc Godard
113 | Luso filmes
104 | Mosfilm
103 | Paramount
106 | Toho
105 | United Artists
111 | Walt Disney
112 | Warner Bros.
108 | Westward

10

SELECT
(13 rows)

Este exemplo mostra como obter a unio das tabelas distribuidores e atores, restringindo o resultado aos
nomes que iniciam pela letra W em cada uma das tabelas. Somente linhas distintas so desejadas, por isso a
palavra chave ALL omitida:
distribuidores:
did |
nome
-----+-------------108 | Westward
111 | Walt Disney
112 | Warner Bros.
...

atores:
id |
nome
----+---------------1 | Woody Allen
2 | Warren Beatty
3 | Walter Matthau
...

SELECT distribuidores.nome
FROM
distribuidores
WHERE distribuidores.nome LIKE W%
UNION
SELECT atores.nome
FROM
atores
WHERE atores.nome LIKE W%;
nome
---------------Walt Disney
Walter Matthau
Warner Bros.
Warren Beatty
Westward
Woody Allen

O exemplo abaixo mostra como usar uma funo de tabela com e sem uma lista de definio de coluna.
distribuidores:
id |
nome
-----+-------------108 | Westward
111 | Walt Disney
112 | Warner Bros.
...
CREATE FUNCTION distribuidores(int)
RETURNS SETOF distribuidores AS
SELECT * FROM distribuidores WHERE id = $1;
LANGUAGE SQL;
SELECT * FROM distribuidores(111);
id |
name
-----+------------111 | Walt Disney
(1 row)
CREATE FUNCTION distribuidores_2(int)
RETURNS SETOF RECORD AS

11

SELECT
SELECT * FROM distribuidores WHERE id = $1;
LANGUAGE SQL;
SELECT * FROM distribuidores_2(111) AS (f1 int, f2 text);
f1 |
f2
-----+------------111 | Walt Disney
(1 row)

Compatibilidade
Extenses
O PostgreSQL permite que seja omitida a clusula FROM da consulta. Esta funcionalidade da linguagem de consulta PostQuel original foi mantida, sendo muita utilizada para calcular os resultados de expresses simples:
SELECT 2+2;
?column?
---------4

Outros bancos de dado SQL no podem fazer isto, a no ser que seja introduzida uma tabela especial com uma
nica linha para se efetuar a seleo a partir desta tabela. Uma utilizao menos bvia desta caracterstica para
abreviar consultas normais a uma ou mais tabelas:
SELECT distribuidores.* WHERE distribuidores.nome = Westward;
did | nome
-----+---------108 | Westward

Isso funciona porque um FROM implcito adicionado para cada tabela que referenciada na consulta mas no
mencionada no FROM. Ao mesmo tempo em que uma forma conveniente de abreviar, fcil de ser usado de
forma errada. Por exemplo, a consulta
SELECT distribuidores.* FROM distribuidores d;

deve ser um engano; provavelmente o que se deseja

SELECT d.* FROM distribuidores d;

em vez da juno sem restries

SELECT distribuidores.* FROM distribuidores d, distribuidores distribuidores;

que obtido na realidade. Para ajudar a detectar este tipo de engano, o PostgreSQL 7.1, e posteriores, advertem
quando um FROM implcito usado em uma consulta que tambm possui uma clusula FROM explcita.

12

SELECT
A funcionalidade de funo de tabela uma extenso do PostgreSQL.

SQL92
Clusula SELECT
No padro SQL92, a palavra chave opcional AS somente informativa podendo ser omitida sem afetar o significado. O analisador (parser) do PostgreSQL requer a presena desta palavra chave para mudar o nome das colunas
da sada, porque a funcionalidade de extensibilidade de tipo ocasiona ambigidades no analisador dentro deste
contexto. Entretanto, AS opcional nos itens da clusula FROM.
A frase DISTINCT ON no faz parte do SQL92, assim como LIMIT e OFFSET.
No SQL92, uma clusula ORDER BY pode utilizar somente os nomes das colunas do resultado, ou nmeros,
enquanto uma clusula GROUP BY pode utilizar somente os nomes das colunas da entrada. O PostgreSQL
estende cada uma destas clusulas para permitir a outra escolha tambm (mas utiliza a interpretao padro no
caso de ambigidade). O PostgreSQL tambm permite que as duas clusulas especifiquem expresses arbitrrias.
Observe que os nomes que aparecem em uma expresso so sempre obtidos a partir dos nomes das colunas da
entrada, e no dos nomes das colunas do resultado.

Clusulas UNION/INTERSECT/EXCEPT
A sintaxe do SQL92 para UNION/INTERSECT/EXCEPT permite a adio da opo CORRESPONDING BY:

tabela_consulta UNION [ALL]

[CORRESPONDING [BY (nome_coluna [,...])]]
tabela_consulta

A clusula CORRESPONDING BY no suportada pelo PostgreSQL.

13

SELECT INTO
Nome
SELECT INTO cria uma nova tabela a partir do resultado de uma consulta

Sinopse
SELECT [ ALL | DISTINCT [ ON ( expresso [, ...] ) ] ]
* | expresso [ AS nome_de_sada ] [, ...]
INTO [ TEMPORARY | TEMP ] [ TABLE ] nova_tabela
[ FROM item_de [, ...] ]
[ WHERE condio ]
[ GROUP BY expresso [, ...] ]
[ HAVING condio [, ...] ]
[ { UNION | INTERSECT | EXCEPT } [ ALL ] select ]
[ ORDER BY expresso [ ASC | DESC | USING operador ] [, ...] ]
[ LIMIT { contador | ALL } ]
[ OFFSET incio ]
[ FOR UPDATE [ OF nome_da_tabela [, ...] ] ]

Entradas
TEMPORARY
TEMP
Se for especificado a tabela criada como sendo uma tabela temporria. Consulte o comando CREATE
TABLE para obter detalhes.
nova_tabela
O nome (opcionalmente qualificado pelo esquema) da tabela a ser criada.

Todas as outras entradas esto descritas detalhadamente no comando SELECT.

Sadas
Consulte os comandos CREATE TABLE e SELECT para obter um sumrio das mensagens de sada possveis.

Descrio
O comando SELECT INTO cria uma nova tabela e a preenche com os dados produzidos por uma consulta. Os
dados no so retornados para o cliente, como acontece em um comando SELECT normal. As colunas da nova
tabela possuem os mesmos nomes e tipos de dado das colunas de sada do comando SELECT.
Nota: O comando CREATE TABLE AS funcionalmente equivalente ao comando SELECT INTO. A sintaxe
CREATE TABLE AS recomendada porque SELECT INTO no padro. Alm disso, esta forma do SELECT

SELECT INTO
INTO no est disponvel no PL/pgSQL nem no ecpg porque os dois interpretam a clusula INTO de forma
diferente.

Compatibilidade
O SQL92 utiliza o comando SELECT ... INTO para representar a seleo de valores para dentro de variveis
escalares do programa hospedeiro, em vez de criar uma nova tabela. Esta a mesma utilizao encontrada no
PL/pgSQL e no ecpg. A utilizao no PostgreSQL do comando SELECT INTO para representar a criao de uma
tabela histrica. melhor utilizar o comando CREATE TABLE AS para esta finalidade nos programas novos (O
comando CREATE TABLE AS tambm no padro, mas tem menos chance de causar confuso).

SET
Nome
SET muda um parmetro de tempo de execuo

Sinopse
SET [ SESSION | LOCAL ] varivel { TO | = } { valor | valor | DEFAULT }
SET [ SESSION | LOCAL ] TIME ZONE { zona_horria | LOCAL | DEFAULT }

Entradas
SESSION

Especifica que o comando vale para a sesso corrente. (Este o padro se nem SESSION ou LOCAL forem
declarados.)
LOCAL

Especifica que o comando vale apenas para a transao corrente. Aps o COMMIT ou ROLLBACK passa a valer
novamente a definio em nvel de sesso. Observe que SET LOCAL parece no ter nenhum efeito se for
executado fora de um bloco BEGIN, uma vez que a transao termina imediatamente.
varivel
Um parmetro de tempo de execuo cujo valor pode ser mudado.
valor
O novo valor do parmetro. Pode ser usado DEFAULT para especificar a atribuio do valor padro do
parmetro. Listas de cadeias de caracteres so permitidas, mas construes mais complexas podem precisar
estar entre apstrofos () ou entre aspas (").

Descrio
O comando SET altera os parmetros de configurao de tempo de execuo. Muitos parmetros de tempo de
execuo descritos no Guia do Administrador podem ser mudados durante a execuo pelo comando SET (Mas
alguns requerem privilgio de superusurio para serem mudados, e outros no podem ser mudados aps a inicializao do servidor ou o incio da sesso). Observe que o comando SET afeta apenas os valores utilizados na
sesso corrente.
Se o comando SET ou SET SESSION for executado dentro de uma transao que for abortada mais tarde, os
efeitos do comando SET iro desaparecer quando a transao for desfeita (Este comportamento representa uma
mudana do PostgreSQL com relao s verses anteriores a 7.3, onde os efeitos do SET no eram desfeitos aps
um erro). Uma vez que a transao envoltria seja efetivada, os efeitos persistem at o final da sesso, a menos
que seja redefinido por outro comando SET.

SET
Os efeitos do comando SET LOCAL duram apenas at o final da transao corrente, seja esta efetivada ou no.
Um caso especial ocorre quando o comando SET seguido por um comando SET LOCAL dentro da mesma
transao: o valor do comando SET LOCAL fica valendo at o final da transao, mas depois disso (se a transao
for efetivada) o valor do comando SET fica valendo.
Mesmo quando o autocommit est definido como off, o comando SET no inicia um novo bloco de transao.
Consulte a seo sobre autocommit no Guia do Administrador para obter detalhes.
Abaixo est mostrados detalhes adicionais sobre alguns parmetros que podem ser definidos:
DATESTYLE

Escolhe o estilo de representao da data/hora. Duas definies separadas esto envolvidas: o padro de sada
para data/hora, e a interpretao da entrada ambgua.
Estes so os estilos de sada para data/hora:
ISO

Usa o estilo ISO 8601 para data e hora (YYYY-MM-DD HH:MM:SS). Este o padro.
SQL

Usa o estilo Oracle/Ingres para data e hora. Observe que este estilo no tem relao com o SQL (que
define o estilo ISO 8601). O nome desta opo apenas um acidente histrico.
PostgreSQL

Usa o formato tradicional do PostgreSQL.

German

Usa dd.mm.yyyy para representar as datas numricas.

As duas opes a seguir determinam o subestilo dos formatos de sada SQL e PostgreSQL, e a interpretao preferencial para a entrada de data ambgua.
European

Usa dd/mm/yyyy para representar as datas numricas.

NonEuropean
US

Usa mm/dd/yyyy para representar as datas numricas.

O valor para SET DATESTYLE pode ser um da primeira relao (estilos de sada), ou um da segunda relao
(subestilos), ou um de cada separados por vrgula.
SET DATESTYLE tem efeito sobre a interpretao da entrada e fornece vrios formatos padro para a sada.

Para os aplicativos que necessitam de formatos diferentes, ou de um controle mais rgido sobre a entrada ou
a sada, deve ser levado em conta a utilizao da famlia de funes to_char.
Existem vrias formas obsoletas de se definir o estilo da data alm dos mtodos normais de definio usando
o comando SET ou a entrada no arquivo de configurao:
Setting the postmasters PGDATESTYLE environment variable. (This will be overridden by any of the other
methods.)

SET
Running postmaster using the option -o -e to set dates to the European convention. (This overrides
environment variables and configuration-file entries.)
Setting the clients PGDATESTYLE environment variable. If PGDATESTYLE is set in the frontend environment of a client based on libpq, libpq will automatically set DATESTYLE to the value of PGDATESTYLE
during connection start-up. This is equivalent to a manually issued SET DATESTYLE.

NAMES
SET NAMES is an alias for SET CLIENT_ENCODING.

SEED
Define a semente interna para o gerador de nmeros randmicos.
valor
O valor da semente a ser usada pela funo random. Os valores permitidos so nmeros de ponto
flutuante entre 0 e 1, os quais so ento multiplicados por 231-1.

A semente tambm pode ser definida atravs da funo setseed do SQL:

SELECT setseed(valor);

SERVER_ENCODING
Mostra a codificao multibyte do servidor. (Atualmente este parmetro pode ser exibido mas no pode ser
definido, uma vez que a codificao determinada em tempo de initdb.)
TIME ZONE
TIMEZONE
Define a zona horria padro para a sesso. Os argumentos podem ser uma constante SQL de intervalo de
tempo, uma constante inteira ou de preciso dupla, ou uma cadeia de caracteres representando uma zona
horria reconhecida pelo sistema operacional hospedeiro.
Abaixo esto mostrados alguns valores tpicos para definir a zona horria:
PST8PDT
Define a zona horria para Berkeley, Califrnia.
Portugal
Define a zona horria para Portugal.
Europe/Rome
Define a zona horria para a Itlia.
7
Define a zona horria para 7 horas de deslocamento oeste do GMT (equivalente PDT).
INTERVAL 08:00 HOUR TO MINUTE
Define a zona horria para 8 horas de deslocamento oeste do GMT (equivalente PST).

SET
LOCAL
DEFAULT
Define como sendo a zona horria local (a zona horria do sistema operacional).

Os nomes disponveis para a zona horria dependem do sistema operacional. Por exemplo, no Linux o diretrio /usr/share/zoneinfo contm o banco de dados de zonas horrias; os nomes dos arquivos deste
diretrio podem ser usados como parmetro para este comando.
Se uma zona horria invlida for especificada, a zona horria torna-se GMT (na maioria dos sistemas).
Se a varivel de ambiente PGTZ tiver valor definido numa estao do cliente baseada na libpq, automaticamente a libpq executa SET TIMEZONE para o valor de PGTZ durante a inicializao da conexo.

Use o comando SHOW para mostrar o valor correntes definido para um parmetro.

Diagnsticos
SET

Mensagem retornada se o comando for executado com sucesso.

ERROR: nome is not a valid option name

O parmetro que se tentou definir no existe.

ERROR: nome: permission denied

necessrio ser um superusurio para alterar certas definies.

ERROR: nome cannot be changed after server start

Certos parmetros no podem ser mudados aps o servidor ter sido inicializado.

Exemplos
Definir o estilo de data tradicional do PostgreSQL com convenes europias:
SET DATESTYLE TO PostgreSQL,European;

Definir a zona horria para Berkeley, Califrnia, usando apstrofos para preservar os atributos maisculos do
nome da zona horria (note que o formato da data/hora PostgreSQL neste exemplo):
SET TIME ZONE PST8PDT;
SELECT CURRENT_TIMESTAMP AS hoje;
hoje

SET
-----------------------------------Tue Feb 26 07:32:21.42834 2002 PST

Definir a zona horria para a Itlia (observe que necessrio o uso de apstrofos para tratar os caracteres especiais):
SET TIME ZONE Europe/Rome;
SELECT CURRENT_TIMESTAMP AS hoje;
hoje
------------------------------2002-10-08 05:39:35.008271+02

Compatibilidade
SQL92
SET TIME ZONE estende a sintaxe definida no SQL9x. O SQL9x permite somente deslocamentos numricos para

a zona horria enquanto o PostgreSQL tambm permite a utilizao de cadeias de caracteres para especificar a
zona horria. Todas as outras funcionalidades do comando SET so extenses do PostgreSQL.

See Also
The function set_config provides the equivalent capability. See Miscellaneous Functions in the PostgreSQL
Users Guide.

SET CONSTRAINTS
Nome
SET CONSTRAINTS especifica o modo de restrio da transao corrente

Sinopse
SET CONSTRAINTS { ALL | restrio [, ...] } { DEFERRED | IMMEDIATE }

Descrio
O comando SET CONSTRAINTS especifica o comportamento da avaliao da restrio na transao corrente.
No modo IMMEDIATE (imediato), as restries so verificadas ao final de cada comando. No modo DEFERRED
(postergado), as restries no so verificadas at a efetivao (commit) da transao.
Nota: Este comando somente altera o comportamento das restries dentro da transao corrente. Portanto,
se este comando for executado fora de um bloco de transao explcito (tal como um que comece por BEGIN),
parecer que no produziu nenhum efeito. Se for desejado mudar o comportamento das restries sem haver
a necessidade de executar o comando SET CONSTRAINTS em todas as transaes, deve ser especificado
INITIALLY DEFERRED ou INITIALLY IMMEDIATE quando a restrio for criada.

Quando se muda o modo da restrio para que se torne IMMEDIATE , o novo modo de restrio produz efeito
retroativo: todos os dados modificados que deveriam ser verificados no final da transao (ao se usar DEFERRED)
so verificados durante a execuo do comando SET CONSTRAINTS.
Na hora da criao, sempre dada restrio uma destas trs caractersticas: INITIALLY DEFERRED (inicialmente postergada), INITIALLY IMMEDIATE DEFERRABLE (inicialmente imediata, postergvel), ou INITIALLY
IMMEDIATE NOT DEFERRABLE (inicialmente imediata, no postergvel). A terceira classe no afetada pelo
comando SET CONSTRAINTS.
Atualmente, somente as restries de chave estrangeira so afetadas por este comando. As restries de verificao
(check) e de unicidade so sempre inicialmente imediata no postergvel.

Compatibilidade
SQL92, SQL99
SET CONSTRAINTS definida no SQL92 e no SQL99. A implementao no PostgreSQL est em conformidade com o comportamento definido no padro, exceto com relao limitao do PostgreSQL de que SET
CONSTRAINTS no pode ser usado em restries de verificao e de unicidade.

SET SESSION AUTHORIZATION

Nome
SET SESSION AUTHORIZATION define o identificador do usurio da sesso e o identificador do usurio
corrente, da sesso corrente.

Sinopse
SET [ SESSION | LOCAL ] SESSION AUTHORIZATION nome_do_usurio
SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT
RESET SESSION AUTHORIZATION

Descrio
Este comando define o identificador do usurio da sesso e o identificador do usurio corrente, do contexto da
sesso SQL corrente, como sendo nome_do_usurio. The user name may be written as either an identifier or
a string literal. The session user identifier is valid for the duration of a connection; for example, it is possible to
temporarily become an unprivileged user and later switch back to become a superuser.
O identificador do usurio da sesso inicialmente definido como sendo o (possivelmente autenticado) nome
do usurio fornecido pelo cliente. O identificador do usurio corrente normalmente igual ao identificador do
usurio da sesso, mas pode mudar temporariamente no contexto das funes setuid e de outros mecanismos
semelhantes. O identificador do usurio corrente relevante para a verificao das permisses.
O identificador do usurio da sesso pode ser mudado apenas se o usurio inicial da sesso (o usurio autenticado) possuir o privilgio de superusurio. Seno, o comando aceito somente se especificar o nome do usurio
autenticado.
Os modificadores SESSION e LOCAL atuam da mesma maneira que atuam para o comando SET comum.
As formas DEFAULT e RESET redefinem os identificadores da sesso e do usurio corrente como sendo o nome
do usurio autenticado originalmente. Esta forma sempre aceita.

Exemplos
SELECT SESSION_USER, CURRENT_USER;
current_user | session_user
--------------+-------------pedro
| pedro
SET SESSION AUTHORIZATION paulo;
SELECT SESSION_USER, CURRENT_USER;
current_user | session_user
--------------+-------------paulo
| paulo

SET SESSION AUTHORIZATION

Compatibilidade
SQL99
O SQL99 permite que algumas outras expresses apaream no lugar de nome_do_usurio, as quais no so
importantes na prtica. O PostgreSQL permite a sintaxe do identificador ("nome_do_usurio"), que o SQL
no permite. O SQL no permite a execuo deste comando durante uma transao; O PostgreSQL no faz esta
restrio porque no h motivo para faz-la. O padro deixa os privilgios necessrios para executar este comando
por conta da implementao.

SET TRANSACTION
Nome
SET TRANSACTION define as caractersticas da transao corrente

Sinopse
SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE }
SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL
{ READ COMMITTED | SERIALIZABLE }

Descrio
Este comando define o nvel de isolamento da transao. O comando SET TRANSACTION define as caractersticas
para a transao SQL corrente, no possuindo qualquer efeito sobre nenhuma transao posterior. Este comando
no pode ser utilizado aps a primeira consulta ou declarao que modifique os dados (SELECT, INSERT, DELETE,
UPDATE, FETCH, COPY) da transao tiver sido executada. O comando SET SESSION CHARACTERISTICS define
o nvel de isolamento padro para todas as transaes da sesso. O comando SET TRANSACTION pode substitui-lo
para uma transao individual.
O nvel de isolamento de uma transao determina quais dados a transao pode enxergar quando outras
transaes esto processando ao mesmo tempo.
READ COMMITTED
Uma declarao enxerga apenas as linhas efetivadas (commit) antes do incio da sua execuo. Este o
padro.
SERIALIZABLE
A transao corrente enxerga apenas as linhas efetivadas (commit) antes da primeira consulta ou declarao
de modificao de dados ter sido executada nesta transao.
Dica: Intuitivamente serializvel significa que, duas transaes concorrentes deixam o banco de dados no mesmo estado que estas duas transaes, executadas uma aps a outra em qualquer ordem,
deixaria.

Notas
O nvel de isolamento padro da transao tambm pode ser definido pelo comando
SET default_transaction_isolation = valor

no arquivo de configurao. Consulte o Guia do Administrador para obter mais informaes.

SET TRANSACTION

Compatibilidade
SQL92, SQL99
SERIALIZABLE o nvel de isolamento padro do SQL. O PostgreSQL no possui os nveis de isolamento READ
UNCOMMITTED e REPEATABLE READ. Devido ao controle de concorrncia multi-verso, o nvel SERIALIZABLE

no verdadeiramente serializvel. Consulte o Guia do Usurio para obter mais informaes.

No SQL existem outras duas caractersticas da transao que podem ser definidas com este comando: se a
transao de leitura apenas e o tamanho da rea de diagnsticos. Nenhum destes conceitos suportado pelo
PostgreSQL.

SHOW
Nome
SHOW mostra o valor de um parmetro de tempo de execuo

Sinopse
SHOW nome

SHOW ALL

Entradas
nome
O nome de um parmetro de tempo de execuo. Consulte o comando SET para ver a relao.
ALL
Mostra todos os parmetros da sesso corrente.

Descrio
O comando SHOW mostra o valor corrente de um parmetro de tempo de execuo. Estas variveis podem ser
definidas pelo comando SET, editando-se o arquivo postgresql.conf, atravs da varivel de ambiente
PGOPTIONS ou atravs de uma opo de linha de comando ao iniciar o postmaster.
Mesmo quando o autocommit (autoefetivao) est definido como off, o comando SHOW no inicia um novo
bloco de transao. Veja a seo sobre autocommit no Guia do Administrador para obter detalhes.

Diagnsticos
ERROR: Option nome is not recognized

Mensagem retornada quando nome no corresponde a um parmetro existente.

SHOW

Exemplos
Mostrar o valor corrente de DateStyle (estilo da data):
SHOW DateStyle;
DateStyle
--------------------------------------ISO with US (NonEuropean) conventions
(1 row)

Mostrar o estado corrente do otimizador gentico (geqo):

SHOW GEQO;
geqo
-----on
(1 row)

Mostrar todas as definies:

SHOW ALL;
name
|
setting
-------------------------------+--------------------------------------australian_timezones
| off
authentication_timeout
| 60
checkpoint_segments
| 3
.
.
.
wal_debug
| 0
wal_sync_method
| fdatasync
(94 rows)

Compatibilidade
O comando SHOW uma extenso do PostgreSQL linguagem.

Consulte tambm
A funo current_setting produz uma sada semelhante. Veja Funes Diversas (Miscellaneous
Functions) no Guia do Usurio do PostgreSQL.

START TRANSACTION
Nome
START TRANSACTION inicia um bloco de transao

Sinopse
START TRANSACTION [ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ]

Entradas
Nenhuma.

Sadas
START TRANSACTION

Mensagem retornada se o comando for executado com sucesso.

WARNING: BEGIN: already a transaction in progress

Se houver uma transao em andamento no momento em que o comando for executado.

Descrio
Este comando inicia uma nova transao. Se o nvel de isolamento for especificado, a nova transao ter este
nvel de isolamento. Em todos os outros aspectos, o comportamento deste comando idntico ao do comando
BEGIN.

Notas
O nvel de isolamento de uma transao tambm pode ser definido pelo comando SET TRANSACTION. Se nenhum nvel de isolamento for especificado, o nvel de isolamento padro ser usado.

Compatibilidade
SQL99
SERIALIZABLE o nvel de isolamento padro no SQL99, mas geralmente no o padro no PostgreSQL: o
padro definido originalmente READ COMMITTED. O PostgreSQL no fornece os nveis de isolamento READ

START TRANSACTION
UNCOMMITTED e REPEATABLE READ. Devido a ausncia de bloqueio de predicado, o nvel SERIALIZABLE no
verdadeiramente serializvel. Consulte o Guia do Usurio para obter mais informaes.

No SQL99 esta declarao pode especificar duas outras propriedades da nova transao: se a transao apenas de leitura e o tamanho da rea de diagnsticos. Nenhum destes conceitos so suportados atualmente pelo
PostgreSQL.

TRUNCATE
Nome
TRUNCATE esvazia a tabela

Sinopse
TRUNCATE [ TABLE ] nome

Entradas
nome
O nome (opcionalmente qualificado pelo esquema) da tabela a ser truncada.

Sadas
TRUNCATE TABLE

Mensagem retornada se a tabela for truncada com sucesso.

Descrio
O comando TRUNCATE remove rapidamente todas as linhas da tabela. Tem o mesmo efeito do comando DELETE
sem a clusula WHERE, mas como no varre a tabela mais rpido. mais vantajoso para tabelas grandes.
O comando TRUNCATE no pode ser utilizado dentro de um bloco de transao (delimitado por BEGIN/COMMIT),
porque no existe a possibilidade de desfaz-lo.

Utilizao
Truncar a tabela tbl_grande:
TRUNCATE TABLE tbl_grande;

TRUNCATE

Compatibilidade
SQL92
No existe o comando TRUNCATE no SQL92.

UNLISTEN
Nome
UNLISTEN pra de escutar uma notificao

Sinopse
UNLISTEN { nome_notificao | * }

Entradas
nome_notificao
O nome de uma condio de notificao registrada previamente.
*

Todos os registros de escuta atuais deste processo servidor so removidos.

Sadas
UNLISTEN

Constata que o comando foi executado.

Descrio
O comando UNLISTEN utilizado para remover um registro de NOTIFY existente. UNLISTEN cancela
qualquer registro existente da sesso corrente do PostgreSQL para escutar a condio de notificao
nome_notificao. A condio especial * (curinga) cancela todos os registros de escuta da sesso corrente.
O comando NOTIFY contm uma discusso mais extensa da utilizao do comando LISTEN e do comando
NOTIFY.

Notas
O nome_notificao no necessita ser um nome de classe vlido, podendo ser qualquer cadeia de caracteres
vlida como um nome, com at 64 caracteres.
O servidor no reclama quando executado o UNLISTEN para algo que no esteja sendo escutado. Cada processo
servidor executa automaticamente o comando UNLISTEN * ao encerrar sua execuo.

UNLISTEN

Utilizao
Para participar de um registro existente:
LISTEN virtual;
LISTEN
NOTIFY virtual;
NOTIFY
Asynchronous NOTIFY virtual from backend with pid 8448 received

Quando o comando UNLISTEN executado, os comandos NOTIFY posteriores so ignorados:

UNLISTEN virtual;
UNLISTEN
NOTIFY virtual;
NOTIFY
-- notice no NOTIFY event is received

Compatibilidade
SQL92
No existe o comando UNLISTEN no SQL92.

UPDATE
Nome
UPDATE atualiza linhas de uma tabela

Sinopse
UPDATE [ ONLY ] tabela SET coluna = expresso [, ...]
[ FROM lista_de ]
[ WHERE condio ]

Entradas
tabela
O nome (opcionalmente qualificado pelo esquema) de uma tabela existente. Se ONLY for especificado,
somente esta tabela atualizada. Se ONLY no for especificado, a tabela e todas as suas tabelas descendentes (se existirem) so atualizada. Um * pode ser apensado ao nome para indicar que as tabelas descendentes devem ser varridas, mas na verso atual este o comportamento padro. (Nas verses anteriores a
7.1, ONLY era o comportamento padro. O padro pode ser alterado mudando-se a opo de configurao
SQL_INHERITANCE.
coluna
O nome de uma coluna da tabela.
expresso
Uma expresso vlida ou um valor a ser atribudo coluna.
lista_de
Uma extenso no padro do PostgreSQL que permite colunas de outras tabelas aparecerem na condio
WHERE.
condio
Consulte o comando SELECT para obter uma descrio mais detalhada da clusula WHERE.

Sadas
UPDATE #

Mensagem retornada se o comando for executado com sucesso. O # representa o nmero de linhas atualizadas. Se # for 0 ento nenhuma linha foi atualizada.

UPDATE

Descrio
O comando UPDATE muda os valores das colunas especificadas em todas as linhas que satisfazem a condio.
Somente as colunas a serem modificadas devem aparecer na relao de colunas da declarao.
Referncias a matrizes (arrays) utilizam a mesma sintaxe encontrada no comando SELECT. Assim sendo, um
nico elemento de uma matriz, uma faixa de elementos de uma matriz, ou toda uma matriz pode ser substituda
em um nico comando.
necessrio possuir acesso de escrita na tabela para poder modific-la, assim como acesso de leitura em todas as
tabelas mencionadas na condio da clusula WHERE.
Por padro, o comando UPDATE atualiza todas as tuplas da tabela especificada e de suas descendentes. Para
atualizar apenas a tabela referenciada deve ser utilizada a clusula ONLY.

Utilizao
Mudar a palavra Drama por Suspense na coluna tipo:
UPDATE filmes
SET tipo = Suspense
WHERE tipo = Drama;
SELECT *
FROM filmes
WHERE tipo = Drama OR tipo = Suspense;
cod
|
titulo
| did | data_prod |
tipo
| tempo
-------+---------------+-----+------------+----------+------BL101 | The Third Man | 101 | 1949-12-23 | Suspense | 01:44
P_302 | Becket
| 103 | 1964-02-03 | Suspense | 02:28
M_401 | War and Peace | 104 | 1967-02-12 | Suspense | 05:57
T_601 | Yojimbo
| 106 | 1961-06-16 | Suspense | 01:50
DA101 | Das Boot
| 110 | 1981-11-11 | Suspense | 02:29

Compatibilidade
SQL92
O SQL92 define uma sintaxe distinta para a declarao UPDATE na posio do cursor:
UPDATE tabela SET coluna = expresso [, ...]
WHERE CURRENT OF cursor

onde cursor identifica um cursor aberto.

VACUUM
Nome
VACUUM limpa e opcionalmente analisa o banco de dados

Sinopse
VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ tabela ]
VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ tabela [ (coluna [, ...] ) ] ]

Entradas
FULL
Seleciona uma limpeza completa, que pode recuperar mais espao, mas muito mais demorada e bloqueia
a tabela em modo exclusivo.
FREEZE
Seleciona um congelamento agressivo das tuplas.
VERBOSE
Produz um relatrio detalhado da atividade de limpeza de cada tabela.
ANALYZE
Atualiza as estatsticas utilizadas pelo otimizador para determinar o modo mais eficiente de executar uma
consulta.
tabela
O nome (opcionalmente qualificado pelo esquema) da tabela especfica a ser limpa. Por padro todas as
tabelas do banco de dados corrente.
coluna
O nome da coluna especfica a ser analisada. Por padro todas as colunas.

Sadas
VACUUM

O comando terminou.
INFO: --Relation tabela--

O cabealho do relatrio da tabela.

VACUUM
INFO: Pages 98: Changed 25, Reapped 74, Empty 0, New 0; Tup 1000: Vac 3000, Crash
0, UnUsed 0, MinLen 188, MaxLen 188; Re-using: Free/Avail. Space 586952/586952;
EndEmpty/Avail. Pages 0/74. Elapsed 0/0 sec.

A anlise da tabela.
INFO: Index index: Pages 28; Tuples 1000: Deleted 3000. Elapsed 0/0 sec.

A anlise de um ndice da tabela.

Descrio
O comando VACUUM recupera a rea de armazenamento ocupada pelas tuplas excludas. Na operao normal
do PostgreSQL as tuplas que so excludas (DELETE), ou que se tornam obsoletas devido a uma atualizao
(UPDATE), no so fisicamente removidas da tabela; elas permanecem presentes at que o comando VACUUM seja
executado. Portanto, necessrio executar o VACUUM periodicamente, especialmente em tabelas freqentemente
atualizadas.
Sem nenhum parmetro, o VACUUM processa todas as tabelas do banco de dados corrente. Com um parmetro, o
VACUUM processa somente esta tabela.
O comando VACUUM ANALYZE executa o comando VACUUM e depois o comando ANALYZE para cada tabela selecionada. Esta uma forma de combinao adequada para os scripts das rotinas de manuteno. Consulte o
comando ANALYZE para obter mais detalhes sobre o seu processamento.
O comando VACUUM (sem o FULL) simplesmente recupera o espao tornando-o disponvel para ser reutilizado.
Esta forma do comando pode operar em paralelo com a leitura e escrita normal, uma vez que no requer o bloqueio
exclusivo da tabela. O VACUUM FULL executa um processamento mais extenso, incluindo a movimentao das
tuplas atravs de blocos para tentar compactar a tabela para o menor nmero de blocos de disco. Esta forma
muito mais lenta e requer o bloqueio exclusivo de cada tabela para process-la.
O FREEZE uma opo com finalidade especial, que faz as tuplas serem marcadas como congeladas logo que
seja possvel, em vez de aguardar at que sejam bastante velhas. Se for realizado quando no existir nenhuma
outra transao sendo executada no mesmo banco de dados, ento garantido que todas as tuplas do banco de
dados sejam congeladas e no estaro sujeitas aos problemas do recomeo do ID de transao, no importa
quanto tempo o banco de dados for deixado sem executar o VACUUM. O FREEZE no recomendado para uso
rotineiro. Sua nica utilizao esperada em conjunto com a preparao dos bancos de dados de gabarito dos
usurios, ou outros bancos de dados que so unicamente para leitura e no recebero as operaes da rotina de
manuteno VACUUM. Consulte o Guia do Administrador para obter detalhes.

Notas
Recomenda-se que os bancos de dados de produo ativos sejam VACUUM-nizados freqentemente (pelo menos
toda noite), para que sejam removidas as linhas expiradas. Aps incluir ou excluir um grande nmero de linhas,
pode ser uma boa idia executar o comando VACUUM ANALYZE para a tabela afetada. Esta operao vai atualizar
os catlogos do sistema com os resultados de todas as mudanas recentes, permitindo ao otimizador de consultas
do PostgreSQL fazer melhores escolhas ao planejar as consultas dos usurios.
A opo FULL no recomendada para uso rotineiro, mas pode ser til em casos especiais. Um exemplo aps
ter sido removida a maioria das linhas da tabela e deseja-se que a tabela seja fisicamente encolhida para ocupar
menos espao em disco. O comando VACUUM FULL geralmente encolhe mais a tabela do que o comando VACUUM
simples.

VACUUM

Utilizao
Abaixo est mostrado um exemplo da execuo do comando VACUUM em uma tabela do banco de dados
regression:
regression=> VACUUM VERBOSE ANALYZE onek;
INFO: --Relation onek-INFO: Index onek_unique1: Pages 14; Tuples 1000: Deleted 3000.
CPU 0.00s/0.11u sec elapsed 0.12 sec.
INFO: Index onek_unique2: Pages 16; Tuples 1000: Deleted 3000.
CPU 0.00s/0.10u sec elapsed 0.10 sec.
INFO: Index onek_hundred: Pages 13; Tuples 1000: Deleted 3000.
CPU 0.00s/0.10u sec elapsed 0.10 sec.
INFO: Index onek_stringu1: Pages 31; Tuples 1000: Deleted 3000.
CPU 0.01s/0.09u sec elapsed 0.10 sec.
INFO: Removed 3000 tuples in 70 pages.
CPU 0.02s/0.04u sec elapsed 0.07 sec.
INFO: Pages 94: Changed 0, Empty 0; Tup 1000: Vac 3000, Keep 0, UnUsed 0.
Total CPU 0.05s/0.45u sec elapsed 0.59 sec.
INFO: Analyzing onek
VACUUM

Compatibilidade
SQL92
No existe o comando VACUUM no SQL92.

II. Aplicativos para a estao cliente do

PostgreSQL
Esta parte contm informaes de referncia para os aplicativos e utilitrios usados na estao cliente do PostgreSQL. Nem todos os comandos so de uso geral, alguns requerem privilgios especiais para serem executados.
A caracterstica comum destes aplicativos que podem ser executados a partir de qualquer computador, independentemente de onde o servidor de banco de dados esteja instalado.

clusterdb
Nome
clusterdb reagrupa as tabelas de um banco de dados do PostgreSQL

Sinopse
clusterdb [opes_de_conexo...] [--table | -t tabela ] [nome_bd]
clusterdb [opes_de_conexo...] [--all | -a]

Descrio
O clusterdb um utilitrio para reagrupar as tabelas de um banco de dados do PostgreSQL. Encontra as tabelas
que foram anteriormente agrupadas, reagrupando-as novamente usando o mesmo ndice que foi utilizado antes.
As tabelas que nunca foram agrupadas no so tocadas.
O clusterdb um script envoltrio que usa o comando do servidor CLUSTER atravs do terminal interativo do
PostgreSQL psql. No existe diferena efetiva entre agrupar bancos de dados atravs deste ou de outro comando.
O psql deve ser encontrado pelo script e o servidor de banco de dados deve estar executando na mquina de
destino. Tambm se aplicam os padres definidos e as variveis de ambiente disponveis para o psql e para a
biblioteca cliente libpq.
Pode ser necessrio o clusterdb se conectar vrias vezes ao servidor PostgreSQL, solicitando a senha em cada
uma das vezes. conveniente existir o aquivo $HOME/.pgpass neste caso.

Opes
O clusterdb aceita os seguintes argumentos de linha de comando:
-a
--all

Agrupa todos os bancos de dados.

[-d] nome_bd
[--dbname] nome_bd

Especifica o nome do banco de dados a ser agrupado. Se no for especificado e -a (ou --all) no for usado,
o nome do banco de dados obtido a partir da varivel de ambiente PGDATABASE. Se esta varivel no estiver
definida, ento o nome do usurio especificado para a conexo usado.
-e
--echo

Ecoa os comandos que o clusterdb gera e envia para o servidor.

clusterdb
-q
--quiet

No exibe resposta.
-t tabela
--table tabela

Agrupa apenas a tabela.

O clusterdb tambm aceita os seguintes argumentos de linha de comando para os parmetros de conexo:
-h hospedeiro
--host hospedeiro

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p porta
--port porta

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes.
-U nome_do_usurio
--username nome_do_usurio

Nome do usurio para se conectar.

-W
--password

Fora a solicitao da senha.

Diagnsticos
CLUSTER

Tudo correu bem.

clusterdb: Cluster failed.

Aconteceu algum problema. O clusterdb apenas um script envoltrio. Consulte o comando CLUSTER e
o aplicativo psql para obter uma descrio detalhada das mensagens de erro e dos problemas potenciais.
Observe que esta mensagem pode aparecer uma vez para cada tabela agrupada.

clusterdb

Ambiente
PGDATABASE
PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo.

Exemplos
Para agrupar o banco de dados teste:
$ clusterdb teste

Para agrupar apenas a tabela foo no banco de dados chamado xyzzy:

$ clusterdb --table foo xyzzy

Consulte tambm
CLUSTER

createdb
Nome
createdb cria um novo banco de dados do PostgreSQL

Sinopse
createdb [opes...] [nome_bd] [descrio]

Descrio
O createdb cria um banco de dados novo do PostgreSQL.
Normalmente, o usurio que executa este comando se torna o dono do banco de dados. Entretanto, um outro
dono pode ser especificado atravs da opo -O, se este comando for utilizado por um usurio com os privilgios
adequados.
O createdb um script envoltrio que usa o comando SQL CREATE DATABASE atravs do terminal interativo do
PostgreSQL psql. Portanto, no existe nada em especial sobre criar bancos de dados desta ou daquela maneira,
significando que o psql deve ser encontrado pelo script, e que o servidor de banco de dados deve estar executando
na mquina de destino. Tambm se aplicam os padres definidos e as variveis de ambiente disponveis para o
psql e para a biblioteca cliente libpq.

Opes
O createdb aceita os seguintes argumentos de linha de comando:
nome_bd
Especifica o nome do banco de dados a ser criado. O nome deve ser nico entre todos os bancos de dados
do PostgreSQL desta instalao. O padro criar o banco de dados com o mesmo nome do usurio atual do
sistema operacional.
descrio
Especifica, opcionalmente, um comentrio a ser associado com o banco de dados criado.
-D diretrio_de_dados
--location diretrio_de_dados

Especifica o local alternativo de banco de dados. Consulte tambm o aplicativo initlocation.

-e
--echo

Exibe os comandos que o createdb gera e envia para o servidor.

-E codificao
--encoding codificao

Especifica o esquema de codificao de caracteres a ser usado neste banco de dados.

createdb
-O nome_do_usurio
--owner nome_do_usurio

Especifica o usurio que ser o dono do banco de dados.

-q
--quiet

No exibe resposta.
-T gabarito
--template gabarito

Especifica o banco de dados de gabarito, a partir do qual este banco de dados ser gerado.

As opes -D, -E, -O e -T correspondem s opes do comando CREATE DATABASE subjacente; consulte este
comando para obter mais informaes sobre estas opes.
O createdb tambm aceita os seguintes argumentos de linha de comando para os parmetros de conexo:
-h hospedeiro
--host hospedeiro

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p porta
--port porta

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes.
-U nome_do_usurio
--username nome_do_usurio

Nome do usurio para se conectar.

-W
--password

Fora a solicitao da senha.

Diagnsticos
CREATE DATABASE

O banco de dados foi criado com sucesso.

createdb: Database creation failed.

A criao do banco de dados falhou.

createdb
createdb: Comment creation failed. (Database was created.)

O comentrio/descrio do banco de dados no pde ser criado, mas o banco de dados foi criado. Pode ser
usado agora o comando SQL COMMENT ON DATABASE para criar o comentrio.

Se houver uma condio de erro, a mensagem de erro do servidor ser exibida. Consulte o comando CREATE
DATABASE e o aplicativo psql para ver as causas possveis.

Ambiente
PGDATABASE

Se estiver definida, especifica o nome do banco de dados a ser criado, a menos que tenha sido informado na
linha de comando.
PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo. PGUSER tambm determina o nome do banco de dados a ser criado, caso
no seja informado na linha de comando ou atravs de PGDATABASE.

Exemplos
Para criar o banco de dados demo usando o servidor de banco de dados padro:
$ createdb demo
CREATE DATABASE

A resposta a mesma que teria sido recebida se fosse executado o comando SQL CREATE DATABASE.
Para criar o banco de dados demo usando o servidor na mquina eden, a porta 5000, o esquema de codificao
LATIN1 e vendo o comando subjacente:
$ createdb -p 5000 -h eden -E LATIN1 -e demo
CREATE DATABASE "demo" WITH ENCODING = LATIN1
CREATE DATABASE

Consulte tambm
dropdb, CREATE DATABASE

10

createlang
Nome
createlang cria uma nova linguagem procedural do PostgreSQL

Sinopse
createlang [opes_de_conexo...] nome_da_linguagem [nome_bd]
createlang [opes_de_conexo...] --list | -l nome_bd

Descrio
O createlang um utilitrio para adicionar uma nova linguagem de programao a um banco de dados do PostgreSQL. O createlang pode tratar todas as linguagens fornecidas junto com a distribuio padro do PostgreSQL,
mas no as linguagens fornecidas por terceiros.
Embora as linguagens de programao do servidor possam ser adicionadas diretamente usando vrios comandos
SQL, recomenda-se o uso do createlang porque este realiza vrias verificaes, e muito mais fcil de usar.
Consulte o comando CREATE LANGUAGE para obter informaes adicionais.

Opes
O createlang aceita os seguintes argumentos de linha de comando:
nome_da_linguagem
Especifica o nome da linguagem de programao procedural a ser definida.
[-d] nome_bd
[--dbname] nome_bd

Especifica em qual banco de dados a linguagem deve ser adicionada. O padro usar o banco de dados com
o mesmo nome do usurio atual do sistema operacional.
-e
--echo

Exibe os comandos SQL sendo executados.

-l
--list

Exibe a relao das linguagens instaladas no banco de dados de destino (que deve ser especificado).
-L diretrio

Especifica o diretrio onde o interpretador da linguagem deve ser encontrado. Normalmente o diretrio
encontrado automaticamente; esta opo tem por finalidade a depurao.

O createlang tambm aceita os seguintes argumentos de linha de comando para os parmetros de conexo:

11

createlang
-h hospedeiro
--host hospedeiro

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p porta
--port porta

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes.
-U nome_do_usurio
--username nome_do_usurio

Nome do usurio para se conectar.

-W
--password

Fora a solicitao da senha.

Ambiente
PGDATABASE
PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo.

Diagnsticos
A maioria das mensagens de erro so auto-explicativas. Se no for, execute o createlang com a opo --echo
e consulte o comando SQL respectivo para obter detalhes. Consulte tambm o aplicativo psql para ver outras
possibilidades.

Notas
Use o droplang para remover uma linguagem.
O createlang um script envoltrio que chama o psql vrias vezes. Se as coisas estiverem dispostas de uma
maneira que seja requerida uma senha para se conectar, a senha ser solicitada vrias vezes.

Exemplos
Para instalar a linguagem pltcl no banco de dados template1:
$ createlang pltcl template1

12

createlang

Consulte tambm
droplang, CREATE LANGUAGE

13

createuser
Nome
createuser cria uma nova conta de usurio do PostgreSQL

Sinopse
createuser [opes...] [nome_do_usurio]

Descrio
O createuser cria um novo usurio do PostgreSQL. Somente os superusurios (usurios com o usesuper definido
na tabela pg_shadow) podem criar novos usurios do PostgreSQL, portanto o createuser deve ser executado por
algum que possa se conectar como um superusurio do PostgreSQL.
Ser um superusurio tambm implica na capacidade de no ser afetado pelas verificaes de permisso de acesso
do banco de dados, portanto o privilgio de superusurio deve ser concedido criteriosamente.
O createuser um script envoltrio que usa o comando SQL CREATE USER atravs do terminal interativo do
PostgreSQL psql. Portanto, no existe nada em especial sobre criar usurios desta ou daquela maneira, significando que o psql deve ser encontrado pelo script, e que o servidor de banco de dados deve estar executando na
mquina de destino. Tambm se aplicam os padres definidos e as variveis de ambiente disponveis para o psql
e para a biblioteca cliente libpq.

Opes
O createuser aceita os seguintes argumentos na linha de comando:
nome_do_usurio
Especifica o nome do usurio do PostgreSQL a ser criado. Este nome deve ser nico entre todos os usurios
do PostgreSQL.
-a
--adduser

permitido ao novo usurio criar outros usurios (Nota: na verdade isto faz do novo usurio um superusurio. Esta opo no tem um nome apropriado).
-A
--no-adduser

No permitido ao novo usurio criar outros usurios (ou seja, o novo usurio um usurio normal, e no
um superusurio).
-d
--createdb

permitido ao novo usurio criar bancos de dados.

14

createuser
-D
--no-createdb

No permitido ao novo usurio criar bancos de dados.

-e
--echo

Exibe os comandos que o createuser gera e envia para o servidor.

-E
--encrypted

Criptografa a senha do usurio armazenada no banco de dados. Se no for especificado, o padro ser utilizado.
-i uid
--sysid uid

Permite escolher uma identificao do usurio diferente da padro. Embora no seja necessrio, algumas
pessoas gostam.
-N
--unencrypted

No criptografa a senha do usurio armazenada no banco de dados. Se no for especificado, o padro ser
utilizado.
-P
--pwprompt

Se for fornecido, o createuser solicita a senha do novo usurio, no sendo necessrio caso no se pretenda
usar autenticao por senha.
-q
--quiet

No exibe resposta.

Ser solicitado o nome e outras informaes necessrias, se no forem especificadas na linha de comando.
O createuser tambm aceita os seguintes argumentos de linha de comando para os parmetros de conexo:
-h host
--host host

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p porta
--port porta

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes.
-U nome_do_usurio
--username nome_do_usurio

Nome do usurio para se conectar (no o nome do usurio a ser criado)

15

createuser
-W
--password

Fora a solicitao da senha (para se conectar ao servidor, e no a senha do novo usurio).

Ambiente
PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo.

Diagnsticos
CREATE USER

O usurio foi criado com sucesso.

createuser: creation of user "nome_do_usurio" failed

Aconteceu algum erro. O usurio no foi criado.

Se houver uma condio de erro, a mensagem de erro do servidor ser exibida. Consulte o comando CREATE
USER e o aplicativo psql para ver as causas possveis.

Exemplos
Para criar o usurio joel no servidor de banco de dados padro:
$ createuser joel
Is the new user allowed to create databases? (y/n) n
Shall the new user be allowed to create more new users? (y/n) n
CREATE USER

Criar o mesmo usurio joel usando o servidor na mquina eden, porta 5000, evitando o pedido de informaes
e vendo o comando subjacente:
$ createuser -p 5000 -h eden -D -A -e joel
CREATE USER "joel" NOCREATEDB NOCREATEUSER
CREATE USER

16

createuser

Consulte tambm
dropuser, CREATE USER

17

dropdb
Nome
dropdb remove um banco de dados do PostgreSQL

Sinopse
dropdb [opes...] nome_bd

Descrio
O dropdb remove do PostgreSQL um banco de dados existente. Para executar este comando necessrio ser um
superusurio, ou o dono do banco de dados.
O dropdb um script envoltrio que usa o comando SQL DROP DATABASE atravs do terminal interativo do
PostgreSQL psql. Portanto, no existe nada em especial sobre remover bancos de dados desta ou daquela maneira,
significando que o psql deve ser encontrado pelo script, e que o servidor de banco de dados deve estar executando
na mquina de destino. Tambm se aplicam os padres definidos e as variveis de ambiente disponveis para o
psql e para a biblioteca cliente libpq.

Opes
O dropdb aceita os seguintes argumentos de linha de comando:
nome_bd
Especifica o nome do banco de dados a ser removido. O banco de dados deve ser um dos bancos de dados
existentes nesta instalao do PostgreSQL.
-e
--echo

Exibe os comandos que o dropdb gera e envia para o servidor.

-i
--interactive

Solicita a confirmao antes de fazer qualquer operao destrutiva.

-q
--quiet

No exibe resposta.

O createdb tambm aceita os seguintes argumentos de linha de comando para os parmetros de conexo:

18

dropdb
-h hospedeiro
--host hospedeiro

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p porta
--port porta

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes.
-U username
--username username

Nome do usurio para se conectar.

-W
--password

Fora a solicitao da senha.

Diagnsticos
DROP DATABASE

O banco de dados foi removido com sucesso.

dropdb: Database removal failed.

Aconteceu algum erro.

Havendo uma condio de erro, a mensagem de erro do servidor exibida. Consulte o comando DROP
DATABASE e o aplicativo psql para ver as causas possveis.

Ambiente
PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo.

Exemplos
Para remover o banco de dados demo do servidor de banco de dados padro:
$ dropdb demo
DROP DATABASE

19

dropdb

Para remover o banco de dados demo usando o servidor na mquina eden, porta 5000, com confirmao e vendo
o comando utilizado:
$ dropdb -p 5000 -h eden -i -e demo
Database "demo" will be permanently deleted.
Are you sure? (y/n) y
DROP DATABASE "demo"
DROP DATABASE

Consulte tambm
createdb, DROP DATABASE

20

droplang
Nome
droplang remove uma linguagem procedural do PostgreSQL

Sinopse
droplang [opes_de_conexo...] nome_da_linguagem [nome_bd]
droplang [opes_de_conexo...] --list | -l nome_bd

Descrio
O droplang um utilitrio para remover de um banco de dados do PostgreSQL uma linguagem de programao existente. O droplang pode remover qualquer linguagem procedural, mesmo quelas no fornecidas na distribuio
do PostgreSQL.
Embora as linguagens de programao do servidor possam ser removidas diretamente usando vrios comandos
SQL, recomenda-se usar o droplang porque este executa vrias verificaes e muito mais fcil de usar. Consulte
o comando DROP LANGUAGE para obter mais informaes.

Opes
O droplang aceita os seguintes argumentos de linha de comando:
nome_da_linguagem
Especifica o nome da linguagem de programao do servidor a ser removida.
[-d] nome_bd
[--dbname] nome_bd

Especifica de qual banco de dados a linguagem deve ser removida. O padro usar o banco de dados com o
mesmo nome do usurio atual do sistema operacional.
-e
--echo

Exibe os comandos SQL medida que so executados.

-l
--list

Exibe a relao das linguagens instaladas no banco de dados de destino (que deve ser especificado).

O droplang tambm aceita os seguintes argumentos de linha de comando para os parmetros de conexo:

21

droplang
-h host
--host host

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p port
--port port

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes.
-U username
--username username

Nome do usurio para se conectar.

-W
--password

Fora a solicitao da senha.

Ambiente
PGDATABASE
PGHOST
PGPORT
PGUSER

Parmetros de conexo padro.

Diagnsticos
A maioria das mensagens de erro so auto-explicativas. Se no for, execute o droplang com a opo --echo
e consulte o comando SQL respectivo para obter detalhes. Consulte tambm o aplicativo psql para ver outras
possibilidades.

Notes
Use createlang to add a language.

Exemplos
Para remover a linguagem pltcl:
$ droplang pltcl nome_bd

22

droplang

See Also
createlang, DROP LANGUAGE

23

dropuser
Nome
dropuser remove uma conta de usurio do PostgreSQL

Sinopse
dropuser [opes...] [nome_do_usurio]

Descrio
O aplicativo dropuser remove um usurio desta instalao do PostgreSQL, e os bancos de dados que este usurio
possui. Somente os usurios com usesuper definido na tabela pg_shadow podem remover usurios do PostgreSQL.
O dropuser um script envoltrio que usa o comando SQL DROP USER atravs do terminal interativo do PostgreSQL psql. Portanto, no existe nada em especial sobre remover usurios desta ou daquela maneira, significando
que o psql deve ser encontrado pelo script, e que o servidor de banco de dados deve estar executando na mquina
de destino. Tambm se aplicam os padres definidos e as variveis de ambiente disponveis para o psql e para a
biblioteca cliente libpq.

Opes
O dropuser aceita os seguintes argumentos de linha de comando:
nome_do_usurio
Especifica o nome do usurio do PostgreSQL a ser removido. O nome deve existir no PostgreSQL. Ser
solicitado o nome caso no seja fornecido na linha de comando.
-e
--echo

Exibe os comandos que o dropuser gera e envia para o servidor.

-i
--interactive

Solicita a confirmao antes de remover o usurio.

-q
--quiet

No exibe resposta.

O createuser tambm aceita os seguintes argumentos de linha de comando para os parmetros de conexo:

24

dropuser
-h hospedeiro
--host hospedeiro

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p porta
--port porta

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes.
-U nome_do_usurio
--username nome_do_usurio

Nome do usurio que se deseja conectar como (no o usurio a ser removido).
-W
--password

Fora a solicitao da senha (usada para se conectar ao servidor, e no a senha do usurio a ser removido).

Ambiente
PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo.

Diagnsticos
DROP USER

O usurio foi removido com sucesso.

dropuser: deletion of user "nome_do_usurio" failed

Aconteceu algum erro. O usurio no foi removido.

Havendo uma condio de erro, a mensagem de erro do servidor exibida. Consulte o comando DROP USER e o
aplicativo psql para ver as causas possveis.

Exemplos
Para remover o usurio joel do servidor de banco de dados padro:
$ dropuser joel
DROP USER

25

dropuser

Para remover o usurio joel usando o postmaster na mquina eden, porta 5000, com confirmao e vendo o
comando utilizado:
$ dropuser -p 5000 -h eden -i -e joel
User "joel" and any owned databases will be permanently deleted.
Are you sure? (y/n) y
DROP USER "joel"
DROP USER

Consulte tambm
createuser, DROP USER

26

ecpg
Nome
ecpg pr-processador de SQL embutido para a linguagem C

Sinopse
ecpg [opo...] arquivo...

Descrio
O ecpg o pr-processador de SQL embutido para programas C. Converte programas C com comandos SQL
em cdigo C normal, substituindo as chamadas ao SQL por chamadas a funes especiais. Os arquivos de sada
podem ento ser compilados por qualquer compilador C.
O ecpg converte cada arquivo de entrada presente na linha de comando no arquivo C correspondente. De preferncia, os arquivos de entrada devem possuir a extenso .pgc, e neste caso a extenso ser substituda por .c para
construir o nome do arquivo de sada. Se a extenso do arquivo de entrada no for .pgc, ento o nome do arquivo
de sada ser construdo anexando .c ao nome completo do arquivo de entrada. O nome do arquivo de sada pode
ser especificado atravs da opo -o.
Esta pgina de referncia no descreve a linguagem SQL embutida. Consulte o Guia do Programador do PostgreSQL para esta finalidade.

Opes
O ecpg aceita os seguintes argumentos de linha de comando:
-c

Gera automaticamente cdigo C a partir do cdigo SQL. Atualmente funciona para EXEC SQL TYPE.
-D smbolo

Define um smbolo do pr-processador C.

-I caminho_de_incluso

Especifica um caminho de incluso adicional, utilizado para encontrar arquivos especificados atravs
do EXEC SQL INCLUDE. Por padro os seguintes: . (o diretrio atual), /usr/local/include,
o caminho de incluso que foi definido na hora da compilao do PostgreSQL (por padro
/usr/local/pgsql/include) e /usr/include, nesta ordem.
-o arquivo_de_sada

Especifica que o ecpg deve escrever toda a sua sada no arquivo_de_sada.

-t

Ativa a auto-efetivao (auto-commit) das transaes. Neste modo, cada comando automaticamente efetivado, a menos que esteja dentro de um bloco de transao explcito. No modo padro, os comandos s so
efetivados quando o EXEC SQL COMMIT executado.

27

ecpg
-v

Exibe informaes adicionais, incluindo a verso e o caminho de incluso.

---help

Exibe um breve sumrio da utilizao do aplicativo e depois termina.

--version

Exibe a verso e depois termina.

Notas
Ao compilar arquivos com o cdigo C pr-processado, o compilador necessita encontrar os arquivos de cabealho
do ECPG no diretrio de incluso do PostgreSQL. Portanto, necessrio usar a opo -I ao chamar o compilador
(por exemplo, -I/usr/local/pgsql/include).
Os programas escritos em C com SQL embutido necessitam da biblioteca libecpg para a ligao. Pode ser
usado, por exemplo, os sinalizadores -L/usr/local/pgsql/lib -lecpg.
Os diretrios apropriados para a instalao podem ser encontrados utilizando pg_config.

Exemplos
Havendo um arquivo fonte C com SQL embutido chamado prog1.pgc, pode ser gerado um programa executvel
utilizando a seguinte seqncia de comandos:
ecpg prog1.pgc
cc -I/usr/local/pgsql/include -c prog1.c
cc -o prog1 prog1.o -L/usr/local/pgsql/lib -lecpg

Consulte tambm
Guia do Programador do PostgreSQL para obter uma descrio mais detalhada da interface do SQL embutido.

28

pg_config
Nome
pg_config retorna informaes sobre a verso instalada do PostgreSQL

Sinopse
pg_config {--bindir | --includedir | --includedir-server | --libdir | --pkglibdir | --configure | --version}...

Descrio
O utilitrio pg_config exibe os parmetros de configurao da verso do PostgreSQL atualmente instalada. Sua
finalidade , por exemplo, ser usado por pacotes de software que desejem interfacear com o PostgreSQL para
encontrar os arquivos de cabealho e bibliotecas necessrios.

Opes
Para usar o pg_config deve-se fornecer uma ou mais das seguintes opes:
--bindir

Exibe a localizao dos executveis do usurio. Usa-se, por exemplo, para encontrar o programa psql. Normalmente, este tambm o local onde o programa pg_config reside.
--includedir

Exibe a localizao dos arquivos de cabealho da linguagem C das interfaces do cliente.

--includedir-server

Exibe a localizao dos arquivos de cabealho da linguagem C para o servidor.

--libdir

Exibe a localizao das bibliotecas de cdigo objeto.

--pkglibdir

Exibe a localizao dos mdulos carregveis dinamicamente, ou onde o servidor deve procur-los ( Tambm
podem estar instalados neste diretrio outros arquivos de dados dependentes da arquitetura).
--configure

Exibe as opes que foram passadas para o script configure quando o PostgreSQL foi configurado para ser
gerado. Pode ser utilizado para reproduzir uma configurao idntica, ou para descobrir com quais opes o
pacote binrio foi gerado (Entretanto, note que os pacotes binrios geralmente contm modificaes especficas da distribuio).
--version

Exibe a verso do PostgreSQL e termina.

Se mais de uma opo (exceto --version) for fornecida, a informao exibida na mesma ordem, uma por
linha.

29

pg_config

Notas
A opo --includedir-server nova no PostgreSQL 7.2. Nas verses anteriores, os arquivos de incluso
do servidor estavam instalados no mesmo local dos cabealhos dos clientes, que podia ser consultado pelo
--includedir. Para tratar os dois casos, deve-se tentar primeiro a nova opo e testar o status da sada, para
verificar se foi executado com sucesso.
Nas verses anteriores ao PostgreSQL 7.1, antes do comando pg_config existir, no existia um mtodo equivalente para encontrar as informaes de configurao.

Histrico
O utilitrio pg_config apareceu pela primeira vez no PostgreSQL 7.1.

Consulte tambm
Guia do Programador do PostgreSQL

30

pg_dump
Nome
pg_dump extrai um banco de dados do PostgreSQL para um arquivo script ou de exportao

Sinopse
pg_dump [opes...] [nome_bd]

Descrio
O pg_dump um utilitrio para salvar um banco de dados do PostgreSQL em um arquivo script ou de exportao.
Os arquivos script so no formato texto-puro, e contm os comandos SQL necessrios para reconstruir o banco
de dados no estado em que este se encontrava no momento que foi salvo. Para efetuar a restaurao atravs destes
scripts deve ser usado o psql. Estes scripts podem ser usados inclusive para reconstruir o banco de dados em outras
mquinas com outras arquiteturas e, com algumas modificaes, at em outros SGBDR.
Alm do script, existem outros formatos de exportao feitos para serem usados em conjunto com o pg_restore
para reconstruir o banco de dados. Permitem ao pg_restore selecionar o que deve ser restaurado, ou mesmo
mudar a ordem de restaurao dos itens. Estes formatos de exportao tambm so projetados para serem portveis
entre arquiteturas.
O pg_dump salva as informaes necessrias para regerar todos os tipos, funes, tabelas, ndices, agregaes e
operadores definidos pelo usurio. Adicionalmente, todos os dados so salvos no formato texto para que possam
ser prontamente importados, bem como tratados por ferramentas de edio.
Quando usado com um dos formatos de exportao e combinado com o pg_restore, o pg_dump fornece um
mecanismo de exportao e importao flexvel. O pg_dump pode ser usado para exportar todo o banco de dados
e, posteriormente, o pg_restore pode ser usado para examinar o arquivo e/ou selecionar que partes do banco de
dados devem ser importadas. O formato mais flexvel produzido o personalizado (custom, -Fc), que permite
a seleo e a reordenao de todos os itens exportados, sendo comprimido por padro. O formato tar (-Ft) no
comprimido e no permite reordenar os dados durante a importao mas, por outro lado, bastante flexvel; alm
disso, pode ser tratado por outras ferramentas como o tar.
Ao executar o pg_dump deve-se examinar a sada procurando por advertncias (escritas na sada de erro padro),
atento especialmente s limitaes listadas abaixo.
O pg_dump cria cpias de segurana consistentes, mesmo se o banco de dados estiver sendo usado concorrentemente. O pg_dump no bloqueia os outros usurios que porventura estejam acessando o banco de dados (leitura
ou gravao).

Opes
As seguintes opes de linha de comando so utilizadas para controlar o formato de sada:
nome_bd
Especifica o nome do banco de dados a ser exportado. Se no for especificado, a varivel de ambiente
PGDATABASE utilizado. Caso no esteja definida, o nome do usurio especificado na conexo utilizado.

31

pg_dump
-a
--data-only

Exporta somente os dados, no o esquema (definies dos dados).

Esta opo s faz sentido para o formato texto-puro. Para os outros formatos esta opo pode ser especificada
ao se chamar o pg_restore.
-b
--blobs

Exporta os objetos binrios grandes (blobs).

-c
--clean

Gera comandos para excluir (drop) os objetos do banco de dados precedendo os comandos para cri-los.
Esta opo s faz sentido para o formato texto-puro. Para os outros formatos esta opo pode ser especificada
ao se chamar o pg_restore.
-C
--create

Inicia a sada por um comando para criar o prprio banco de dados e se conectar ao banco de dados criado
(Com um script assim, no importa em qual o banco de dados se est conectado antes de executar o script).
Esta opo s faz sentido para o formato texto-puro. Para os outros formatos esta opo pode ser especificada
ao se chamar o pg_restore.
-d
--inserts

Exporta os dados como comandos INSERT (em vez de COPY). Torna a importao muito lenta, mas os
arquivos exportados so mais facilmente portados para outros bancos de dados SQL.
-D
--column-inserts
--attribute-inserts

Exporta os dados como comandos INSERT com nomes explcitos das colunas (INSERT INTO tabela
(coluna, ...) VALUES ...), tornando a importao muito lenta, mas necessrio se for desejado mudar a ordem das colunas.
-f arquivo
--file=arquivo

Envia a sada para o arquivo especificado. Se for omitido, a sada padro usada.
-F formato
--format=formato

Seleciona o formato da sada. O formato pode ser um dos seguintes:

p
Produz um script SQL em um arquivo texto-puro (padro)
t
Exporta um arquivo tar adequado para servir de entrada para o pg_restore. Usando este formato de
exportao pode-se reordenar e/ou excluir elementos do esquema durante a restaurao do banco de
dados. Tambm possvel limitar quais dados so importados durante a restaurao.

32

pg_dump
c
Exporta um arquivo personalizado apropriado para servir de entrada para o pg_restore. Este o formato
mais flexvel porque permite a reordenao da importao dos dados, assim como dos elementos do
esquema. Este formato tambm comprimido por padro.

-i
--ignore-version

Ignora a diferena de verso entre o pg_dump e o servidor de banco de dados.

O pg_dump pode tratar bancos de dados de verses anteriores do PostgreSQL, mas as verses muito antigas no so mais suportadas (atualmente anteriores a 7.0). Esta opo deve ser utilizada se for necessrio
desconsiderar a verificao de verso (mas se o pg_dump falhar, no diga que no foi avisado).
-o
--oids

Exporta os identificadores de objeto (OIDs) para todas as tabelas. Esta opo deve ser usada quando a coluna
OID referenciada de alguma maneira (por exemplo, em uma restrio de chave estrangeira). Caso contrrio
esta opo no deve ser usada.
-O
--no-owner

No gera comandos para definir o mesmo dono do objeto do banco de dados original. Tipicamente, o
pg_dump gera comandos \connect (especfico do psql) para definir o dono dos elementos do esquema.
Consulte tambm as opes -R e -X use-set-session-authorization. Observe que a opo -O no
impede todas as reconexes ao banco de dados, mas somente quelas que so usadas exclusivamente para
acertar o dono.
Esta opo s faz sentido para o formato texto-puro. Para os outros formatos esta opo pode ser especificada
ao se chamar o pg_restore.
-R
--no-reconnect

Probe o pg_dump gerar um script que requeira reconexes com o banco de dados quando for
realizada a importao. Usualmente, um script de importao necessita reconectar vrias vezes como
usurios diferentes para especificar o dono original dos objetos. Esta opo um instrumento bastante
rudimentar, porque faz o pg_dump perder a informao sobre o dono, a menos que seja usada a opo -X
use-set-session-authorization.
Uma das razes possveis para no se desejar a reconexo durante a importao o acesso ao banco de dados
requerer interveno manual (por exemplo, senhas).
Esta opo s faz sentido para o formato texto-puro. Para os outros formatos esta opo pode ser especificada
ao se chamar o pg_restore.
-s
--schema-only

Exporta somente o esquema (definies dos dados), sem os dados.

-S nome_do_usurio
--superuser=nome_do_usurio

Especifica o nome do superusurio a ser utilizado para desativar os gatilhos. Esta opo somente
relevante quando --disable-triggers utilizado. (Normalmente melhor especificar

33

pg_dump
--use-set-session-authorization, e depois executar o script produzido como um superusurio).
-t tabela
--table=tabela

Exporta os dados da tabela apenas.

-v
--verbose

Especifica o modo verboso. Faz com que o pg_dump exiba as mensagens de progresso na sada de erro
padro.
-x
--no-privileges
--no-acl

Impede gerar os privilgios de acessos (comandos GRANT/REVOKE).

-X use-set-session-authorization
--use-set-session-authorization

Normalmente, se o script (modo texto-puro) gerado pelo pg_dump necessita trocar o usurio corrente do
banco de dados (por exemplo, para definir o dono correto do objeto) usado o comando \connect do
psql. Este comando na verdade abre uma nova conexo, o que pode requerer a interveno manual (por
exemplo, senhas). Se for usada a opo -X use-set-session-authorization, ento o pg_dump vai
usar o comando SET SESSION AUTHORIZATION. Embora produza o mesmo efeito, requer que o usurio
que for fazer a importao do banco de dados a partir do script gerado seja um superusurio. Esta opo
substitui a opo -R.
Como o SET SESSION AUTHORIZATION um comando SQL padro, enquanto o \connect somente
funciona no psql, esta opo tambm aumenta a portabilidade terica do script gerado.
Esta opo s faz sentido para o formato texto-puro. Para os outros formatos esta opo pode ser especificada
ao se chamar o pg_restore.
-X disable-triggers
--disable-triggers

Esta opo somente relevante quando criado um arquivo de exportao de dados apenas. Informa ao
pg_dump para incluir comandos que desativam, temporariamente, os gatilhos da tabela de destino enquanto
os dados so recarregados. Deve ser utilizado quando existem verificaes de integridade referencial, ou
outros gatilhos na tabela, que no se deseja utilizar durante a recarga dos dados.
Atualmente, os comandos emitidos para --disable-triggers devem ser executados como um superusurio. Portanto, tambm deve ser fornecido o nome de um superusurio com -S ou, de preferncia, ser
especificado --use-set-session-authorization e depois, com cuidado, executar o script produzido
como um superusurio. Se nenhuma das opes for fornecida, todo o script deve ser executado como um
superusurio.
Esta opo s faz sentido para o formato texto-puro. Para os outros formatos esta opo pode ser especificada
ao se chamar o pg_restore.
-Z 0..9
--compress=0..9

Especifica o nvel de compresso a ser usado nos arquivos com formatos que suportam compresso (atualmente somente o formato personalizado suporta compresso).

34

pg_dump
As seguintes opes de linha de comando controlam os parmetros de conexo com o servidor de banco de dados:

-h hospedeiro
--host=hospedeiro

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p porta
--port=porta

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes. O padro para o nmero da porta 5432, ou o valor da varivel de ambiente PGPORT (se estiver
definida).
-U nome_do_usurio

Nome do usurio para se conectar.

-W

Fora a solicitao da senha. Deve acontecer automaticamente se o servidor requer autenticao por senha.

As formas longas das opes esto presentes apenas em algumas plataformas.

Ambiente
PGDATABASE
PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo.

Diagnsticos
Connection to database template1 failed.
connectDBStart() -- connect() failed: No such file or directory
Is the postmaster running locally
and accepting connections on Unix socket /tmp/.s.PGSQL.5432?

O pg_dump no pde se conectar ao servidor PostgreSQL usando o computador e a porta especificados.

Se esta mensagem for recebida, deve-se garantir que o servidor est executando na mquina especificada e
usando a porta especificada.

35

pg_dump
Nota: O pg_dump executa internamente comandos SELECT. Se houver problema ao executar o pg_dump,
deve-se ter certeza de poder consultar as informaes no banco de dados usando, por exemplo, o psql.

Notas
Se na instalao houver alguma adio local ao banco de dados template1, deve-se ter o cuidado de restaurar
a sada do pg_dump em um banco de dados realmente vazio; de outra forma podem acontecer erros devido
duplicidade de definies dos objetos adicionados. Para criar um banco de dados vazio, sem nenhuma adio
local, deve-se faz-lo partir do template0, e no do template1. Por exemplo:
CREATE DATABASE foo WITH TEMPLATE template0;

O pg_dump possui algumas poucas limitaes:

Ao exportar uma nica tabela, ou no formato texto-puro, o pg_dump no trata objetos grandes. Os objetos
grandes devem ser exportados em sua inteireza usando um dos formatos binrios de exportao.

Ao exportar somente os dados, o pg_dump gera comandos para desativar os gatilhos das tabelas do usurio
antes de inserir os dados, e comandos para reativ-los aps os dados terem sido inseridos. Se a restaurao for
interrompida no meio, os catlogos do sistema podem ficar em um estado errado.

Os membros de arquivos tar esto limitados a um tamanho inferior a 8 GB (esta limitao inerente ao formato
dos arquivos tar). Portanto, este formato no pode ser utilizado se a representao textual da tabela exceder este
tamanho. O tamanho total do arquivo tar, e dos outros formatos de sada, no possui limitao exceto, talvez,
pelo sistema operacional.

Exemplos
Para exportar um banco de dados:
$ pg_dump meu_bd > db.out

Para importar este banco de dados:

$ psql -d database -f db.out

Para exportar um banco de dados chamado meu_bd que contm objetos grandes para um arquivo tar:
$ pg_dump -Ft -b meu_bd > bd.tar

Para importar este banco de dados (com os objetos grandes) para um banco de dados existente chamado novo_bd:
$ pg_restore -d novo_bd bd.tar

36

pg_dump

Histrico
O utilitrio pg_dump apareceu pela primeira vez no Postgres95 verso 0.02. Os formatos de sada no-texto-puro
foram introduzidos no PostgreSQL verso 7.1.

Consulte tambm
pg_dumpall, pg_restore, psql, Guia do Administrador do PostgreSQL

37

pg_dumpall
Nome
pg_dumpall extrai um agrupamento de bancos de dados do PostgreSQL para um arquivo script

Sinopse
pg_dumpall [opes...]

Descrio
O pg_dumpall um utilitrio para exportar (dump) todos os bancos de dados do PostgreSQL para um arquivo
script. O arquivo script contm comandos SQL que podem ser usados como entrada do psql para restaurar os
bancos de dados. Exporta chamando pg_dump para cada banco de dados do PostgreSQL. O pg_dumpall tambm exporta objetos globais que so comuns a todos os bancos de dados (O pg_dump no salva estes objetos).
Atualmente, isto inclui informaes sobre os usurios do banco de dados e os grupos.
Portanto, o pg_dumpall uma soluo integrada para realizar cpias de segurana dos bancos de dados. Mas
observe a limitao: no pode exportar objetos grandes, porque o pg_dump no exporta estes objetos para
arquivos texto. Se existirem bancos de dados contendo objetos grandes, estes devem ser exportados usando um
dos modos no-texto do pg_dump.
Como o pg_dumpall l as tabelas de todos os bancos de dados, muito provavelmente ser necessrio se conectar
como um superusurio para poder gerar a exportao completa. Tambm ser necessrio o privilgio de superusurio para executar o script salvo, para poder criar usurios e grupos, e para poder criar os bancos de dados.
O script SQL escrito na sada padro. Devem ser usados operadores na linha de comando para redirecion-lo
para um arquivo.
Pode ser necessrio o pg_dumpall se conectar vrias vezes ao servidor PostgreSQL, solicitando a senha em cada
uma destas vezes. Neste caso conveniente existir o arquivo $HOME/.pgpass.

Opes
Os seguintes argumentos de linha de comando so utilizados para controlar o formato da sada:
-c
--clean

Gera comandos para excluir (drop) os objetos do banco de dados antes de cri-los.
-d
--inserts

Exporta os dados como comandos INSERT (em vez de COPY). Torna a importao muito lenta, mas os
arquivos exportados so mais facilmente portados para outros SGBDR.

38

pg_dumpall
-D
--column-inserts
--attribute-inserts

Exporta os dados como comandos INSERT com nomes explcitos das colunas (INSERT INTO tabela
(coluna, ...) VALUES ...). Torna a importao muito lenta, mas necessrio se for desejado mudar a
ordem das colunas.
-g
--globals-only

Exporta somente os objetos globais (usurios e grupos), nenhum banco de dados.

-i
--ignore-version

Ignora a diferena de verso entre o pg_dump e o servidor de banco de dados.

O pg_dumpall pode tratar bancos de dados de verses anteriores do PostgreSQL, mas as verses muito
antigas no so mais suportadas (atualmente anteriores a 7.0). Esta opo deve ser utilizada se for necessrio
desconsiderar a verificao de verso (mas se o pg_dumpall falhar, no diga que no foi avisado).
-o
--oids

Exporta os identificadores de objeto (OIDs) para todas as tabelas. Esta opo deve ser usada quando a coluna
OID referenciada de alguma maneira (por exemplo, em uma restrio de chave estrangeira). Caso contrrio,
esta opo no deve ser usada.
-v
--verbose

Especifica o modo verboso. Faz com que o pg_dumpall exiba mensagens de progresso na sada de erro
padro.

Os seguintes argumentos de linha de comando controlam os parmetros de conexo ao banco de dados:

-h hospedeiro
Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix. O padro obtido da varivel de ambiente
PGHOST, se estiver definida, seno tentada uma conexo pelo soquete do domnio Unix.
-p porta
O nmero da porta na qual o servidor est aguardando as conexes. O padro obtido da varivel de ambiente
PGPORT se estiver definida, ou do padro da compilao.
-U nome_do_usurio
Nome do usurio para se conectar.
-W
Fora a solicitao da senha. Deve acontecer automaticamente se o servidor requerer autenticao por senha.

As opes longas somente esto disponveis em algumas plataformas.

39

pg_dumpall

Ambiente
PGHOST
PGPORT
PGUSER

Parmetros padro de conexo.

Notas
Como o pg_dumpall chama o pg_dump internamente, algumas mensagens de diagnsticos se referem ao
pg_dump.
O pg_dumpall necessita se conectar vrias vezes ao servidor PostgreSQL. Se estiver configurado autenticao por
senha, a senha ser solicitada em cada uma destas vezes. Neste caso conveniente criar um arquivo de senha.

Exemplos
Para exportar todos bancos de dados:
$ pg_dumpall > db.out

Para importar estes bancos de dados pode ser usado, por exemplo:
$ psql -f db.out template1

(No importante em qual banco de dados se conectar porque o script criado pelo pg_dumpall contm os comandos apropriados para criar e conectar aos bancos de dados salvos).

Consulte tambm
pg_dump, psql. Check Veja tambm detalhes sobre as possveis condies de erro.

40

pg_restore
Nome
pg_restore restaura um banco de dados do PostgreSQL a partir de um arquivo gerado pelo pg_dump

Sinopse
pg_restore [opes...]

Descrio
O pg_restore um utilitrio para restaurar um banco de dados do PostgreSQL a partir de um arquivo gerado pelo
pg_dump em um dos formatos no-texto-puro. So executados os comandos necessrios para criar novamente
todos os tipos, funes, tabelas, ndices, agregaes e operadores definidos pelo usurio, assim como os dados
das tabelas.
Os arquivos de exportao contm informaes para o pg_restore reconstruir o banco de dados, mas tambm
permitem ao pg_restore selecionar o que deve ser restaurado, ou mesmo reordenar a restaurarao dos itens. Os
arquivos de exportao so projetados para serem portveis entre arquiteturas.
O pg_restore pode operar de dois modos: Se um nome de banco de dados for especificado, o arquivo de exportao
restaurado diretamente no banco de dados. Seno, um script contendo os comandos SQL necessrios para
reconstruir o banco de dados criado (e escrito em um arquivo ou na sada padro), semelhante aos scripts
criados pelo pg_dump no formato texto-puro. Algumas das opes que controlam a criao do script so, portanto,
anlogas s opes do pg_dump.
Obviamente, o pg_restore no pode restaurar informaes que no estejam presentes no arquivo de exportao;
por exemplo, se o arquivo de exportao foi gerado usando a opo exportar dados como INSERT, o pg_restore
no poder importar os dados usando o comando COPY.

Opes
O pg_restore aceita os seguintes argumentos de linha de comando (As formas longas das opes esto disponveis
em algumas plataformas apenas).
nome_do_arquivo_exportado
Especifica a localizao do arquivo de exportao a ser restaurado. Se no for especificado, a entrada padro
usada.
-a
--data-only

Importa somente os dados, no o esquema (definies dos dados).

-c
--clean

Exclui (drop) os objetos do banco de dados antes de cri-los.

41

pg_restore
-C
--create

Cria o banco de dados antes de restaur-lo (Quando esta opo est presente, o banco de dados designado
por -d usado apenas para executar o comando CREATE DATABASE inicial. Todos os dados so restaurados
no banco de dados cujo nome aparece no arquivo de exportao).
-d nome_bd
--dbname=nome_bd

Conecta ao nome_bd e restaura diretamente no banco de dados. Os objetos grandes somente podem ser
restaurados usando uma conexo direta ao banco de dados.
-f arquivo_de_sada
--file=arquivo_de_sada

Especifica o nome do arquivo contendo o script gerado, ou contendo a listagem quando for utilizado com a
opo -l. Por padro a sada padro.
-F formato
--format=formato

Especifica o formato do arquivo de exportao. No necessrio especificar o formato, porque o pg_restore

reconhece o formato automaticamente. Se for especificado, poder ser um dos seguintes:
t
O arquivo de exportao est no formato tar. Este formato de arquivo de exportao permite reordenar
e/ou excluir elementos do esquema durante a importao. Tambm permite limitar quais dados so
carregados durante a importao.
c
O arquivo de exportao est no formato personalizado do pg_dump. Este o formato mais flexvel
porque permite a reordenao da importao dos dados e dos elementos do esquema. Este formato
tambm comprimido por padro.

-i
--ignore-version

Ignora a verificao da verso do banco de dados.

-I nome_do_ndice
--index=nome_do_ndice

Restaura apenas a definio do ndice chamado nome_do_ndice.

-l
--list

Lista o contedo do arquivo de exportao. A sada deste comando pode ser usada com a opo -L para
restringir e reordenar os itens que vo ser restaurados.
-L arquivo_da_listagem
--use-list=arquivo_da_listagem

Restaura apenas os elementos presentes no arquivo_da_listagem, e na ordem em que aparecem neste

arquivo. As linhas podem ser movidas e, tambm, podem virar comentrio colocando-se um ; no seu incio.

42

pg_restore
-N
--orig-order

Restaura os itens na ordem original de exportao. Por padro, o pg_dump ir exportar os itens em uma
ordem conveniente para o pg_dump, e depois salvar o arquivo de exportao em uma ordem de OID modificada. Esta opo substitui a da ordem de OID.
-o
--oid-order

Restaura os itens na ordem de OID. Por padro o pg_dump ir exportar exporta os itens em uma ordem
conveniente para o pg_dump, e depois salvar o arquivo de exportao em uma ordem de OID modificada.
Esta opo impe a estrita ordem de OID.
-O
--no-owner

Impede qualquer tentativa de restabelecer o dono original do objeto. O usurio conectado ao banco de dados
se torna o dono dos objetos.
-P nome_da_funo(tipo_do_argumento [, ...])
--function=nome_da_funo(tipo_do_argumento [, ...])

Especifica o procedimento ou a funo a ser restaurada.

-r
--rearrange

Restaura os itens na ordem modificada de OID. Por padro, o pg_dump ir exportar os itens em uma ordem
conveniente para o pg_dump, e depois salvar o arquivo de exportao em uma ordem de OID modificada. A
maior parte dos objetos restaurada na ordem de OID, mas alguns elementos (por exemplo, regras e ndices)
so restaurados no fim do processo sem respeitar os OIDs. Esta a opo padro.
-R
--no-reconnect

Durante a restaurao do arquivo de exportao, o pg_restore usualmente necessita reconectar ao banco de

dados vria vezes com nomes de usurio diferentes, para definir o dono correto dos objetos criados. Se isto
no for desejvel (por exemplo, se a interveno manual for necessria para cada reconexo), esta opo
probe o pg_restore requisitar reconexes (uma requisio de conexo em modo texto-puro, no conectado
ao banco de dados, feita emitindo o comando \connect do psql). Entretanto, esta opo um instrumento
bastante rudimentar, porque faz o pg_restore perder a informao sobre o dono, a menos que seja usada a
opo -X use-set-session-authorization.
-s
--schema-only

Restaura somente o esquema (definies dos dados), sem os dados. Os valores das seqncias so substitudos.
-S nome_do_superusurio
--superuser=nome_do_superusurio

Especifica o nome do superusurio a ser usado para desativar os gatilhos. Somente relevante quando
--disable-triggers usado.
-t tabela
--table=tabela

Restaura o esquema/dados da tabela apenas.

43

pg_restore
-T gatilho
--trigger=gatilho

Restaura a definio do gatilho apenas.

-v
--verbose

Especifica o modo verboso.

-x
--no-privileges
--no-acl

Impede a restaurao dos privilgios de acesso (comandos GRANT/REVOKE).

-X use-set-session-authorization
--use-set-session-authorization

Normalmente, se para restaurar um arquivo de exportao for necessrio trocar o usurio corrente do banco
de dados (por exemplo, para definir o dono correto do objeto), ento dever ser aberta uma nova conexo
com o banco de dados, o que poder requerer interveno manual (por exemplo, senhas). Se for usada a
opo -X use-set-session-authorization, ento o pg_restore vai usar o comando SET SESSION
AUTHORIZATION. Embora produza o mesmo efeito, requer que o usurio que for fazer a importao do
banco de dados a partir do arquivo de exportao gerado seja um superusurio. Esta opo substitui a opo
-R.
-X disable-triggers
--disable-triggers

Esta opo somente relevante quando ao se realizar uma importao dos dados apenas. Informa ao
pg_restore para incluir comandos que desativam, temporariamente, os gatilhos da tabela de destino
enquanto os dados so recarregados. Deve ser utilizado quando existem verificaes de integridade
referencial, ou outros gatilhos na tabela, que no se deseja utilizar durante a recarga dos dados.
Atualmente, os comandos emitidos para --disable-triggers devem ser executados como um superusurio. Portanto, tambm deve ser fornecido o nome de um superusurio com -S ou, de preferncia, ser
especificado --use-set-session-authorization e executar pg_restore como um superusurio do PostgreSQL.

O pg_restore tambm aceita os seguintes argumentos de linha de comando para os parmetros de conexo:
-h hospedeiro
--host=hospedeiro

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p porta
--port=porta

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes. O padro para o nmero da porta 5432, ou o valor da varivel de ambiente PGPORT (se estiver
definida).
-U nome_do_usurio

Nome do usurio para se conectar.

44

pg_restore
-W

Fora a solicitao da senha. Deve acontecer automaticamente se o servidor requerer autenticao por senha.

Ambiente
PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo.

Diagnsticos
Connection to database template1 failed.
connectDBStart() -- connect() failed: No such file or directory
Is the postmaster running locally
and accepting connections on Unix socket /tmp/.s.PGSQL.5432?

O pg_restore no pde se conectar ao servidor PostgreSQL usando o computador e a porta especificada.

Se esta mensagem for recebida, deve-se garantir que o servidor est processando na mquina especificada
e usando a porta especificada. Se a instalao usa um sistema de autenticao, assegure-se de ter obtido as
credenciais de autenticao necessrias.

Nota: Quando uma conexo direta ao banco de dados especificada atravs da opo -d, o pg_restore
executa internamente os comandos SQL. Se houver problema ao executar o pg_restore, deve-se ter certeza
de poder consultar as informaes no banco de dados usando, por exemplo, o psql.

Notas
Se na instalao houver alguma adio local ao banco de dados template1, deve-se ter o cuidado de restaurar
a sada do pg_restore em um banco de dados realmente vazio; de outra forma podem acontecer erros devido
duplicidade de definies dos objetos adicionados. Para criar um banco de dados vazio, sem nenhuma adio
local, deve-se faz-lo a partir do template0, e no do template1. Por exemplo:
CREATE DATABASE foo WITH TEMPLATE = template0;

As limitaes do pg_restore esto descritas abaixo:

45

pg_restore

Ao se restaurar os dados para tabelas pr-existentes, o pg_restore emite comandos para desativar os gatilhos das
tabelas dos usurios antes de inserir os dados, e comandos para reativ-los aps os dados terem sido inseridos.
Se a restaurao for interrompida no meio, os catlogos do sistema podem ficar em um estado errado.

O pg_restore no restaura objetos grandes para uma nica tabela. Se o arquivo de exportao contm objetos
grandes, ento todos os objetos grandes so restaurados.

Consulte tambm a documentao do pg_dump para obter detalhes sobre as limitaes do pg_dump.

Exemplos
Para exportar um banco de dados:
$ pg_dump meu_bd > bd.out

Para importar este banco de dados:

$ psql -d database -f bd.out

Para exportar um banco de dados chamado meu_bd que contm objetos grandes para um arquivo tar:
$ pg_dump -Ft -b meu_bd > bd.tar

Para importar este banco de dados (com os objetos grandes) para um banco de dados existente chamado bd_novo:
$ pg_restore -d bd_novo bd.tar

Para reordenar os itens do banco de dados, primeiro necesrio exportar a tabela de contedo (ndice) do arquivo
de exportao:
$ pg_restore -l arqexp.file > arqexp.list

O arquivo de listagem consiste do cabealho e de uma linha para cada item, como no exemplo abaixo:
;
; Archive created at Fri Jul 28 22:28:36 2000
;
dbname: birds
;
TOC Entries: 74
;
Compression: 0
;
Dump Version: 1.4-0
;
Format: CUSTOM
;
;
; Selected TOC Entries:
;
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres

46

pg_restore
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old

Ponto-e-vrgula so delimitadores de comentrios, e os nmeros no incio das linhas referem-se aos identificadores
interno do arquivo de exportao atribudos a cada item.
As linhas do arquivo podem ser transformadas em comentrio, excludas e reordenadas. Por exemplo:
10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres

poderia ser usado como entrada para o pg_restore e somente restauraria os itens 10 e 6, nesta ordem.
$ pg_restore -L arqexp.list arqexp.file

Histrico
O utilitrio pg_restore apareceu pela primera vez no PostgreSQL 7.1.

Consulte tambm
pg_dump, pg_dumpall, psql, Guia do Administrador do PostgreSQL

47

psql
Nome
psql terminal interativo do PostgreSQL

Sinopse
psql [opes] [nome_bd [nome_do_usurio]]

Descrio
O psql um cliente do PostgreSQL em modo terminal. Permite digitar os comandos interativamente, envi-los
para o PostgreSQL e ver os resultados. Como alternativa, a entrada pode vir de um arquivo. Adicionalmente,
possui um certo nmero de meta-comandos e diversas funcionalidades semelhantes s da shell para facilitar a
criao de scripts e automatizar um grande nmero de tarefas.

Opes
-a
--echo-all

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 varivel ECHO como all.
-A
--no-align

Muda para o modo de sada no alinhado (Seno, o modo de sada padro ser o alinhado).
-c comando
--command comando

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,
no contm nenhuma funcionalidade especfica do psql), ou ser um nico comando de contrabarra. Portanto,
no podem ser misturados comandos SQL com meta-comandos do psql. Para fazer isto, pode ser enviada a
cadeia de caracteres para o psql conforme mostrado a seguir: echo "\x \\ select * from foo;" |
psql.
-d nome_bd
--dbname nome_bd

Especifica o nome do banco de dados a se conectar. Equivale a especificar nome_bd como o primeiro
argumento no-opo na linha de comando.
-e
--echo-queries

Mostra todos os comandos enviados para o servidor. Equivale a definir a varivel ECHO como queries.

48

psql
-E
--echo-hidden

Exibe o comando real gerado pelo \d e por outros comandos de contrabarra. Pode ser usado caso se deseje
incluir uma funcionalidade similar nos prprios programas. Equivale a definir a varivel ECHO_HIDDEN a
partir do psql.
-f nome_do_arquivo
--file nome_do_arquivo

Usa o arquivo nome_do_arquivo como origem dos comandos, em vez de ler os comandos interativamente. Aps o arquivo ser processado, o psql termina. Sob muitos aspectos equivale ao comando interno
\i.
Se o nome_do_arquivo for - (hfen) a entrada padro lida.
O uso desta opo 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 mensagens de erro
contendo o nmero da linha. Ao se usar esta opo tambm existe uma pequena chance de reduzir a sobrecarga da inicializao. Por outro lado, utilizando o redirecionamento da entrada (em teoria) garante produzir
exatamente a mesma sada que seria produzida se tudo tivesse sido digitado manualmente.
-F separador
--field-separator separador

Usa separador como o separador de campos. Equivale a \pset fieldsep ou ao comando \f.
-h hospedeiro
--host hospedeiro

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/), usado
como sendo o diretrio do soquete do domnio Unix.
-H
--html

Ativa a sada tabular HTML. Equivale a \pset format html ou ao comando \H.
-l
--list

Lista todos os bancos de dados disponveis e depois termina. Outras opes que no sejam de conexo so
ignoradas. Semelhante ao comando interno \list.
-o nome_do_arquivo
--output nome_do_arquivo

Envia a sada de todos os comandos para o arquivo nome_do_arquivo. Equivale ao comando \o.
-p porta
--port porta

Especifica a porta TCP/IP ou, por omisso, a extenso do arquivo de soquete do domnio Unix local, onde
o postmaster est aguardando as conexes. Por padro o valor da varivel de ambiente PGPORT ou, se no
estiver definida, a porta especificada durante a compilao, usualmente 5432.
-P atribuio
--pset atribuio

Permite especificar opes de impresso 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 espao. Portanto, para definir o formato de sada
como LaTeX, deve-se escrever -P format=latex.

49

psql
-q
--quiet

Especifica que o psql deve trabalhar em silncio. Por padro, so exibidas mensagens de boas-vindas e
diversas outras mensagens informativas. Se esta opo for usada, nada disso acontece. til em conjunto
com com a opo -c. Dentro do psql pode-se tambm definir a varivel QUIET para obter o mesmo efeito.
-R separador
--record-separator separador

Usa o separador como separador de registros. Equivale a \pset recordsep.

-s
--single-step

Executa no modo passo-nico, significando que ser solicitada uma confirmao antes de cada comando ser
enviado para o servidor, com a opo de cancelar a execuo. Usado para depurar scripts.
-S
--single-line

Executa no modo linha-nica, onde o caractere de nova-linha termina o comando, como o ponto-e-vrgula
faz.
Nota: Este modo fornecido para queles que insistem em us-lo, mas no se encoraja a sua utilizao.
Em particular, se forem misturados comandos SQL e meta-comandos na mesma linha, a ordem de
execuo nem sempre ser clara para o usurio inexperiente.

-t
--tuples-only

Desativa a impresso dos nomes das colunas e do rodap com o nmero de linhas do resultado, etc...
totalmente equivalente ao meta-comando \t.
-T opes_de_tabela
--table-attr opes_de_tabela

Permite especificar opes a serem colocadas dentro da tag table do HTML. Veja \pset para obter detalhes.
-u

Faz com que o psql solicite o nome do usurio e a senha antes de se conectar ao banco de dados.
Esta opo est obsoleta, porque conceitualmente errada (Solicitar um nome de usurio no padro e
solicitar uma senha porque o servidor requer so duas coisas realmente diferentes). Encoraja-se o uso das
opes -U e -W em seu lugar.
-U nome_do_usurio
--username nome_do_usurio

Conecta-se as banco de dados como o usurio nome_do_usurio em vez do padro ( necessrio ter
permisso para faz-lo, claro).
-v atribuio
--set atribuio
--variable atribuio

Realiza a atribuio de varivel, como o comando interno \set. Observe que necessrio separar o nome
e o valor, se houver, por um sinal de igual na linha de comando. Para remover a definio de uma varivel
omite-se o sinal de igual. Para definir uma varivel sem um valor, usa-se o sinal de igual mas omite-se o valor.

50

psql
Estas atribuies so realizadas durante um estgio bem no princpio da inicializao, portanto as variveis
reservadas para finalidades internas devem ser sobrescritas mais tarde.
-V
--version

Mostra a verso do psql.

-W
--password

Requer que o psql solicite a senha antes de se conectar ao banco de dados. Esta continuar definida por toda
a sesso, mesmo que a conexo ao banco de dados seja mudada com o meta-comando \connect.
Na verso corrente o psql automaticamente solicita a senha, sempre que o servidor requer autenticao
por senha. Uma vez que atualmente isto se baseia em um hack, o reconhecimento automtico pode falhar
misteriosamente e, por isso, existe esta opo para forar a solicitao. Se a solicitao da senha no for feita,
e se o servidor requer autenticao por senha, a tentativa de conexo ir falhar.
-x
--expanded

Ativa o modo formato de linha estendido. Equivale ao comando \x.

-X,
--no-psqlrc

No l o arquivo de inicializao ~/.psqlrc.

-?
--help

Mostra a ajuda para os argumentos de linha de comando do psql.

As opes longas no esto disponveis em todas as plataformas.

Status de sada
O psql retorna: 0 se terminar normalmente; 1 se ocorrer um erro fatal prprio (falta de memria, arquivo no
encontrado); 2 se a conexo com o servidor teve problema e a sesso no interativa; 3 se ocorrer um erro em um
script e a varivel ON_ERROR_STOP estiver definida.

Utilizao
Conexo com o banco de dados
O psql um aplicativo cliente do PostgreSQL comum. Para se conectar a um banco de dados necessrio que se
saiba o nome do banco de dados, o nome da mquina e o nmero da porta do servidor, e o nome de usurio a ser
usado para a conexo. O psql pode ser informado sobre estes parmetros atravs das opes de linha de comando
-d, -h, -p e -U, respectivamente. Se for encontrado um argumento que no pertena a nenhuma opo, este ser
interpretado como o nome do banco de dados (ou o nome do usurio, se o nome do banco de dados for fornecido).
Nem todas estas opes so requeridas, os padres se aplicam. Se for omitido o nome da mquina, ento o psql
se conecta atravs do soquete do domnio Unix ao servidor na mquina local. O nmero padro para a porta
determinado em tempo de compilao. Desde que o servidor de banco de dados use o mesmo padro, no ser
necessrio especificar a porta na maioria dos casos. O nome de usurio padro o nome do usurio do Unix, como

51

psql
tambm o nome do banco de dados padro. Observe que no possvel se conectar a qualquer banco de dados
com qualquer nome de usurio. O administrador de banco de dados informa as permisses de acesso concedidas.
Para evitar a digitao, podem ser definidas as variveis de ambiente PGDATABASE, PGHOST, PGPORT e PGUSER
com os valores apropriados.
Se a conexo no puder ser estabelecida por algum motivo (por exemplo, privilgios insuficientes, o postmaster
no est executando no servidor, etc...), o psql retorna uma mensagem de erro e termina.

Entrada de comandos
No modo normal de operao, 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 7.3.2, 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 usurio pode digitar comandos SQL. Normalmente, as linhas de entrada so enviadas para o servidor
quando o caractere ponto-e-vrgula, que termina o comando, encontrado. Um caractere de fim-de-linha no
termina um comando! Portanto os comandos podem ocupar vrias 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 tambm procura por eventos de notificao assncronos gerados
pelo LISTEN e NOTIFY.

Meta-comandos
Qualquer texto digitado no psql que comece por uma contrabarra (\) (no entre apstrofos, ) um meta-comando
do psql que processado pelo prprio psql. Estes comandos tornam o psql interessante para a administrao e
para scripts. Os meta-comandos so 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 so separados das letras do comando, e entre si, por qualquer nmero de caracteres
de espao.
Para incluir caracteres de espao em um argumento deve-se coloc-los entre apstrofos (). Para incluir um
apstrofo neste tipo de argumento, deve-se preced-lo por uma contrabarra. Qualquer texto entre apstrofos
est sujeito s substituies no estilo C para o \n (nova-linha), \t (tabulao), \dgitos, \0dgitos e
\0xdgitos (o caractere com o cdigo decimal, octal ou hexadecimal informado).
Se o argumento (no entre apstrofos) comear por dois-pontos (:), este ser considerado como sendo uma
varivel e o valor desta varivel ser usado como o argumento.
Os argumentos entre crases () so considerados como sendo uma linha de comando a ser passada para a
shell. A sada do comando (com o caractere de nova-linha final removido) usada como o valor do argumento.
As seqncias de escape (\) acima tambm se aplicam s crases.

52

psql
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 relao s aspas ("): um identificador que no esteja
entre aspas convertido para letras minsculas, enquanto os espaos em branco dentro das aspas so includos
nos argumentos.
A leitura dos argumentos termina quando outra contrabarra (no entre apstrofos) encontrada. Esta considerada como sendo o incio de um novo meta-comando. A seqncia 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
prosseguir depois do fim da linha.
Os seguintes meta-comandos esto definidos:
\a

Se o formato atual de sada da tabela for desalinhado, muda para alinhado. Se no for desalinhado, define
como desalinhado. Este comando mantido para compatibilidade com as verses anteriores. Veja o \pset
para uma soluo geral.
\cd [nome_do_diretrio]

Muda o diretrio de trabalho corrente para nome_do_diretrio. Sem argumento, muda para o diretrio
home do usurio corrente.
Dica: Para ver o diretrio de trabalho corrente use \!pwd.

\C [ ttulo ]

Define o ttulo de qualquer tabela que seja exibida como resultado de uma consulta, ou remove a definio
deste ttulo. Este comando equivalente ao \pset titlettulo (O nome deste comando deriva de caption (ttulo), porque anteriormente s era usado para definir o ttulo de uma tabela em HTML).
\connect (or \c) [ nome_bd [ nome_do_usurio ] ]

Estabelece a conexo para um banco de dados e/ou nome de usurio novo. A conexo anterior fechada. Se
o nome_bd for - (hfen), ento assumido o nome do banco de dados corrente.
Se o nome_do_usurio for omitido, ento o nome do usurio corrente assumido.
Como regra especial, \connect sem nenhum argumento conecta ao banco de dados padro como o usurio
padro (da mesma forma que aconteceria se o psql fosse executado sem argumentos).
Se a tentativa de conexo falhar (nome de usurio errado, acesso negado, etc...), a conexo anterior ser
mantida se, e somente se, o psql estiver no modo interativo. Ao executar um script no interativo, o processamento ser imediatamente interrompido com um erro. Esta distino foi escolhida por ser mais conveniente
para o usurio que digita menos, e para garantir um mecanismo seguro que impea os scripts atuarem acidentalmente no banco de dados errado.
\copy tabela [ ( lista_de_colunas ) ] { from | to } nome_do_arquivo | stdin | stdout
[ with ] [ oids ] [ delimiter [as] caractere ] [ null [as] cadeia_de_caracteres
]

Executa uma cpia pelo cliente. Esta uma operao que executa o comando SQL COPY, 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 o usurio local, e no o servidor, necessita ter acesso
fsico ao arquivo e os privilgios necessrios, e que no h necessidade de privilgio de superusurio.

53

psql
A sintaxe deste comando semelhante sintaxe do comando SQL COPY (Consulte sua descrio para obter
detalhes). Observe que, por causa disto, regras especiais de anlise se aplicam ao comando \copy. Em
particular, as regras de substituio de varivel e de escapes de contrabarra (\) no se aplicam.
Dica: Este modo de operao no to eficiente quanto o comando SQL COPY, porque todos os dados
passam atravs da conexo IP cliente/servidor ou pelo soquete. Para uma grande quantidade de dados,
o outro modo pode ser prefervel.

Nota: Observe a diferena de interpretao da stdin e da stdout entre as cpias feitas pelo cliente e
pelo servidor: na cpia pelo cliente se referem sempre entrada e sada do psql. Na cpia pelo servidor,
stdin vem do mesmo lugar que o comando COPY veio (por exemplo, um script executado com a opo
-f), e a stdout se refere sada do comando (veja o meta-comando \o abaixo).

\copyright

Mostra os termos da distribuio e dos direitos autorais do PostgreSQL.

\d [ padro ]

Para cada relao (tabela, viso, ndice ou seqncia) que corresponde ao padro, mostra todas as colunas,
juntamente com seus tipos e atributos especiais como NOT NULL ou o valor padro, se houver. Os ndices,
restries, regras e gatilhos associados tambm so mostrados, assim como a definio da viso se a relao
for uma viso. (A Correspondncia com o padro definida abaixo).
A forma \d+ do comando idntica, mas todos os comentrios associados s colunas da tabela tambm so
mostrados.
Nota: Se \d for usado sem um argumento padro, torna-se equivalente ao \dtvs mostrando a lista de
todas as tabelas, vises e seqncias. Isto puramente uma medida de convenincia.

\da [ padro ]

Lista todas as funes de agregao disponveis, juntamente com os tipos de dado com que operam. Se
padro (uma expresso regular) for especificado, somente as agregaes correspondentes sero exibidas.
\dd [ padro ]

Mostra a descrio do objetos que correspondem ao pattern, ou todos os objetos visveis se nenhum
argumento for fornecido. Mas nos dois casos, somente os objetos que possuem uma descrio so listados
(Objeto compreende agregaes, funes, operadores, tipos, relaes [tabelas, vises, ndices, seqncias
e objetos grandes], regras e gatilhos). Por exemplo:
=> \dd version
Object descriptions
Schema
| Name
| Object |
Description
------------+---------+----------+--------------------------pg_catalog | version | function | PostgreSQL version string
(1 row)

As descries dos objetos podem ser criadas pelo comando SQL COMMENT ON.
Nota: O PostgreSQL armazena a descrio dos objetos na tabela do sistema pg_description.

54

psql

\dD [ padro ]

Lista todos os domnios disponveis (tipos derivados). Se padro for especificado, somente os domnios
correspondentes sero mostrados.
\df [ padro ]

Lista as funes disponveis, juntamente com o tipo de dado de seus argumentos e do valor retornado. Se
padro for especificado, somente as funes correspondentes sero mostradas. Se a forma \df+ for usada,
informaes adicionais sobre cada funo, incluindo a linguagem e a descrio, so mostradas.
Nota: Para reduzir a confuso, \df no mostra as funes com tipo de dado I/O. Isto implementado
ignorando-se as funes que recebem ou retornam o tipo cstring.

\distvS [ padro ]

Este no o verdadeiro nome do comando: As letras i, s, t, v, S correspondem ao ndice, seqncia, tabela,

viso e tabela do sistema, respectivamente. Pode-se especificar qualquer uma ou todas as 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 os objetos que no so do sistema so mostrados. Se o caractere + for
anexado ao nome do comando, cada objeto listado juntamente com sua descrio associada, se houver.
Se o padro for especificado, somente os objetos cujos nomes correspondem ao padro so listados.
\dl

Este um sinnimo para \lo_list, que mostra a lista dos objetos grandes.
\do [ padro ]

Lista os operadores disponveis juntamente com o tipo de seus operandos e do valor retornado. Se padro
for especificado, somente os operadores cujos nomes correspondem ao padro sero listados.
\dp [ padro ]

Produz uma lista de todas as tabelas disponveis juntamente com duas permisses de acesso associadas. Se
padro for especificado, somente as tabelas cujos nomes correspondem ao padro so listadas.
Os comandos GRANT e REVOKE so utilizados para definir permisses de acesso. Consulte o comando
GRANT para obter mais informaes.
\dT [ padro ]

Lista todos os tipos de dado, ou somente queles que correspondem ao padro. A forma \dT+ do comando
mostra informaes extras.
\du [ padro ]

Lista todos os usurios do banco de dados, ou somente queles que correspondem ao padro.
\edit (ou \e) [ nome_do_arquivo ]

Se o nome_do_arquivo for especificado, o arquivo editado; aps o fim da execuo do editor, o contedo do arquivo copiado para o buffer de comando. Se nenhum argumento for fornecido, o buffer de
comando corrente copiado para um arquivo temporrio, que editado de maneira idntica.
O novo buffer de comando ento analisado novamente de acordo com as regras normais do psql, onde
todo o buffer tratado como sendo uma nica linha (Portanto, no 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-vrgula
ser executado imediatamente, seno apenas permanece aguardando no buffer de comando.

55

psql
Dica: O psql procura nas variveis de ambiente PSQL_EDITOR, EDITOR e VISUAL (nesta ordem) o editor
a ser usado. Se nenhuma delas estiver definida, ento /bin/vi usado.

\echo texto [ ... ]

Envia os argumentos para a sada padro, separados por um espao e seguido por um caractere de nova-linha,
podendo ser til para intercalar informaes na sada dos scripts. Por exemplo:
=> \echo date
Tue Oct 26 21:40:57 CEST 1999

Se o primeiro argumento for -n (no entre apstrofos) o caractere de nova-linha final no gerado.
Dica: Se for usado o comando \o para redirecionar a sada dos comandos, talvez se deseje utilizar
\qecho em vez deste comando.

\encoding [ codificao ]

Define a codificao do cliente, se estiver sendo utilizada a codificao multibyte. Sem argumento, este
comando mostra a codificao corrente.
\f [ cadeia_de_caracteres ]

Define o separador de campos para a sada de comando no alinhada. O padro a barra vertical (|). Consulte
tambm o \pset para ver uma forma genrica de definir as opes de sada.
\g [ { nome_do_arquivo | |comando } ]

Envia o buffer de entrada de comando corrente para o servidor e, opcionalmente, salva a sada em
nome_do_arquivo, ou envia a sada para uma outra shell do Unix para executar o comando. Um \g
puro e simples virtualmente igual ao ponto-e-vrgula. Um \g com argumento uma alternativa expressa
para o comando \o.
\help (ou \h) [ comando ]

Fornece ajuda para a sintaxe do comando SQL especificado. Se o comando no for especificado, ento o
psql ir listar todos os comandos para os quais a ajuda de sintaxe est disponvel. Se o comando for um
asterisco (*), ento mostrada a ajuda de sintaxe para todos os comandos SQL.
Nota: Para simplificar a digitao, os comandos constitudos por vrias palavras no necessitam estar
entre apstrofos. Portanto, pode-se digitar \help alter table.

\H

Ativa o formato HTML de sada da consulta. Se o formato HTML j estiver ativado, retorna ao formato de
texto alinhado padro. Este comando existe por compatibilidade e convenincia, mas veja no \pset outras
definies de opes de sada.
\i nome_do_arquivo

Ler a entrada no arquivo nome_do_arquivo, e executar como se tivesse sido digitada pelo teclado.
Nota: Se for desejado ver as linhas na tela enquanto estas so lidas deve-se definir a varivel ECHO
como all.

56

psql
\l (ou \list)

Lista todos os bancos de dados do servidor, assim como seus donos. Deve-se anexar o caractere + ao nome
do comando para listar as descries dos bancos de dados tambm. Se o PostgreSQL foi compilado com
suporte codificao multibyte, o esquema de codificao de cada banco de dados tambm mostrado.
\lo_export loid nome_do_arquivo

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 funo do servidor lo_export, que atua com a permisso do usurio como
o qual o servidor de banco de dados processa, e no sistema de arquivos do servidor.
Dica: Use \lo_list para descobrir os OIDs dos objetos grandes.

Nota: Veja a descrio da varivel LO_TRANSACTION para obter informaes importantes com relao a
todas as operaes com objetos grandes.

\lo_import nome_do_arquivo [ comentrio ]

Armazena o arquivo em um objeto grande do PostgreSQL. Opcionalmente, associa o comentrio 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 razo, recomenda-se associar sempre um comentrio inteligvel a todos
os objetos. Estes podem ser vistos atravs do comando \lo_list.
Observe que este comando sutilmente diferente da funo lo_import do servidor, porque atua como o
usurio local no sistema de arquivos local, em vez do usurio e sistema de arquivos do servidor.
Nota: Veja a descrio da varivel LO_TRANSACTION para obter informaes importantes com relao a
todas as operaes com objetos grandes.

\lo_list

Mostra a lista contendo todos os objetos grandes do PostgreSQL armazenados atualmente no banco de
dados, juntamente com os comentrios fornecidos para os mesmos.
\lo_unlink loid

Exclui do banco de dados o objeto grande com o OID igual a loid.

Dica: Use \lo_list para descobrir os OIDs dos objetos grandes.

Nota: Veja a descrio da varivel LO_TRANSACTION para obter informaes importantes com relao a
todas as operaes com objetos grandes.

57

psql
\o [ {nome_do_arquivo | |comando} ]

Salva os resultados das prximas consultas no arquivo nome_do_arquivo, ou envia os prximos resultados para uma outra shell do Unix para executar o comando. Se nenhum argumento for especificado, a
sada da consulta ser enviada para stdout.
Os resultados das consultas incluem todas as tabelas, respostas dos comandos e as notificaes obtidas do
servidor de banco de dados, assim como a sada dos vrios comandos de contrabarra que consultam o banco
de dados (como o \d), mas no as mensagens de erro.
Dica: Para intercalar texto entre os resultados das consultas usa-se \qecho.

\p

Envia o buffer de comando corrente para a sada padro.

\pset parmetro [ valor ]

Este comando define opes que afetam a sada das tabelas de resultado das consultas. O parmetro indica
qual opo ser definida. A semntica do valor depende do parmetro.
As opes ajustveis de exibio so:
format

Define o formato de sada como unaligned (no alinhado), aligned (alinhado), html ou latex.
Abreviaes nicas so 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 sada que sirva de entrada para outro
programa (separada por tabulao, por vrgula, etc...). O modo Aligned a sada de texto padro,
inteligvel e agradavelmente formatada. Os modos HTML e LaTeX produzem tabelas feitas para
serem includas em documentos usando a linguagem de marcao correspondente. No so documentos
completos! (Isto no to problemtico no HTML, mas no LaTeX deve haver um invlucro completo
do documento).
border

O segundo argumento deve ser um nmero. Em geral, quanto maior o nmero 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 divisrias
internas) e 2 (moldura da tabela) fazem sentido.
expanded (ou x)

Alterna entre os formatos regular e expandido. Quando o formato expandido ativado todas as sadas
possuem duas colunas, ficando o nome do campo esquerda e o valor direita. Este modo til quando
os dados no cabem na tela no modo normal horizontal.
O modo expandido suportado por todos os quatro modos de sada.
null

O segundo argumento a cadeia de caracteres a ser impressa sempre que o campo for nulo. O padro
no imprimir nada, o que pode ser facilmente confundido com, por exemplo, uma cadeia de caracteres
vazia. Portanto, pode-se preferir escrever \pset null (nulo).
fieldsep

Especifica o separador de campos a ser utilizado no modo de sada no alinhado. Desta forma pode-se
criar, por exemplo, uma sada separada por tabulao, por vrgula ou por um outro caractere, conforme

58

psql
a preferncia do programa. Para definir o caractere de tabulao como separador de campo deve-se usar
\pset fieldsep \t. O separador de campos padro o | (a barra vertical, ou o smbolo do
pipe).
footer

Alterna a exibio do rodap padro (x linhas).

recordsep

Especifica o separador de registro (linha) a ser usado no modo de sada no alinhado. O padro o
caractere de nova-linha.
tuples_only (ou t)

Alterna entre exibir somente as tuplas e exibir tudo. O modo exibir tudo pode mostrar informaes
adicionais como os cabealhos das colunas, ttulos e vrios rodaps. No modo tuplas-apenas somente
os dados da tabela so mostrados.
title [ texto ]

Define o ttulo para as prximas tabelas a serem impressas. Pode ser usado para colocar textos descritivos na sada. Se nenhum argumento for fornecido, a definio removida.
Nota: Anteriormente s afetava o modo HTML. Atualmente pode ser definido ttulo para qualquer
formato de sada.

tableattr (ou T) [ texto ]

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, no vai se
desejar especificar border aqui, porque isto j tratado pelo \pset border.
pager

Alterna o paginador usado para mostrar a sada da tabela. Se a varivel de ambiente PAGER estiver
definida, a sada enviada para o programa especificado, seno o more utilizado.
De qualquer maneira, o psql somente usa o paginador se julgar adequado, significando que, entre outras
coisas, a sada para um terminal e que a tabela normalmente no caberia na tela. Devido a natureza
modular das rotinas de impresso, nem sempre possvel predizer o nmero de linhas que sero realmente impressas. Por esta razo, o psql pode parecer no muito discriminativo sobre quando usar o
paginador.
Ilustraes mostrando como parecem estes formatos diferentes podem ser vistas na seo Exemplos.

Dica: Existem vrios 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 opes de impresso.

\q

Sair do programa psql.

59

psql
\qecho texto [ ... ]

Este comando idntico ao \echo, exceto que toda a sada escrita no canal de sada de consulta, definido
pelo \o.
\r

Restaura (limpa) o buffer de comando.

\s [ nome_do_arquivo ]

Exibe ou salva o histrico da linha de comando em nome_do_arquivo. Se nome_do_arquivo for

omitido, o histrico enviado para a sada padro. Esta opo somente estar disponvel se o psql estiver
configurado para usar a biblioteca de histrico GNU.
Nota: Na verso corrente no mais necessrio salvar o histrico dos comandos, porque isto feito,
automaticamente, ao trmino do programa. O histrico tambm carregado, automaticamente, toda vez
que o psql inicia.

\set [ nome [ valor [ ... ]]]

Define a varivel interna nome com o valor ou, se mais de um valor for fornecido, com a concatenao de
todos eles. Se o segundo valor no for fornecido, a varivel definida sem valor. Para remover a definio
da varivel deve-se usar o comando \unset.
Nomes vlidos de variveis podem conter letras, dgitos e sublinhados (_). Veja a seo sobre as variveis
do psql para obter detalhes.
Embora possa ser definida qualquer varivel, para fazer qualquer coisa que se deseje, o psql trata diversas
variveis como sendo especiais. Elas esto documentadas na seo sobre variveis.
Nota: Este comando totalmente distinto do comando SQL SET .

\t

Alterna a exibio do cabealho contendo o nome das colunas e do rodap contendo o nmero de linhas.
Este comando equivalente ao \pset tuples_only, sendo fornecido por convenincia.
\T opes_de_tabela

Permite especificar opes a serem colocadas na tag table no modo de sada tabular HTML. Este comando
equivalente ao \pset tableattr opes_de_tabela.
\timing

Alterna a exibio de quanto tempo cada comando SQL demora, em milissegundos.

\w {nome_do_arquivo | |comando}

Escreve o buffer de comando corrente no arquivo nome_do_arquivo, ou envia para o comando Unix
comando atravs de um pipe.
\x

Alterna o modo estendido de formato de linha. Sendo assim, equivalente ao \pset expanded.
\z [ padro ]

Produz uma lista contendo todas as tabelas disponveis, juntamente com suas permisses de acesso. Se
padro for especificado, somente as tabelas cujos nomes correspondem ao padro so listadas.

60

psql
Os comandos GRANT e REVOKE so utilizados para definir as permisses de acesso. Consulte o comando
GRANT para obter mais informaes.
Este comando um sinnimo para o comando \dp (display permissions).
\! [ comando ]

Abre outra shell do Unix, ou executa o comando Unix comando. Os comandos deixam de ser interpretados
e so enviados para a shell como esto.
\?

Obtm informao de ajuda para os comandos de contrabarra (\).

Os diversos comandos \d aceitam como parmetro um padro para especificar os nomes dos objetos a serem
mostrados. Os padres so interpretados de forma semelhante aos identificadores SQL, onde as letras que no
esto entre aspas (") so transformadas em minsculas, enquanto as aspas protegem as letras de serem convertidas
e permitem a introduo de espaos em branco nos identificadores. Dentro das aspas, um par de aspas reduzido
para uma nica aspa dentro do nome gerado. Por exemplo, FOO"BAR"BAZ interpretado como as fooBARbaz, e
"Um nome"" esquisito" se torna Um nome" esquisito.
Mais interessante ainda, os padres para \d permitem o uso do * significando qualquer seqncia de caracteres,
e o ? significando qualquer caractere. (Esta notao anloga a dos padres para nomes de arquivos na shell
do Unix). Os usurios avanados tambm podem utilizar as notaes das expresses regulares tal como classe de
caracteres, por exemplo [0-9] correspondendo a qualquer dgito. Para fazer com que os caracteres especiais
de padro sejam interpretados literalmente, estes devem ser colocdos entre aspas.
Um padro que contenha um ponto (no entre aspas), interpretado como o padro do nome do esquema seguido
pelo padro do nome do objeto. Por exemplo, \dt foo*.bar* mostra todas as tabelas nos esquemas cujos
nomes comeam por foo, e cujos nomes de tabelas comeam por bar. Se no houver nenhum ponto, ento o
padro corresponde somente aos objetos visveis no caminho de procura do esquema corrente.
Sempre que o parmetro padro for omitido, o comando \d ir mostrar todos os objetos visveis no caminho de
procura do esquema corrente. Para mostrar todos os objetos do banco de dados, deve ser usado o padro *.*.

Funcionalidades avanadas
Variveis
O psql fornece uma funcionalidade de substituio de variveis similar a dos comandos comuns da shell do
Unix. Esta funcionalidade nova e no muito sofisticada ainda, mas existem planos para expandi-la no futuro.
As variveis so simplesmente um par nome/valor, onde o valor pode ser uma cadeia de caracteres de qualquer
comprimento. Para definir uma varivel usa-se o meta-comando do psql \set:
testdb=> \set foo bar

define a varivel foo com o valor bar. Para usar o contedo da varivel deve-se preceder o nome por doispontos (:), e us-la como argumento de qualquer comando de contrabarra:
testdb=> \echo :foo
bar

61

psql
Nota: Os argumentos do \set esto sujeitos s mesmas regras de substituio de qualquer outro comando.
Portanto, pode-se construir referncias interessantes como \set :foo something e obter soft links ou
variable variables do Perl e do PHP, respectivamente. Desafortunadamente (ou afortunadamente?), no
existe nenhuma maneira de se fazer qualquer coisa til com estas construes. Por outro lado, \set bar
:foo uma forma perfeitamente vlida de se copiar uma varivel.

Se \set for chamado sem um segundo argumento, a varivel simplesmente definida, mas no possui valor. Para
remover a definio (ou excluir) a varivel, usa-se o comando \unset.
Os nomes das variveis internas do psql podem consistir de letras, nmeros e sublinhados em qualquer ordem
e em qualquer nmero deles. Algumas variveis regulares possuem tratamento especial pelo psql. Elas indicam
certas definies de opes que podem ser mudadas em tempo de execuo alterando-se o valor da varivel, ou
representam algum estado do aplicativo. Embora seja possvel usar estas variveis para qualquer outra finalidade,
isto no recomendado, uma vez que o comportamento do programa pode se tornar muito estranho e muito
rapidamente. Por conveno, todas as variveis com tratamento especial possuem todas as letras maisculas (e
possivelmente nmeros e sublinhados). Para garantir a mxima compatibilidade no futuro, evite estas variveis.
Abaixo segue a lista de todas as variveis com tratamento especial.
DBNAME

O nome do banco de dados conectado correntemente. definida toda vez que se conecta a um banco de
dados (inclusive na inicializao), mas a definio pode ser removida.
ECHO

Se for definida como all, todas as linhas entradas, ou do script, so escritas na sada padro antes de
serem analisadas ou executadas. Para especificar no incio 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 opo para isto
-e.
ECHO_HIDDEN

Quando esta varivel 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 prprios programas. Se a varivel for definida como noexec, a consulta apenas exibida
sem ser enviada para o servidor para executar.
ENCODING

A codificao multibyte corrente do cliente. Se no estiver configurado para usar caracteres multibyte, esta
varivel ir conter sempre SQL_ASCII.
HISTCONTROL

Se esta varivel estiver definida como ignorespace, as linhas que comeam por espao no so salvas na
lista de histrico. Se estiver definida como ignoredups, as linhas idnticas linha anterior do histrico no
so salvas. O valor ignoreboth combina estas duas opes. Se no estiver definida, ou se estiver definida
com um valor diferente destes acima, todas as linhas lidas no modo interativo so salvas na lista de histrico.
Nota: Esta funcionalidade foi plagiada do bash.

HISTSIZE

O nmero de comandos a serem armazenados no histrico de comandos. O valor padro 500.

Nota: Esta funcionalidade foi plagiada do bash.

62

psql

HOST

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 inicializao), mas a definio no pode ser removida.
IGNOREEOF

Se no estiver definida, o envio de um caractere EOF (usualmente Control-D) para uma sesso interativa do
psql termina o aplicativo. Se estiver definida com um valor numrico, este nmero de caracteres EOF so
ignorados antes que o aplicativo termine. Se a varivel estiver definida, mas no tiver um valor numrico, o
padro 10.
Nota: Esta funcionalidade foi plagiada do bash.

LASTOID

O valor do ltimo oid afetado, retornado por um comando INSERT ou lo_insert. Esta varivel somente
garantida como vlida at que o resultado do prximo comando SQL tenha sido mostrado.
LO_TRANSACTION

Se for usada a interface de objeto grande do PostgreSQL para armazenar os dados que no cabem em uma
tupla, todas as operaes devem estar contidas em um bloco de transao (Consulte a documentao da interface de objetos grandes para obter mais informaes). Como o psql no tem maneira de saber se existe uma
transao em andamento quando chamado um de seus comandos internos (\lo_export, \lo_import,
\lo_unlink) este precisa tomar alguma deciso arbitrria. Esta ao pode ser desfazer (roll back) alguma transao que esteja em andamento, efetivar esta transao (commit), ou no fazer nada. Neste ltimo
caso deve ser fornecido o bloco BEGIN TRANSACTION/COMMIT, ou o resultado no ser previsvel (geralmente resultando em que a ao desejada no seja realizada em nenhum caso).
Para escolher o que se deseja fazer deve-se definir esta varivel como rollback, commit ou nothing.
O padro desfazer (roll back) a transao. Se for desejado carregar apenas um ou poucos objetos est
tudo bem. Entretanto, se a inteno for transferir muitos objetos grandes, aconselhvel fornecer um bloco
de transao explcito em torno dos comandos.
ON_ERROR_STOP

Por padro, se um script no-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
no o desejado. Se esta varivel 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 no foi
chamado por uma sesso interativa do psql, mas usando a opo -f, o psql retorna um cdigo de erro 3, para
distinguir este caso das condies de erro fatal (cdigo de erro 1).
PORT

A porta do servidor de banco de dados que se est conectado. Definida toda vez que se conecta ao banco de
dados (inclusive na inicializao), mas a definio pode ser removida.
PROMPT1
PROMPT2
PROMPT3

Especificam como os prompts emitidos pelo psql devem se parecer. Veja Prompt below.

63

psql
QUIET

Esta varivel equivalente opo de linha de comando -q. Provavelmente no muito til no modo
interativo.
SINGLELINE

Esta varivel definida pela opo de linha de comando -S. Pode ser redefinida ou ter a definio removida
em tempo de execuo.
SINGLESTEP

Esta varivel equivalente opo de linha de comando -s.

USER

O usurio do banco de dados que se est conectado. Definida toda vez que se conecta ao banco de dados
(inclusive na inicializao), mas a definio pode ser removida.

Interpolao SQL
Uma funcionalidade bastante prtica das variveis do psql que podem ser substitudas (interpoladas) dentro
de comandos regulares do SQL. A sintaxe para isto novamente prefixar a varivel com dois-pontos (:).
testdb=> \set foo minha_tabela
testdb=> SELECT * FROM :foo;

faria ento a consulta tabela minha_tabela. O valor da varivel copiado literalmente podendo, portanto, conter apstrofos no balanceados ou comandos de contrabarra. Deve-se ter certeza que faz sentido onde colocada.
A interpolao de variveis no realizada dentro de entidades SQL entre apstrofos.
Uma aplicao comum desta funcionalidade para fazer referncia nos comandos seguintes ao ltimo OID inserido, para construir um cenrio de chave estrangeira. Outro uso possvel deste mecanismo copiar o contedo de
um arquivo para um campo. Primeiro deve-se carregar o arquivo na varivel e depois proceder coforme mostrado.
testdb=> \set content \ cat meu_arquivo.txt \
testdb=> INSERT INTO minha_tabela VALUES (:content);

Um problema possvel com esta abordagem que o meu_arquivo.txt pode conter apstrofos, que devem ser
precedidos por uma contrabarra para que no causem erro de sintaxe quando a insero for processada, o que
poderia ser feito atravs do programa sed:
testdb=> \set content \ sed -e "s//\\\\\\/g" < meu_arquivo.txt \

Observe o nmero correto de contabarras (6)! Isto pode ser visto desta maneira: Aps o psql ter analisado esta
linha, vai enviar sed -e "s//\\\/g" < meu_arquivo.txt para a shell. A shell far suas prprias
coisas dentro das aspas e vai executar o sed com os argumentos -e e s//\\/g. Quando o sed fizer a anlise
vai substituir as duas contrabarras por uma nica e ento vai fazer a substituio. 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 tambm, porque as constantes de
texto do SQL tambm esto sujeitas a certas interpretaes. Neste caso melhor preparar o arquivo externamente.
Como os dois-pontos podem aparecer nos comandos, a seguinte regra se aplica: Se a varivel no est definida,
a seqncia de caracteres dois-pontos+nome no mudada. De qualquer maneira pode-se colocar uma contrabarra antes dos dois-pontos para proteg-lo de interpretao (A sintaxe de dois-pontos para variveis o padro

64

psql
SQL para as linguagens embutidas, como o ecpg. A sintaxe de dois-pontos para faixa de matriz e transformaes de tipo so extenses do PostgreSQL, da o conflito).

Prompt
Os prompts mostrados pelo psql podem ser personalizados conforme a preferncia. As trs variveis PROMPT1,
PROMPT2 e PROMPT3 contm cadeias de caracteres e seqncias especiais de escape que descrevem a aparncia
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 no foi
terminado por um ponto-e-vrgula, ou um apstrofo no 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 varivel de prompt exibido literalmente, exceto quando um sinal de percentagem (%)
encontrado. Dependendo do caractere seguinte, certos outros textos so substitudos. As substituies definidas
so:
%M

O nome completo do hospedeiro do servidor de banco de dados (com o nome do domnio), ou [local]
se a conexo for atravs de um soquete do domnio Unix, ou ainda [local:/dir/name], se o soquete do
domnio Unix no estiver no local padro da compilao.
%m

O nome do hospedeiro do servidor de banco de dados, truncado aps o primeiro ponto, ou [local] se a
conexo for atravs de um soquete do domnio Unix.
%>

O nmero da porta na qual o servidor de banco de dados est na espera.

%n

O nome do usurio que se est conectado (no o nome do usurio do sistema operacional local).
%/

O nome do banco de dados corrente.

%~

Como %/, mas a sada ser ~ (til) se o banco de dados for o banco de dados padro.
%#

Se o usurio corrente for um superusurio do banco de dados, ento #, seno >.

%R

No prompt 1 normalmente =, mas ^ se estiver no modo linha-nica e ! se a sesso estiver desconectada

do banco de dados (o que pode acontecer se o \connect falhar). No prompt 2 a seqncia substituda por
-, *, apstrofo, ou aspas, dependendo se o psql est aguardando mais entrada devido ao comando no
ter terminado ainda, porque est dentro de um comentrio /* ... */, ou porque est entre apstrofos ou
aspas. No prompt 3 a seqncia no se transforma em nada.
%dgitos

Se dgitos comear por 0x os caracteres restantes so interpretados como dgitos hexadecimais e o caractere com o cdigo correspondente substitudo. Se o primeiro dgito for 0 os caracteres so interpretados
como um nmero octal e o caractere correspondente substitudo. Seno um nmero decimal assumido.
%:nome:

O valor da varivel nome do psql. Veja a seo Variveis para obter detalhes.

65

psql
%comando

A sada do comando, similar substituio de crase normal.

Para inserir um sinal de percentagem no prompt deve-se escrever %%. Os prompts padro so equivalentes a
%/%R%# para os prompts 1 e 2, e >> para o prompt 3.

Nota: Esta funcionalidade foi plagiada do tcsh.

Edio da linha de comando

O psql suporta as bibliotecas de histrico e de leitura de linha por ser conveniente para a edio e recuperao
da linha. O histrico dos comandos armazenado no arquivo chamado .psql_history no diretrio home do
usurio, sendo recarregado quando o psql inicia. Completao por tabulao tambm suportado, embora a
lgica da completao no pretenda ser a de um analisador SQL. Quando disponvel, o psql construdo para
usar automaticamente esta funcionalidade. Se por algum motivo no se gostar da completao por tabulao,
pode-se desativ-la informando isto no arquivo chamado .inputrc no diretrio home do usurio:
$if psql
set disable-completion on
$endif

(Esta no uma funcionalidade do psql, mas sim do readline. Leia a sua documentao para obter mais detalhes).

Ambiente
HOME

Diretrio do arquivo de inicializao (.psqlrc) e do arquivo de histrico dos comandos (.psql_history).

PAGER

Se o resultado da consulta no couber na tela, exibido atravs deste comando. Os valores tpicos so more
e less. O padro depende da plataforma. A utilizao de um paginador pode ser desabilitado atravs do
comando \pset.
PGDATABASE

Banco de dados padro para se conectar.

PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo.

PSQL_EDITOR
EDITOR
VISUAL

Editor utilizado pelo comando \e. As variveis so examinadas na ordem listada; a primeira que estiver
definida utilizada.

66

psql
SHELL

Comando executado pelo comando \!.

TMPDIR

Diretrio para armazenar os arquivos temporrio. O padro /tmp.

Arquivos

Antes de comear, 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 histrico de linha de comando armazenado no arquivo $HOME/.psql_history.

Notas

Nas verses iniciais o psql permitia o primeiro argumento de um comando de contrabarra de uma nica letra
comear logo aps o comando, sem o espao separador. Por motivo de compatibilidade isto ainda suportado
de alguma forma, que no 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 no seja o esperado.

O psql somente trabalha adequadamente com servidores da mesma verso. Isto no significa que outras combinaes vo falhar inteiramente, mas problemas sutis, e nem to sutis, podem acontecer. Os comandos de
contrabarra so os mais propensos a falhar se o servidor for de uma verso diferente.

Pressionar Control-C durante um copy in (envio de dados para o servidor) no apresenta o mais ideal dos
comportamentos. Se for recebida uma mensagem como COPY state must be terminated first, simplesmente
deve-se refazer a conexo entrando com \c - -.

Exemplos
Nota: Esta seo somente mostra uns poucos exemplos especficos para o psql. Se for desejado aprender o SQL ou se tornar familiar com o PostgreSQL, aconselha-se a leitura do tutorial que est includo na
distribuio.

O primeiro exemplo mostra como distribuir um comando por vrias linhas de entrada. Observe a mudana do
prompt:
testdb=> CREATE TABLE minha_tabela (
testdb(> first integer not null default 0,
testdb(> second text
testdb-> );
CREATE

67

psql
Agora veja novamente a definio 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 vista 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 ","

68

psql
Field separator is ",".
peter@localhost testdb=> \pset tuples_only
Showing only tuples.
peter@localhost testdb=> SELECT second, first FROM minha_tabela;
one,1
two,2
three,3
four,4

Como alternativa, podem ser usados os comandos curtos:

peter@localhost testdb=> \a \t \x
Output format is aligned.
Tuples only is off.
Expanded display is on.
peter@localhost testdb=> SELECT * FROM minha_tabela;
-[ RECORD 1 ]first | 1
second | one
-[ RECORD 2 ]first | 2
second | two
-[ RECORD 3 ]first | 3
second | three
-[ RECORD 4 ]first | 4
second | four

69

pgtclsh
Nome
pgtclsh shell Tcl cliente do PostgreSQL

Sinopse
pgtclsh [nome_do_arquivo [argumentos...]]

Descrio
O pgtclsh uma interface shell Tcl estendida com funes de acesso a bancos de dados do PostgreSQL
(Essencialmente, uma tclsh com a libpgtcl carregada). Como no caso da shell Tcl normal, o primeiro
argumento da linha de comando o nome do arquivo de script, e todos os demais argumentos so passados para
o script. Se nenhum nome de arquivo for fornecido, a shell ser interativa.
Uma shell Tcl com Tk e funes PostgreSQL est disponvel em pgtksh.

Consulte tambm
pgtksh, Guia do Programador do PostgreSQL (descrio da libpgtcl) , tclsh

70

pgtksh
Nome
pgtksh shell Tcl/Tk cliente do PostgreSQL

Sinopse
pgtksh [nome_do_arquivo [argumentos...]]

Description
O pgtksh uma interface shell Tcl/Tk estendida com funes de acesso a bancos de dados do PostgreSQL
(Essencialmente, uma tksh com a libpgtcl carregada). Como no caso da shell Tcl/Tk normal, o primeiro
argumento da linha de comando o nome do arquivo de script, e todos os demais argumentos so passados para
o script. As opes especiais podem ser tratadas pelas bibliotecas do sistema X Window em vez da shell. Se
nenhum nome de arquivo for fornecido, a shell ser interativa.
Uma shell Tcl com funes PostgreSQL est disponvel em pgtclsh.

Consulte tambm
pgtclsh, Guia do Programador do PostgreSQL (descrio da libpgtcl) , tclsh , wish

71

vacuumdb
Nome
vacuumdb limpa e analisa um banco de dados do PostgreSQL

Sinopse
vacuumdb [opes_de_conexo...] [--full | -f] [--verbose | -v] [--analyze | -z] [--table | -t tabela [(
coluna [,...] )] ] [nome_bd]
vacuumdb [opes_de_conexo...] [--all | -a] [--full | -f] [--verbose | -v] [--analyze | -z]

Descrio
O vacuumdb um utilitrio para fazer a limpeza de bancos de dados do PostgreSQL. O vacuumdb tambm gera
estatsticas internas usadas pelo otimizador de consultas do PostgreSQL.
O vacuumdb um script envoltrio que usa o comando do servidor VACUUM atravs do terminal interativo do
PostgreSQL psql. No existe diferena efetiva entre limpar o banco de dados desta ou daquela maneira. O psql
deve ser encontrado pelo script, e o servidor de banco de dados deve estar executando na mquina de destino.
Tambm se aplicam os padres definidos e as variveis de ambiente disponveis para o psql e para a biblioteca
cliente libpq.
Pode ser necessrio o vacuumdb se conectar vrias vezes ao servidor PostgreSQL, solicitando a senha em cada
uma das vezes. conveniente existir o aquivo $HOME/.pgpass neste caso.

Opes
O vacuumdb aceita os seguintes argumentos de linha de comando:
[-d] nome_bd
[--dbname] nome_bd

Especifica o nome do banco de dados a ser limpo ou analisado. Se no for especificado e -a (ou --all) no
for usado, o nome do banco de dados obtido a partir da varivel de ambiente PGDATABASE. Se esta varivel
no estiver definida, ento o nome do usurio especificado para a conexo usado.
-a
--all

Limpa/analisa todos os bancos de dados.

-e
--echo

Ecoa os comandos que o vacuumdb gera e envia para o servidor.

-f
--full

Executa a limpeza completa (full).

72

vacuumdb
-q
--quiet

No exibe resposta.
-t tabela [ (coluna [,...]) ]
--table tabela [ (coluna [,...]) ]

Limpa ou analisa somente a tabela. Os nomes das colunas s podem ser especificados se a opo
--analyze tambm for especificada.
Dica: Se forem especificadas as colunas a serem analisadas, provavelmente ser necessrio fazer o
escape (\) dos parnteses para a shell.

-v
--verbose

Exibe informaes detalhadas durante o processamento.

-z
--analyze

Calcula as estatsticas a serem utilizadas pelo otimizador.

O vacuumdb tambm aceita os seguintes argumentos de linha de comando para os parmetros de conexo:
-h hospedeiro
--host hospedeiro

Especifica o nome da mquina onde o servidor est executando. Se o nome iniciar por uma barra (/),
considerado como sendo o diretrio do soquete do domnio Unix.
-p porta
--port porta

Especifica a porta Internet TCP/IP, ou o soquete do domnio Unix local, onde o servidor est aguardando as
conexes.
-U nome_do_usurio
--username nome_do_usurio

Nome do usurio para se conectar.

-W
--password

Fora a solicitao da senha.

73

vacuumdb

Diagnsticos
VACUUM

O comando foi executado com sucesso.

vacuumdb: Vacuum failed.

Aconteceu algum erro. O vacuumdb apenas um script envoltrio. Consulte o comando VACUUM e o
aplicativo psql para ver uma discusso detalhada das mensagens de erro e dos problemas possveis.

Ambiente
PGDATABASE
PGHOST
PGPORT
PGUSER

Parmetros padro para a conexo.

Exemplos
Para limpar o banco de dados teste:
$ vacuumdb teste

Para limpar e analisar para o otimizador o banco de dados chamado grande_bd:

$ vacuumdb --analyze grande_bd

Para limpar uma nica tabela chamada foo em um banco de dados chamado xyzzy e analisar uma nica coluna
da tabela chamada bar para o otimizador:
$ vacuumdb --analyze --verbose --table foo(bar) xyzzy

Consulte tambm
VACUUM

74

III. Aplicativos para o servidor do

PostgreSQL
Esta parte contm informaes de referncia para os aplicativos do servidor e utilitrios de suporte do PostgreSQL.
Estes comandos s so teis quando executados no computador onde o servidor de banco de dados est instalado.
Outros programas utilitrios esto listados em Referncia II, Aplicativos para a estao cliente do PostgreSQL.

75

initdb
Nome
initdb cria um novo agrupamento de bancos de dados do PostgreSQL

Sinopse
initdb [options...] --pgdata | -D diretrio

Descrio
O initdb cria um novo agrupamento de bancos de dados do PostgreSQL (ou sistema de bancos de dados). Um
agrupamento de bancos de dados uma coleo de bancos de dados que so gerenciados por uma nica instncia
do servidor.
Criar um sistema de banco de dados consiste em criar os diretrios onde os dados dos bancos de dados vo
residir, gerar as tabelas do catlogo compartilhado (tabelas que pertencem ao agrupamento como um todo e no
a algum banco de dados em particular), e criar o banco de dados template1. Quando um novo banco de dados
criado, tudo que existe no banco de dados template1 copiado. Este banco de dados contm tabelas do catlogo
preenchidas com dados como os tipos de dado primitivos.
O initdb inicializa a regio e a codificao do conjunto de caracteres padro do agrupamento de banco de
dados. Algumas categorias de regio so estabelecidas para toda a existncia do agrupamento, portanto muito
importante fazer a escolha correta ao se executar o initdb. Outras categorias de regio podem ser mudadas
mais tarde quando o servidor iniciado. O initdb escreve estas definies de regio no arquivo de configurao
postgresql.conf tornando-as padro, mas podem ser mudadas editando-se este arquivo. Para definir a regio
usada pelo initdb deve ser consultada a descrio da opo --locale. A codificao do conjunto de caracteres
pode ser definida individualmente para cada banco de dados no momento de sua criao. O initdb determina a
codificao para o banco de dados template1, que serve de padro para todos os outros bancos de dados. Para
mudar a codificao padro deve ser usada a opo --encoding.
O initdb deve ser executado pelo mesmo usurio do processo servidor, porque o servidor necessita ter acesso
aos arquivos e diretrios criados pelo initdb. Como o servidor no deve ser executado como root, tambm no
se deve executar o initdb como root (Na verdade, este vai se recusar a faz-lo).
Embora o initdb tente criar o diretrio de dados especificado, muitas vezes no ter permisso para faz-lo,
porque este diretrio geralmente est sob um diretrio que pertence ao root. Para resolver uma situao como
esta, deve-se criar um diretrio de dados vazio como root, depois usar o comando chown para mudar o dono
deste diretrio para o usurio do banco de dados, em seguida executar su para se tornar o usurio do banco de
dados e, finalmente, executar initdb como o usurio do banco de dados.

76

initdb

Opes
-D diretrio
--pgdata=diretrio

Esta opo especifica o diretrio onde o sistema de banco de dados deve ser armazenado. Esta a nica informao requerida pelo initdb, mas pode ser evitado escrev-la definindo a varivel de ambiente PGDATA,
o que conveniente porque, depois, o servidor de banco de dados (postmaster) poder localizar o diretrio
dos bancos de dados usando a mesma varivel.
-E codificao
--encoding=codificao

Seleciona a codificao do banco de dados de gabarito. Ser tambm a codificao padro para todos os
bancos de dados que vierem a ser criados, a menos que seja trocada por uma outra. Para que a funcionalidade
de codificao possa ser usada, esta deve ter sido habilitada em tempo de compilao, quando tambm pode
ser selecionado o valor padro para esta opo.
--locale=locale

Define a regio padro para o agrupamento de banco de dados. Se esta opo no for especificada, a regio
herdada do ambiente em que o initdb executa.
--lc-collate=regio
--lc-ctype=regio
--lc-messages=regio
--lc-monetary=regio
--lc-numeric=regio
--lc-time=regio

Como --locale, mas somente define a regio para a categoria especificada.

-U username
--username=username

Especifica o nome do superusurio do banco de dados. Por padro o nome do usurio efetivo executando
o initdb. No importa realmente qual o nome do superusurio, mas deve-se preferir manter o nome
costumeiro postgres, mesmo que o nome do usurio do sistema operacional seja diferente.
-W
--pwprompt

Faz o initdb solicitar a senha a ser dada ao superusurio do banco de dados. Se no se pretende usar
autenticao por senha, isto no tem importncia. Seno, no ser possvel usar autenticao por senha
enquanto no houver uma senha definida.

Outros parmetros, menos utilizados, tambm esto disponveis:

-d
--debug

Exibe sada de depurao do servidor de bootstrap e algumas outras mensagens de menor interesse para
o pblico em geral. O servidor de bootstrap o programa que o initdb utiliza para criar as tabelas do
catlogo. Esta opo gera uma quantidade tremenda de sada extremamente entediante.

77

initdb
-L diretrio

Especifica onde o initdb deve encontrar os seus arquivos de entrada para inicializar o sistema de banco de
dados. Normalmente no necessrio. Se for necessrio especificar a localizao ser informado explicitamente.
-n
--noclean

Por padro, quando o initdb determina que um erro impediu a criao completa do sistema de bancos
de dados, so removidos todos os arquivos porventura criados antes de ser descoberto que no era possvel
terminar o trabalho. Esta opo impede a limpeza e, portanto, til para a depurao.

Ambiente
PGDATA

Especifica o diretrio onde o sistema de bancos de dados deve ser armazenado; pode ser substitudo pela
opo -D.

Consulte tambm
postgres, postmaster, Guia do Administrador do PostgreSQL

78

initlocation
Nome
initlocation cria uma rea secundria de armazenamento de bancos de dados do PostgreSQL

Sinopse
initlocation diretrio

Description
O initlocation cria uma nova rea secundria de armazenamento de bancos de dados do PostgreSQL. Veja em
CREATE DATABASE a discusso sobre como usar e gerenciar reas de armazenamento secundrias. Se o argumento no contiver uma barra (/), e no for um caminho vlido, ser assumido como sendo uma varivel de
ambiente, a qual referenciada. Veja os exemplos no final.
Para poder usar este comando necessrio estar autenticado no sistema operacional como o superusurio do banco
de dados (usando o comando su, por exemplo).

Exemplos
Para criar um banco de dados em um local alternativo, usando uma varivel de ambiente:
$ export PGDATA2=/opt/postgres/data

Deve-se parar e reiniciar o postmaster para que este enxergue a varivel de ambiente PGDATA2. O sistema deve
ser configurado de maneira que o postmaster enxergue PGDATA2 toda vez que iniciar. Finalmente:
$ initlocation PGDATA2
$ createdb -D PGDATA2 testdb

Quando os caminhos absolutos so permitidos possvel escrever:

$ initlocation /opt/postgres/data
$ createdb -D /opt/postgres/data/testdb testdb

Consulte tambm
Guia do Administrador do PostgreSQL

79

ipcclean
Nome
ipcclean remove a memria compartilhada e os semforos de um servidor PostgreSQL abortado

Sinopse
ipcclean

Descrio
O ipcclean remove todos os segmentos de memria compartilhada e os semforos definidos, pertencentes ao
usurio corrente. Foi desenvolvido para ser usado para fazer a limpeza aps a queda do servidor PostgreSQL
(postmaster). Note que reiniciar o servidor imediatamente tambm limpa a memria compartilhada e os semforos, portanto este comando possui pouca utilidade prtica.
Somente o administrador do banco de dados deve executar este programa, porque pode ocasionar um comportamento bizarro (i.e., quedas) se for executado durante uma sesso multiusuria. Se este comando for executado
enquanto o postmaster estiver executando, a memria compartilhada e os semforos alocados pelo postmaster
sero eliminados, causando uma falha geral nos processos servidores iniciados pelo postmaster.

Notas
Este script um hack mas, durante estes muitos anos desde que foi escrito, ningum conseguiu desenvolver
uma soluo igualmente efetiva e portvel. Como agora o postmaster pode se autolimpar, no provvel que o
ipcclean seja melhorado no futuro.
Este script faz pressuposies sobre o formato da sada do utilitrio ipcs que podem no ser verdadeira entre
sistemas operacionais diferentes. Portanto, pode ser que no funcione no seu sistema operacional.

80

pg_ctl
Nome
pg_ctl inicia, pra ou reinicia o servidor PostgreSQL

Sinopse
pg_ctl start [-w] [-s] [-D diretrio_de_dados] [-l nome_do_arquivo] [-o opes] [-p caminho]
pg_ctl stop [-W] [-s] [-D diretrio_de_dados] [-m s[mart] | f[ast] | i[mmediate] ]
pg_ctl restart [-w] [-s] [-D diretrio_de_dados] [-m s[mart] | f[ast] | i[mmediate] ] [-o opes]
pg_ctl reload [-s] [-D diretrio_de_dados]
pg_ctl status [-D diretrio_de_dados]

Descrio
O pg_ctl um utilitrio para iniciar, parar ou reiniciar o postmaster, o servidor PostgreSQL, ou exibir o status
de um postmaster ativo. Embora o postmaster possa ser iniciado manualmente, o pg_ctl encapsula tarefas como
redirecionar a sada do log, desconectar do terminal e do grupo de processos de maneira adequada, alm de
fornecer opes convenientes para uma parada controlada.
No modo iniciar (start), um novo postmaster lanado. O servidor inicia em segundo plano, e a entrada padro
l de /dev/null. A sada padro e o erro padro so ambos adicionados a um arquivo de log, se a opo -l
for usada, ou so redirecionados para a sada padro do pg_ctl (no o erro padro). Se o arquivo de log no for
definido, a sada padro do pg_ctl deve ser redirecionada para um arquivo ou ser enviada para outro processo
(atravs de um pipe) como, por exemplo, para um programa para rotao de logs, seno o postmaster vai
escrever sua sada no terminal de controle (do segundo plano) e no vai se desconectar do grupo de processo da
shell.
No modo parar (stop), o postmaster que est executando no diretrio de dados especificado parado. Trs
mtodos diferentes de parada podem ser selecionados pela opo -m: O modo Smart (inteligente) aguarda
todos os clientes se desconectarem. Este o modo padro. O modo Fast (rpido) no aguarda os clientes se
desconectarem. Todas as transaes ativas so desfeitas (rollback), os clientes so desconectados fora e, em
seguida, o servidor parado. O modo Immediate (imediato) aborta todos os processor servidores sem executar
uma parada limpa, obrigando um processamento de recuperao ao reiniciar.
O modo reiniciar (restart) executa uma parada seguida por um incio. Permite mudar as opes de linha de
comando do postmaster.
O modo recarregar (reload) simplesmente envia o sinal SIGHUP para o postmaster, fazendo com que este releia
os arquivos de configurao (postgresql.conf, pg_hba.conf, etc.). Permite mudar as opes do arquivo de
configurao que no requerem um reincio completo para ter efeito.
O modo status verifica se o postmaster est executando e, se estiver, exibe o PID e as opes de linha de
comando que foram usadas para cham-lo.

81

pg_ctl

Opes
-D diretrio_de_dados
Especifica a localizao dos arquivos de banco de dados. Se for omitido, a varivel de ambiente PGDATA
usada.
-l nome_do_arquivo
Adiciona a sada do log do servidor ao nome_do_arquivo. Se o arquivo no existir criado. A umask
definida como 077, no permitindo o acesso ao arquivo de log pelos outros usurios por padro.
-m modo
Especifica o modo de parar (shutdown). O modo pode ser smart, fast ou immediate, ou a primeira letra
de um desses trs.
-o opes
Especifica opes a serem passadas diretamente para o postmaster.
Os parmetros geralmente so envoltos por apstrofos () ou aspas(") para garantir que so passados como
um grupo.
-p caminho
Especifica a localizao do arquivo executvel postmaster. Por padro o postmaster pego do mesmo
diretrio do pg_ctl ou, se falhar, do diretrio de instalao. No necessrio usar esta opo a menos que
esteja se fazendo algo diferente do usual e recebendo uma mensagem de erro informando que o postmaster
no foi encontrado.
-s
Mostra somente os erros, sem nenhuma mensagem informativa.
-w
Aguarda o incio ou a parada terminar. Espera no mximo 60 segundos. Este o padro para a parada.
-W
No aguarda o incio ou a parada terminar. Este o padro para o incio e o renicio.

Ambiente
PGDATA

Localizao padro do diretrio de dados.

Para os demais consulte o postmaster.

Arquivos
Se o arquivo postmaster.opts.default existir no diretrio de dados, o contedo deste arquivo ser passado
como opes para o postmaster, a menos que seja substitudo pela opo -o.

82

pg_ctl

Notas
Aguardar o trmino do incio no uma operao bem definida, podendo falhar se o controle de acesso for
definido de uma maneira que o cliente no possa se conectar sem interveno manual. Deve, portanto, ser evitado.

Exemplos
Iniciar o postmaster
Para iniciar o postmaster:
$ pg_ctl start

Exemplo de iniciar o postmaster, bloqueando at que o postmaster esteja ativo:

$ pg_ctl -w start

Para iniciar o postmaster utilizando a porta 5433 e executando sem o fsync pode-se usar:
$ pg_ctl -o "-F -p 5433" start

Parar o postmaster
$ pg_ctl stop

pra o postmaster. A chave -m permite controlar como o servidor vai parar.

Reiniciar o postmaster
Praticamente equivale a parar o postmaster e inici-lo novamente, exceto que o pg_ctl salva e reutiliza as opes
de linha de comando que foram passadas para a instncia executando anteriormente. Para reiniciar o postmaster
da forma mais simples possvel:
$ pg_ctl restart

Para reiniciar o postmaster, aguardando o trmino da parada e da inicializao:

$ pg_ctl -w restart

Para reiniciar usando a porta 5433 e desativando o fsync aps o reincio:

$ pg_ctl -o "-F -p 5433" restart

83

pg_ctl

Exibir o status do postmaster

Abaixo segue uma um exemplo da sada de status mostrada pelo pg_ctl:
$ pg_ctl status
pg_ctl: postmaster is running (pid: 13718)
Command line was:
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data -p 5433 -B 128

Esta a linha de comandos que seria usada no modo de reincio.

Consulte tambm
postmaster, Guia do Administrador do PostgreSQL

84

pg_controldata
Nome
pg_controldata exibe informaes de controle que abragem todo o servidor

Sinopse
pg_controldata [diretrio_de_dados]

Descrio
O aplicativo pg_controldata retorna informaes definidas durante a execuo do initdb, tal como a regio e a
verso do catlogo do servidor. Mostra, tambm, informaes sobre a gravao prvia do registro no log (WAL)
e o processamento dos pontos de controle (checkpoint). Estas informaes abragem todo o servidor, no sendo
especficas para um determinado banco de dados.
Este utilitrio somente pode ser executado pelo usurio que instalou o servidor, porque necessita de acesso de
leitura para o diretrio_de_dados. Pode ser especificado o diretrio de dados na linha de comando, ou pode
ser usada a varivel de ambiente PGDATA.

Ambiente
PGDATA

Localizao padro do diretrio de dados.

85

pg_resetxlog
Nome
pg_resetxlog redefine o contedo do log de escrita prvia e do arquivo pg_control

Sinopse
pg_resetxlog [ -f ] [ -n ] [ -o oid ] [ -x xid ] [ -l fileid,seg ] diretrio_de_dados

Descrio
O pg_resetxlog limpa o log de escrita prvia (WAL) e, opcionalmente, redefine alguns campos do arquivo
pg_control. O uso deste aplicativo necessrio quando os dados destes arquivos esto corrompidos. Deve ser
utilizado apenas como ltimo recurso, quando o servidor no iniciar devido corrupo destes arquivos.
Aps executar este comando deve ser possvel iniciar o servidor, mas deve-se ter em mente que o banco de dados
pode conter dados no consistentes devido existncia de transaes parcialmente efetivadas. Deve ser feita,
imediatamente, uma cpia de segurana, executar o initdb e recarregar os dados. Aps a recarga as inconsistncias
devem ser encontradas e corrigidas conforme necessrio.
Este utilitrio somente pode ser executado pelo usurio que instalou o servidor, porque requer acesso de
leitura/gravao nodiretrio_de_dados. Por motivo de segurana, o diretrio de dados deve ser especificado
na linha de comando. O pg_resetxlog no utiliza a varivel de ambiente PGDATA.
Se o pg_resetxlog informar que no est conseguindo determinar os dados vlidos para o pg_control, pode
ser forado a prosseguir utilizando a chave -f (forar). Neste caso, valores plausveis sero utilizados para os
dados que esto faltando. Deve-se esperar que a maioria dos campos sejam determinados, mas ajuda manual pode
ser necessria para os campos prximo OID, prximo ID de transao, endereo inicial do WAL e regio do banco
de dados. Os trs primeiros deles podem ser definidos usando as chaves discutidas abaixo. O prprio ambiente
do pg_resetxlog a fonte destas informaes para os campos regionais; deve-se cuidar para que LANG e as
demais variveis de ambiente anlogas correspondam s que estavam presentes quando o initdb foi executado. Se
no for possvel determinar o valor correto para todos estes campos o -f ainda pode ser usado, mas o banco de
dados recuperado deve ser considerado ainda mais suspeito do que o usual --- uma cpia de segurana imediata e
sua recarga imperativa. No deve ser executada nenhuma operao que modifique os dados do banco de dados
antes de ser feita a cpia de segurana, porque uma atividade deste tipo pode piorar ainda mais a situao.
As chaves -o, -x e -l permitem definir manualmente o prximo OID, o prximo ID de transao e o endereo
inicial do WAL. Somente sero necessrios quando o pg_resetxlog no conseguir determinar os valores apropriados atravs da leitura do arquivo pg_control. Um valor seguro para o identificador da prxima transao
pode ser determinado verificando-se o maior nome de arquivo em $PGDATA/pg_clog, somando-se 1 e depois
multiplicando-se por 1.048.576. Observe que os nomes dos arquivos esto em hexadecimal. Normalmente
mais fcil especificar o valor da chave em hexadecimal tambm. Por exemplo, se 0011 for a maior entrada em
pg_clog, ento -x 0x1200000 servir (cinco zeros direita fornecem o multiplicador apropriado). O endereo
inicial do WAL deve ser maior do que qualquer nmero de arquivo presente em $PGDATA/pg_xlog. Estes valores tambm esto em hexadecimal, possuindo duas partes. Por exemplo, se 000000FF0000003A for a maior
entrada em pg_xlog, ento -l 0xFF,0x3B servir. No existe nenhuma maneira to fcil de se determinar o
prximo OID, acima do maior existente no banco de dados, mas por sorte no crtico definir o prximo OID
corretamente.

86

pg_resetxlog
A chave -n (nenhuma operao) instrui o pg_resetxlog para imprimir os valores reconstrudos a partir de
pg_control, e depois terminar sem modificar nada. Isto principalmente uma ferramenta de depurao, mas
pode ser til para fazer uma verificao antes de permitir que o pg_resetxlog efetue a operao de verdade.

Notas
Este comando no deve ser usado quando o postmaster estiver executando. O pg_resetxlog se recusa a iniciar
quando encontra o arquivo de bloqueio do postmaster no diretrio_de_dados. Se o postmaster terminar anormalmente, ento o arquivo de bloqueio pode ter sido deixado no diretrio; neste caso, o arquivo de bloqueio pode
ser removido para permitir a execuo do pg_resetxlog, mas antes de fazer isto, deve haver a certeza de que
nem o postmaster nem nenhum processo servidor ainda est executando.

87

postgres
Nome
postgres executa o servidor PostgreSQL no modo monousurio

Sinopse
postgres [-A

0 | 1 ] [-B num_buffers] [-c nome=valor] [-d nvel_de_depurao] [-D

diretrio_de_dados] [-e] [-E] [-f s | i | t | n | m | h ] [-F] [-i] [-N] [-o nome_do_arquivo] [-O] [-P] [-s |
-t pa | pl | ex ] [-S memria_para_ordenao] [-W segundos] [--nome=valor] banco_de_dados
postgres [-A 0 | 1 ] [-B num_buffers] [-c nome=valor] [-d nvel_de_depurao] [-D
diretrio_de_dados] [-e] [-f s | i | t | n | m | h ] [-F] [-i] [-o nome_do_arquivo] [-O] [-p
banco_de_dados] [-P] [-s | -t pa | pl | ex ] [-S memria_para_ordenao] [-v
verso_do_protocolo] [-W segundos] [--nome=valor]

Descrio
O executvel postgres o verdadeiro processo servidor que processa os comandos do PostgreSQL. Normalmente no chamado diretamente; em vez dele o servidor multiusurio postmaster ativado.
A segunda forma mostrada acima como o postgres chamado pelo postmaster (somente conceitualmente,
porque o postmaster e o postgres so, na verdade, o mesmo programa); no devendo ser chamado diretamente desta maneira. A primeira forma chama o servidor diretamente em modo monousurio interativo. A utilizao mais freqente deste modo durante a inicializao pelo initdb. Algumas vezes utilizado para depurao
ou para recuperao de desastre.
Quando chamado em modo interativo a partir da shell, o usurio pode entrar com comandos e os resultados so
exibidos na tela, mas em uma forma que mais til para os desenvolvedores do que para os usurios finais. Devese notar que executar o servidor em modo monousurio no muito apropriado para a depurao do servidor,
porque no vai acontecer nenhuma comunicao entre processos e bloqueio genunos.
Ao executar o servidor autnomo, o usurio da sesso ser definido como o usurio com o identificador 1. Este
usurio no necessita existir, portanto o servidor autnomo pode ser usado para recuperar manualmente certos
tipos de danos acidentais dos catlogos do sistema. Poderes implcitos de superusurio so concedidos ao usurio
com identificador igual a 1 no modo autnomo.

Opes
Quando o postgres iniciado pelo postmaster, herda todas as opes definidas para este. Adicionalmente, opes
especficas do postgres podem ser passadas pelo postmaster usando a chave -o.
Pode-se evitar digitar a maior parte destas opes usando o arquivo de configurao. Consulte o Guia do Administrador para obter detalhes. Algumas opes (seguras) tambm podem ser definidas pelo cliente ao se conectar,
de um modo dependente do aplicativo. Por exemplo, se a varivel de ambiente PGOPTIONS estiver definida, ento
os clientes baseados na libpq passam esta cadeia de caracteres para o servidor, que vai interpret-la como uma
opo de linha de comando do postgres.

88

postgres

Finalidade geral
As opes -A, -B, -c, -d, -D, -F e --name possuem o mesmo significado que no postmaster, exceto que -d 0
impede o nvel de depurao do postmaster ser propagado para o processo servidor.
-e

Define o estilo padro da data como European, indicando que a regra dia precedendo o ms (em vez de
ms precedendo o dia) deve ser usada para interpretar a entrada de datas ambguas, e que o dia precede o
ms em certos formatos de exibio de data. Consulte o Guia do Usurio do PostgreSQL para obter mais
informaes.
-o nome_do_arquivo

Envia toda a sada de depurao e de erros para o nome_do_arquivo. Se o processo servidor estiver
executando sob o postmaster ento esta opo ser ignorada, e a stderr herdada do postmaster ser usada.
-P

Ignora os ndices do sistema ao varrer/atualizar as tuplas do sistema. O comando REINDEX para as

tabelas/ndices do sistema requer que esta opo seja utilizada.
-s

Exibe a informao de tempo e outras estatsticas ao final de cada comando. til para efetuar medies ou
para definir o nmero de buffers.
-S memria_para_ordenao

Especifica a quantidade de memria a ser usada pelas ordenaes e hashes internos antes de recorrer a arquivos temporrios em disco. O valor especificado em kilobytes, sendo o valor padro 512 kilobytes.
Observe que para uma consulta complexa, diversas ordenaes e/ou hashes podem ser executadas em
paralelo, podendo cada uma utilizar a quantidade de memria_para_ordenao kilobytes antes de
comear a escrever os dados em arquivos temporrios.

Opes para o modo autnomo

banco_de_dados
Especifica o nome do banco de dados a ser acessado. Se for omitido o padro o nome do usurio.
-E

Exibe todos os comandos.

-N

Desativa o uso do caractere de nova-linha como delimitador do comando.

Opes semi-internas
Existem vrias outras opes que podem ser especificadas, usadas principalmente para fins de depurao, que
esto mostradas aqui somente para uso pelos desenvolvedores de sistema do PostgreSQL. A utilizao de qualquer uma destas opes altamente desaconselhada. Alm disso, qualquer uma destas opes poder mudar ou
desaparecer em verses futuras sem nenhum aviso.

89

postgres
-f { s | i | m | n | h }

Probe o uso de um mtodo de varredura ou de juno em particular: s e i desativam as varreduras seqenciais e de ndices respectivamente, enquanto que n, m e h desativam as junes de lao-aninhado, mesclagem
e hash respectivamente.
Nota: Nem as varreduras seqenciais nem as junes de lao aninhado podem ser desativadas completamente; as opes -fs e -fn simplesmente desencorajam o uso pelo otimizador de planos deste
tipo, se houver alguma outra alternativa.

-i

Probe a execuo da consulta, mas mostra a rvore do plano.

-O

Permite modificar a estrutura das tabelas do sistema. Usado pelo initdb.

-p banco_de_dados

Indica que este servidor foi inicializado pelo postmaster fazendo suposies diferentes sobre o gerenciamento
do buffer pool, descritores de arquivos, etc...
-t pa[rser] | pl[anner] | e[xecutor]

Exibe estatsticas de tempo para cada comando, relacionando com cada um dos principais mdulos do sistema. Esta opo no pode ser usada junto com a opo -s.
-v verso_do_protocolo

Especifica o nmero da verso do protocolo cliente/servidor a ser usado por esta sesso em particular.
-W segundos

To logo esta opo seja encontrada, o processo adormece a quantidade especificada de segundos, dando ao
desenvolvedor tempo para ligar o depurador ao processo servidor.

Ambiente
PGDATA

Localizao padro do diretrio de dados.

Para outras, que possuem pouca influncia durante o modo mono-usurio, consulte o postmaster.

Notas
Para terminar a execua de um comando deve ser usado o sinal SIGINT. Para fazer com que o postgres leia
novamente o arquivo de configurao deve ser usado o sinal SIGHUP. O postmaster utiliza o sinal SIGTERM para
dizer a um processo postgres que o mesmo deve terminar normalmente, e SIGQUIT para que termine sem executar
os procedimentos de limpeza normais. Estes sinais no devem ser utilizados pelos usurios.

90

postgres

Utilizao
Inicie o servidor autnomo com um comando do tipo:
postgres -D $PGDATA outras_opes meu_bd

Fornea o caminho correto para a rea de banco de dados com -D, ou garanta que a varivel de ambiente PGDATA
esteja definida. Tambm especifique o nome do banco de dados em que deseja trabalhar.
Normalmente, o servidor autnomo trata o caractere de nova-linha como trmino da entrada; no existe inteligncia com relao ao ponto-e-vrgula, como existe no psql. Para estender um comando por vrias linhas, deve ser
digitado uma contrabarra (\) logo antes de cada nova-linha, exceto a ltima.
Mas se for usada a chave de linha de comando -N, o caractere de nova-linha no termina a entrada do comando.
O servidor vai ler a entrada padro at a marca de fim-de-arquivo (EOF) e, ento, vai processar a entrada como
sendo a cadeia de caracteres de um nico comando. A seqncia contrabarra nova-linha no recebe tratamento
especial neste caso.
Para sair da sesso tecle EOF (geralmente Control+D). Se for usado o -N, ento dois EOFs consecutivos so
necessrios para sair.
Observe que o servidor autnomo no fornece funcionalidades sofisticadas para edio de linha (no existe o
histrico dos comandos, por exemplo).

Consulte tambm
initdb, ipcclean, postmaster

91

postmaster
Nome
postmaster servidor de banco de dados multiusurio do PostgreSQL

Sinopse
postmaster [-A 0 | 1 ] [-B num_buffers] [-c nome=valor] [-d nvel_de_depurao] [-D
diretrio_de_dados] [-F] [-h nome_do_hospedeiro] [-i] [-k diretrio] [-l] [-N
num_max_conexes] [-o opes_extras] [-p porta] [-S] [--nome=valor] [-n | -s]

Descrio
O postmaster o servidor de banco de dados multiusurio do PostgreSQL. Para um aplicativo cliente acessar um
banco de dados deve se conectar (atravs de uma rede ou localmente) a um postmaster. O postmaster ento inicia
um processo servidor separado (postgres) para manter a conexo. O postmaster tambm gerencia a comunicao
entre os processos servidores.
Por padro, o postmaster inicia em primeiro plano (foreground) e envia as mensagens de log para a sada
padro. Na prtica o postmaster deve ser iniciado como um processo em segundo plano (background), provavelmente durante a inicializao do sistema operacional.
Um postmaster gerencia sempre os dados de exatamente um agrupamento de bancos de dados. Um agrupamento
de bancos de dados uma coleo de bancos de dados que armazenada em um local comum no sistema de
arquivos. Quando o postmaster inicia necessita saber a localizao dos arquivos do agrupamento de bancos de
dados (rea de dados), o que feito atravs da opo de chamada -D, ou atravs da varivel de ambiente
PGDATA; no existe nenhum valor padro. Mais de um processo postmaster pode estar executando no sistema
operacional no mesmo instante, desde que utilizem reas de dados diferentes e portas de comunicao diferentes
(veja abaixo). A rea de dados criada pelo aplicativo initdb.

Opes
Consulte o Guia do Administrador para ver uma discusso detalhada das opes. Pode-se evitar digitar a maior
parte destas opes usando o arquivo de configurao. O postmaster aceita os seguintes argumentos de linha de
comando:
-A 0|1
Ativa a verificao das assertivas de tempo de execuo, o que uma ajuda de depurao para detectar
enganos de programao. S est disponvel quando habilitada durante a compilao. Se for, o padro
ativa.
-B num_buffers
Define o nmero de buffers compartilhados para uso pelos processos servidores (SHARED_BUFFERS =
num_buffers). Por padro 64 buffers, cada um de 8 kB.

92

postmaster
-c nome=valor
Define o parmetro de tempo de execuo designado. Consulte o Guia do Administrador para obter a relao
destes parmetros e as suas descries. A maior parte das outras opes de linha de comando so, na verdade,
formas curtas de atribuio destes parmetros. A opo -c pode aparecer vrias vezes para definir vrios
parmetros.
-d nvel_de_depurao
Define o nvel de depurao (DEBUG_LEVEL = nvel_de_depurao). Quanto maior for definido este valor,
mais sada de depurao ser escrita no log do servidor. Os valores vo de 1 a 5.
-D diretrio_de_dados
Especifica a localizao do diretrio de dados no sistema de arquivos. Veja a discusso acima.
-F
Desativa as chamadas a fsync para melhorar o desempenho, correndo o risco de corrupo dos dados
na ocorrncia de uma falha do sistema. Este parmetro corresponde a definir fsync=false no arquivo
postgresql.conf. Leia com ateno a documentao antes de usar esta opo!
--fsync=true possui o efeito contrrio desta opo.

-h nome_do_hospedeiro
Especifica o nome ou o endereo do hospedeiro TCP/IP no qual o postmaster aguarda as conexes dos
aplicativos clientes (VIRTUAL_HOST = nome_do_hospedeiro). Por padro aguarda em todos os endereos
configurados (incluindo localhost).
-i
Permite os clientes se conectarem via TCP/IP (Domnio da Internet). Sem esta opo, somente as conexes
via soquete do domnio Unix local so aceitas. Esta opo corresponde a definir tcpip_socket=true no
arquivo postgresql.conf.
--tcpip_socket=false possui o efeito oposto desta opo.

-k diretrio
Especifica o diretrio do soquete do domnio Unix, no qual o postmaster est aguardando as conexes dos
aplicativos clientes (UNIX_SOCKET_DIRECTORY = diretrio). Normalmente o padro /tmp, mas pode
ser mudado em tempo de compilao.
-l
Ativa as conexes seguras usando SSL (SSL = TRUE). A opo -i tambm requerida. Deve ter sido
compilado com SSL habilitado para ser possvel o uso desta opo.
-N num_max_conexes
Define o nmero mximo de conexes de clientes aceitas por este postmaster (MAX_CONNECTIONS =
num_max_conexes). Por padro este valor 32, mas pode ser definido to alto quanto o sistema operacional
suportar (Observe que a opo -B deve ser pelo menos o dobro da opo -N. Veja a discusso sobre os
recursos do sistema requeridos para a conexo de um grande nmero de clientes no Guia do Administrador).
-o opes_extras
As opes estilo linha de comando especificadas nas opes_extras so passadas para todos os processos servidores comeando por este postmaster. Consulte o postgres para ver as possibilidades. Se a cadeia de
caracteres contendo a opo contiver espaos, toda a cadeia de caracteres deve vir entre apstrofos ().
-p porta
Especifica a porta TCP/IP, ou o soquete do domnio Unix local, onde o postmaster est aguardando as
conexes dos aplicativos cliente (PORT = porta). Por padro o valor da varivel de ambiente PGPORT ou, se

93

postmaster
PGPORT no estiver definida, o valor estabelecido durante a compilao (normalmente 5432). Se for especi-

ficada outra porta diferente da porta padro, ento todos os aplicativos cliente devem especificar a mesma
porta usando a opo de linha de comando ou a varivel de ambiente PGPORT.
-S
Especifica que o processo postmaster deve iniciar no modo silencioso, ou seja, ser dissociado do terminal
do usurio, iniciar seu prprio grupo de processos e redirecionar sua sada padro e erro padro para
/dev/null.
O uso desta chave descarta toda a sada para o log, o que provavelmente no o desejado, porque torna
muito difcil a soluo dos problemas. Veja abaixo uma maneira mais adequada de iniciar o postmaster em
segundo plano.
--silent_mode=false possui o efeito oposto desta opo.

--nome=valor
Define o parmetro de tempo de execuo designado; uma forma mais curta da opo -c.

Duas opes adicionais de linha de comando esto disponveis para a depurao de problemas que fazem o servidor terminar anormalmente. Estas opes controlam o comportamento do postmaster nesta situao, e nenhuma
delas foi feita para ser usada durante a operao normal.
A estratgia comum para esta situao notificar a todos os outros servidores que eles devem terminar e, ento,
reinicializar a memria compartilhada e os semforos. Isto necessrio porque um servidor errante pode ter
corrompido algum estado compartilhado antes de terminar.
Estas opes caso-especial so:
-n
O postmaster no ir reinicializar as estruturas de dado compartilhadas. Um programador de sistemas com
conhecimento adequado poder, ento, usar um depurador para examinar a memria compartilhada e o estado do semforo.
-s
O postmaster ir parar todos os outros processos servidores enviando o sinal SIGSTOP, mas no ir faz-los
terminar, permitindo aos programadores de sistema coletar os core dumps de todos os processos servidores
manualmente.

Ambiente
PGCLIENTENCODING

A codificao de caracters padro utilizada pelos clientes. (Os clientes podem redefini-la individualmente).
Este valor tambm pode ser definido no arquivo de configurao.
PGDATA

Localizao padro do diretrio de dados.

94

postmaster
PGDATASTYLE

Valor padro do parmetro de tempo de execuo datestyle (A utilizao desta varivel de ambiente est
obsoleta).
PGPORT

Porta padro (definida de preferncia no arquivo de configurao).

TZ

Zona horria do servidor.

outras
Outras variveis de ambiente podem ser usadas para designar locais alternativos para armazenamento dos
dados. Consulte o Guia do Administrador para obter mais informaes.

Diagnsticos
semget: No space left on device

Se esta mensagem for recebida deve-se executar o comando ipcclean e, em seguida, tentar iniciar o postmaster novamente. Se ainda assim no funcionar, provavelmente ser necessrio configurar o ncleo (kernel)
para a memria compartilhada e os semforos conforme descrito nas notas de instalao. Se forem executadas vrias instncias do postmaster em um nico hospedeiro, ou se o ncleo tiver memria compartilhada
e/ou limites de semforo particularmente pequenos, provavelmente ser necessrio reconfigurar o ncleo
para aumentar os parmetros de memria compartilhada ou de semforos.
Dica: Pode-se conseguir adiar a reconfigurao do ncleo diminuindo-se -B para reduzir o consumo de
memria compartilhada do PostgreSQL, e/ou reduzindo-se -N para reduzir o consumo de semforos.

StreamServerPort: cannot bind to port

Se esta mensagem for vista, deve-se ter certeza de que no h nenhum outro processo postmaster executando
no mesmo computador usando o mesmo nmero de porta. A maneira mais fcil de se ver usando o comando
$ ps ax | grep postmaster

ou
$ ps -e | grep postmaster

dependendo do sistema operacional.

Havendo certeza de que nenhum outro processo postmaster est executando, e o erro continuar acontecendo,
deve-se tentar especificar uma porta diferente usando a opo -p. possvel acontecer este erro se o postmaster for terminado e imediatamente reiniciado usando a mesma porta; neste caso deve-se simplesmente
aguardar alguns segundos at que o sistema operacional feche a porta antes de tentar novamente. Finalmente, este erro pode acontecer se for especificado um nmero de porta que o sistema operacional considera
ser reservado. Por exemplo, muitas verses do Unix consideram os nmeros de porta abaixo de 1024 como
sendo trusted (confiadas) s permitindo o acesso aos superusurios do Unix.

95

postmaster

Notas
Sempre que for possvel no deve ser usado o SIGKILL para terminar o postmaster. Isto impede que o postmaster
libere os recursos do sistema utilizados (memria compartilhada e semforos, por exemplo) antes de terminar.
Para terminar o postmaster normalmente, os sinais SIGTERM, SIGINT ou SIGQUIT podem ser usados. O primeiro
aguarda todos os clientes terminarem antes de fechar, o segundo fora a desconexo de todos os clientes e o
terceiro fecha imediatamente sem um shutdown apropriado, acarretando a execuo da recuperao ao reiniciar.
O utilitrio pg_ctl pode ser usado para iniciar e terminar o postmaster com segurana e conforto.
As opes -- no funcionam no FreeBSD nem no OpenBSD. Use o -c em seu lugar. Esta uma falha destes
sistemas operacionais; uma verso futura do PostgreSQL disponibilizar uma forma de contornar este problema,
caso no seja corrigido.

Exemplos
Para iniciar o postmaster em segundo plano usando os valores padro:
$ nohup postmaster >logfile 2>&1 </dev/null &

Para iniciar o postmaster usando uma porta especfica:

$ postmaster -p 1234

Este comando inicia o postmaster se comunicando atravs da porta 1234. Para se conectar a este postmaster
usando o psql, deve-se executar:
$ psql -p 1234

ou definir a varivel de ambiente PGPORT:

$ export PGPORT=1234
$ psql

Parmetros de tempo de execuo nomeados podem ser definidos usando-se um destes estilos:
$ postmaster -c sort_mem=1234
$ postmaster --sort-mem=1234

As duas formas substituem o que estiver definido para sort_mem em postgresql.conf. Observe que os sublinhados nos nomes dos parmetros podem ser escritos na linha de comando com o caractere sublinhado ou o
trao (dash).
Dica: Exceto para experimentos de curta durao, provavelmente uma prtica melhor editar as definies
no arquivo postgresql.conf do que depender das chaves da linha de comando para definir os parmetros.

Consulte tambm
initdb, pg_ctl

96