Como Convencer Alguem em 90 Seg - Nicholas Boothman

Documentação do PostgreSQL 8.2.
Documentação do PostgreSQL 8.2.0

Projeto de Tradução para o Português do Brasil
The PostgreSQL Global Development Group
Copyright © 1996-2006 The PostgreSQL Global Development Group
Sumário
Prefácio
O que é o PostgreSQL?
Uma breve história do PostgreSQL
Conventions
Further Information
Bug Reporting Guidelines
I. Tutorial
1. Início
2. A linguagem SQL
3. Funcionalidades avançadas
II. A linguagem SQL
4. SQL Syntax
5. Data Definition
6. Data Manipulation
7. Queries
8. Data Types
9. Functions and Operators
10. Type Conversion
11. Indexes
12. Concurrency Control
13. Performance Tips
III. Administração do servidor
14. Installation Instructions

15. Client-Only Installation on Windows
16. Operating System Environment
17. Server Configuration
18. Database Roles and Privileges
19. Managing Databases
20. Client Authentication
21. Localization
22. Routine Database Maintenance Tasks
23. Backup and Restore
24. High Availability and Load Balancing
25. Monitoring Database Activity
http://pgdocptbr.sourceforge.net/pg82/index.html[09/02/2018 17:47:31]
26. Monitoring Disk Usage

27. Reliability and the Write-Ahead Log
28. Regression Tests
IV. Interfaces cliente
29. libpq - C Library

30. Large Objects
31. ECPG - Embedded SQL in C
32. The Information Schema
V. Programação servidor
33. Extending SQL

34. Triggers
35. The Rule System
36. Procedural Languages
37. PL/pgSQL - SQL Procedural Language
38. PL/Tcl - Tcl Procedural Language
39. PL/Perl - Perl Procedural Language
40. PL/Python - Python Procedural Language
41. Server Programming Interface
VI. Referência
I. Comandos SQL
II. Aplicativos cliente do PostgreSQL
III. Aplicativos do servidor PostgreSQL
VII. Internamente
42. Overview of PostgreSQL Internals

43. System Catalogs
44. Frontend/Backend Protocol
45. PostgreSQL Coding Conventions
46. Native Language Support
47. Writing A Procedural Language Handler
48. Genetic Query Optimizer
49. Index Access Method Interface Definition
50. GiST Indexes
51. GIN Indexes
52. Database Physical Storage
53. BKI Backend Interface
54. How the Planner Uses Statistics
VIII. Apêndices
A. PostgreSQL Error Codes

B. Date/Time Support
C. SQL Key Words
D. SQL Conformance
E. Release Notes
F. The CVS Repository
G. Documentation
H. External Projects
Bibliografia
Índice Remissivo
Lista de Tabelas
4-1. Operator Precedence (decreasing)
8-1. Data Types
8-2. Numeric Types
8-3. Monetary Types
8-4. Character Types
8-5. Special Character Types
8-6. Binary Data Types
8-7. bytea Literal Escaped Octets
8-8. bytea Output Escaped Octets
8-9. Date/Time Types
8-10. Date Input
8-11. Time Input
8-12. Time Zone Input
8-13. Special Date/Time Inputs
8-14. Date/Time Output Styles
8-15. Date Order Conventions
8-16. Geometric Types
8-17. Network Address Types
8-18. cidr Type Input Examples
8-19. Object Identifier Types
8-20. Pseudo-Types
9-1. Comparison Operators
9-2. Mathematical Operators
9-3. Mathematical Functions
9-4. Trigonometric Functions
9-5. SQL String Functions and Operators
9-6. Other String Functions
9-7. Built-in Conversions
9-8. SQL Binary String Functions and Operators
9-9. Other Binary String Functions
9-10. Bit String Operators
9-11. Regular Expression Match Operators
9-12. Regular Expression Atoms
9-13. Regular Expression Quantifiers
9-14. Regular Expression Constraints
9-15. Regular Expression Character-Entry Escapes
9-16. Regular Expression Class-Shorthand Escapes
9-17. Regular Expression Constraint Escapes
9-18. Regular Expression Back References
9-19. ARE Embedded-Option Letters
9-20. Formatting Functions
9-21. Template Patterns for Date/Time Formatting
9-22. Template Pattern Modifiers for Date/Time Formatting
9-23. Template Patterns for Numeric Formatting
9-24. to_char Examples
9-25. Date/Time Operators
9-26. Date/Time Functions
9-27. AT TIME ZONE Variants
9-28. Geometric Operators
9-29. Geometric Functions
9-30. Geometric Type Conversion Functions
9-31. cidr and inet Operators
9-32. cidr and inet Functions
9-33. macaddr Functions
9-34. Sequence Functions
9-35. array Operators

9-36. array Functions
9-37. General-Purpose Aggregate Functions
9-38. Aggregate Functions for Statistics
9-39. Series Generating Functions
9-40. Session Information Functions
9-41. Access Privilege Inquiry Functions
9-42. Schema Visibility Inquiry Functions
9-43. System Catalog Information Functions
9-44. Comment Information Functions
9-45. Configuration Settings Functions
9-46. Server Signalling Functions
9-47. Backup Control Functions
9-48. Database Object Size Functions
9-49. Generic File Access Functions
9-50. Advisory Lock Functions
12-1. SQL Transaction Isolation Levels
16-1. System V IPC parameters
16-2. Configuration parameters affecting PostgreSQL's shared memory usage
17-1. Short option key
21-1. PostgreSQL Character Sets
21-2. Client/Server Character Set Conversions
25-1. Standard Statistics Views
25-2. Statistics Access Functions
25-3. Built-in Trace Points
31-1. Valid input formats for PGTYPESdate_from_asc
31-2. Valid input formats for PGTYPESdate_fmt_asc
31-3. Valid input formats for rdefmtdate
31-4. Valid input formats for PGTYPEStimestamp_from_asc
32-1. information_schema_catalog_name Columns
32-2. administrable_role_authorizations Columns
32-3. applicable_roles Columns
32-4. attributes Columns
32-5. check_constraint_routine_usage Columns
32-6. check_constraints Columns
32-7. column_domain_usage Columns
32-8. column_privileges Columns
32-9. column_udt_usage Columns
32-10. columns Columns
32-11. constraint_column_usage Columns
32-12. constraint_table_usage Columns
32-13. data_type_privileges Columns
32-14. domain_constraints Columns
32-15. domain_udt_usage Columns
32-16. domains Columns
32-17. element_types Columns
32-18. enabled_roles Columns
32-19. key_column_usage Columns
32-20. parameters Columns
32-21. referential_constraints Columns
32-22. role_column_grants Columns
32-23. role_routine_grants Columns
32-24. role_table_grants Columns
32-25. role_usage_grants Columns
32-26. routine_privileges Columns
32-27. routines Columns
32-28. schemata Columns
32-29. sequences Columns
32-30. sql_features Columns
32-31. sql_implementation_info Columns
32-32. sql_languages Columns
32-33. sql_packages Columns

32-34. sql_parts Columns
32-35. sql_sizing Columns
32-36. sql_sizing_profiles Columns
32-37. table_constraints Columns
32-38. table_privileges Columns
32-39. tables Columns
32-40. triggers Columns
32-41. usage_privileges Columns
32-42. view_column_usage Columns
32-43. view_routine_usage Columns
32-44. view_table_usage Columns
32-45. views Columns
33-1. Equivalent C Types for Built-In SQL Types
33-2. B-tree Strategies
33-3. Hash Strategies
33-4. GiST Two-Dimensional "R-tree" Strategies
33-5. GIN Array Strategies
33-6. B-tree Support Functions
33-7. Hash Support Functions
33-8. GiST Support Functions
33-9. GIN Support Functions
43-1. System Catalogs
43-2. pg_aggregate Columns
43-3. pg_am Columns
43-4. pg_amop Columns
43-5. pg_amproc Columns
43-6. pg_attrdef Columns
43-7. pg_attribute Columns
43-8. pg_authid Columns
43-9. pg_auth_members Columns
43-10. pg_autovacuum Columns
43-11. pg_cast Columns
43-12. pg_class Columns
43-13. pg_constraint Columns
43-14. pg_conversion Columns
43-15. pg_database Columns
43-16. pg_depend Columns
43-17. pg_description Columns
43-18. pg_index Columns
43-19. pg_inherits Columns
43-20. pg_language Columns
43-21. pg_largeobject Columns
43-22. pg_listener Columns
43-23. pg_namespace Columns
43-24. pg_opclass Columns
43-25. pg_operator Columns
43-26. pg_pltemplate Columns
43-27. pg_proc Columns
43-28. pg_rewrite Columns
43-29. pg_shdepend Columns
43-30. pg_shdescription Columns
43-31. pg_statistic Columns
43-32. pg_tablespace Columns
43-33. pg_trigger Columns
43-34. pg_type Columns
43-35. System Views
43-36. pg_cursors Columns
43-37. pg_group Columns
43-38. pg_indexes Columns
43-39. pg_locks Columns
43-40. pg_prepared_statements Columns

43-41. pg_prepared_xacts Columns
43-42. pg_roles Columns
43-43. pg_rules Columns
43-44. pg_settings Columns
43-45. pg_shadow Columns
43-46. pg_stats Columns
43-47. pg_tables Columns
43-48. pg_timezone_abbrevs Columns
43-49. pg_timezone_names Columns
43-50. pg_user Columns
43-51. pg_views Columns
52-1. Contents of PGDATA
52-2. Overall Page Layout
52-3. PageHeaderData Layout
52-4. HeapTupleHeaderData Layout
A-1. PostgreSQL Error Codes
B-1. Month Names
B-2. Day of the Week Names
B-3. Date/Time Field Modifiers
C-1. SQL Key Words
H-1. Externally Maintained Client Interfaces
H-2. Externally Maintained Procedural Languages
Lista de Figuras
48-1. Structured Diagram of a Genetic Algorithm
Lista de Exemplos
8-1. Using the character types
8-2. Using the boolean type
8-3. Using the bit string types
10-1. Exponentiation Operator Type Resolution
10-2. String Concatenation Operator Type Resolution
10-3. Absolute-Value and Negation Operator Type Resolution
10-4. Rounding Function Argument Type Resolution
10-5. Substring Function Type Resolution
10-6. character Storage Type Conversion
10-7. Type Resolution with Underspecified Types in a Union
10-8. Type Resolution in a Simple Union
10-9. Type Resolution in a Transposed Union
11-1. Setting up a Partial Index to Exclude Common Values
11-2. Setting up a Partial Index to Exclude Uninteresting Values
11-3. Setting up a Partial Unique Index
20-1. Example pg_hba.conf entries
20-2. An example pg_ident.conf file
29-1. libpq Example Program 1
30-1. Large Objects with libpq Example Program
33-1. Função para agregar texto
33-2. Função para agregar texto com dois parâmetros
33-3. Função para gerar histograma
33-4. Função para listar inteiros
36-1. Manual Installation of PL/pgSQL
37-1. Exceptions with UPDATE/INSERT
37-2. A PL/pgSQL Trigger Procedure
37-3. A PL/pgSQL Trigger Procedure For Auditing
37-4. A PL/pgSQL Trigger Procedure For Maintaining A Summary Table
37-5. Porting a Simple Function from PL/SQL to PL/pgSQL
37-6. Porting a Function that Creates Another Function from PL/SQL to PL/pgSQL
37-7. Porting a Procedure With String Manipulation and OUT Parameters from PL/SQL to PL/pgSQL
37-8. Porting a Procedure from PL/SQL to PL/pgSQL
Acima Próxima
Subir um nível Prefácio
Prefácio

Anterior Início Fim Próxima
Prefácio
Sumário
Conventions
Further Information
Este livro é a documentação oficial do PostgreSQL, escrita por seus desenvolvedores e outros
voluntários em paralelo ao desenvolvimento do software. Nesta documentação estão descritas
todas as funcionalidades suportadas oficialmente pela versão corrente do PostgreSQL.
Para tornar uma grande quantidade de informações sobre o PostgreSQL gerenciável, este livro está
organizado em várias partes. Cada parte se destina a uma classe diferente de usuários, ou a
usuários com graus diferentes de experiência com o PostgreSQL:
Parte I é uma introdução informal para os novos usuários.
Parte II documenta o ambiente da linguagem de comandos SQL, incluindo tipos de dado e

funções, assim como ajuste de desempenho no nível de usuário. Todo usuário do PostgreSQL
deve ler esta parte.
Parte III descreve a instalação e a administração do servidor. Todas as pessoas responsáveis

pelo servidor PostgreSQL, seja para uso particular ou por terceiros, devem ler esta parte.
Parte IV descreve as interfaces de programação para os programas cliente do PostgreSQL.
Parte V contém informações para os usuários avançados sobre a capacidade de extensão do

servidor. Os tópicos incluem, por exemplo, tipos de dado definidos pelos usuários e funções.
Parte VI contém informações de referência sobre os comandos SQL, programas cliente e

servidor. Esta parte apóia as outras partes com informações estruturadas classificadas por
comando ou por programa.
Parte VII contém diversas informações úteis para os desenvolvedores do PostgreSQL.
Anterior Principal Próxima

Documentação do PostgreSQL O que é o PostgreSQL?
8.2.0
http://pgdocptbr.sourceforge.net/pg82/preface.html[09/02/2018 17:48:02]

Anterior Início Prefácio Fim Próxima
O PostgreSQL é um sistema de gerenciamento de banco de dados objeto-relacional (SGBDOR) [1]
baseado no POSTGRES Versão 4.2 desenvolvido pelo Departamento de Ciência da Computação da
Universidade da Califórnia em Berkeley. O POSTGRES foi pioneiro em vários conceitos que somente
se tornaram disponíveis muito mais tarde em alguns sistemas de banco de dados comerciais.
O PostgreSQL é um descendente de código fonte aberto deste código original de Berkeley, que
suporta grande parte do padrão SQL e oferece muitas funcionalidades modernas, como:
comandos complexos
chaves estrangeiras
gatilhos
visões
integridade transacional
controle de simultaneidade multiversão
Além disso, o PostgreSQL pode ser ampliado pelo usuário de muitas maneiras como, por exemplo,
adicionando novos
tipos de dado
funções
operadores
funções de agregação
métodos de índice
linguagens procedurais
Devido à sua licença liberal, o PostgreSQL pode ser utilizado, modificado e distribuído por qualquer
pessoa para qualquer finalidade, seja particular, comercial ou acadêmica, livre de encargos.
Notas
[1]
Um banco de dados objeto-relacional (ORD), ou sistema de gerenciamento de banco de dados
objeto-relacional (ORDBMS ou SGBDOR) é um sistema de gerenciamento de banco de dados
relacional que permite aos desenvolvedores integrar ao banco de dados seus próprios tipos de dado e
métodos personalizados. Muitas idéias dos primeiros esforços para bancos de dados objeto-
relacionais foram amplamente adicionadas ao SQL:1999. Na verdade, todo produto que adere aos
aspectos orientados a objeto do SQL:1999 pode ser descrito como um produto de gerenciamento de
banco de dados objeto-relacional. Por exemplo, o DB2 da IBM, o Oracle e o SQL Server da Microsoft
declaram suportar esta tecnologia com graus variados de sucesso. — Object-relational database

Prefácio Acima Uma breve história do PostgreSQL
http://pgdocptbr.sourceforge.net/pg82/intro-whatis.html[09/02/2018 17:48:16]


O sistema de gerenciamento de banco de dados objeto-relacional hoje conhecido por PostgreSQL, é
derivado do pacote POSTGRES escrito na Universidade da Califórnia em Berkeley. Com mais de uma
década de desenvolvimento por trás, o PostgreSQL é atualmente o mais avançado banco de dados
de código aberto disponível em qualquer lugar.
O projeto POSTGRES de Berkeley
O projeto POSTGRES, liderado pelo Professor Michael Stonebraker, foi patrocinado pela Defense
Advanced Research Projects Agency (DARPA), pelo Army Research Office (ARO), pela National Science
Foundation (NSF)) e pela ESL, Inc. A implementação do POSTGRES começou em 1986. Os conceitos
iniciais para o sistema foram apresentados em The design of POSTGRES , e a definição do modelo de
dados inicial foi descrita em The POSTGRES data model . O projeto do sistema de regras desta época
foi descrito em The design of the POSTGRES rules system. Os fundamentos lógicos e a arquitetura do
gerenciador de armazenamento foram detalhados em The design of the POSTGRES storage system .
O Postgres passou por várias versões principais desde então. A primeira "versão de demonstração"
do sistema se tornou operacional em 1987, e foi exibida em 1988 na Conferência ACM-SIGMOD. A
versão 1, descrita em The implementation of POSTGRES , foi liberada para alguns poucos usuários
externos em junho de 1989. Em resposta à crítica ao primeiro sistema de regras (A commentary on
the POSTGRES rules system ), o sistema de regras foi reprojetado (On Rules, Procedures, Caching and
Views in Database Systems ), e a versão 2 foi liberada em junho de 1990, contendo um novo sistema
de regras. A versão 3 surgiu em 1991 adicionando suporte a múltiplos gerenciadores de
armazenamento, um executor de comandos melhorado, e um sistema de regras reescrito. Em sua
maior parte as versões seguintes, até o Postgres95 (veja abaixo), focaram a portabilidade e a
confiabilidade.
O POSTGRES tem sido usado para implementar muitos aplicativos diferentes de pesquisa e de
produção, incluindo: sistema de análise de dados financeiros, pacote de monitoração de
desempenho de motor a jato, banco de dados de acompanhamento de asteróides, banco de dados
de informações médicas, e vários sistemas de informações geográficas. O POSTGRES também tem
sido usado como ferramenta educacional por várias universidades. Por fim, a Illustra Information
Technologies (posteriormente incorporada pela Informix, que agora pertence à IBM) pegou o código
e o comercializou. O POSTGRES se tornou o gerenciador de dados principal do projeto de
computação científica Sequoia 2000 no final de 1992.
O tamanho da comunidade de usuários externos praticamente dobrou durante o ano de 1993.

Começou a ficar cada vez mais óbvio que a manutenção do código do protótipo e o suporte estavam
consumindo grande parte do tempo que deveria ser dedicado a pesquisas de banco de dados. Em
um esforço para reduzir esta sobrecarga de suporte, o projeto do POSTGRES de Berkeley terminou
oficialmente na versão 4.2.
O Postgres95
Em 1994, Andrew Yu e Jolly Chen adicionaram um interpretador da linguagem SQL ao POSTGRES.

Sob um novo nome, o Postgres95 foi em seguida liberado na Web para encontrar seu próprio
caminho no mundo, como descendente de código aberto do código original do POSTGRES de
Berkeley.
http://pgdocptbr.sourceforge.net/pg82/history.html[09/02/2018 17:48:29]
O código do Postgres95 era totalmente escrito em ANSI C, com tamanho reduzido em 25%. Muitas
mudanças internas melhoraram o desempenho e a facilidade de manutenção. O Postgres95 versão
1.0.x era 30-50% mais rápido que o POSTGRES versão 4.2, pelo Wisconsin Benchmark. Além da
correção de erros, as principais melhorias foram as seguintes:
A linguagem de comandos PostQUEL foi substituída pela linguagem SQL (implementada no

servidor). Não foram permitidas subconsultas até o PostgreSQL (veja abaixo), mas estas
podiam ser simuladas no Postgres95 por meio de funções SQL definidas pelo usuário. As
funções de agregação foram reimplementadas. Também foi adicionado suporte a cláusula
GROUP BY nas consultas.
Foi fornecido um novo programa para executar comandos SQL interativos, o psql, utilizando o
Readline do GNU, que substituiu com vantagens o programa monitor antigo.
Uma nova biblioteca cliente, a libpgtcl, dava suporte a clientes baseados no Tcl. O
interpretador de comandos pgtclsh fornecia novos comandos Tcl para interfacear programas
Tcl com o servidor Postgres95.
A interface para objetos grandes foi revisada. A inversão de objetos grandes [1] era o único
mecanismo para armazenar objetos grandes (O sistema de arquivos inversão foi removido).
O sistema de regras no nível de instância foi removido. As regras ainda eram disponíveis
como regras de reescrita.
Um breve tutorial introduzindo as funcionalidades regulares da linguagem SQL, assim como as

do Postgres95, foi distribuído junto com o código fonte.
O utilitário make do GNU (em vez do make do BSD) foi utilizado para a geração. Além disso, o
Postgres95 podia ser compilado com o GCC sem correções (o alinhamento de dados para a
precisão dupla foi corrigido).
O PostgreSQL
Em 1996 ficou claro que o nome "Postgres95" não resistiria ao teste do tempo. Foi escolhido um
novo nome, PostgreSQL, para refletir o relacionamento entre o POSTGRES original e as versões
mais recentes com capacidade SQL. Ao mesmo tempo, foi mudado o número da versão para
começar em 6.0, colocando a numeração de volta à seqüência original começada pelo projeto
POSTGRES de Berkeley.
A ênfase durante o desenvolvimento do Postgres95 era identificar e compreender os problemas

existentes no código do servidor. Com o PostgreSQL a ênfase foi reorientada para o aumento das
funcionalidades e recursos, embora o trabalho continuasse em todas as áreas.
Os detalhes sobre o que aconteceu com o PostgreSQL desde então podem ser encontrados no
Apêndice E.
Notas
[1]
A implementação da inversão de objetos grandes divide os objetos grandes em "pedaços", e
armazena os pedaços em linhas no banco de dados. Um índice B-tree garante a procura rápida do
número correto do pedaço ao serem feitos acessos aleatórios de leitura e gravação. Manual de
Referência do PostgreSQL 6.3 (N. do T.)

O que é o PostgreSQL? Acima Conventions
http://pgdocptbr.sourceforge.net/pg82/history.html[09/02/2018 17:48:29]
Conventions

Conventions
This book uses the following typographical conventions to mark certain portions of text: new terms,
foreign phrases, and other important passages are emphasized in italics. Everything that represents
input or output of the computer, in particular commands, program code, and screen output, is
shown in a monospaced font (example). Within such passages, italics (exemplo) indicate
placeholders; you must insert an actual value instead of the placeholder. On occasion, parts of
program code are emphasized in bold face (example ), if they have been added or changed since
the preceding example.
The following conventions are used in the synopsis of a command: brackets ([ and ]) indicate
optional parts. (In the synopsis of a Tcl command, question marks (?) are used instead, as is usual
in Tcl.) Braces ({ and }) and vertical lines (|) indicate that you must choose one alternative. Dots
(...) mean that the preceding element can be repeated.
Where it enhances the clarity, SQL commands are preceded by the prompt =>, and shell
commands are preceded by the prompt $. Normally, prompts are not shown, though.
An administrator is generally a person who is in charge of installing and running the server. A user
could be anyone who is using, or wants to use, any part of the PostgreSQL system. These terms
should not be interpreted too narrowly; this book does not have fixed presumptions about system
administration procedures.

Uma breve história do PostgreSQL Acima Further Information
http://pgdocptbr.sourceforge.net/pg82/notation.html[09/02/2018 17:48:42]
Further Information

Further Information
Besides the documentation, that is, this book, there are other resources about PostgreSQL:
FAQs
The FAQ list contains continuously updated answers to frequently asked questions.
READMEs
README files are available for most contributed packages.
Web Site
The PostgreSQL web site carries details on the latest release and other information to make
your work or play with PostgreSQL more productive.
Mailing Lists
The mailing lists are a good place to have your questions answered, to share experiences with
other users, and to contact the developers. Consult the PostgreSQL web site for details.
Yourself!
PostgreSQL is an open-source project. As such, it depends on the user community for ongoing
support. As you begin to use PostgreSQL, you will rely on others for help, either through the
documentation or through the mailing lists. Consider contributing your knowledge back. Read
the mailing lists and answer questions. If you learn something which is not in the
documentation, write it up and contribute it. If you add features to the code, contribute them.

Conventions Acima Bug Reporting Guidelines
http://pgdocptbr.sourceforge.net/pg82/resources.html[09/02/2018 17:48:51]


When you find a bug in PostgreSQL we want to hear about it. Your bug reports play an important
part in making PostgreSQL more reliable because even the utmost care cannot guarantee that
every part of PostgreSQL will work on every platform under every circumstance.
The following suggestions are intended to assist you in forming bug reports that can be handled in
an effective fashion. No one is required to follow them but doing so tends to be to everyone's
advantage.
We cannot promise to fix every bug right away. If the bug is obvious, critical, or affects a lot of
users, chances are good that someone will look into it. It could also happen that we tell you to
update to a newer version to see if the bug happens there. Or we might decide that the bug cannot
be fixed before some major rewrite we might be planning is done. Or perhaps it is simply too hard
and there are more important things on the agenda. If you need help immediately, consider
obtaining a commercial support contract.
Identifying Bugs
Before you report a bug, please read and re-read the documentation to verify that you can really do
whatever it is you are trying. If it is not clear from the documentation whether you can do
something or not, please report that too; it is a bug in the documentation. If it turns out that a
program does something different from what the documentation says, that is a bug. That might
include, but is not limited to, the following circumstances:
A program terminates with a fatal signal or an operating system error message that would
point to a problem in the program. (A counterexample might be a "disk full" message, since
you have to fix that yourself.)
A program produces the wrong output for any given input.
A program refuses to accept valid input (as defined in the documentation).
A program accepts invalid input without a notice or error message. But keep in mind that your
idea of invalid input might be our idea of an extension or compatibility with traditional
practice.
PostgreSQL fails to compile, build, or install according to the instructions on supported

platforms.
Here "program" refers to any executable, not only the backend server.
Being slow or resource-hogging is not necessarily a bug. Read the documentation or ask on one of
the mailing lists for help in tuning your applications. Failing to comply to the SQL standard is not
necessarily a bug either, unless compliance for the specific feature is explicitly claimed.
Before you continue, check on the TODO list and in the FAQ to see if your bug is already known. If
you cannot decode the information on the TODO list, report your problem. The least we can do is
make the TODO list clearer.
What to report
The most important thing to remember about bug reporting is to state all the facts and only facts.
http://pgdocptbr.sourceforge.net/pg82/bug-reporting.html[09/02/2018 17:49:18]
Do not speculate what you think went wrong, what "it seemed to do", or which part of the program
has a fault. If you are not familiar with the implementation you would probably guess wrong and
not help us a bit. And even if you are, educated explanations are a great supplement to but no
substitute for facts. If we are going to fix the bug we still have to see it happen for ourselves first.
Reporting the bare facts is relatively straightforward (you can probably copy and paste them from
the screen) but all too often important details are left out because someone thought it does not
matter or the report would be understood anyway.
The following items should be contained in every bug report:
The exact sequence of steps from program start-up necessary to reproduce the problem. This
should be self-contained; it is not enough to send in a bare SELECT statement without the
preceding CREATE TABLE and INSERT statements, if the output should depend on the data in
the tables. We do not have the time to reverse-engineer your database schema, and if we are
supposed to make up our own data we would probably miss the problem.
The best format for a test case for SQL-related problems is a file that can be run through the
psql frontend that shows the problem. (Be sure to not have anything in your ~/.psqlrc start-
up file.) An easy start at this file is to use pg_dump to dump out the table declarations and
data needed to set the scene, then add the problem query. You are encouraged to minimize
the size of your example, but this is not absolutely necessary. If the bug is reproducible, we
will find it either way.
If your application uses some other client interface, such as PHP, then please try to isolate the
offending queries. We will probably not set up a web server to reproduce your problem. In any
case remember to provide the exact input files; do not guess that the problem happens for
"large files" or "midsize databases", etc. since this information is too inexact to be of use.
The output you got. Please do not say that it "didn't work" or "crashed". If there is an error
message, show it, even if you do not understand it. If the program terminates with an
operating system error, say which. If nothing at all happens, say so. Even if the result of your
test case is a program crash or otherwise obvious it might not happen on our platform. The
easiest thing is to copy the output from the terminal, if possible.
Nota: If you are reporting an error message, please obtain the most verbose form
of the message. In psql, say \set VERBOSITY verbose beforehand. If you are
extracting the message from the server log, set the run-time parameter
log_error_verbosity to verbose so that all details are logged.
Nota: In case of fatal errors, the error message reported by the client might not
contain all the information available. Please also look at the log output of the
database server. If you do not keep your server's log output, this would be a good
time to start doing so.
The output you expected is very important to state. If you just write "This command gives me
that output." or "This is not what I expected.", we might run it ourselves, scan the output,
and think it looks OK and is exactly what we expected. We should not have to spend the time
to decode the exact semantics behind your commands. Especially refrain from merely saying
that "This is not what SQL says/Oracle does." Digging out the correct behavior from SQL is not
a fun undertaking, nor do we all know how all the other relational databases out there
behave. (If your problem is a program crash, you can obviously omit this item.)
Any command line options and other start-up options, including any relevant environment
variables or configuration files that you changed from the default. Again, please provide exact
information. If you are using a prepackaged distribution that starts the database server at
boot time, you should try to find out how that is done.
Anything you did at all differently from the installation instructions.
The PostgreSQL version. You can run the command SELECT version(); to find out the version
of the server you are connected to. Most executable programs also support a --version option;
at least postgres --version and psql --version should work. If the function or the options do
not exist then your version is more than old enough to warrant an upgrade. If you run a
prepackaged version, such as RPMs, say so, including any subversion the package may have.
If you are talking about a CVS snapshot, mention that, including its date and time.
If your version is older than 8.2.0 we will almost certainly tell you to upgrade. There are many
bug fixes and improvements in each new release, so it is quite possible that a bug you have
encountered in an older release of PostgreSQL has already been fixed. We can only provide
limited support for sites using older releases of PostgreSQL; if you require more than we can
provide, consider acquiring a commercial support contract.
Platform information. This includes the kernel name and version, C library, processor, memory
information, and so on. In most cases it is sufficient to report the vendor and version, but do
not assume everyone knows what exactly "Debian" contains or that everyone runs on
Pentiums. If you have installation problems then information about the toolchain on your
machine (compiler, make, and so on) is also necessary.
Do not be afraid if your bug report becomes rather lengthy. That is a fact of life. It is better to
report everything the first time than us having to squeeze the facts out of you. On the other hand,
if your input files are huge, it is fair to ask first whether somebody is interested in looking into it.
Here is an article that outlines some more tips on reporting bugs.
Do not spend all your time to figure out which changes in the input make the problem go away.
This will probably not help solving it. If it turns out that the bug cannot be fixed right away, you will
still have time to find and share your work-around. Also, once again, do not waste your time
guessing why the bug exists. We will find that out soon enough.
When writing a bug report, please avoid confusing terminology. The software package in total is
called "PostgreSQL", sometimes "Postgres" for short. If you are specifically talking about the
backend server, mention that, do not just say "PostgreSQL crashes". A crash of a single backend
server process is quite different from crash of the parent "postgres" process; please don't say "the
server crashed" when you mean a single backend process went down, nor vice versa. Also, client
programs such as the interactive frontend "psql" are completely separate from the backend. Please
try to be specific about whether the problem is on the client or server side.
Where to report bugs
In general, send bug reports to the bug report mailing list at <pgsql-bugs@postgresql.org> . You are
requested to use a descriptive subject for your email message, perhaps parts of the error message.
Another method is to fill in the bug report web-form available at the project's web site. Entering a
bug report this way causes it to be mailed to the <pgsql-bugs@postgresql.org> mailing list.
If your bug report has security implications and you'd prefer that it not become immediately visible
in public archives, don't send it to pgsql-bugs. Security issues can be reported privately to
<security@postgresql.org> .
Do not send bug reports to any of the user mailing lists, such as <pgsql-sql@postgresql.org> or
<pgsql-general@postgresql.org> . These mailing lists are for answering user questions, and their
subscribers normally do not wish to receive bug reports. More importantly, they are unlikely to fix
them.
Also, please do not send reports to the developers' mailing list <pgsql-hackers@postgresql.org> .
This list is for discussing the development of PostgreSQL, and it would be nice if we could keep the
bug reports separate. We might choose to take up a discussion about your bug report on pgsql-
hackers, if the problem needs more review.
If you have a problem with the documentation, the best place to report it is the documentation
mailing list <pgsql-docs@postgresql.org> . Please be specific about what part of the documentation
you are unhappy with.
If your bug is a portability problem on a non-supported platform, send mail to <pgsql-

ports@postgresql.org> , so we (and you) can work on porting PostgreSQL to your platform.
Nota: Due to the unfortunate amount of spam going around, all of the above email
addresses are closed mailing lists. That is, you need to be subscribed to a list to be
allowed to post on it. (You need not be subscribed to use the bug-report web form,
however.) If you would like to send mail but do not want to receive list traffic, you can
subscribe and set your subscription option to nomail. For more information send mail to
<majordomo@postgresql.org> with the single word help in the body of the message.

Further Information Acima Tutorial
Tutorial

I. Tutorial
Bem vindo ao Tutorial do PostgreSQL. Os poucos capítulos a seguir têm por objetivo fornecer uma
introdução simples ao PostgreSQL, aos conceitos de banco de dados relacional e à linguagem SQL,
para os iniciantes em qualquer um destes tópicos. Somente é pressuposto um conhecimento geral
sobre a utilização de computadores. Não é necessária nenhuma experiência com Unix ou em
programação. Esta parte tem como objetivo principal fornecer experiência prática sobre os aspectos
importantes do sistema PostgreSQL. Não há nenhuma intenção em dar-se um tratamento completo
ou abrangente dos tópicos cobertos.
Após ler este tutorial pode-se prosseguir através da leitura da Parte II para obter um maior
conhecimento formal da linguagem SQL, ou da Parte IV para obter informações sobre o
desenvolvimento de aplicativos para o PostgreSQL. Aqueles que instalam e gerenciam seus próprios
servidores também devem ler a Parte III.
Sumário
1. Início
1.1. Instalação
1.2. Fundamentos da arquitetura
1.3. Criação de banco de dados
1.4. Acesso a banco de dados
2. A linguagem SQL
2.1. Introdução
2.2. Conceitos
2.3. Criação de tabelas
2.4. Inserção de linhas em tabelas
2.5. Consultar tabelas
2.6. Junções entre tabelas
2.7. Funções de agregação
2.8. Atualizações
2.9. Exclusões
3. Funcionalidades avançadas
3.1. Introdução
3.2. Visões
3.3. Chaves estrangeiras
3.4. Transações
3.5. Herança
3.6. Conclusão

Bug Reporting Guidelines Início
http://pgdocptbr.sourceforge.net/pg82/tutorial.html[09/02/2018 17:49:35]
Início

Capítulo 1. Início
Sumário
1.1. Instalação

Tutorial Acima Instalação
http://pgdocptbr.sourceforge.net/pg82/tutorial-start.html[09/02/2018 17:49:46]
Instalação

Anterior Início Capítulo 1. Início Fim Próxima
1.1. Instalação
Antes de usar o PostgreSQL é necessário instalá-lo, obviamente. É possível que o PostgreSQL já
esteja instalado na máquina, seja porque está incluído na distribuição do sistema operacional [1] ,
ou porque o administrador do sistema fez a instalação. Se este for o caso, devem ser obtidas
informações na documentação do sistema operacional, ou com o administrador do sistema, sobre
como acessar o PostgreSQL.
Não havendo certeza se o PostgreSQL está disponível, ou se pode ser utilizado para seus
experimentos, então você mesmo poderá fazer a instalação. Proceder desta maneira não é difícil,
podendo ser um bom exercício. O PostgreSQL pode ser instalado por qualquer usuário sem
privilégios, porque não é necessário nenhum acesso de superusuário (root).
Se for instalar o PostgreSQL por si próprio, então leia o Capítulo 14 para conhecer as instruções de
instalação, e depois retorne para este capítulo quando a instalação estiver terminada. Certifique-se
de seguir de perto a seção sobre a configuração das variáveis de ambiente apropriadas.
Se o administrador do sistema não fez a configuração da maneira padrão, talvez seja necessário
algum trabalho adicional. Por exemplo, se a máquina servidora de banco de dados for uma máquina
remota, será necessário definir a variável de ambiente PGHOST com o nome da máquina servidora
de banco de dados. Também, talvez tenha que ser definida a variável de ambiente PGPORT. A regra
básica é esta: quando se tenta iniciar um programa aplicativo e este informa que não está
conseguindo conectar com o banco de dados, deve ser consultado o administrador do servidor ou,
caso seja você mesmo, a documentação, para ter certeza que o ambiente está configurado de
maneira apropriada. Caso não tenha entendido o parágrafo anterior então, por favor, leia a próxima
seção.
Notas
[1]
distribuição — Uma árvore de código fonte de software empacotada para distribuição; Desde cerca
de 1996 a utilização não qualificada deste termo geralmente implica numa "distribuição Linux". A
forma curta "distro" geralmente é utilizada neste sentido. The Jargon File (N. do T.)

Início Acima Fundamentos da arquitetura
http://pgdocptbr.sourceforge.net/pg82/tutorial-install.html[09/02/2018 17:49:55]
Fundamentos da arquitetura


Antes de prosseguir, é necessário conhecer a arquitetura de sistema básica do PostgreSQL.
Compreender como as partes do PostgreSQL interagem torna este capítulo mais claro.
No jargão de banco de dados, o PostgreSQL utiliza o modelo cliente-servidor. Uma sessão do

PostgreSQL consiste nos seguintes processos (programas) cooperando entre si:
Um processo servidor, que gerencia os arquivos de banco de dados, aceita conexões dos
aplicativos cliente com o banco de dados, e executa ações no banco de dados em nome dos
clientes. O programa servidor de banco de dados se chama postgres.
O aplicativo cliente do usuário (frontend) que deseja executar operações de banco de dados.
Os aplicativos cliente podem ter naturezas muito diversas: o cliente pode ser uma ferramenta
no modo caractere, um aplicativo gráfico, um servidor Web que acessa o banco de dados para
mostrar páginas Web, ou uma ferramenta especializada para manutenção do banco de dados.
Alguns aplicativos cliente são fornecidos na distribuição do PostgreSQL, sendo a maioria
desenvolvido pelos usuários. [1]
Como é típico na arquitetura cliente-servidor, o cliente e o servidor podem estar em hospedeiros

diferentes. Neste caso, se comunicam através de uma conexão de rede TCP/IP. Deve-se ter isto em
mente, porque arquivos que podem ser acessados na máquina cliente podem ser inacessíveis para
a máquina servidora (ou somente podem ser acessados usando um nome de arquivo diferente).
O servidor PostgreSQL pode tratar várias conexões simultâneas de clientes. Para esta finalidade é
iniciado um novo processo (fork [2] ) para cada conexão. Deste ponto em diante, o cliente e o novo
processo servidor se comunicam sem intervenção do processo postgres original. Por isso, o
processo servidor mestre está sempre executando aguardando por novas conexões dos clientes,
enquanto os clientes e seus processos servidor associados surgem e desaparecem (obviamente
tudo isso é invisível para o usuário, sendo mencionado somente para ficar completo).
Notas
[1]
Também pode ser utilizada a ferramenta de administração do PostgreSQL baseada na Web
phpPgAdmin. (N. do T.)
[2]
fork — Para criar um novo processo, o processo copia a si próprio através da chamada de sistema
fork. O fork cria uma cópia do processo original que é em grande parte idêntica à ancestral. O novo
processo possui um PID (identificador de processo) próprio, e suas próprias informações de
contabilização. O fork possui a propriedade única de retornar dois valores diferentes. Do ponto de
vista do filho retorna zero. Por outro lado, para o pai é retornado o PID do filho recém criado. Uma
vez que fora isso os dois processos são idênticos, ambos precisam examinar o valor retornado para
descobrir o papel a ser desempenhado. Linux Administration Handbook — Evi Nemeth e outros — Prentice
Hall PTR. (N. do T.)

Instalação Acima Criação de banco de dados
http://pgdocptbr.sourceforge.net/pg82/tutorial-arch.html[09/02/2018 17:50:03]
Criação de banco de dados


O primeiro teste para verificar se é possível acessar o servidor de banco de dados é tentar criar um
banco de dados. Um servidor PostgreSQL pode gerenciar muitos bancos de dados. Normalmente é
utilizado um banco de dados em separado para cada projeto ou para cada usuário.
Possivelmente, o administrador já criou um banco de dados para seu uso. Ele deve ter dito qual é o
nome do seu banco de dados. Neste caso esta etapa pode ser omitida, indo-se direto para a
próxima seção.
Para criar um novo banco de dados, chamado meu_bd neste exemplo, deve ser utilizado o
comando:
$ createdb meu_bd
Que deve produzir a seguinte resposta:
CREATE DATABASE
Se esta resposta for mostrada então esta etapa foi bem sucedida, podendo-se pular o restante da
seção.
Se aparecer uma mensagem semelhante a
createdb: comando não encontrado
então o PostgreSQL não foi instalado da maneira correta, ou não foi instalado, ou o caminho de
procura não foi definido corretamente. Tente executar o comando utilizando o caminho absoluto:
$ /usr/local/pgsql/bin/createdb meu_bd
O caminho na sua máquina pode ser diferente. Fale com o administrador, ou verifique novamente
as instruções de instalação para corrigir a situação. [1]
Outra resposta pode ser esta: [2]
createdb: could not connect to database postgres:

could not connect to server: No such file or directory
Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
-- Tradução da mensagem (N. do T.)
createdb: não foi possível conectar com o banco de dados postgres:
não foi possível conectar com o servidor: Arquivo ou diretório inexistente
O servidor está executando localmente e aceitando conexões
no soquete do domínio Unix "/tmp/.s.PGSQL.5432"?
Significando que o servidor não foi inicializado, ou que não foi inicializado onde o createdb esperava
que fosse. Novamente, verifique as instruções de instalação ou consulte o administrador.
Outra resposta pode ser esta:
http://pgdocptbr.sourceforge.net/pg82/tutorial-createdb.html[09/02/2018 17:50:23]
createdb: could not connect to database postgres:

FATAL: role "joel" does not exist
createdb: não foi possível conectar com o banco de dados postgres:
FATAL: o papel "joel" não existe
onde é mencionado o nome de seu login. Isto acontecerá se o administrador não tiver criado uma
conta de usuário no PostgreSQL para seu uso (As contas de usuário do PostgreSQL são distintas das
contas de usuário do sistema operacional). Se você for o administrador, obtenha ajuda para criar
contas no Capítulo 18. Será necessário se tornar o usuário do sistema operacional que instalou o
PostgreSQL (geralmente postgres) para criar a primeira conta de usuário. Também pode ter sido
atribuído para você um nome de usuário do PostgreSQL diferente do nome de usuário do sistema
operacional; neste caso, será necessário utilizar a chave -U, ou definir a variável de ambiente
PGUSER, para especificar o nome de usuário do PostgreSQL.
Caso se possua uma conta de usuário, mas esta conta não possua o privilégio necessário para criar
bancos de dados, será exibida a seguinte mensagem:
createdb: database creation failed:

ERROR: permission denied to create database
createdb: a criação do banco de dados falhou:
ERRO: negada a permissão para criar banco de dados
Nem todo usuário possui autorização para criar bancos de dados. Se o PostgreSQL se recusar a
criar o banco de dados, então o administrador do banco de dados deverá conceder permissão para
você criar bancos de dados. Consulte o administrador caso isto ocorra. Caso tenha instalado o
PostgreSQL por si próprio, então você deverá se conectar ao PostgreSQL sob a mesma conta de
usuário do sistema operacional utilizada para inicializar o servidor, para as finalidades deste
tutorial. [3]
Também podem ser criados bancos de dados com outros nomes. O PostgreSQL permite a criação de
qualquer número de bancos de dados em uma instalação. Os nomes dos bancos de dados devem
ter o primeiro caractere alfabético, sendo limitados a um comprimento de 63 caracteres. Uma
escolha conveniente é criar o banco de dados com o mesmo nome do usuário corrente do sistema
operacional. Muitas ferramentas assumem este nome de banco de dados como sendo o nome
padrão, evitando a necessidade de digitá-lo. Para criar este banco de dados deve ser digitado
simplesmente:
$ createdb
Se não desejar mais utilizar o seu banco de dados, você poderá removê-lo. Por exemplo, se você
for o dono (criador) do banco de dados meu_bd, poderá removê-lo utilizando o seguinte comando:
$ dropdb meu_bd
Para este comando o nome de usuário do sistema operacional não é utilizado como nome padrão do
banco de dados: o nome sempre deve ser especificado. Esta ação remove fisicamente todos os
arquivos associados ao banco de dados não podendo ser desfeita, portanto esta operação somente
deve ser feita após um longo período de reflexão.
Podem ser encontradas informações adicionais sobre os utilitários createdb e dropdb em createdb e
dropdb, respectivamente.
Notas
[1]
/usr/bin/createdb no RedHat, Fedora, Mandrake, Debian e SuSE. (N. do T.)
[2]
soquete — As chamadas de sistema para estabelecer a conexão são um tanto diferentes para o
cliente e para o servidor, mas ambas envolvem basicamente a construção de um soquete. O soquete
é uma extremidade do canal de comunicação entre processos. Cada um dos dois processos
estabelece seu próprio soquete. Para criar o soquete, o programa precisa especificar o domínio de
endereço e o tipo de soquete. Dois processos podem se comunicar somente se seus soquetes são do
mesmo tipo e do mesmo domínio. Existem dois domínios de endereço amplamente utilizados: o
domínio Unix, no qual dois processos compartilham um arquivo do sistema em comum para se
comunicar; e o domínio Internet, no qual dois processos executando em dois hospedeiros quaisquer
na Internet se comunicam. Cada um destes domínios possui seu próprio formato de endereço. O
endereço de soquete do domínio Unix é uma cadeia de caracteres, que é basicamente uma entrada
no sistema de arquivos. O endereço de soquete do domínio Internet consiste no endereço de Internet
da máquina hospedeira (todo computador na Internet possui um endereço único de 32 bits,
geralmente chamado de endereço de IP). Adicionalmente, no domínio Internet, cada soquete
necessita do número da porta no hospedeiro. Sockets Tutorial (N. do T.)
[3]
Uma explicação do motivo pelo qual isto funciona: Os nomes de usuário do PostgreSQL são distintos
das contas de usuário do sistema operacional. Ao estabelecer a conexão com um banco de dados,
pode ser escolhido o nome do usuário do PostgreSQL com o qual se deseja fazer a conexão; Se isto
não for feito, o padrão é utilizar um nome igual ao da conta atual do sistema operacional. Como isto
ocorre, sempre existirá uma conta de usuário do PostgreSQL com nome igual ao do usuário do
sistema operacional que inicializou o servidor; acontece, também, que este usuário sempre tem
permissão para criar banco de dados. Em vez de conectar como este usuário, pode ser especificada a
chave -U em todos os aplicativos para escolher o nome do usuário do PostgreSQL com o qual se
deseja conectar.

Fundamentos da arquitetura Acima Acesso a banco de dados
Acesso a banco de dados


Após o banco de dados ter sido criado, este pode ser acessado pela:
Execução do programa de terminal interativo do PostgreSQL chamado psql, que permite

digitar, editar e executar comandos SQL interativamente.
Utilização de uma ferramenta cliente gráfica existente como o PgAccess, ou de um pacote de

automação de escritórios com suporte a ODBC para criar e manusear bancos de dados. Estas
possibilidades não estão descritas neste tutorial.
Criação de aplicativos personalizados, usando um dos vários vínculos com linguagens

disponíveis. Estas possibilidades são mostradas mais detalhadamente na Parte IV.
Você provavelmente vai desejar ativar o psql para executar os exemplos deste tutorial. O psql pode
ser ativado para usar o banco de dados meu_bd digitando o comando:
$ psql meu_bd
Se o nome do banco de dados for omitido, então será usado o nome padrão igual ao nome da conta
do usuário no sistema operacional. Isto já foi visto na seção anterior.
O psql saúda o usuário com a seguinte mensagem:
Bem-vindo ao psql 8.2.0, o terminal interativo do PostgreSQL.

Digite: \copyright para mostrar a licença da distribuição
\h para ajuda nos comandos SQL
\? para ajuda nos comandos do psql
\g ou finalizar com ponto-e-vírgula para executar o comando
\q para sair
meu_bd=>
A última linha também pode ser
meu_bd=#
significando que o usuário é um superusuário do banco de dados, acontecendo geralmente quando

se instala o PostgreSQL por si próprio. Ser um superusuário significa não estar sujeito a controles
de acesso. Para as finalidades deste tutorial isto não tem importância.
Caso aconteçam problemas ao inicializar o psql, então retorne à seção anterior. Os diagnósticos do
psql e do createdb são semelhantes, e se um funcionou o outro deve funcionar também.
A última linha exibida pelo psql é a linha de comando (prompt), indicando que o psql está lhe
aguardando, e que você pode digitar comandos SQL dentro do espaço de trabalho mantido pelo
psql. Tente estes comandos:
meu_bd=> SELECT version();

version
--------------------------------------------------------------------------------------------
---------------------------
PostgreSQL 8.2.0 on i686-pc-linux-gnu, compiled by GCC gcc (GCC) 4.1.2 20060928
(prerelease) (Ubuntu 4.1.1-13ubuntu5)
(1 linha)
http://pgdocptbr.sourceforge.net/pg82/tutorial-accessdb.html[09/02/2018 17:50:54]
Acesso a banco de dados
meu_bd=> SELECT current_date;

date
------------
2007-03-31
(1 linha)
meu_bd=> SELECT 2 + 2;
?column?
----------
4
(1 linha)
O programa psql possui vários comandos internos que não são comandos SQL. Estes comandos
começam pelo caractere de contrabarra, "\". Alguns destes comandos são mostrados na mensagem
de saudação. Por exemplo, pode ser obtida ajuda sobre a sintaxe de vários comandos SQL do
PostgreSQL digitando:
meu_bd=> \h
Para sair do psql digite
meu_bd=> \q
e o psql terminará retornando para o interpretador de comandos. Para conhecer outros comandos
internos digite \? na linha de comando (prompt) do psql. Todas as funcionalidades do psql estão
documentadas em psql. Se o PostgreSQL tiver sido instalado corretamente, também pode-se digitar
man psql na linha de comando do sistema operacional para ver a documentação. Neste tutorial
estas funcionalidades não serão utilizadas explicitamente, mas use por si próprio quando julgar
adequado.

Criação de banco de dados Acima A linguagem SQL
http://pgdocptbr.sourceforge.net/pg82/tutorial-accessdb.html[09/02/2018 17:50:54]
A linguagem SQL

Capítulo 2. A linguagem SQL

Sumário
2.1. Introdução
2.2. Conceitos
2.8. Atualizações
2.9. Exclusões

Acesso a banco de dados Acima Introdução
http://pgdocptbr.sourceforge.net/pg82/tutorial-sql.html[09/02/2018 17:51:14]
Introdução

Anterior Início Capítulo 2. A linguagem SQL Fim Próxima
2.1. Introdução
Este capítulo fornece uma visão geral sobre como utilizar a linguagem SQL para realizar operações
simples. O propósito deste tutorial é apenas fazer uma introdução e, de forma alguma, ser um
tutorial completo sobre a linguagem SQL. Existem muitos livros escritos sobre a linguagem SQL,
incluindo Understanding the New SQL e A Guide to the SQL Standard. É preciso estar ciente que
algumas funcionalidades da linguagem SQL do PostgreSQL são extensões ao padrão.
Nos exemplos a seguir supõe-se que tenha sido criado o banco de dados chamado meu_bd,
conforme descrito no capítulo anterior, e que o psql esteja ativo.
Os exemplos presentes neste manual também podem ser encontrados na distribuição do código
fonte do PostgreSQL, no diretório src/tutorial/. [1] Para usar estes arquivos, primeiro deve-se
tornar o diretório src/tutorial/ o diretório corrente, e depois executar o utilitário make, conforme
mostrado abaixo:
$ cd ..../src/tutorial
$ make
Este procedimento cria os scripts e compila os arquivos C contendo as funções e tipos definidos pelo
usuário (Se tiver sido instalada uma versão pré-empacotada do PostgreSQL em vez de ter sido
construído a partir do código fonte, deve ser procurado o diretório tutorial na documentação do
PostgreSQL. A parte do "make" já deve ter sido feita para você). Depois disso, para iniciar o tutorial
faça o seguinte:
$ cd ..../tutorial
$ psql -s meu_bd
...
meu_bd=> \i basics.sql
O comando \i lê os comandos no arquivo especificado. A opção -s ativa o modo passo a passo, que
faz uma pausa antes de enviar cada comando para o servidor. Os comandos utilizados nesta seção
estão no arquivo basics.sql.
Notas
[1]
Os arquivos basics.sql e advanced.sql foram traduzidos e colocados como links nesta tradução. Para
usá-los basta salvar os arquivos em disco, abrir o interpretador de comandos, tornar o diretório onde
os arquivos foram salvos o diretório corrente, executar na linha de comando psql -s meu_bd e usar o
comando \i basics.sql ou \i advanced.sql para executar o arquivo, como mostrado neste capítulo. (N.
do T.)

A linguagem SQL Acima Conceitos
http://pgdocptbr.sourceforge.net/pg82/tutorial-sql-intro.html[09/02/2018 17:51:28]
Conceitos

2.2. Conceitos
O PostgreSQL é um sistema de gerenciamento de banco de dados relacional (SGBDR). Isto
significa que é um sistema para gerenciar dados armazenados em relações. Relação é,
essencialmente, um termo matemático para tabela. A noção de armazenar dados em tabelas é tão
trivial hoje em dia que pode parecer totalmente óbvio, mas existem várias outras formas de
organizar bancos de dados. Arquivos e diretórios em sistemas operacionais tipo Unix são um
exemplo de banco de dados hierárquico. Um desenvolvimento mais moderno são os bancos de
dados orientados a objeto.
Cada tabela é uma coleção nomeada de linhas. Todas as linhas de uma determinada tabela
possuem o mesmo conjunto de colunas nomeadas, e cada coluna é de um tipo de dado específico.
Enquanto as colunas possuem uma ordem fixa nas linhas, é importante lembrar que o SQL não
garante a ordem das linhas dentro de uma tabela (embora as linhas possam ser explicitamente
ordenadas para a exibição).
As tabelas são agrupadas em bancos de dados, e uma coleção de bancos de dados gerenciados por
uma única instância do servidor PostgreSQL forma um agrupamento de bancos de dados.

Introdução Acima Criação de tabelas
http://pgdocptbr.sourceforge.net/pg82/tutorial-concepts.html[09/02/2018 17:51:37]
Criação de tabelas


Pode-se criar uma tabela especificando o seu nome juntamente com os nomes das colunas e seus
tipos de dado:
CREATE TABLE clima (

cidade varchar(80),
temp_min int, -- temperatura mínima
temp_max int, -- temperatura máxima
prcp real, -- precipitação
data date
);
Este comando pode ser digitado no psql com quebras de linha. O psql reconhece que o comando só
termina quando é encontrado o ponto-e-vírgula.
Espaços em branco (ou seja, espaços, tabulações e novas linhas) podem ser utilizados livremente
nos comandos SQL. Isto significa que o comando pode ser digitado com um alinhamento diferente
do mostrado acima, ou mesmo tudo em uma única linha. Dois hífens ("--") iniciam um comentário;
tudo que vem depois é ignorado até o final da linha. A linguagem SQL não diferencia letras
maiúsculas e minúsculas nas palavras chave e nos identificadores, a não ser que os identificadores
sejam delimitados por aspas (") para preservar letras maiúsculas e minúsculas, o que não foi feito
acima.
No comando, varchar(80) especifica um tipo de dado que pode armazenar cadeias de caracteres
arbitrárias com comprimento até 80 caracteres; int é o tipo inteiro normal; real é o tipo para
armazenar números de ponto flutuante de precisão simples; date é o tipo para armazenar data e
hora (a coluna do tipo date pode se chamar date, o que tanto pode ser conveniente quanto pode
causar confusão).
O PostgreSQL suporta os tipos de dado SQL padrão int, smallint, real, double precision, char(N),
varchar(N), date, time, timestamp e interval, assim como outros tipos de utilidade geral, e um
conjunto diversificado de tipos geométricos. O PostgreSQL pode ser personalizado com um número
arbitrário de tipos de dado definidos pelo usuário. Como conseqüência, sintaticamente os nomes
dos tipos não são palavras chave, exceto onde for requerido para suportar casos especiais do
padrão SQL.
No segundo exemplo são armazenadas cidades e suas localizações geográficas associadas:
CREATE TABLE cidades (

nome varchar(80),
localizacao point
);
O tipo point é um exemplo de tipo de dado específico do PostgreSQL.
Para terminar deve ser mencionado que, quando a tabela não é mais necessária, ou se deseja
recriá-la de uma forma diferente, é possível removê-la por meio do comando:
DROP TABLE nome_da_tabela;

Conceitos Acima Inserção de linhas em tabelas
http://pgdocptbr.sourceforge.net/pg82/tutorial-table.html[09/02/2018 17:51:45]
Inserção de linhas em tabelas


É utilizado o comando INSERT para inserir linhas nas tabelas:
INSERT INTO clima VALUES ('São Francisco', 46, 50, 0.25, '1994-11-27');
Repare que todos os tipos de dado possuem formato de entrada de dados bastante óbvios. As
constantes, que não são valores numéricos simples, geralmente devem estar entre apóstrofos ('),
como no exemplo acima. O tipo date é, na verdade, muito flexível em relação aos dados que aceita,
mas para este tutorial vamos nos fixar no formato sem ambigüidade mostrado acima.
O tipo point requer um par de coordenadas como entrada, como mostrado abaixo:
INSERT INTO cidades VALUES ('São Francisco', '(-194.0, 53.0)');
A sintaxe usada até agora requer que seja lembrada a ordem das colunas. Uma sintaxe alternativa
permite declarar as colunas explicitamente:
INSERT INTO clima (cidade, temp_min, temp_max, prcp, data)

VALUES ('São Francisco', 43, 57, 0.0, '1994-11-29');
Se for desejado, pode-se declarar as colunas em uma ordem diferente, ou mesmo, omitir algumas
colunas. Por exemplo, se a precipitação não for conhecida:
INSERT INTO clima (data, cidade, temp_max, temp_min)

VALUES ('1994-11-29', 'Hayward', 54, 37);
Muitos desenvolvedores consideram que declarar explicitamente as colunas é um estilo melhor que
confiar na ordem implícita.
Por favor, entre todos os comando mostrados acima para ter alguns dados para trabalhar nas
próximas seções.
Também pode ser utilizado o comando COPY para carregar uma grande quantidade de dados a
partir de arquivos texto puro. Geralmente é mais rápido, porque o comando COPY é otimizado para
esta finalidade, embora possua menos flexibilidade que o comando INSERT. Como exemplo
poderíamos ter:
COPY clima FROM '/home/user/clima.txt';
onde o arquivo contendo os dados deve estar disponível para a máquina servidora, e não para a
estação cliente, porque o servidor lê o arquivo diretamente. Podem ser obtidas mais informações
sobre o comando COPY em COPY.

Criação de tabelas Acima Consultar tabelas
http://pgdocptbr.sourceforge.net/pg82/tutorial-populate.html[09/02/2018 17:51:55]
Consultar tabelas


Para trazer os dados de uma tabela, a tabela deve ser consultada. Para esta finalidade é utilizado o
comando SELECT do SQL. Este comando é dividido em lista de seleção (a parte que especifica as
colunas a serem trazidas), lista de tabelas (a parte que especifica as tabelas de onde os dados vão
ser trazidos), e uma qualificação opcional (a parte onde são especificadas as restrições). Por
exemplo, para trazer todas as linhas da tabela clima digite:
SELECT * FROM clima;
Aqui o * é uma forma abreviada de "todas as colunas". [1] Seriam obtidos os mesmos resultados
usando:
SELECT cidade, temp_min, temp_max, prcp, data FROM clima;
A saída deve ser:
cidade | temp_min | temp_max | prcp | data

-----------------+----------+----------+------+------------
São Francisco | 46 | 50 | 0.25 | 1994-11-27
São Francisco | 43 | 57 | 0 | 1994-11-29
Hayward | 37 | 54 | | 1994-11-29
(3 linhas)
Na lista de seleção podem ser especificadas expressões, e não apenas referências a colunas. Por
exemplo, pode ser escrito
SELECT cidade, (temp_max+temp_min)/2 AS temp_media, data FROM clima;
devendo produzir:
cidade | temp_media | data

-----------------+------------+------------
São Francisco | 48 | 1994-11-27
São Francisco | 50 | 1994-11-29
Hayward | 45 | 1994-11-29
(3 linhas)
Perceba que a cláusula AS foi utilizada para mudar o nome da coluna de saída (a cláusula AS é
opcional).
A consulta pode ser "qualificada", adicionando a cláusula WHERE para especificar as linhas
desejadas. A cláusula WHERE contém expressões booleanas (valor verdade), e somente são
retornadas as linhas para as quais o resultado da expressão booleana for verdade. São permitidos
os operadores booleanos usuais (AND, OR e NOT) na qualificação. Por exemplo, o comando abaixo
mostra o clima de São Francisco nos dias de chuva:
SELECT * FROM clima

WHERE cidade = 'São Francisco' AND prcp > 0.0;
Resultado:
http://pgdocptbr.sourceforge.net/pg82/tutorial-select.html[09/02/2018 17:52:27]
Consultar tabelas

-----------------+----------+----------+------+------------
São Francisco | 46 | 50 | 0.25 | 1994-11-27
(1 linha)
Pode ser solicitado que os resultados da consulta sejam retornados em uma determinada ordem:
SELECT * FROM clima

ORDER BY cidade;

-----------------+----------+----------+------+------------
Hayward | 37 | 54 | | 1994-11-29
São Francisco | 43 | 57 | 0 | 1994-11-29
São Francisco | 46 | 50 | 0.25 | 1994-11-27
Neste exemplo a ordem de classificação não está totalmente especificada e, portanto, as linhas de
São Francisco podem retornar em qualquer ordem. Mas sempre seriam obtidos os resultados
mostrados acima se fosse executado:
SELECT * FROM clima

ORDER BY cidade, temp_min;
Pode ser solicitado que as linhas duplicadas sejam removidas do resultado da consulta: [2]
SELECT DISTINCT cidade

FROM clima;
cidade
---------------
Hayward
São Francisco
(2 linhas)
Novamente, neste exemplo a ordem das linhas pode variar. Pode-se garantir resultados
consistentes utilizando DISTINCT e ORDER BY juntos: [3] [4]
SELECT DISTINCT cidade

FROM clima
ORDER BY cidade;
Notas
[1]
Embora o SELECT * seja útil para consultas improvisadas, geralmente é considerado um estilo ruim
para código em produção, uma vez que a adição de uma coluna à tabela mudaria os resultados.
[2]
Oracle — Deve ser especificado DISTINCT ou UNIQUE se for desejado que o banco de dados retorne
apenas um cópia de cada conjunto de linhas duplicadas selecionadas. Estas duas palavras chave são
sinônimos. As linhas duplicadas são aquelas com valores correspondentes para cada expressão da
lista de seleção. Oracle® Database SQL Reference 10g Release 1 (10.1) Part Number B10759-01 (N. do T.)
[3]
Em alguns sistemas de banco de dados, incluindo as versões antigas do PostgreSQL, a
implementação do DISTINCT ordena automaticamente as linhas e, por isso, o ORDER BY não é
necessário. Mas isto não é requerido pelo padrão SQL, e o PostgreSQL corrente não garante que
DISTINCT faça com que as linhas sejam ordenadas.
[4]
Oracle — A seguinte restrição se aplica à cláusula ORDER BY: Se for especificado o operador
DISTINCT no comando SELECT, então a cláusula ORDER BY não poderá fazer referência a colunas, a
menos que estas apareçam na lista de seleção. Oracle® Database SQL Reference 10g Release 1 (10.1)
Part Number B10759-01 (Foi observado que esta restrição também se aplica ao PostgreSQL, ao DB2 e
ao SQL Server). (N. do T.)
Consultar tabelas

Inserção de linhas em tabelas Acima Junções entre tabelas
Junções entre tabelas


Até agora as consultas somente acessaram uma tabela de cada vez. As consultas podem acessar
várias tabelas de uma vez, ou acessar a mesma tabela de uma maneira que várias linhas da tabela
sejam processadas ao mesmo tempo. A consulta que acessa várias linhas da mesma tabela, ou de
tabelas diferentes, de uma vez, é chamada de consulta de junção. Como exemplo, suponha que se
queira listar todas as linhas de clima junto com a localização da cidade associada. Para fazer isto, é
necessário comparar a coluna cidade de cada linha da tabela clima com a coluna nome de todas as
linhas da tabela cidades, e selecionar os pares de linha onde estes valores são correspondentes.
Nota: Este é apenas um modelo conceitual, a junção geralmente é realizada de uma

maneira mais eficiente que realmente comparar cada par de linhas possível, mas isto
não é visível para o usuário.
Esta operação pode ser efetuada por meio da seguinte consulta:
SELECT *
FROM clima, cidades
WHERE cidade = nome;
cidade | temp_min | temp_max | prcp | data | nome | localizacao
-----------------+----------+----------+------+------------+---------------+-------------
São Francisco | 46 | 50 | 0.25 | 1994-11-27 | São Francisco | (-194,53)
São Francisco | 43 | 57 | 0 | 1994-11-29 | São Francisco | (-194,53)
(2 linhas)
Duas coisas devem ser observadas no conjunto de resultados produzido:
Não existe nenhuma linha de resultado para a cidade Hayward. Isto acontece porque não
existe entrada correspondente na tabela cidades para Hayward, e a junção ignora as linhas da
tabela clima sem correspondência. Veremos em breve como isto pode ser corrigido.
Existem duas colunas contendo o nome da cidade, o que está correto porque a lista de
colunas das tabelas clima e cidades estão concatenadas. Na prática isto não é desejado,
sendo preferível, portanto, escrever a lista das colunas de saída explicitamente em vez de
utilizar o *:
SELECT cidade, temp_min, temp_max, prcp, data, localizacao

FROM clima, cidades
Exercício: Tentar descobrir a semântica desta consulta quando a cláusula WHERE é omitida.
Como todas as colunas possuem nomes diferentes, o analisador encontra automaticamente a tabela
que a coluna pertence. Se existissem nomes de colunas duplicados nas duas tabelas, seria
necessário qualificar os nomes das colunas para mostrar qual delas está sendo referenciada, como
em:
SELECT clima.cidade, clima.temp_min, clima.temp_max,

clima.prcp, clima.data, cidades.localizacao
FROM clima, cidades
WHERE cidades.nome = clima.cidade;
Muitos consideram um bom estilo qualificar todos os nomes de colunas nas consultas de junção,
para que a consulta não falhe ao se adicionar posteriormente um nome de coluna duplicado a uma
http://pgdocptbr.sourceforge.net/pg82/tutorial-join.html[09/02/2018 17:52:42]
das tabelas.
As consultas de junção do tipo visto até agora também podem ser escritas da seguinte forma
alternativa:
SELECT *
FROM clima INNER JOIN cidades ON (clima.cidade = cidades.nome);
A utilização desta sintaxe não é tão comum quanto a usada acima, mas é mostrada para ajudar a
entender os próximos tópicos.
Agora vamos descobrir como se faz para obter as linhas de Hayward. Desejamos o seguinte: que a
consulta varra a tabela clima e, para cada uma de suas linhas, encontre a linha correspondente na
tabela cidades. Se não for encontrada nenhuma linha correspondente, desejamos que sejam
colocados "valores vazios" nas colunas da tabela cidades. Este tipo de consulta é chamada de
junção externa (outer join). As junções vistas até agora foram junções internas (inner join). O
comando então fica assim:
SELECT *
FROM clima LEFT OUTER JOIN cidades ON (clima.cidade = cidades.nome);
cidade | temp_min | temp_max | prcp | data | nome | localizacao
-----------------+----------+----------+------+------------+---------------+------------
Hayward | 37 | 54 | | 1994-11-29 | |
São Francisco | 46 | 50 | 0.25 | 1994-11-27 | São Francisco | (-194,53)
São Francisco | 43 | 57 | 0 | 1994-11-29 | São Francisco | (-194,53)
(3 linhas)
Esta consulta é chamada de junção externa esquerda (left outer join), porque a tabela mencionada
à esquerda do operador de junção terá cada uma de suas linhas aparecendo na saída pelo menos
uma vez, enquanto a tabela à direita terá somente as linhas correspondendo a alguma linha da
tabela à esquerda aparecendo na saída. Ao listar uma linha da tabela à esquerda, para a qual não
existe nenhuma linha correspondente na tabela à direita, são colocados valores vazios (nulos) nas
colunas da tabela à direita.
Exercício: Existem também a junção externa direita (right outer join) e a junção externa completa
(full outer join). Tente descobrir o que fazem.
Também é possível fazer a junção da tabela consigo mesma. Isto é chamado de autojunção (self
join). Como exemplo, suponha que desejamos descobrir todas as linhas de clima que estão no
intervalo de temperatura de outros registros de clima. Para isso é necessário comparar as colunas
temp_min e temp_max de cada linha da tabela clima com as colunas temp_min e temp_max de
todos as outras linhas da mesma tabela clima, o que pode ser feito utilizando a seguinte consulta:
SELECT C1.cidade, C1.temp_min AS menor, C1.temp_max AS maior,

C2.cidade, C2.temp_min AS menor, C2.temp_max AS maior
FROM clima C1, clima C2
WHERE C1.temp_min < C2.temp_min
AND C1.temp_max > C2.temp_max;
cidade | menor | maior | cidade | menor | maior
-----------------+-------+-------+---------------+-------+-------
São Francisco | 43 | 57 | São Francisco | 46 | 50
Hayward | 37 | 54 | São Francisco | 46 | 50
(2 linhas)
A tabela clima teve seu nome mudado para C1 e C2, para ser possível distinguir o lado esquerdo e
o lado direito da junção. Estes tipos de "aliases" também podem ser utilizados em outras consultas
para reduzir a digitação como, por exemplo:
SELECT *
FROM clima w, cidades c
WHERE w.cidade = c.nome;
Será encontrada esta forma de abreviar com bastante freqüência.
Consultar tabelas Acima Funções de agregação
Funções de agregação


Como a maioria dos produtos de banco de dados relacional, o PostgreSQL suporta funções de
agregação. Uma função de agregação computa um único resultado para várias linhas de entrada.
Por exemplo, existem funções de agregação para contar (count), somar (sum), calcular a média
(avg), o valor máximo (max) e o valor mínimo (min) para um conjunto de linhas.
Para servir de exemplo, é possível encontrar a maior temperatura mínima observada em qualquer
lugar usando
SELECT max(temp_min) FROM clima;

max
-----
46
(1 linha)
Se for desejado saber a cidade (ou cidades) onde esta temperatura ocorreu pode-se tentar usar
SELECT cidade FROM clima WHERE temp_min = max(temp_min); ERRADO
mas não vai funcionar, porque a função de agregação max não pode ser usada na cláusula WHERE
(Esta restrição existe porque a cláusula WHERE determina quais linhas serão incluídas no cálculo da
agregação e, neste caso, teria que ser avaliada antes das funções de agregação serem
computadas). Entretanto, como é geralmente o caso, a consulta pode ser reformulada para obter o
resultado pretendido, o que será feito por meio de uma subconsulta:
SELECT cidade FROM clima

WHERE temp_min = (SELECT max(temp_min) FROM clima);
cidade
---------------
São Francisco
(1 linha)
Isto está correto porque a subconsulta é uma ação independente, que calcula sua agregação
isoladamente do que está acontecendo na consulta externa.
As agregações também são muito úteis em combinação com a cláusula GROUP BY. Por exemplo,
pode ser obtida a maior temperatura mínima observada em cada cidade usando
SELECT cidade, max(temp_min)

FROM clima
GROUP BY cidade;
cidade | max
-----------------+-----
Hayward | 37
São Francisco | 46
(2 linhas)
produzindo uma linha de saída para cada cidade. Cada resultado da agregação é computado sobre
as linhas da tabela correspondendo a uma cidade. As linhas agrupadas podem ser filtradas
utilizando a cláusula HAVING

FROM clima
http://pgdocptbr.sourceforge.net/pg82/tutorial-agg.html[09/02/2018 17:52:54]
Funções de agregação
GROUP BY cidade
HAVING max(temp_min) < 40;
cidade | max
-----------+-----
Hayward | 37
(1 linha)
que mostra os mesmos resultados, mas apenas para as cidades que possuem os valores de
max(temp_min) abaixo de 40. Para concluir, se desejarmos somente as cidades com nome
começando pela letra "S" podemos escrever:

FROM clima
WHERE cidade LIKE 'S%'(1)
GROUP BY cidade
HAVING max(temp_min) < 40;
(1)
O operador LIKE faz correspondência com padrão, sendo explicado na Seção 9.7.
É importante compreender a interação entre as agregações e as cláusulas WHERE e HAVING do

SQL. A diferença fundamental entre WHERE e HAVING é esta: WHERE seleciona as linhas de
entrada antes dos grupos e agregações serem computados (portanto, controla quais linhas irão
para o computo da agregação), enquanto HAVING seleciona linhas de grupo após os grupos e
agregações serem computados. Portanto, a cláusula WHERE não pode conter funções de agregação;
não faz sentido tentar utilizar uma agregação para determinar quais linhas serão a entrada da
agregação. Por outro lado, a cláusula HAVING sempre contém funções de agregação (A rigor, é
permitido escrever uma cláusula HAVING que não possui agregação, mas raramente é útil: A
mesma condição pode ser utilizada de forma mais eficiente no estágio do WHERE).
No exemplo anterior, a restrição do nome da cidade pode ser aplicada na cláusula WHERE, porque
não necessita de nenhuma agregação. É mais eficiente que colocar a restrição na cláusula HAVING,
porque evita realizar os procedimentos de agrupamento e agregação em todas as linhas que não
atendem a cláusula WHERE.

Junções entre tabelas Acima Atualizações
http://pgdocptbr.sourceforge.net/pg82/tutorial-agg.html[09/02/2018 17:52:54]
Atualizações

2.8. Atualizações
As linhas existentes podem ser atualizadas utilizando o comando UPDATE. Suponha ter sido
descoberto que as leituras de temperatura realizadas após 28 de novembro de 1994 estão todas 2
graus mais altas. Os dados podem ser atualizados da seguinte maneira:
UPDATE clima
SET temp_max = temp_max - 2, temp_min = temp_min - 2
WHERE data > '1994-11-28';
Agora vejamos o novo estado dos dados:

-----------------+----------+----------+------+------------
São Francisco | 46 | 50 | 0.25 | 1994-11-27
São Francisco | 41 | 55 | 0 | 1994-11-29
Hayward | 35 | 52 | | 1994-11-29
(3 linhas)

Funções de agregação Acima Exclusões
http://pgdocptbr.sourceforge.net/pg82/tutorial-update.html[09/02/2018 17:53:02]
Exclusões

2.9. Exclusões
As linhas podem ser excluídas da tabela através do comando DELETE. Suponha que não estamos
mais interessados no clima de Hayward. Então podemos executar comando a seguir para excluir
estas linhas da tabela
DELETE FROM clima WHERE cidade = 'Hayward';
e todos os registros de clima pertencentes a Hayward serão removidos. Agora vejamos o novo
estado dos dados:

---------------+----------+----------+------+------------
São Francisco | 46 | 50 | 0.25 | 1994-11-27
São Francisco | 41 | 55 | 0 | 1994-11-29
(2 linhas)
Deve-se tomar cuidado com comandos na forma

DELETE FROM nome_da_tabela;
porque, sem uma qualificação, o comando DELETE remove todas as linhas da tabela, deixando-a
vazia. O sistema não solicita confirmação antes de realizar esta operação!

Atualizações Acima Funcionalidades avançadas
http://pgdocptbr.sourceforge.net/pg82/tutorial-delete.html[09/02/2018 17:53:11]
Funcionalidades avançadas

Capítulo 3. Funcionalidades avançadas

Sumário
3.1. Introdução
3.2. Visões
3.4. Transações
3.5. Herança
3.6. Conclusão

Exclusões Acima Introdução
http://pgdocptbr.sourceforge.net/pg82/tutorial-advanced.html[09/02/2018 17:53:25]
Introdução

Anterior Início Capítulo 3. Funcionalidades avançadas Fim Próxima
3.1. Introdução
Nos capítulos anteriores foi descrita a utilização básica da linguagem SQL para armazenar e acessar
dados no PostgreSQL. Neste capítulo serão mostradas algumas funcionalidades mais avançadas da
linguagem SQL que simplificam a gerência, e evitam que os dados sejam perdidos ou danificados.
No final serão vistas algumas extensões do PostgreSQL.
Em certas ocasiões este capítulo faz referência aos exemplos encontrados no Capítulo 2 para
modificá-los ou melhorá-los, portanto será vantajoso se este capítulo já tiver sido lido. Alguns
exemplos do presente capítulo também se encontram no arquivo advanced.sql no diretório do
tutorial. Este arquivo também contém dados dos exemplos a serem carregados, que não serão
repetidos aqui (consulte a Seção 2.1 para saber como usar este arquivo).

Funcionalidades avançadas Acima Visões
http://pgdocptbr.sourceforge.net/pg82/tutorial-advanced-intro.html[09/02/2018 17:53:35]
Visões

3.2. Visões
Reveja as consultas na Seção 2.6. Supondo que a consulta combinando os registros de clima com a
localização das cidades seja de particular interesse para um projeto, mas que não se deseja digitar
esta consulta toda vez que for necessária, então é possível criar uma visão baseada na consulta,
atribuindo um nome a esta consulta pelo qual será possível referenciá-la como se fosse uma tabela
comum.
CREATE VIEW minha_visao AS

SELECT cidade, temp_min, temp_max, prcp, data, localizacao
FROM clima, cidades
SELECT * FROM minha_visao;
Fazer livre uso de visões é um aspecto chave de um bom projeto de banco de dados SQL. As visões
permitem encapsular detalhes das estruturas das tabelas, que podem mudar à medida que os
aplicativos evoluem, atrás de interfaces consistentes.
As visões podem ser utilizadas em quase todos os lugares onde uma tabela real pode ser utilizada.
Construir visões baseadas em visões não é raro.

Introdução Acima Chaves estrangeiras
http://pgdocptbr.sourceforge.net/pg82/tutorial-views.html[09/02/2018 17:54:03]
Chaves estrangeiras


Reveja as tabelas clima e cidades no Capítulo 2. Considere o seguinte problema: Desejamos ter
certeza que não serão inseridas linhas na tabela clima sem que haja um registro correspondente na
tabela cidades. Isto é chamado de manter a integridade referencial dos dados. Em sistemas de
banco de dados muito simples poderia ser implementado (caso fosse) olhando primeiro a tabela
cidades para verificar se existe a linha correspondente e, depois, inserir ou rejeitar a nova linha de
clima. Esta abordagem possui vários problemas, e é muito inconveniente, por isso o PostgreSQL
pode realizar esta operação por você.
A nova declaração das tabelas ficaria assim:

cidade varchar(80) PRIMARY KEY,
localizacao point
);
CREATE TABLE clima (
cidade varchar(80) REFERENCES cidades(cidade),
temp_min int,
temp_max int,
prcp real,
data date
);
Agora, ao se tentar inserir uma linha inválida:
INSERT INTO clima VALUES ('Berkeley', 45, 53, 0.0, '1994-11-28');

ERROR: insert or update on table "clima" violates foreign key constraint
"clima_cidade_fkey"
DETAIL: Key (cidade)=(Berkeley) is not present in table "cidades".
-- Tradução da mensagem
ERRO: inserção ou atualização na tabela "clima" viola a restrição de chave estrangeira
"clima_cidade_fkey"
DETALHE: Chave (cidade)=(Berkeley) não está presente na tabela "cidades".
O comportamento das chaves estrangeiras pode receber ajuste fino no aplicativo. Não iremos além
deste exemplo simples neste tutorial, mas consulte o Capítulo 5 para obter informações adicionais.
Com certeza o uso correto de chaves estrangeiras melhora a qualidade dos aplicativos de banco de
dados, portanto incentivamos muito que se aprenda a usá-las.

Visões Acima Transações
http://pgdocptbr.sourceforge.net/pg82/tutorial-fk.html[09/02/2018 17:54:11]
Transações

3.4. Transações
Transação é um conceito fundamental de todo sistema de banco de dados. O ponto essencial da
transação é englobar vários passos em uma única operação de tudo ou nada. Os estados
intermediários entre os passos não são vistos pelas demais transações simultâneas e, se ocorrer
alguma falha que impeça a transação chegar até o fim, então nenhum dos passos intermediários irá
afetar o banco de dados de forma alguma.
Por exemplo, considere um banco de dados de uma instituição financeira contendo o saldo da conta
corrente de vários clientes, assim como o saldo total dos depósitos de cada agência. Suponha que
se deseje transferir $100.00 da conta da Alice para a conta do Bob. Simplificando ao extremo, os
comandos SQL para esta operação seriam:
UPDATE conta_corrente SET saldo = saldo - 100.00

WHERE nome = 'Alice';
UPDATE filiais SET saldo = saldo - 100.00
WHERE nome = (SELECT nome_filial FROM conta_corrente WHERE nome = 'Alice');
UPDATE conta_corrente SET saldo = saldo + 100.00
WHERE nome = 'Bob';
UPDATE filiais SET saldo = saldo + 100.00
WHERE nome = (SELECT nome_filial FROM conta_corrente WHERE nome = 'Bob');
Os detalhes destes comandos não são importantes aqui; o ponto importante é o fato de existirem
várias atualizações distintas envolvidas para realizar esta operação tão simples. A contabilidade do
banco quer ter certeza que todas estas atualizações foram realizadas, ou que nenhuma delas foi
realizada. Com certeza não é interessante que uma falha no sistema faça com que Bob receba
$100.00 que não foi debitado da Alice. Além disso, Alice não continuará sendo uma cliente satisfeita
se o dinheiro for debitado de sua conta e não for creditado na conta do Bob. É necessário garantir
que, caso aconteça algo errado no meio da operação, nenhum dos passos executados até este
ponto irá valer. Agrupar as atualizações em uma transação dá esta garantia. Uma transação é dita
como sendo atômica: do ponto de vista das outras transações, ou a transação acontece por inteiro,
ou nada acontece.
Desejamos, também, ter a garantia de estando a transação completa e aceita pelo sistema de
banco de dados que a mesma fique definitivamente gravada, e não seja perdida mesmo no caso de
acontecer uma pane logo em seguida. Por exemplo, se estiver sendo registrado um saque em
dinheiro pelo Bob não se deseja, de forma alguma, que o débito em sua conta corrente desapareça
por causa de uma pane ocorrida logo depois do Bob sair da agência. Um banco de dados
transacional garante que todas as atualizações realizadas por uma transação ficam registradas em
meio de armazenamento permanente (ou seja, em disco), antes da transação ser considerada
completa.
Outra propriedade importante dos bancos de dados transacionais está muito ligada à noção de
atualizações atômicas: quando várias transações estão executando ao mesmo tempo, nenhuma
delas deve enxergar as alterações incompletas efetuadas pelas outras. Por exemplo, se uma
transação está ocupada totalizando o saldo de todas as agências, não pode ser visto o débito
efetuado na agência da Alice mas ainda não creditado na agência do Bob, nem o contrário.
Portanto, as transações devem ser tudo ou nada não apenas em termos do efeito permanente no
banco de dados, mas também em termos de visibilidade durante o processamento. As atualizações
feitas por uma transação em andamento não podem ser vistas pelas outras transações enquanto
não terminar, quando todas as atualizações se tornam visíveis ao mesmo tempo.
No PostgreSQL a transação é definida envolvendo os comandos SQL da transação pelos comandos

BEGIN e COMMIT. Sendo assim, a nossa transação bancária ficaria:
http://pgdocptbr.sourceforge.net/pg82/tutorial-transactions.html[09/02/2018 17:54:20]
Transações
BEGIN;
-- etc etc
COMMIT;
Se no meio da transação for decidido que esta não deve ser efetivada (talvez porque tenha sido
visto que o saldo da Alice ficou negativo), pode ser usado o comando ROLLBACK em vez do COMMIT
para fazer com que todas as atualizações sejam canceladas.
O PostgreSQL, na verdade, trata todo comando SQL como sendo executado dentro de uma
transação. Se não for emitido o comando BEGIN, então cada comando possuirá um BEGIN implícito
e, se der tudo certo, um COMMIT, envolvendo-o. Um grupo de comandos envolvidos por um BEGIN
e um COMMIT é algumas vezes chamado de bloco de transação.
Nota: Algumas bibliotecas cliente emitem um comando BEGIN e um comando COMMIT

automaticamente, fazendo com que se obtenha o efeito de um bloco de transação sem
perguntar se isto é desejado. Verifique a documentação da interface utilizada.
É possível controlar os comandos na transação de uma forma mais granular utilizando os pontos de
salvamento (savepoints). Os pontos de salvamento permitem descartar partes da transação
seletivamente, e efetivar as demais partes. Após definir o ponto de salvamento através da instrução
SAVEPOINT, é possível cancelar a transação até o ponto de salvamento, se for necessário, usando
ROLLBACK TO. Todas as alterações no banco de dados efetuadas pela transação entre o
estabelecimento do ponto de salvamento e o cancelamento são descartadas, mas as alterações
efetuadas antes do ponto de salvamento são mantidas.
Após cancelar até o ponto de salvamento, este ponto de salvamento continua definido e, portanto,
é possível cancelar várias vezes. Ao contrário, havendo certeza que não vai ser mais necessário
cancelar até o ponto de salvamento, o ponto de salvamento poderá ser liberado, para que o sistema
possa liberar alguns recursos. Deve-se ter em mente que liberar ou cancelar até um ponto de
salvamento libera, automaticamente, todos os pontos de salvamento definidos após o mesmo.
Tudo isto acontece dentro do bloco de transação e, portanto, nada disso é visto pelas outras
sessões do banco de dados. Quando o bloco de transação é efetivado, as ações efetivadas se
tornam visíveis como uma unidade para as outras sessões, enquanto as ações desfeitas nunca se
tornam visíveis.
Recordando o banco de dados da instituição financeira, suponha que tivesse sido debitado $100.00
da conta da Alice e creditado na conta do Bob, e descoberto em seguida que era para ser creditado
na conta do Wally. Isso poderia ser feito utilizando um ponto de salvamento, conforme mostrado
abaixo:
BEGIN;
SAVEPOINT meu_ponto_de_salvamento;
WHERE nome = 'Bob';
-- uai ... o certo é na conta do Wally
ROLLBACK TO meu_ponto_de_salvamento;
WHERE nome = 'Wally';
COMMIT;
Obviamente este exemplo está simplificado ao extremo, mas é possível efetuar um grau elevado de
controle sobre a transação através do uso de pontos de salvamento. Além disso, a instrução
ROLLBACK TO é a única forma de obter novamente o controle sobre um bloco de transação
colocado no estado interrompido pelo sistema devido a um erro, fora cancelar completamente e
começar tudo de novo.

Chaves estrangeiras Acima Herança
http://pgdocptbr.sourceforge.net/pg82/tutorial-transactions.html[09/02/2018 17:54:20]
Herança

3.5. Herança
Herança é um conceito de banco de dados orientado a objeto, que abre novas possibilidades
interessantes ao projeto de banco de dados.
Vamos criar duas tabelas: a tabela cidades e a tabela capitais. Como é natural, as capitais também
são cidades e, portanto, deve existir alguma maneira para mostrar implicitamente as capitais
quando todas as cidades são mostradas. Se formos bastante perspicazes, poderemos criar um
esquema como este:
CREATE TABLE capitais (

nome text,
populacao real,
altitude int, -- (em pés)
estado char(2)
);
CREATE TABLE interior (
nome text,
populacao real,
altitude int -- (em pés)
);
CREATE VIEW cidades AS
SELECT nome, populacao, altitude FROM capitais
UNION
SELECT nome, populacao, altitude FROM interior;
Este esquema funciona bem para as consultas, mas não é bom quando é necessário atualizar várias
linhas, entre outras coisas.
Esta é uma solução melhor:

nome text,
populacao real,
altitude int -- (em pés)
);
CREATE TABLE capitais (
estado char(2)
) INHERITS (cidades);
Neste caso, as linhas da tabela capitais herdam todas as colunas (nome, populacao e altitude) da
sua tabela ancestral cidades. O tipo da coluna nome é text, um tipo nativo do PostgreSQL para
cadeias de caracteres de tamanho variável. As capitais dos estados possuem uma coluna a mais
chamada estado, que armazena a sigla do estado. No PostgreSQL uma tabela pode herdar de
nenhuma, de uma, ou de várias tabelas.
Por exemplo, a consulta abaixo retorna os nomes de todas as cidades, incluindo as capitais dos
estados, localizadas a uma altitude superior a 500 pés:
SELECT nome, altitude

FROM cidades
WHERE altitude > 500;
nome | altitude
-----------+----------
Las Vegas | 2174
Mariposa | 1953
Madison | 845
(3 linhas)
http://pgdocptbr.sourceforge.net/pg82/tutorial-inheritance.html[09/02/2018 17:54:37]
Herança
Por outro lado, a consulta abaixo retorna todas as cidades que não são capitais de estado e estão
situadas a uma altitude superior a 500 pés:
SELECT nome, altitude

FROM ONLY cidades
nome | altitude
-----------+----------
Las Vegas | 2174
Mariposa | 1953
(2 linhas)
Na consulta acima a palavra chave ONLY antes de cidades indica que a consulta deve ser efetuada
apenas na tabela cidades, sem incluir as tabelas abaixo de cidades na hierarquia de herança. Muitos
comandos mostrados até agora — SELECT, UPDATE e DELETE — permitem usar a notação ONLY.
Nota: Embora a hierarquia seja útil com freqüência, sua utilidade é limitada porque não
está integrada com as restrições de unicidade e de chave estrangeira. Para obter mais
detalhes deve ser consultada a Seção 5.8.

Transações Acima Conclusão
http://pgdocptbr.sourceforge.net/pg82/tutorial-inheritance.html[09/02/2018 17:54:37]
Conclusão

3.6. Conclusão
O PostgreSQL possui muitas funcionalidades não abordadas neste tutorial introdutório, o qual está
orientado para os usuários com pouca experiência na linguagem SQL. Estas funcionalidades são
mostradas com mais detalhes no restante desta documentação.
Se sentir necessidade de mais material introdutório, por favor visite o sítio do PostgreSQL na Web e o
sítio PostgreSQLBrasil para obter indicações sobre onde encontrar este material.

Herança Acima A linguagem SQL
http://pgdocptbr.sourceforge.net/pg82/tutorial-conclusion.html[09/02/2018 17:54:46]
A linguagem SQL

II. A linguagem SQL

Esta parte descreve a utilização da linguagem SQL no PostgreSQL. Começa descrevendo a sintaxe
geral do SQL e, depois, explica como criar estruturas para armazenar dados, como carregar o banco
de dados e como consultá-lo. A parte intermediária mostra os tipos de dado disponíveis e as
funções utilizadas nos comandos SQL. O restante trata de vários aspectos importantes para ajustar
o banco de dados para obter um desempenho otimizado.
As informações contidas nesta parte estão dispostas de maneira que um usuário inexperiente possa
seguir do princípio ao fim para obter uma compreensão completa dos tópicos, sem ser necessário
fazer referência a partes posteriores muitas vezes. A intenção foi criar capítulos auto-contidos, de
modo que os usuários avançados possam ler os capítulos individualmente conforme haja
necessidade. As informações nesta parte estão apresentadas sob forma de narrativa, sendo cada
unidade um tópico. Os leitores à procura de uma descrição completa de um determinado comando
devem consultar a Parte VI.
Os leitores desta parte devem saber como conectar ao banco de dados PostgreSQL e executar
comandos SQL. Incentivamos os leitores não familiarizados com estes procedimentos lerem
primeiro a Parte I. Normalmente os comandos SQL são executados utilizando o terminal interativo
do PostgreSQL psql, mas também podem ser utilizados outros programas com funcionalidades
equivalentes.
Sumário
4. SQL Syntax
4.1. Lexical Structure

4.2. Value Expressions
5. Data Definition
5.1. Table Basics

5.2. Default Values
5.3. Constraints
5.4. System Columns
5.5. Modifying Tables
5.6. Privileges
5.7. Schemas
5.8. Herança
5.9. Partitioning
5.10. Other Database Objects
5.11. Dependency Tracking
6. Data Manipulation
6.1. Inserting Data

6.2. Updating Data
6.3. Deleting Data
7. Queries
7.1. Visão geral

7.2. Table Expressions
7.3. Select Lists
http://pgdocptbr.sourceforge.net/pg82/sql.html[09/02/2018 17:55:03]
A linguagem SQL
7.4. Combining Queries

7.5. Sorting Rows
7.6. LIMIT and OFFSET
7.7. VALUES Lists
8. Data Types
8.1. Numeric Types

8.2. Monetary Types
8.3. Character Types
8.4. Binary Data Types
8.5. Date/Time Types
8.6. Boolean Type
8.7. Geometric Types
8.8. Network Address Types
8.9. Bit String Types
8.10. Arrays
8.11. Composite Types
8.12. Object Identifier Types
8.13. Pseudo-Types
8.14. XML Document Support
9. Functions and Operators
9.1. Logical Operators

9.2. Comparison Operators
9.3. Mathematical Functions and Operators
9.4. String Functions and Operators
9.5. Binary String Functions and Operators
9.6. Bit String Functions and Operators
9.7. Pattern Matching
9.8. Data Type Formatting Functions
9.9. Date/Time Functions and Operators
9.10. Geometric Functions and Operators
9.11. Network Address Functions and Operators
9.12. Sequence Manipulation Functions
9.13. Conditional Expressions
9.14. Array Functions and Operators
9.15. Aggregate Functions
9.16. Subquery Expressions
9.17. Row and Array Comparisons
9.18. Set Returning Functions
9.19. System Information Functions
9.20. System Administration Functions
10. Type Conversion
10.1. Visão geral

10.2. Operators
10.3. Functions
10.4. Value Storage
10.5. UNION, CASE, and Related Constructs
11. Indexes
11.1. Introdução
11.2. Index Types
11.3. Multicolumn Indexes
11.4. Combining Multiple Indexes
11.5. Unique Indexes
11.6. Indexes on Expressions
11.7. Partial Indexes
A linguagem SQL
11.8. Operator Classes

11.9. Examining Index Usage
12. Concurrency Control
12.1. Introdução
12.2. Transaction Isolation
12.3. Explicit Locking
12.4. Data Consistency Checks at the Application Level
12.5. Locking and Indexes
13. Performance Tips
13.1. Using EXPLAIN

13.2. Statistics Used by the Planner
13.3. Controlling the Planner with Explicit JOIN Clauses
13.4. Populating a Database

Conclusão SQL Syntax
SQL Syntax

Capítulo 4. SQL Syntax

Sumário
4.1.1. Identifiers and Key Words

4.1.2. Constants
4.1.3. Operators
4.1.4. Special Characters
4.1.5. Comments
4.1.6. Lexical Precedence
4.2.1. Column References

4.2.2. Positional Parameters
4.2.3. Subscripts
4.2.4. Field Selection
4.2.5. Operator Invocations
4.2.6. Function Calls
4.2.7. Aggregate Expressions
4.2.8. Type Casts
4.2.9. Scalar Subqueries
4.2.10. Array Constructors
4.2.11. Row Constructors
4.2.12. Expression Evaluation Rules
This chapter describes the syntax of SQL. It forms the foundation for understanding the following
chapters which will go into detail about how the SQL commands are applied to define and modify
data.
We also advise users who are already familiar with SQL to read this chapter carefully because there
are several rules and concepts that are implemented inconsistently among SQL databases or that
are specific to PostgreSQL.

A linguagem SQL Acima Lexical Structure
http://pgdocptbr.sourceforge.net/pg82/sql-syntax.html[09/02/2018 17:55:24]
Lexical Structure

Anterior Início Capítulo 4. SQL Syntax Fim Próxima

SQL input consists of a sequence of commands. A command is composed of a sequence of tokens,
terminated by a semicolon (";"). The end of the input stream also terminates a command. Which
tokens are valid depends on the syntax of the particular command.
A token can be a key word, an identifier, a quoted identifier, a literal (or constant), or a special
character symbol. Tokens are normally separated by whitespace (space, tab, newline), but need not
be if there is no ambiguity (which is generally only the case if a special character is adjacent to
some other token type).
Additionally, comments can occur in SQL input. They are not tokens, they are effectively equivalent
to whitespace.
For example, the following is (syntactically) valid SQL input:
SELECT * FROM MY_TABLE;

UPDATE MY_TABLE SET A = 5;
INSERT INTO MY_TABLE VALUES (3, 'hi there');
This is a sequence of three commands, one per line (although this is not required; more than one
command can be on a line, and commands can usefully be split across lines).
The SQL syntax is not very consistent regarding what tokens identify commands and which are
operands or parameters. The first few tokens are generally the command name, so in the above
example we would usually speak of a "SELECT", an "UPDATE", and an "INSERT" command. But for
instance the UPDATE command always requires a SET token to appear in a certain position, and this
particular variation of INSERT also requires a VALUES in order to be complete. The precise syntax
rules for each command are described in Parte VI.
4.1.1. Identifiers and Key Words
Tokens such as SELECT, UPDATE, or VALUES in the example above are examples of key words, that
is, words that have a fixed meaning in the SQL language. The tokens MY_TABLE and A are
examples of identifiers. They identify names of tables, columns, or other database objects,
depending on the command they are used in. Therefore they are sometimes simply called "names".
Key words and identifiers have the same lexical structure, meaning that one cannot know whether a
token is an identifier or a key word without knowing the language. A complete list of key words can
be found in Apêndice C.
SQL identifiers and key words must begin with a letter (a-z, but also letters with diacritical marks
and non-Latin letters) or an underscore (_). Subsequent characters in an identifier or key word can
be letters, underscores, digits (0-9), or dollar signs ($). Note that dollar signs are not allowed in
identifiers according to the letter of the SQL standard, so their use may render applications less
portable. The SQL standard will not define a key word that contains digits or starts or ends with an
underscore, so identifiers of this form are safe against possible conflict with future extensions of the
standard.
The system uses no more than NAMEDATALEN-1 characters of an identifier; longer names can be
written in commands, but they will be truncated. By default, NAMEDATALEN is 64 so the maximum
identifier length is 63. If this limit is problematic, it can be raised by changing the NAMEDATALEN
http://pgdocptbr.sourceforge.net/pg82/sql-syntax-lexical.html[09/02/2018 17:55:32]
Lexical Structure
constant in src/include/postgres_ext.h.
Identifier and key word names are case insensitive. Therefore
UPDATE MY_TABLE SET A = 5;
can equivalently be written as
uPDaTE my_TabLE SeT a = 5;
A convention often used is to write key words in upper case and names in lower case, e.g.,
UPDATE my_table SET a = 5;
There is a second kind of identifier: the delimited identifier or quoted identifier. It is formed by
enclosing an arbitrary sequence of characters in double-quotes ("). A delimited identifier is always
an identifier, never a key word. So "select" could be used to refer to a column or table named
"select", whereas an unquoted select would be taken as a key word and would therefore provoke a
parse error when used where a table or column name is expected. The example can be written with
quoted identifiers like this:
UPDATE "my_table" SET "a" = 5;
Quoted identifiers can contain any character, except the character with code zero. (To include a
double quote, write two double quotes.) This allows constructing table or column names that would
otherwise not be possible, such as ones containing spaces or ampersands. The length limitation still
applies.
Quoting an identifier also makes it case-sensitive, whereas unquoted names are always folded to
lower case. For example, the identifiers FOO, foo, and "foo" are considered the same by
PostgreSQL, but "Foo" and "FOO" are different from these three and each other. (The folding of
unquoted names to lower case in PostgreSQL is incompatible with the SQL standard, which says
that unquoted names should be folded to upper case. Thus, foo should be equivalent to "FOO" not
"foo" according to the standard. If you want to write portable applications you are advised to always
quote a particular name or never quote it.)
4.1.2. Constants
There are three kinds of implicitly-typed constants in PostgreSQL: strings, bit strings, and numbers.
Constants can also be specified with explicit types, which can enable more accurate representation
and more efficient handling by the system. These alternatives are discussed in the following
subsections.
4.1.2.1. String Constants
A string constant in SQL is an arbitrary sequence of characters bounded by single quotes ('), for
example 'This is a string'. To include a single-quote character within a string constant, write two
adjacent single quotes, e.g. 'Dianne''s horse'. Note that this is not the same as a double-quote
character (").
Two string constants that are only separated by whitespace with at least one newline are
concatenated and effectively treated as if the string had been written as one constant. For example:
SELECT 'foo'
'bar';
Lexical Structure
is equivalent to
SELECT 'foobar';
but
SELECT 'foo' 'bar';
is not valid syntax. (This slightly bizarre behavior is specified by SQL; PostgreSQL is following the
standard.)
PostgreSQL also accepts "escape" string constants, which are an extension to the SQL standard. An
escape string constant is specified by writing the letter E (upper or lower case) just before the
opening single quote, e.g. E'foo'. (When continuing an escape string constant across lines, write E
only before the first opening quote.) Within an escape string, a backslash character (\) begins a C-
like backslash escape sequence, in which the combination of backslash and following character(s)
represents a special byte value. \b is a backspace, \f is a form feed, \n is a newline, \r is a carriage
return, \t is a tab. Also supported are \dígitos, where dígitos represents an octal byte value, and
\xdígitos_hexadecimais, where dígitos_hexadecimais represents a hexadecimal byte value. (It is
your responsibility that the byte sequences you create are valid characters in the server character
set encoding.) Any other character following a backslash is taken literally. Thus, to include a
backslash character, write two backslashes (\\). Also, a single quote can be included in an escape
string by writing \', in addition to the normal way of ''.
Cuidado
If the configuration parameter standard_conforming_strings is off, then PostgreSQL recognizes backslash

escapes in both regular and escape string constants. This is for backward compatibility with the historical
behavior, in which backslash escapes were always recognized. Although standard_conforming_strings
currently defaults to off, the default will change to on in a future release for improved standards
compliance. Applications are therefore encouraged to migrate away from using backslash escapes. If you
need to use a backslash escape to represent a special character, write the constant with an E to be sure it
will be handled the same way in future releases.
In addition to standard_conforming_strings, the configuration parameters escape_string_warning and

backslash_quote govern treatment of backslashes in string constants.
The character with the code zero cannot be in a string constant.
4.1.2.2. Dollar-Quoted String Constants
While the standard syntax for specifying string constants is usually convenient, it can be difficult to
understand when the desired string contains many single quotes or backslashes, since each of
those must be doubled. To allow more readable queries in such situations, PostgreSQL provides
another way, called "dollar quoting", to write string constants. A dollar-quoted string constant
consists of a dollar sign ($), an optional "tag" of zero or more characters, another dollar sign, an
arbitrary sequence of characters that makes up the string content, a dollar sign, the same tag that
began this dollar quote, and a dollar sign. For example, here are two different ways to specify the
string "Dianne's horse" using dollar quoting:
$$Dianne's horse$$
$SomeTag$Dianne's horse$SomeTag$
Notice that inside the dollar-quoted string, single quotes can be used without needing to be
escaped. Indeed, no characters inside a dollar-quoted string are ever escaped: the string content is
always written literally. Backslashes are not special, and neither are dollar signs, unless they are
part of a sequence matching the opening tag.
It is possible to nest dollar-quoted string constants by choosing different tags at each nesting level.
Lexical Structure
This is most commonly used in writing function definitions. For example:
$function$
BEGIN
RETURN ($1 ~ $q$[\t\r\n\v\\]$q$);
END;
$function$
Here, the sequence $q$[\t\r\n\v\\]$q$ represents a dollar-quoted literal string [\t\r\n\v\\], which
will be recognized when the function body is executed by PostgreSQL. But since the sequence does
not match the outer dollar quoting delimiter $function$, it is just some more characters within the
constant so far as the outer string is concerned.
The tag, if any, of a dollar-quoted string follows the same rules as an unquoted identifier, except
that it cannot contain a dollar sign. Tags are case sensitive, so $tag$String content$tag$ is correct,
but $TAG$String content$tag$ is not.
A dollar-quoted string that follows a keyword or identifier must be separated from it by whitespace;
otherwise the dollar quoting delimiter would be taken as part of the preceding identifier.
Dollar quoting is not part of the SQL standard, but it is often a more convenient way to write
complicated string literals than the standard-compliant single quote syntax. It is particularly useful
when representing string constants inside other constants, as is often needed in procedural function
definitions. With single-quote syntax, each backslash in the above example would have to be
written as four backslashes, which would be reduced to two backslashes in parsing the original
string constant, and then to one when the inner string constant is re-parsed during function
execution.
4.1.2.3. Bit-String Constants
Bit-string constants look like regular string constants with a B (upper or lower case) immediately
before the opening quote (no intervening whitespace), e.g., B'1001'. The only characters allowed
within bit-string constants are 0 and 1.
Alternatively, bit-string constants can be specified in hexadecimal notation, using a leading X (upper
or lower case), e.g., X'1FF'. This notation is equivalent to a bit-string constant with four binary
digits for each hexadecimal digit.
Both forms of bit-string constant can be continued across lines in the same way as regular string
constants. Dollar quoting cannot be used in a bit-string constant.
4.1.2.4. Numeric Constants
Numeric constants are accepted in these general forms:

dígitos
dígitos.[dígitos][e[+-]dígitos]
[dígitos].dígitos[e[+-]dígitos]
dígitose[+-]dígitos
where dígitos is one or more decimal digits (0 through 9). At least one digit must be before or after
the decimal point, if one is used. At least one digit must follow the exponent marker (e), if one is
present. There may not be any spaces or other characters embedded in the constant. Note that any
leading plus or minus sign is not actually considered part of the constant; it is an operator applied
to the constant.
These are some examples of valid numeric constants:
42
3.5
4.
.001
5e2
1.925e-3
Lexical Structure
A numeric constant that contains neither a decimal point nor an exponent is initially presumed to
be type integer if its value fits in type integer (32 bits); otherwise it is presumed to be type bigint if
its value fits in type bigint (64 bits); otherwise it is taken to be type numeric. Constants that
contain decimal points and/or exponents are always initially presumed to be type numeric.
The initially assigned data type of a numeric constant is just a starting point for the type resolution
algorithms. In most cases the constant will be automatically coerced to the most appropriate type
depending on context. When necessary, you can force a numeric value to be interpreted as a
specific data type by casting it. For example, you can force a numeric value to be treated as type
real (float4) by writing
REAL '1.23' -- string style

1.23::REAL -- PostgreSQL (historical) style
These are actually just special cases of the general casting notations discussed next.
4.1.2.5. Constants of Other Types
A constant of an arbitrary type can be entered using any one of the following notations:
tipo 'cadeia_de_caracteres'
'cadeia_de_caracteres'::tipo
CAST ( 'cadeia_de_caracteres' AS tipo )
The string constant's text is passed to the input conversion routine for the type called tipo. The
result is a constant of the indicated type. The explicit type cast may be omitted if there is no
ambiguity as to the type the constant must be (for example, when it is assigned directly to a table
column), in which case it is automatically coerced.
The string constant can be written using either regular SQL notation or dollar-quoting.
It is also possible to specify a type coercion using a function-like syntax:

nome_do_tipo ( 'cadeia_de_caracteres' )
but not all type names may be used in this way; see Seção 4.2.8 for details.
The ::, CAST(), and function-call syntaxes can also be used to specify run-time type conversions of
arbitrary expressions, as discussed in Seção 4.2.8. But the form tipo 'cadeia_de_caracteres' can only
be used to specify the type of a literal constant. Another restriction on tipo 'cadeia_de_caracteres' is
that it does not work for array types; use :: or CAST() to specify the type of an array constant.
The CAST() syntax conforms to SQL. The tipo 'cadeia_de_caracteres' syntax is a generalization of
the standard: SQL specifies this syntax only for a few data types, but PostgreSQL allows it for all
types. The syntax with :: is historical PostgreSQL usage, as is the function-call syntax.
4.1.3. Operators
An operator name is a sequence of up to NAMEDATALEN-1 (63 by default) characters from the

following list:
+ - * / < > = ~ ! @ # % ^ & | ` ?
There are a few restrictions on operator names, however:
-- and /* cannot appear anywhere in an operator name, since they will be taken as the start
of a comment.
A multiple-character operator name cannot end in + or -, unless the name also contains at
least one of these characters:
~ ! @ # % ^ & | ` ?
Lexical Structure
For example, @- is an allowed operator name, but *- is not. This restriction allows PostgreSQL
to parse SQL-compliant queries without requiring spaces between tokens.
When working with non-SQL-standard operator names, you will usually need to separate adjacent
operators with spaces to avoid ambiguity. For example, if you have defined a left unary operator
named @, you cannot write X*@Y; you must write X* @Y to ensure that PostgreSQL reads it as two
operator names not one.
4.1.4. Special Characters
Some characters that are not alphanumeric have a special meaning that is different from being an
operator. Details on the usage can be found at the location where the respective syntax element is
described. This section only exists to advise the existence and summarize the purposes of these
characters.
A dollar sign ($) followed by digits is used to represent a positional parameter in the body of a
function definition or a prepared statement. In other contexts the dollar sign may be part of
an identifier or a dollar-quoted string constant.
Parentheses (()) have their usual meaning to group expressions and enforce precedence. In
some cases parentheses are required as part of the fixed syntax of a particular SQL
command.
Brackets ([]) are used to select the elements of an array. See Seção 8.10 for more information
on arrays.
Commas (,) are used in some syntactical constructs to separate the elements of a list.
The semicolon (;) terminates an SQL command. It cannot appear anywhere within a
command, except within a string constant or quoted identifier.
The colon (:) is used to select "slices" from arrays. (See Seção 8.10.) In certain SQL dialects
(such as Embedded SQL), the colon is used to prefix variable names.
The asterisk (*) is used in some contexts to denote all the fields of a table row or composite
value. It also has a special meaning when used as the argument of an aggregate function,
namely that the aggregate does not require any explicit parameter.
The period (.) is used in numeric constants, and to separate schema, table, and column
names.
4.1.5. Comments
A comment is an arbitrary sequence of characters beginning with double dashes and extending to
the end of the line, e.g.:
-- This is a standard SQL comment
Alternatively, C-style block comments can be used:
/* multiline comment
* with nesting: /* nested block comment */
*/
where the comment begins with /* and extends to the matching occurrence of */. These block
comments nest, as specified in the SQL standard but unlike C, so that one can comment out larger
blocks of code that may contain existing block comments.
A comment is removed from the input stream before further syntax analysis and is effectively
Lexical Structure
replaced by whitespace.
4.1.6. Lexical Precedence
Tabela 4-1 shows the precedence and associativity of the operators in PostgreSQL. Most operators
have the same precedence and are left-associative. The precedence and associativity of the
operators is hard-wired into the parser. This may lead to non-intuitive behavior; for example the
Boolean operators < and > have a different precedence than the Boolean operators <= and >=.
Also, you will sometimes need to add parentheses when using combinations of binary and unary
operators. For instance
SELECT 5 ! - 6;
will be parsed as
SELECT 5 ! (- 6);
because the parser has no idea — until it is too late — that ! is defined as a postfix operator, not an
infix one. To get the desired behavior in this case, you must write
SELECT (5 !) - 6;
This is the price one pays for extensibility.
Tabela 4-1. Operator Precedence (decreasing)
Operator/Element Associativity Description

. left table/column name separator
:: left PostgreSQL-style typecast
[] left array element selection
- right unary minus
^ left exponentiation
*/% left multiplication, division, modulo
+- left addition, subtraction
IS IS TRUE, IS FALSE, IS UNKNOWN, IS NULL
ISNULL test for null
NOTNULL test for not null
(any other) left all other native and user-defined operators
IN set membership
BETWEEN range containment
OVERLAPS time interval overlap
LIKE ILIKE SIMILAR string pattern matching
<> less than, greater than
= right equality, assignment
NOT right logical negation
AND left logical conjunction
OR left logical disjunction
Note that the operator precedence rules also apply to user-defined operators that have the same
names as the built-in operators mentioned above. For example, if you define a "+" operator for
some custom data type it will have the same precedence as the built-in "+" operator, no matter
what yours does.
Lexical Structure
When a schema-qualified operator name is used in the OPERATOR syntax, as for example in
SELECT 3 OPERATOR(pg_catalog.+) 4;
the OPERATOR construct is taken to have the default precedence shown in Tabela 4-1 for "any
other" operator. This is true no matter which specific operator name appears inside OPERATOR().

SQL Syntax Acima Value Expressions
Value Expressions

Anterior Início Capítulo 4. SQL Syntax Fim Próxima

Value expressions are used in a variety of contexts, such as in the target list of the SELECT
command, as new column values in INSERT or UPDATE, or in search conditions in a number of
commands. The result of a value expression is sometimes called a scalar, to distinguish it from the
result of a table expression (which is a table). Value expressions are therefore also called scalar
expressions (or even simply expressions). The expression syntax allows the calculation of values
from primitive parts using arithmetic, logical, set, and other operations.
A value expression is one of the following:
A constant or literal value.
A column reference.
A positional parameter reference, in the body of a function definition or prepared statement.
A subscripted expression.
A field selection expression.
An operator invocation.
A function call.
An aggregate expression.
A type cast.
A scalar subquery.
An array constructor.
A row constructor.
Another value expression in parentheses, useful to group subexpressions and override

precedence.
In addition to this list, there are a number of constructs that can be classified as an expression but
do not follow any general syntax rules. These generally have the semantics of a function or
operator and are explained in the appropriate location in Capítulo 9. An example is the IS NULL
clause.
We have already discussed constants in Seção 4.1.2. The following sections discuss the remaining
options.
4.2.1. Column References
A column can be referenced in the form

correlação.nome_da_coluna
correlação is the name of a table (possibly qualified with a schema name), or an alias for a table
defined by means of a FROM clause, or one of the key words NEW or OLD. (NEW and OLD can only
http://pgdocptbr.sourceforge.net/pg82/sql-expressions.html[09/02/2018 17:55:40]
Value Expressions
appear in rewrite rules, while other correlation names can be used in any SQL statement.) The
correlation name and separating dot may be omitted if the column name is unique across all the
tables being used in the current query. (See also Capítulo 7.)
4.2.2. Positional Parameters
A positional parameter reference is used to indicate a value that is supplied externally to an SQL
statement. Parameters are used in SQL function definitions and in prepared queries. Some client
libraries also support specifying data values separately from the SQL command string, in which case
parameters are used to refer to the out-of-line data values. The form of a parameter reference is:
$número
For example, consider the definition of a function, dept, as
CREATE FUNCTION dept(text) RETURNS dept

AS $$ SELECT * FROM dept WHERE name = $1 $$
LANGUAGE SQL;
Here the $1 references the value of the first function argument whenever the function is invoked.
4.2.3. Subscripts
If an expression yields a value of an array type, then a specific element of the array value can be
extracted by writing
expressão[índice]
or multiple adjacent elements (an "array slice") can be extracted by writing

expressão[lower_subscript:índice_superior]
(Here, the brackets [ ] are meant to appear literally.) Each índice is itself an expression, which must
yield an integer value.
In general the array expressão must be parenthesized, but the parentheses may be omitted when
the expression to be subscripted is just a column reference or positional parameter. Also, multiple
subscripts can be concatenated when the original array is multidimensional. For example,
mytable.arraycolumn[4]
mytable.two_d_column[17][34]
$1[10:42]
(arrayfunction(a,b))[42]
The parentheses in the last example are required. See Seção 8.10 for more about arrays.
4.2.4. Field Selection
If an expression yields a value of a composite type (row type), then a specific field of the row can
be extracted by writing
expressão.nome_do_campo
In general the row expressão must be parenthesized, but the parentheses may be omitted when
the expression to be selected from is just a table reference or positional parameter. For example,
mytable.mycolumn
$1.somecolumn
(rowfunction(a,b)).col3
(Thus, a qualified column reference is actually just a special case of the field selection syntax.)
Value Expressions
4.2.5. Operator Invocations
There are three possible syntaxes for an operator invocation:
expressão operador expressão (binary infix operator)

operador expressão (unary prefix operator)
expressão operador (unary postfix operator)
where the operador token follows the syntax rules of Seção 4.1.3, or is one of the key words AND,
OR, and NOT, or is a qualified operator name in the form
OPERATOR(esquema.nome_do_operador)
Which particular operators exist and whether they are unary or binary depends on what operators
have been defined by the system or the user. Capítulo 9 describes the built-in operators.
4.2.6. Function Calls
The syntax for a function call is the name of a function (possibly qualified with a schema name),
followed by its argument list enclosed in parentheses:
função ([expressão [, expressão ... ]] )
For example, the following computes the square root of 2:
sqrt(2)
The list of built-in functions is in Capítulo 9. Other functions may be added by the user.
4.2.7. Aggregate Expressions
An aggregate expression represents the application of an aggregate function across the rows
selected by a query. An aggregate function reduces multiple inputs to a single output value, such as
the sum or average of the inputs. The syntax of an aggregate expression is one of the following:
nome_da_agregação (expressão [ , ... ] )
nome_da_agregação (ALL expressão [ , ... ] )
nome_da_agregação (DISTINCT expressão [ , ... ] )
nome_da_agregação ( * )
where nome_da_agregação is a previously defined aggregate (possibly qualified with a schema

name), and expressão is any value expression that does not itself contain an aggregate expression.
The first form of aggregate expression invokes the aggregate across all input rows for which the
given expression(s) yield non-null values. (Actually, it is up to the aggregate function whether to
ignore null values or not — but all the standard ones do.) The second form is the same as the first,
since ALL is the default. The third form invokes the aggregate for all distinct non-null values of the
expressions found in the input rows. The last form invokes the aggregate once for each input row
regardless of null or non-null values; since no particular input value is specified, it is generally only
useful for the count(*) aggregate function.
For example, count(*) yields the total number of input rows; count(f1) yields the number of input
rows in which f1 is non-null; count(distinct f1) yields the number of distinct non-null values of f1.
The predefined aggregate functions are described in Seção 9.15. Other aggregate functions may be
added by the user.
An aggregate expression may only appear in the result list or HAVING clause of a SELECT
command. It is forbidden in other clauses, such as WHERE, because those clauses are logically
evaluated before the results of aggregates are formed.
When an aggregate expression appears in a subquery (see Seção 4.2.9 and Seção 9.16), the
Value Expressions
aggregate is normally evaluated over the rows of the subquery. But an exception occurs if the
aggregate's arguments contain only outer-level variables: the aggregate then belongs to the
nearest such outer level, and is evaluated over the rows of that query. The aggregate expression as
a whole is then an outer reference for the subquery it appears in, and acts as a constant over any
one evaluation of that subquery. The restriction about appearing only in the result list or HAVING
clause applies with respect to the query level that the aggregate belongs to.
Nota: PostgreSQL currently does not support DISTINCT with more than one input
expression.
4.2.8. Type Casts
A type cast specifies a conversion from one data type to another. PostgreSQL accepts two
equivalent syntaxes for type casts:
CAST ( expressão AS tipo )
expressão::tipo
The CAST syntax conforms to SQL; the syntax with :: is historical PostgreSQL usage.
When a cast is applied to a value expression of a known type, it represents a run-time type
conversion. The cast will succeed only if a suitable type conversion operation has been defined.
Notice that this is subtly different from the use of casts with constants, as shown in Seção 4.1.2.5. A
cast applied to an unadorned string literal represents the initial assignment of a type to a literal
constant value, and so it will succeed for any type (if the contents of the string literal are acceptable
input syntax for the data type).
An explicit type cast may usually be omitted if there is no ambiguity as to the type that a value
expression must produce (for example, when it is assigned to a table column); the system will
automatically apply a type cast in such cases. However, automatic casting is only done for casts
that are marked "OK to apply implicitly" in the system catalogs. Other casts must be invoked with
explicit casting syntax. This restriction is intended to prevent surprising conversions from being
applied silently.
It is also possible to specify a type cast using a function-like syntax:

nome_do_tipo ( expressão )
However, this only works for types whose names are also valid as function names. For example,
double precision can't be used this way, but the equivalent float8 can. Also, the names interval,
time, and timestamp can only be used in this fashion if they are double-quoted, because of
syntactic conflicts. Therefore, the use of the function-like cast syntax leads to inconsistencies and
should probably be avoided in new applications. (The function-like syntax is in fact just a function
call. When one of the two standard cast syntaxes is used to do a run-time conversion, it will
internally invoke a registered function to perform the conversion. By convention, these conversion
functions have the same name as their output type, and thus the "function-like syntax" is nothing
more than a direct invocation of the underlying conversion function. Obviously, this is not
something that a portable application should rely on.)
4.2.9. Scalar Subqueries
A scalar subquery is an ordinary SELECT query in parentheses that returns exactly one row with one
column. (See Capítulo 7 for information about writing queries.) The SELECT query is executed and
the single returned value is used in the surrounding value expression. It is an error to use a query
that returns more than one row or more than one column as a scalar subquery. (But if, during a
particular execution, the subquery returns no rows, there is no error; the scalar result is taken to be
null.) The subquery can refer to variables from the surrounding query, which will act as constants
during any one evaluation of the subquery. See also Seção 9.16 for other expressions involving
subqueries.
For example, the following finds the largest city population in each state:
Value Expressions
SELECT name, (SELECT max(pop) FROM cities WHERE cities.state = states.name)

FROM states;
4.2.10. Array Constructors
An array constructor is an expression that builds an array value from values for its member
elements. A simple array constructor consists of the key word ARRAY, a left square bracket [, one
or more expressions (separated by commas) for the array element values, and finally a right square
bracket ]. For example,
SELECT ARRAY[1,2,3+4];
array
---------
{1,2,7}
(1 row)
The array element type is the common type of the member expressions, determined using the
same rules as for UNION or CASE constructs (see Seção 10.5).
Multidimensional array values can be built by nesting array constructors. In the inner constructors,
the key word ARRAY may be omitted. For example, these produce the same result:
SELECT ARRAY[ARRAY[1,2], ARRAY[3,4]];

array
---------------
{{1,2},{3,4}}
(1 row)
SELECT ARRAY[[1,2],[3,4]];
array
---------------
{{1,2},{3,4}}
(1 row)
Since multidimensional arrays must be rectangular, inner constructors at the same level must
produce sub-arrays of identical dimensions.
Multidimensional array constructor elements can be anything yielding an array of the proper kind,
not only a sub-ARRAY construct. For example:
CREATE TABLE arr(f1 int[], f2 int[]);

INSERT INTO arr VALUES (ARRAY[[1,2],[3,4]], ARRAY[[5,6],[7,8]]);
SELECT ARRAY[f1, f2, '{{9,10},{11,12}}'::int[]] FROM arr;
array
------------------------------------------------
{{{1,2},{3,4}},{{5,6},{7,8}},{{9,10},{11,12}}}
(1 row)
It is also possible to construct an array from the results of a subquery. In this form, the array
constructor is written with the key word ARRAY followed by a parenthesized (not bracketed)
subquery. For example:
SELECT ARRAY(SELECT oid FROM pg_proc WHERE proname LIKE 'bytea%');

?column?
-------------------------------------------------------------
{2011,1954,1948,1952,1951,1244,1950,2005,1949,1953,2006,31}
(1 row)
The subquery must return a single column. The resulting one-dimensional array will have an
element for each row in the subquery result, with an element type matching that of the subquery's
output column.
The subscripts of an array value built with ARRAY always begin with one. For more information
about arrays, see Seção 8.10.
Value Expressions
4.2.11. Row Constructors
A row constructor is an expression that builds a row value (also called a composite value) from
values for its member fields. A row constructor consists of the key word ROW, a left parenthesis,
zero or more expressions (separated by commas) for the row field values, and finally a right
parenthesis. For example,
SELECT ROW(1,2.5,'this is a test');
The key word ROW is optional when there is more than one expression in the list.
A row constructor can include the syntax valor_linha.*, which will be expanded to a list of the
elements of the row value, just as occurs when the .* syntax is used at the top level of a SELECT
list. For example, if table t has columns f1 and f2, these are the same:
SELECT ROW(t.*, 42) FROM t;

SELECT ROW(t.f1, t.f2, 42) FROM t;
Nota: Before PostgreSQL 8.2, the .* syntax was not expanded, so that writing ROW(t.*,
42) created a two-field row whose first field was another row value. The new behavior is
usually more useful. If you need the old behavior of nested row values, write the inner
row value without .*, for instance ROW(t, 42).
By default, the value created by a ROW expression is of an anonymous record type. If necessary, it
can be cast to a named composite type — either the row type of a table, or a composite type
created with CREATE TYPE AS. An explicit cast may be needed to avoid ambiguity. For example:
CREATE TABLE mytable(f1 int, f2 float, f3 text);

CREATE FUNCTION getf1(mytable) RETURNS int AS 'SELECT $1.f1' LANGUAGE SQL;
-- No cast needed since only one getf1() exists
SELECT getf1(ROW(1,2.5,'this is a test'));
getf1
-------
1
(1 row)
CREATE TYPE myrowtype AS (f1 int, f2 text, f3 numeric);
CREATE FUNCTION getf1(myrowtype) RETURNS int AS 'SELECT $1.f1' LANGUAGE SQL;
-- Now we need a cast to indicate which function to call:
SELECT getf1(ROW(1,2.5,'this is a test'));
ERROR: function getf1(record) is not unique
SELECT getf1(ROW(1,2.5,'this is a test')::mytable);
getf1
-------
1
(1 row)
SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
getf1
-------
11
(1 row)
Row constructors can be used to build composite values to be stored in a composite-type table
column, or to be passed to a function that accepts a composite parameter. Also, it is possible to
compare two row values or test a row with IS NULL or IS NOT NULL, for example
SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');

SELECT ROW(table.*) IS NULL FROM table; -- detect all-null rows
For more detail see Seção 9.17. Row constructors can also be used in connection with subqueries, as
discussed in Seção 9.16.
4.2.12. Expression Evaluation Rules
Value Expressions
The order of evaluation of subexpressions is not defined. In particular, the inputs of an operator or
function are not necessarily evaluated left-to-right or in any other fixed order.
Furthermore, if the result of an expression can be determined by evaluating only some parts of it,
then other subexpressions might not be evaluated at all. For instance, if one wrote
SELECT true OR somefunc();
then somefunc() would (probably) not be called at all. The same would be the case if one wrote
SELECT somefunc() OR true;
Note that this is not the same as the left-to-right "short-circuiting" of Boolean operators that is
found in some programming languages.
As a consequence, it is unwise to use functions with side effects as part of complex expressions. It
is particularly dangerous to rely on side effects or evaluation order in WHERE and HAVING clauses,
since those clauses are extensively reprocessed as part of developing an execution plan. Boolean
expressions (AND/OR/NOT combinations) in those clauses may be reorganized in any manner
allowed by the laws of Boolean algebra.
When it is essential to force evaluation order, a CASE construct (see Seção 9.13) may be used. For
example, this is an untrustworthy way of trying to avoid division by zero in a WHERE clause:
SELECT ... WHERE x <> 0 AND y/x > 1.5;
But this is safe:
SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
A CASE construct used in this fashion will defeat optimization attempts, so it should only be done
when necessary. (In this particular example, it would doubtless be best to sidestep the problem by
writing y > 1.5*x instead.)

Lexical Structure Acima Data Definition
Data Definition

Capítulo 5. Data Definition

Sumário
5.1. Table Basics
5.2. Default Values
5.3. Constraints
5.3.1. Check Constraints

5.3.2. Not-Null Constraints
5.3.3. Unique Constraints
5.3.4. Primary Keys
5.3.5. Chaves estrangeiras
5.4. System Columns

5.5.1. Adding a Column

5.5.2. Removing a Column
5.5.3. Adding a Constraint
5.5.4. Removing a Constraint
5.5.5. Changing a Column's Default Value
5.5.6. Changing a Column's Data Type
5.5.7. Renaming a Column
5.5.8. Renaming a Table
5.6. Privileges
5.7. Schemas
5.7.1. Creating a Schema

5.7.2. The Public Schema
5.7.3. The Schema Search Path
5.7.4. Schemas and Privileges
5.7.5. The System Catalog Schema
5.7.6. Usage Patterns
5.7.7. Portability
5.8. Herança
5.9. Partitioning
5.9.1. Visão geral

5.9.2. Implementing Partitioning
5.9.3. Managing Partitions
5.9.4. Partitioning and Constraint Exclusion
5.9.5. Caveats

This chapter covers how one creates the database structures that will hold one's data. In a
relational database, the raw data is stored in tables, so the majority of this chapter is devoted to
explaining how tables are created and modified and what features are available to control what data
is stored in the tables. Subsequently, we discuss how tables can be organized into schemas, and
how privileges can be assigned to tables. Finally, we will briefly look at other features that affect the
http://pgdocptbr.sourceforge.net/pg82/ddl.html[09/02/2018 17:55:59]
Data Definition
data storage, such as inheritance, views, functions, and triggers.

Value Expressions Acima Table Basics
http://pgdocptbr.sourceforge.net/pg82/ddl.html[09/02/2018 17:55:59]
Table Basics

Anterior Início Capítulo 5. Data Definition Fim Próxima
5.1. Table Basics

A table in a relational database is much like a table on paper: It consists of rows and columns. The
number and order of the columns is fixed, and each column has a name. The number of rows is
variable — it reflects how much data is stored at a given moment. SQL does not make any
guarantees about the order of the rows in a table. When a table is read, the rows will appear in
random order, unless sorting is explicitly requested. This is covered in Capítulo 7. Furthermore, SQL
does not assign unique identifiers to rows, so it is possible to have several completely identical rows
in a table. This is a consequence of the mathematical model that underlies SQL but is usually not
desirable. Later in this chapter we will see how to deal with this issue.
Each column has a data type. The data type constrains the set of possible values that can be
assigned to a column and assigns semantics to the data stored in the column so that it can be used
for computations. For instance, a column declared to be of a numerical type will not accept arbitrary
text strings, and the data stored in such a column can be used for mathematical computations. By
contrast, a column declared to be of a character string type will accept almost any kind of data but
it does not lend itself to mathematical calculations, although other operations such as string
concatenation are available.
PostgreSQL includes a sizable set of built-in data types that fit many applications. Users can also
define their own data types. Most built-in data types have obvious names and semantics, so we
defer a detailed explanation to Capítulo 8. Some of the frequently used data types are integer for
whole numbers, numeric for possibly fractional numbers, text for character strings, date for dates,
time for time-of-day values, and timestamp for values containing both date and time.
To create a table, you use the aptly named CREATE TABLE command. In this command you specify
at least a name for the new table, the names of the columns and the data type of each column. For
example:
CREATE TABLE my_first_table (

first_column text,
second_column integer
);
This creates a table named my_first_table with two columns. The first column is named
first_column and has a data type of text; the second column has the name second_column and the
type integer. The table and column names follow the identifier syntax explained in Seção 4.1.1. The
type names are usually also identifiers, but there are some exceptions. Note that the column list is
comma-separated and surrounded by parentheses.
Of course, the previous example was heavily contrived. Normally, you would give names to your
tables and columns that convey what kind of data they store. So let's look at a more realistic
example:
CREATE TABLE products (

product_no integer,
name text,
price numeric
);
(The numeric type can store fractional components, as would be typical of monetary amounts.)
Dica: When you create many interrelated tables it is wise to choose a consistent naming
http://pgdocptbr.sourceforge.net/pg82/ddl-basics.html[09/02/2018 17:56:09]
Table Basics
pattern for the tables and columns. For instance, there is a choice of using singular or
plural nouns for table names, both of which are favored by some theorist or other.
There is a limit on how many columns a table can contain. Depending on the column types, it is
between 250 and 1600. However, defining a table with anywhere near this many columns is highly
unusual and often a questionable design.
If you no longer need a table, you can remove it using the DROP TABLE command. For example:
DROP TABLE my_first_table;

DROP TABLE products;
Attempting to drop a table that does not exist is an error. Nevertheless, it is common in SQL script
files to unconditionally try to drop each table before creating it, ignoring any error messages, so
that the script works whether or not the table exists. (If you like, you can use the DROP TABLE IF
EXISTS variant to avoid the error messages, but this is not standard SQL.)
If you need to modify a table that already exists look into Seção 5.5 later in this chapter.
With the tools discussed so far you can create fully functional tables. The remainder of this chapter
is concerned with adding features to the table definition to ensure data integrity, security, or
convenience. If you are eager to fill your tables with data now you can skip ahead to Capítulo 6 and
read the rest of this chapter later.

Data Definition Acima Default Values
http://pgdocptbr.sourceforge.net/pg82/ddl-basics.html[09/02/2018 17:56:09]
Default Values

5.2. Default Values

A column can be assigned a default value. When a new row is created and no values are specified
for some of the columns, those columns will be filled with their respective default values. A data
manipulation command can also request explicitly that a column be set to its default value, without
having to know what that value is. (Details about data manipulation commands are in Capítulo 6.)
If no default value is declared explicitly, the default value is the null value. This usually makes
sense because a null value can be considered to represent unknown data.
In a table definition, default values are listed after the column data type. For example:

product_no integer,
name text,
price numeric DEFAULT 9.99
);
The default value may be an expression, which will be evaluated whenever the default value is
inserted (not when the table is created). A common example is that a timestamp column may have
a default of now(), so that it gets set to the time of row insertion. Another common example is
generating a "serial number" for each row. In PostgreSQL this is typically done by something like

product_no integer DEFAULT nextval('products_product_no_seq'),
...
);
where the nextval() function supplies successive values from a sequence object (see Seção 9.12).
This arrangement is sufficiently common that there's a special shorthand for it:

product_no SERIAL,
...
);
The SERIAL shorthand is discussed further in Seção 8.1.4.

Table Basics Acima Constraints
http://pgdocptbr.sourceforge.net/pg82/ddl-default.html[09/02/2018 17:56:18]
Constraints

5.3. Constraints
Data types are a way to limit the kind of data that can be stored in a table. For many applications,
however, the constraint they provide is too coarse. For example, a column containing a product
price should probably only accept positive values. But there is no standard data type that accepts
only positive numbers. Another issue is that you might want to constrain column data with respect
to other columns or rows. For example, in a table containing product information, there should be
only one row for each product number.
To that end, SQL allows you to define constraints on columns and tables. Constraints give you as
much control over the data in your tables as you wish. If a user attempts to store data in a column
that would violate a constraint, an error is raised. This applies even if the value came from the
default value definition.
5.3.1. Check Constraints
A check constraint is the most generic constraint type. It allows you to specify that the value in a
certain column must satisfy a Boolean (truth-value) expression. For instance, to require positive
product prices, you could use:

product_no integer,
name text,
price numeric CHECK (price > 0)
);
As you see, the constraint definition comes after the data type, just like default value definitions.
Default values and constraints can be listed in any order. A check constraint consists of the key
word CHECK followed by an expression in parentheses. The check constraint expression should
involve the column thus constrained, otherwise the constraint would not make too much sense.
You can also give the constraint a separate name. This clarifies error messages and allows you to
refer to the constraint when you need to change it. The syntax is:

product_no integer,
name text,
price numeric CONSTRAINT positive_price CHECK (price > 0)
);
So, to specify a named constraint, use the key word CONSTRAINT followed by an identifier followed
by the constraint definition. (If you don't specify a constraint name in this way, the system chooses
a name for you.)
A check constraint can also refer to several columns. Say you store a regular price and a discounted
price, and you want to ensure that the discounted price is lower than the regular price.

product_no integer,
name text,
price numeric CHECK (price > 0),
discounted_price numeric CHECK (discounted_price > 0),
CHECK (price > discounted_price)
http://pgdocptbr.sourceforge.net/pg82/ddl-constraints.html[09/02/2018 17:56:31]
Constraints
);
The first two constraints should look familiar. The third one uses a new syntax. It is not attached to
a particular column, instead it appears as a separate item in the comma-separated column list.
Column definitions and these constraint definitions can be listed in mixed order.
We say that the first two constraints are column constraints, whereas the third one is a table
constraint because it is written separately from any one column definition. Column constraints can
also be written as table constraints, while the reverse is not necessarily possible, since a column
constraint is supposed to refer to only the column it is attached to. (PostgreSQL doesn't enforce
that rule, but you should follow it if you want your table definitions to work with other database
systems.) The above example could also be written as

product_no integer,
name text,
price numeric,
CHECK (price > 0),
discounted_price numeric,
CHECK (discounted_price > 0),
CHECK (price > discounted_price)
);
or even

product_no integer,
name text,
price numeric CHECK (price > 0),
CHECK (discounted_price > 0 AND price > discounted_price)
);
It's a matter of taste.
Names can be assigned to table constraints in just the same way as for column constraints:

product_no integer,
name text,
price numeric,
CHECK (price > 0),
CHECK (discounted_price > 0),
CONSTRAINT valid_discount CHECK (price > discounted_price)
);
It should be noted that a check constraint is satisfied if the check expression evaluates to true or
the null value. Since most expressions will evaluate to the null value if any operand is null, they will
not prevent null values in the constrained columns. To ensure that a column does not contain null
values, the not-null constraint described in the next section can be used.
5.3.2. Not-Null Constraints
A not-null constraint simply specifies that a column must not assume the null value. A syntax
example:

product_no integer NOT NULL,
name text NOT NULL,
price numeric
);
A not-null constraint is always written as a column constraint. A not-null constraint is functionally

equivalent to creating a check constraint CHECK (nome_da_coluna IS NOT NULL), but in
PostgreSQL creating an explicit not-null constraint is more efficient. The drawback is that you
Constraints
cannot give explicit names to not-null constraints created this way.
Of course, a column can have more than one constraint. Just write the constraints one after
another:

product_no integer NOT NULL,
name text NOT NULL,
price numeric NOT NULL CHECK (price > 0)
);
The order doesn't matter. It does not necessarily determine in which order the constraints are
checked.
The NOT NULL constraint has an inverse: the NULL constraint. This does not mean that the column
must be null, which would surely be useless. Instead, this simply selects the default behavior that
the column may be null. The NULL constraint is not present in the SQL standard and should not be
used in portable applications. (It was only added to PostgreSQL to be compatible with some other
database systems.) Some users, however, like it because it makes it easy to toggle the constraint
in a script file. For example, you could start with

product_no integer NULL,
name text NULL,
price numeric NULL
);
and then insert the NOT key word where desired.
Dica: In most database designs the majority of columns should be marked not null.
5.3.3. Unique Constraints
Unique constraints ensure that the data contained in a column or a group of columns is unique with
respect to all the rows in the table. The syntax is

product_no integer UNIQUE,
name text,
price numeric
);
when written as a column constraint, and

product_no integer,
name text,
price numeric,
UNIQUE (product_no)
);
when written as a table constraint.
If a unique constraint refers to a group of columns, the columns are listed separated by commas:
CREATE TABLE example (

a integer,
b integer,
c integer,
UNIQUE (a, c)
);
This specifies that the combination of values in the indicated columns is unique across the whole
table, though any one of the columns need not be (and ordinarily isn't) unique.
Constraints
You can assign your own name for a unique constraint, in the usual way:

product_no integer CONSTRAINT must_be_different UNIQUE,
name text,
price numeric
);
In general, a unique constraint is violated when there are two or more rows in the table where the
values of all of the columns included in the constraint are equal. However, two null values are not
considered equal in this comparison. That means even in the presence of a unique constraint it is
possible to store duplicate rows that contain a null value in at least one of the constrained columns.
This behavior conforms to the SQL standard, but we have heard that other SQL databases may not
follow this rule. So be careful when developing applications that are intended to be portable.
5.3.4. Primary Keys
Technically, a primary key constraint is simply a combination of a unique constraint and a not-null
constraint. So, the following two table definitions accept the same data:

product_no integer UNIQUE NOT NULL,
name text,
price numeric
);

product_no integer PRIMARY KEY,
name text,
price numeric
);
Primary keys can also constrain more than one column; the syntax is similar to unique constraints:
CREATE TABLE example (

a integer,
b integer,
c integer,
PRIMARY KEY (a, c)
);
A primary key indicates that a column or group of columns can be used as a unique identifier for
rows in the table. (This is a direct consequence of the definition of a primary key. Note that a
unique constraint does not, by itself, provide a unique identifier because it does not exclude null
values.) This is useful both for documentation purposes and for client applications. For example, a
GUI application that allows modifying row values probably needs to know the primary key of a table
to be able to identify rows uniquely.
A table can have at most one primary key. (There can be any number of unique and not-null
constraints, which are functionally the same thing, but only one can be identified as the primary
key.) Relational database theory dictates that every table must have a primary key. This rule is not
enforced by PostgreSQL, but it is usually best to follow it.
5.3.5. Chaves estrangeiras
A foreign key constraint specifies that the values in a column (or a group of columns) must match
the values appearing in some row of another table. We say this maintains the referential integrity
between two related tables.
Say you have the product table that we have used several times already:
Constraints

name text,
price numeric
);
Let's also assume you have a table storing orders of those products. We want to ensure that the
orders table only contains orders of products that actually exist. So we define a foreign key
constraint in the orders table that references the products table:
CREATE TABLE orders (

order_id integer PRIMARY KEY,
product_no integer REFERENCES products (product_no),
quantity integer
);
Now it is impossible to create orders with product_no entries that do not appear in the products
table.
We say that in this situation the orders table is the referencing table and the products table is the
referenced table. Similarly, there are referencing and referenced columns.
You can also shorten the above command to

product_no integer REFERENCES products,
quantity integer
);
because in absence of a column list the primary key of the referenced table is used as the
referenced column(s).
A foreign key can also constrain and reference a group of columns. As usual, it then needs to be
written in table constraint form. Here is a contrived syntax example:
CREATE TABLE t1 (
a integer PRIMARY KEY,
b integer,
c integer,
FOREIGN KEY (b, c) REFERENCES other_table (c1, c2)
);
Of course, the number and type of the constrained columns need to match the number and type of
the referenced columns.
You can assign your own name for a foreign key constraint, in the usual way.
A table can contain more than one foreign key constraint. This is used to implement many-to-many
relationships between tables. Say you have tables about products and orders, but now you want to
allow one order to contain possibly many products (which the structure above did not allow). You
could use this table structure:

name text,
price numeric
);
shipping_address text,
...
);
CREATE TABLE order_items (
product_no integer REFERENCES products,
order_id integer REFERENCES orders,
quantity integer,
PRIMARY KEY (product_no, order_id)
);
Constraints
Notice that the primary key overlaps with the foreign keys in the last table.
We know that the foreign keys disallow creation of orders that do not relate to any products. But
what if a product is removed after an order is created that references it? SQL allows you to handle
that as well. Intuitively, we have a few options:
Disallow deleting a referenced product
Delete the orders as well
Something else?
To illustrate this, let's implement the following policy on the many-to-many relationship example
above: when someone wants to remove a product that is still referenced by an order (via
order_items), we disallow it. If someone removes an order, the order items are removed as well.

name text,
price numeric
);
shipping_address text,
...
);
CREATE TABLE order_items (
product_no integer REFERENCES products ON DELETE RESTRICT,
order_id integer REFERENCES orders ON DELETE CASCADE,
quantity integer,
PRIMARY KEY (product_no, order_id)
);
Restricting and cascading deletes are the two most common options. RESTRICT prevents deletion of
a referenced row. NO ACTION means that if any referencing rows still exist when the constraint is
checked, an error is raised; this is the default behavior if you do not specify anything. (The
essential difference between these two choices is that NO ACTION allows the check to be deferred
until later in the transaction, whereas RESTRICT does not.) CASCADE specifies that when a
referenced row is deleted, row(s) referencing it should be automatically deleted as well. There are
two other options: SET NULL and SET DEFAULT. These cause the referencing columns to be set to
nulls or default values, respectively, when the referenced row is deleted. Note that these do not
excuse you from observing any constraints. For example, if an action specifies SET DEFAULT but the
default value would not satisfy the foreign key, the operation will fail.
Analogous to ON DELETE there is also ON UPDATE which is invoked when a referenced column is
changed (updated). The possible actions are the same.
More information about updating and deleting data is in Capítulo 6.
Finally, we should mention that a foreign key must reference columns that either are a primary key
or form a unique constraint. If the foreign key references a unique constraint, there are some
additional possibilities regarding how null values are matched. These are explained in the reference
documentation for CREATE TABLE.

Default Values Acima System Columns
System Columns

5.4. System Columns

Every table has several system columns that are implicitly defined by the system. Therefore, these
names cannot be used as names of user-defined columns. (Note that these restrictions are separate
from whether the name is a key word or not; quoting a name will not allow you to escape these
restrictions.) You do not really need to be concerned about these columns, just know they exist.
oid
The object identifier (object ID) of a row. This column is only present if the table was created
using WITH OIDS, or if the default_with_oids configuration variable was set at the time. This
column is of type oid (same name as the column); see Seção 8.12 for more information about
the type.
tableoid
The OID of the table containing this row. This column is particularly handy for queries that
select from inheritance hierarchies (see Seção 5.8), since without it, it's difficult to tell which
individual table a row came from. The tableoid can be joined against the oid column of
pg_class to obtain the table name.
xmin
The identity (transaction ID) of the inserting transaction for this row version. (A row version is
an individual state of a row; each update of a row creates a new row version for the same
logical row.)
cmin
The command identifier (starting at zero) within the inserting transaction.
xmax
The identity (transaction ID) of the deleting transaction, or zero for an undeleted row version.
It is possible for this column to be nonzero in a visible row version. That usually indicates that
the deleting transaction hasn't committed yet, or that an attempted deletion was rolled back.
cmax
The command identifier within the deleting transaction, or zero.
ctid
The physical location of the row version within its table. Note that although the ctid can be
used to locate the row version very quickly, a row's ctid will change each time it is updated or
moved by VACUUM FULL. Therefore ctid is useless as a long-term row identifier. The OID, or
even better a user-defined serial number, should be used to identify logical rows.
OIDs are 32-bit quantities and are assigned from a single cluster-wide counter. In a large or long-
lived database, it is possible for the counter to wrap around. Hence, it is bad practice to assume
that OIDs are unique, unless you take steps to ensure that this is the case. If you need to identify
the rows in a table, using a sequence generator is strongly recommended. However, OIDs can be
used as well, provided that a few additional precautions are taken:
http://pgdocptbr.sourceforge.net/pg82/ddl-system-columns.html[09/02/2018 17:56:39]
System Columns
A unique constraint should be created on the OID column of each table for which the OID will
be used to identify rows. When such a unique constraint (or unique index) exists, the system
takes care not to generate an OID matching an already-existing row. (Of course, this is only
possible if the table contains fewer than 232 (4 billion) rows, and in practice the table size had
better be much less than that, or performance may suffer.)
OIDs should never be assumed to be unique across tables; use the combination of tableoid
and row OID if you need a database-wide identifier.
Of course, the tables in question must be created WITH OIDS. As of PostgreSQL 8.1,
WITHOUT OIDS is the default.
Transaction identifiers are also 32-bit quantities. In a long-lived database it is possible for
transaction IDs to wrap around. This is not a fatal problem given appropriate maintenance
procedures; see Capítulo 22 for details. It is unwise, however, to depend on the uniqueness of
transaction IDs over the long term (more than one billion transactions).
Command identifiers are also 32-bit quantities. This creates a hard limit of 232 (4 billion) SQL
commands within a single transaction. In practice this limit is not a problem — note that the limit is
on number of SQL commands, not number of rows processed.

Constraints Acima Modifying Tables
http://pgdocptbr.sourceforge.net/pg82/ddl-system-columns.html[09/02/2018 17:56:39]
Modifying Tables


When you create a table and you realize that you made a mistake, or the requirements of the
application change, then you can drop the table and create it again. But this is not a convenient
option if the table is already filled with data, or if the table is referenced by other database objects
(for instance a foreign key constraint). Therefore PostgreSQL provides a family of commands to
make modifications to existing tables. Note that this is conceptually distinct from altering the data
contained in the table: here we are interested in altering the definition, or structure, of the table.
You can
Add columns,
Remove columns,
Add constraints,
Remove constraints,
Change default values,
Change column data types,
Rename columns,
Rename tables.
All these actions are performed using the ALTER TABLE command, which see for details beyond
those given here.
5.5.1. Adding a Column
To add a column, use a command like this:
ALTER TABLE products ADD COLUMN description text;
The new column is initially filled with whatever default value is given (null if you don't specify a
DEFAULT clause).
You can also define constraints on the column at the same time, using the usual syntax:
ALTER TABLE products ADD COLUMN description text CHECK (description <> '');
In fact all the options that can be applied to a column description in CREATE TABLE can be used
here. Keep in mind however that the default value must satisfy the given constraints, or the ADD
will fail. Alternatively, you can add constraints later (see below) after you've filled in the new
column correctly.
Dica: Adding a column with a default requires updating each row of the table (to store
the new column value). However, if no default is specified, PostgreSQL is able to avoid
the physical update. So if you intend to fill the column with mostly nondefault values, it's
http://pgdocptbr.sourceforge.net/pg82/ddl-alter.html[09/02/2018 17:56:48]
Modifying Tables
best to add the column with no default, insert the correct values using UPDATE, and
then add any desired default as described below.
5.5.2. Removing a Column
To remove a column, use a command like this:
ALTER TABLE products DROP COLUMN description;
Whatever data was in the column disappears. Table constraints involving the column are dropped,
too. However, if the column is referenced by a foreign key constraint of another table, PostgreSQL
will not silently drop that constraint. You can authorize dropping everything that depends on the
column by adding CASCADE:
ALTER TABLE products DROP COLUMN description CASCADE;
See Seção 5.11 for a description of the general mechanism behind this.
5.5.3. Adding a Constraint
To add a constraint, the table constraint syntax is used. For example:
ALTER TABLE products ADD CHECK (name <> '');

ALTER TABLE products ADD CONSTRAINT some_name UNIQUE (product_no);
ALTER TABLE products ADD FOREIGN KEY (product_group_id) REFERENCES product_groups;
To add a not-null constraint, which cannot be written as a table constraint, use this syntax:
ALTER TABLE products ALTER COLUMN product_no SET NOT NULL;
The constraint will be checked immediately, so the table data must satisfy the constraint before it
can be added.
5.5.4. Removing a Constraint
To remove a constraint you need to know its name. If you gave it a name then that's easy.
Otherwise the system assigned a generated name, which you need to find out. The psql command
\d nome_da_tabela can be helpful here; other interfaces might also provide a way to inspect table
details. Then the command is:
ALTER TABLE products DROP CONSTRAINT some_name;
(If you are dealing with a generated constraint name like $2, don't forget that you'll need to
double-quote it to make it a valid identifier.)
As with dropping a column, you need to add CASCADE if you want to drop a constraint that
something else depends on. An example is that a foreign key constraint depends on a unique or
primary key constraint on the referenced column(s).
This works the same for all constraint types except not-null constraints. To drop a not null
constraint use
ALTER TABLE products ALTER COLUMN product_no DROP NOT NULL;
Modifying Tables
(Recall that not-null constraints do not have names.)
5.5.5. Changing a Column's Default Value
To set a new default for a column, use a command like this:
ALTER TABLE products ALTER COLUMN price SET DEFAULT 7.77;
Note that this doesn't affect any existing rows in the table, it just changes the default for future
INSERT commands.
To remove any default value, use
ALTER TABLE products ALTER COLUMN price DROP DEFAULT;
This is effectively the same as setting the default to null. As a consequence, it is not an error to
drop a default where one hadn't been defined, because the default is implicitly the null value.
5.5.6. Changing a Column's Data Type
To convert a column to a different data type, use a command like this:
ALTER TABLE products ALTER COLUMN price TYPE numeric(10,2);
This will succeed only if each existing entry in the column can be converted to the new type by an
implicit cast. If a more complex conversion is needed, you can add a USING clause that specifies
how to compute the new values from the old.
PostgreSQL will attempt to convert the column's default value (if any) to the new type, as well as
any constraints that involve the column. But these conversions may fail, or may produce surprising
results. It's often best to drop any constraints on the column before altering its type, and then add
back suitably modified constraints afterwards.
5.5.7. Renaming a Column
To rename a column:
ALTER TABLE products RENAME COLUMN product_no TO product_number;
5.5.8. Renaming a Table
To rename a table:
ALTER TABLE products RENAME TO items;

System Columns Acima Privileges
Privileges

5.6. Privileges
When you create a database object, you become its owner. By default, only the owner of an object
can do anything with the object. In order to allow other users to use it, privileges must be granted.
(However, users that have the superuser attribute can always access any object.)
There are several different privileges: SELECT, INSERT, UPDATE, DELETE, REFERENCES, TRIGGER,
CREATE, CONNECT, TEMPORARY, EXECUTE, and USAGE. The privileges applicable to a particular
object vary depending on the object's type (table, function, etc). For complete information on the
different types of privileges supported by PostgreSQL, refer to the GRANT reference page. The
following sections and chapters will also show you how those privileges are used.
The right to modify or destroy an object is always the privilege of the owner only.
Nota: To change the owner of a table, index, sequence, or view, use the ALTER TABLE
command. There are corresponding ALTER commands for other object types.
To assign privileges, the GRANT command is used. For example, if joe is an existing user, and
accounts is an existing table, the privilege to update the table can be granted with
GRANT UPDATE ON accounts TO joe;
Writing ALL in place of a specific privilege grants all privileges that are relevant for the object type.
The special "user" name PUBLIC can be used to grant a privilege to every user on the system. Also,
"group" roles can be set up to help manage privileges when there are many users of a database —
for details see Capítulo 18.
To revoke a privilege, use the fittingly named REVOKE command:
REVOKE ALL ON accounts FROM PUBLIC;
The special privileges of the object owner (i.e., the right to do DROP, GRANT, REVOKE, etc.) are
always implicit in being the owner, and cannot be granted or revoked. But the object owner can
choose to revoke his own ordinary privileges, for example to make a table read-only for himself as
well as others.
Ordinarily, only the object's owner (or a superuser) can grant or revoke privileges on an object.
However, it is possible to grant a privilege "with grant option", which gives the recipient the right to
grant it in turn to others. If the grant option is subsequently revoked then all who received the
privilege from that recipient (directly or through a chain of grants) will lose the privilege. For details
see the GRANT and REVOKE reference pages.

Modifying Tables Acima Schemas
http://pgdocptbr.sourceforge.net/pg82/ddl-priv.html[09/02/2018 17:56:56]
Schemas

5.7. Schemas
A PostgreSQL database cluster contains one or more named databases. Users and groups of users
are shared across the entire cluster, but no other data is shared across databases. Any given client
connection to the server can access only the data in a single database, the one specified in the
connection request.
Nota: Users of a cluster do not necessarily have the privilege to access every database
in the cluster. Sharing of user names means that there cannot be different users named,
say, joe in two databases in the same cluster; but the system can be configured to allow
joe access to only some of the databases.
A database contains one or more named schemas, which in turn contain tables. Schemas also
contain other kinds of named objects, including data types, functions, and operators. The same
object name can be used in different schemas without conflict; for example, both schema1 and
myschema may contain tables named mytable. Unlike databases, schemas are not rigidly
separated: a user may access objects in any of the schemas in the database he is connected to, if
he has privileges to do so.
There are several reasons why one might want to use schemas:
To allow many users to use one database without interfering with each other.
To organize database objects into logical groups to make them more manageable.
Third-party applications can be put into separate schemas so they cannot collide with the
names of other objects.
Schemas are analogous to directories at the operating system level, except that schemas cannot be
nested.
5.7.1. Creating a Schema
To create a schema, use the CREATE SCHEMA command. Give the schema a name of your choice.
For example:
CREATE SCHEMA myschema;
To create or access objects in a schema, write a qualified name consisting of the schema name and
table name separated by a dot:
esquema.tabela
This works anywhere a table name is expected, including the table modification commands and the
data access commands discussed in the following chapters. (For brevity we will speak of tables only,
but the same ideas apply to other kinds of named objects, such as types and functions.)
Actually, the even more general syntax

banco_de_dados.esquema.tabela
can be used too, but at present this is just for pro forma compliance with the SQL standard. If you
http://pgdocptbr.sourceforge.net/pg82/ddl-schemas.html[09/02/2018 17:57:07]
Schemas
write a database name, it must be the same as the database you are connected to.
So to create a table in the new schema, use
CREATE TABLE myschema.mytable (

...
);
To drop a schema if it's empty (all objects in it have been dropped), use
DROP SCHEMA myschema;
To drop a schema including all contained objects, use
DROP SCHEMA myschema CASCADE;
See Seção 5.11 for a description of the general mechanism behind this.
Often you will want to create a schema owned by someone else (since this is one of the ways to
restrict the activities of your users to well-defined namespaces). The syntax for that is:
CREATE SCHEMA nome_do_esquema AUTHORIZATION nome_do_usuário;
You can even omit the schema name, in which case the schema name will be the same as the user
name. See Seção 5.7.6 for how this can be useful.
Schema names beginning with pg_ are reserved for system purposes and may not be created by
users.
5.7.2. The Public Schema
In the previous sections we created tables without specifying any schema names. By default, such
tables (and other objects) are automatically put into a schema named "public". Every new database
contains such a schema. Thus, the following are equivalent:
CREATE TABLE products ( ... );
and
CREATE TABLE public.products ( ... );
5.7.3. The Schema Search Path
Qualified names are tedious to write, and it's often best not to wire a particular schema name into
applications anyway. Therefore tables are often referred to by unqualified names, which consist of
just the table name. The system determines which table is meant by following a search path, which
is a list of schemas to look in. The first matching table in the search path is taken to be the one
wanted. If there is no match in the search path, an error is reported, even if matching table names
exist in other schemas in the database.
The first schema named in the search path is called the current schema. Aside from being the first
schema searched, it is also the schema in which new tables will be created if the CREATE TABLE
command does not specify a schema name.
Schemas
To show the current search path, use the following command:
SHOW search_path;
In the default setup this returns:
search_path
--------------
"$user",public
The first element specifies that a schema with the same name as the current user is to be searched.
If no such schema exists, the entry is ignored. The second element refers to the public schema that
we have seen already.
The first schema in the search path that exists is the default location for creating new objects. That
is the reason that by default objects are created in the public schema. When objects are referenced
in any other context without schema qualification (table modification, data modification, or query
commands) the search path is traversed until a matching object is found. Therefore, in the default
configuration, any unqualified access again can only refer to the public schema.
To put our new schema in the path, we use
SET search_path TO myschema,public;
(We omit the $user here because we have no immediate need for it.) And then we can access the
table without schema qualification:
DROP TABLE mytable;
Also, since myschema is the first element in the path, new objects would by default be created in it.
We could also have written
SET search_path TO myschema;
Then we no longer have access to the public schema without explicit qualification. There is nothing
special about the public schema except that it exists by default. It can be dropped, too.
See also Seção 9.19 for other ways to manipulate the schema search path.
The search path works in the same way for data type names, function names, and operator names
as it does for table names. Data type and function names can be qualified in exactly the same way
as table names. If you need to write a qualified operator name in an expression, there is a special
provision: you must write
OPERATOR(esquema.operador)
This is needed to avoid syntactic ambiguity. An example is
SELECT 3 OPERATOR(pg_catalog.+) 4;
In practice one usually relies on the search path for operators, so as not to have to write anything
so ugly as that.
5.7.4. Schemas and Privileges
By default, users cannot access any objects in schemas they do not own. To allow that, the owner
Schemas
of the schema needs to grant the USAGE privilege on the schema. To allow users to make use of
the objects in the schema, additional privileges may need to be granted, as appropriate for the
object.
A user can also be allowed to create objects in someone else's schema. To allow that, the CREATE
privilege on the schema needs to be granted. Note that by default, everyone has CREATE and
USAGE privileges on the schema public. This allows all users that are able to connect to a given
database to create objects in its public schema. If you do not want to allow that, you can revoke
that privilege:
REVOKE CREATE ON SCHEMA public FROM PUBLIC;
(The first "public" is the schema, the second "public" means "every user". In the first sense it is an
identifier, in the second sense it is a key word, hence the different capitalization; recall the
guidelines from Seção 4.1.1.)
5.7.5. The System Catalog Schema
In addition to public and user-created schemas, each database contains a pg_catalog schema,
which contains the system tables and all the built-in data types, functions, and operators.
pg_catalog is always effectively part of the search path. If it is not named explicitly in the path then
it is implicitly searched before searching the path's schemas. This ensures that built-in names will
always be findable. However, you may explicitly place pg_catalog at the end of your search path if
you prefer to have user-defined names override built-in names.
In PostgreSQL versions before 7.3, table names beginning with pg_ were reserved. This is no longer
true: you may create such a table name if you wish, in any non-system schema. However, it's best
to continue to avoid such names, to ensure that you won't suffer a conflict if some future version
defines a system table named the same as your table. (With the default search path, an unqualified
reference to your table name would be resolved as the system table instead.) System tables will
continue to follow the convention of having names beginning with pg_, so that they will not conflict
with unqualified user-table names so long as users avoid the pg_ prefix.
5.7.6. Usage Patterns
Schemas can be used to organize your data in many ways. There are a few usage patterns that are
recommended and are easily supported by the default configuration:
If you do not create any schemas then all users access the public schema implicitly. This
simulates the situation where schemas are not available at all. This setup is mainly
recommended when there is only a single user or a few cooperating users in a database. This
setup also allows smooth transition from the non-schema-aware world.
You can create a schema for each user with the same name as that user. Recall that the
default search path starts with $user, which resolves to the user name. Therefore, if each user
has a separate schema, they access their own schemas by default.
If you use this setup then you might also want to revoke access to the public schema (or drop
it altogether), so users are truly constrained to their own schemas.
To install shared applications (tables to be used by everyone, additional functions provided by

third parties, etc.), put them into separate schemas. Remember to grant appropriate
privileges to allow the other users to access them. Users can then refer to these additional
objects by qualifying the names with a schema name, or they can put the additional schemas
into their search path, as they choose.
5.7.7. Portability
In the SQL standard, the notion of objects in the same schema being owned by different users does
Schemas
not exist. Moreover, some implementations do not allow you to create schemas that have a
different name than their owner. In fact, the concepts of schema and user are nearly equivalent in a
database system that implements only the basic schema support specified in the standard.
Therefore, many users consider qualified names to really consist of
nome_do_usuário.nome_da_tabela. This is how PostgreSQL will effectively behave if you create a
per-user schema for every user.
Also, there is no concept of a public schema in the SQL standard. For maximum conformance to the
standard, you should not use (perhaps even remove) the public schema.
Of course, some SQL database systems might not implement schemas at all, or provide namespace
support by allowing (possibly limited) cross-database access. If you need to work with those
systems, then maximum portability would be achieved by not using schemas at all.

Privileges Acima Herança
Herança

5.8. Herança
PostgreSQL implements table inheritance, which can be a useful tool for database designers.
(SQL:1999 and later define a type inheritance feature, which differs in many respects from the
features described here.)
Let's start with an example: suppose we are trying to build a data model for cities. Each state has
many cities, but only one capital. We want to be able to quickly retrieve the capital city for any
particular state. This can be done by creating two tables, one for state capitals and one for cities
that are not capitals. However, what happens when we want to ask for data about a city, regardless
of whether it is a capital or not? The inheritance feature can help to resolve this problem. We define
the capitals table so that it inherits from cities:
CREATE TABLE cities (

name text,
population float,
altitude int -- in feet
);
CREATE TABLE capitals (
state char(2)
) INHERITS (cities);
In this case, the capitals table inherits all the columns of its parent table, cities. State capitals also
have an extra column, state, that shows their state.
In PostgreSQL, a table can inherit from zero or more other tables, and a query can reference either
all rows of a table or all rows of a table plus all of its descendant tables. The latter behavior is the
default. For example, the following query finds the names of all cities, including state capitals, that
are located at an altitude over 500ft:
SELECT name, altitude

FROM cities
Given the sample data from the PostgreSQL tutorial (see Seção 2.1), this returns:
name | altitude
-----------+----------
Las Vegas | 2174
Mariposa | 1953
Madison | 845
On the other hand, the following query finds all the cities that are not state capitals and are situated
at an altitude over 500ft:
SELECT name, altitude

FROM ONLY cities
name | altitude
-----------+----------
Las Vegas | 2174
Mariposa | 1953
Here the ONLY keyword indicates that the query should apply only to cities, and not any tables
below cities in the inheritance hierarchy. Many of the commands that we have already discussed —
http://pgdocptbr.sourceforge.net/pg82/ddl-inherit.html[09/02/2018 17:57:16]
Herança
SELECT, UPDATE and DELETE — support the ONLY keyword.
In some cases you may wish to know which table a particular row originated from. There is a
system column called tableoid in each table which can tell you the originating table:
SELECT c.tableoid, c.name, c.altitude

FROM cities c
WHERE c.altitude > 500;
which returns:
tableoid | name | altitude

----------+-----------+----------
139793 | Las Vegas | 2174
139793 | Mariposa | 1953
139798 | Madison | 845
(If you try to reproduce this example, you will probably get different numeric OIDs.) By doing a join
with pg_class you can see the actual table names:
SELECT p.relname, c.name, c.altitude

FROM cities c, pg_class p
WHERE c.altitude > 500 and c.tableoid = p.oid;
which returns:
relname | name | altitude

----------+-----------+----------
cities | Las Vegas | 2174
cities | Mariposa | 1953
capitals | Madison | 845
Inheritance does not automatically propagate data from INSERT or COPY commands to other tables
in the inheritance hierarchy. In our example, the following INSERT statement will fail:
INSERT INTO cities (name, population, altitude, state)

VALUES ('New York', NULL, NULL, 'NY');
We might hope that the data would somehow be routed to the capitals table, but this does not
happen: INSERT always inserts into exactly the table specified. In some cases it is possible to
redirect the insertion using a rule (see Capítulo 35). However that does not help for the above case
because the cities table does not contain the column state, and so the command will be rejected
before the rule can be applied.
All check constraints and not-null constraints on a parent table are automatically inherited by its
children. Other types of constraints (unique, primary key, and foreign key constraints) are not
inherited.
A table can inherit from more than one parent table, in which case it has the union of the columns
defined by the parent tables. Any columns declared in the child table's definition are added to
these. If the same column name appears in multiple parent tables, or in both a parent table and the
child's definition, then these columns are "merged" so that there is only one such column in the
child table. To be merged, columns must have the same data types, else an error is raised. The
merged column will have copies of all the check constraints coming from any one of the column
definitions it came from, and will be marked not-null if any of them are.
Table inheritance is typically established when the child table is created, using the INHERITS clause
of the CREATE TABLE statement. Alternatively, a table which is already defined in a compatible way
can have a new parent relationship added, using the INHERIT variant of ALTER TABLE. To do this the
new child table must already include columns with the same names and types as the columns of the
parent. It must also include check constraints with the same names and check expressions as those
of the parent. Similarly an inheritance link can be removed from a child using the NO INHERIT
variant of ALTER TABLE. Dynamically adding and removing inheritance links like this can be useful
Herança
when the inheritance relationship is being used for table partitioning (see Seção 5.9).
One convenient way to create a compatible table that will later be made a new child is to use the
LIKE clause in CREATE TABLE. This creates a new table with the same columns as the source table.
If there are any CHECK constraints defined on the source table, the INCLUDING CONSTRAINTS
option to LIKE should be specified, as the new child must have constraints matching the parent to
be considered compatible.
A parent table cannot be dropped while any of its children remain. Neither can columns of child
tables be dropped or altered if they are inherited from any parent tables. If you wish to remove a
table and all of its descendants, one easy way is to drop the parent table with the CASCADE option.
ALTER TABLE will propagate any changes in column data definitions and check constraints down the
inheritance hierarchy. Again, dropping columns or constraints on parent tables is only possible when
using the CASCADE option. ALTER TABLE follows the same rules for duplicate column merging and
rejection that apply during CREATE TABLE.
5.8.1. Caveats
Table access permissions are not automatically inherited. Therefore, a user attempting to access a
parent table must either have permissions to do the operation on all its child tables as well, or must
use the ONLY notation. When adding a new child table to an existing inheritance hierarchy, be
careful to grant all the needed permissions on it.
A serious limitation of the inheritance feature is that indexes (including unique constraints) and
foreign key constraints only apply to single tables, not to their inheritance children. This is true on
both the referencing and referenced sides of a foreign key constraint. Thus, in the terms of the
above example:
If we declared cities.name to be UNIQUE or a PRIMARY KEY, this would not stop the capitals
table from having rows with names duplicating rows in cities. And those duplicate rows would
by default show up in queries from cities. In fact, by default capitals would have no unique
constraint at all, and so could contain multiple rows with the same name. You could add a
unique constraint to capitals, but this would not prevent duplication compared to cities.
Similarly, if we were to specify that cities.name REFERENCES some other table, this constraint
would not automatically propagate to capitals. In this case you could work around it by
manually adding the same REFERENCES constraint to capitals.
Specifying that another table's column REFERENCES cities(name) would allow the other table
to contain city names, but not capital names. There is no good workaround for this case.
These deficiencies will probably be fixed in some future release, but in the meantime considerable
care is needed in deciding whether inheritance is useful for your problem.
Deprecated: In releases of PostgreSQL prior to 7.1, the default behavior was not to
include child tables in queries. This was found to be error prone and also in violation of
the SQL standard. You can get the pre-7.1 behavior by turning off the sql_inheritance
configuration option.

Schemas Acima Partitioning
Partitioning

5.9. Partitioning
PostgreSQL supports basic table partitioning. This section describes why and how to implement
partitioning as part of your database design.
5.9.1. Visão geral
Partitioning refers to splitting what is logically one large table into smaller physical pieces.
Partitioning can provide several benefits:
Query performance can be improved dramatically in certain situations, particularly when most
of the heavily accessed rows of the table are in a single partition or a small number of
partitions. The partitioning substitutes for leading columns of indexes, reducing index size and
making it more likely that the heavily-used parts of the indexes fit in memory.
When queries or updates access a large percentage of a a single partition, performance can be
improved by taking advantage of sequential scan of that partition instead of using an index
and random access reads scattered across the whole table.
Bulk loads and deletes may be accomplished by adding or removing partitions, if that
requirement is planned into the partitioning design. ALTER TABLE is far faster than a bulk
operation. It also entirely avoids the VACUUM overhead caused by a bulk DELETE.
Seldom-used data can be migrated to cheaper and slower storage media.
The benefits will normally be worthwhile only when a table would otherwise be very large. The
exact point at which a table will benefit from partitioning depends on the application, although a
rule of thumb is that the size of the table should exceed the physical memory of the database
server.
Currently, PostgreSQL supports partitioning via table inheritance. Each partition must be created as
a child table of a single parent table. The parent table itself is normally empty; it exists just to
represent the entire data set. You should be familiar with inheritance (see Seção 5.8) before
attempting to set up partitioning.
The following forms of partitioning can be implemented in PostgreSQL:
Range Partitioning
The table is partitioned into "ranges" defined by a key column or set of columns, with no
overlap between the ranges of values assigned to different partitions. For example one might
partition by date ranges, or by ranges of identifiers for particular business objects.
List Partitioning
The table is partitioned by explicitly listing which key values appear in each partition.
5.9.2. Implementing Partitioning
To set up a partitioned table, do the following:
1. Create the "master" table, from which all of the partitions will inherit.
http://pgdocptbr.sourceforge.net/pg82/ddl-partitioning.html[09/02/2018 17:57:24]
Partitioning
This table will contain no data. Do not define any check constraints on this table, unless you
intend them to be applied equally to all partitions. There is no point in defining any indexes or
unique constraints on it, either.
2. Create several "child" tables that each inherit from the master table. Normally, these tables
will not add any columns to the set inherited from the master.
We will refer to the child tables as partitions, though they are in every way normal PostgreSQL
tables.
3. Add table constraints to the partition tables to define the allowed key values in each partition.
Typical examples would be:
CHECK ( x = 1 )
CHECK ( county IN ( 'Oxfordshire', 'Buckinghamshire', 'Warwickshire' ))
CHECK ( outletID >= 100 AND outletID < 200 )
Ensure that the constraints guarantee that there is no overlap between the key values
permitted in different partitions. A common mistake is to set up range constraints like this:
CHECK ( outletID BETWEEN 100 AND 200 )

CHECK ( outletID BETWEEN 200 AND 300 )
This is wrong since it is not clear which partition the key value 200 belongs in.
Note that there is no difference in syntax between range and list partitioning; those terms are
descriptive only.
4. For each partition, create an index on the key column(s), as well as any other indexes you
might want. (The key index is not strictly necessary, but in most scenarios it is helpful. If you
intend the key values to be unique then you should always create a unique or primary-key
constraint for each partition.)
5. Optionally, define a rule or trigger to redirect modifications of the master table to the
appropriate partition.
6. Ensure that the constraint_exclusion configuration parameter is enabled in postgresql.conf.

Without this, queries will not be optimized as desired.
For example, suppose we are constructing a database for a large ice cream company. The company
measures peak temperatures every day as well as ice cream sales in each region. Conceptually, we
want a table like this:
CREATE TABLE measurement (

city_id int not null,
logdate date not null,
peaktemp int,
unitsales int
);
We know that most queries will access just the last week's, month's or quarter's data, since the
main use of this table will be to prepare online reports for management. To reduce the amount of
old data that needs to be stored, we decide to only keep the most recent 3 years worth of data. At
the beginning of each month we will remove the oldest month's data.
In this situation we can use partitioning to help us meet all of our different requirements for the
measurements table. Following the steps outlined above, partitioning can be set up as follows:
1. The master table is the measurement table, declared exactly as above.
2. Next we create one partition for each active month:
CREATE TABLE measurement_y2004m02 ( ) INHERITS (measurement);
Partitioning

...
Each of the partitions are complete tables in their own right, but they inherit their definition
from the measurement table.
This solves one of our problems: deleting old data. Each month, all we will need to do is
perform a DROP TABLE on the oldest child table and create a new child table for the new
month's data.
3. We must add non-overlapping table constraints, so that our table creation script becomes:
CREATE TABLE measurement_y2004m02 (

CHECK ( logdate >= DATE '2004-02-01' AND logdate < DATE '2004-03-01' )
) INHERITS (measurement);
...
4. We probably need indexes on the key columns too:
CREATE INDEX measurement_y2004m02_logdate ON measurement_y2004m02 (logdate);

...
We choose not to add further indexes at this time.
5. If data will be added only to the latest partition, we can set up a very simple rule to insert
data. We must redefine this each month so that it always points to the current partition.
CREATE OR REPLACE RULE measurement_current_partition AS

ON INSERT TO measurement
DO INSTEAD
INSERT INTO measurement_y2006m01 VALUES ( NEW.city_id,
NEW.logdate,
NEW.peaktemp,
NEW.unitsales );
We might want to insert data and have the server automatically locate the partition into which
the row should be added. We could do this with a more complex set of rules as shown below.
CREATE RULE measurement_insert_y2004m02 AS

ON INSERT TO measurement WHERE
( logdate >= DATE '2004-02-01' AND logdate < DATE '2004-03-01' )
DO INSTEAD
NEW.logdate,
NEW.peaktemp,
NEW.unitsales );
...
DO INSTEAD
NEW.logdate,
NEW.peaktemp,
NEW.unitsales );
DO INSTEAD
NEW.logdate,
Partitioning
NEW.peaktemp,
NEW.unitsales );
Note that the WHERE clause in each rule exactly matches the the CHECK constraint for its
partition.
As we can see, a complex partitioning scheme could require a substantial amount of DDL. In the
above example we would be creating a new partition each month, so it may be wise to write a script
that generates the required DDL automatically.
Partitioning can also be arranged using a UNION ALL view:
CREATE VIEW measurement AS

SELECT * FROM measurement_y2004m02
UNION ALL SELECT * FROM measurement_y2004m03
...
UNION ALL SELECT * FROM measurement_y2006m01;
However, the need to recreate the view adds an extra step to adding and dropping individual
partitions of the data set.
5.9.3. Managing Partitions
Normally the set of partitions established when initially defining the table are not intended to
remain static. It is common to want to remove old partitions of data and periodically add new
partitions for new data. One of the most important advantages of partitioning is precisely that it
allows this otherwise painful task to be executed nearly instantaneously by manipulating the
partition structure, rather than physically moving large amounts of data around.
The simplest option for removing old data is simply to drop the partition that is no longer
necessary:
DROP TABLE measurement_y2003m02;
This can very quickly delete millions of records because it doesn't have to individually delete every
record.
Another option that is often preferable is to remove the partition from the partitioned table but
retain access to it as a table in its own right:
ALTER TABLE measurement_y2003m02 NO INHERIT measurement;
This allows further operations to be performed on the data before it is dropped. For example, this is
often a useful time to back up the data using COPY, pg_dump, or similar tools. It can also be a
useful time to aggregate data into smaller formats, perform other data manipulations, or run
reports.
Similarly we can add a new partition to handle new data. We can create an empty partition in the
partitioned table just as the original partitions were created above.

As an alternative, it is sometimes more convenient to create the new table outside the partition
structure, and make it a proper partition later. This allows the data to be loaded, checked, and
transformed prior to it appearing in the partitioned table.
CREATE TABLE measurement_y2006m02

(LIKE measurement INCLUDING DEFAULTS INCLUDING CONSTRAINTS);
Partitioning
ALTER TABLE measurement_y2006m02 ADD CONSTRAINT y2006m02

CHECK ( logdate >= DATE '2006-02-01' AND logdate < DATE '2006-03-01' );
\copy measurement_y2006m02 from 'measurement_y2006m02'
-- possibly some other data preparation work
ALTER TABLE measurement_y2006m02 INHERIT measurement;
5.9.4. Partitioning and Constraint Exclusion
Constraint exclusion is a query optimization technique that improves performance for partitioned
tables defined in the fashion described above. As an example:
SET constraint_exclusion = on;

SELECT count(*) FROM measurement WHERE logdate >= DATE '2006-01-01';
Without constraint exclusion, the above query would scan each of the partitions of the
measurement table. With constraint exclusion enabled, the planner will examine the constraints of
each partition and try to prove that the partition need not be scanned because it could not contain
any rows meeting the query's WHERE clause. When the planner can prove this, it excludes the
partition from the query plan.
You can use the EXPLAIN command to show the difference between a plan with
constraint_exclusion on and a plan with it off. A typical default plan for this type of table setup is:
SET constraint_exclusion = off;

EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2006-01-01';
QUERY PLAN
--------------------------------------------------------------------------------------------
---
Aggregate (cost=158.66..158.68 rows=1 width=0)
-> Append (cost=0.00..151.88 rows=2715 width=0)
-> Seq Scan on measurement (cost=0.00..30.38 rows=543 width=0)
Filter: (logdate >= '2006-01-01'::date)
-> Seq Scan on measurement_y2004m02 measurement (cost=0.00..30.38 rows=543
width=0)
width=0)
...
width=0)
width=0)
Some or all of the partitions might use index scans instead of full-table sequential scans, but the
point here is that there is no need to scan the older partitions at all to answer this query. When we
enable constraint exclusion, we get a significantly reduced plan that will deliver the same answer:
SET constraint_exclusion = on;

EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2006-01-01';
QUERY PLAN
--------------------------------------------------------------------------------------------
---
Aggregate (cost=63.47..63.48 rows=1 width=0)
-> Append (cost=0.00..60.75 rows=1086 width=0)
-> Seq Scan on measurement (cost=0.00..30.38 rows=543 width=0)
width=0)
Note that constraint exclusion is driven only by CHECK constraints, not by the presence of indexes.
Therefore it isn't necessary to define indexes on the key columns. Whether an index needs to be
created for a given partition depends on whether you expect that queries that scan the partition will
generally scan a large part of the partition or just a small part. An index will be helpful in the latter
case but not the former.
5.9.5. Caveats
Partitioning
The following caveats apply to partitioned tables:
There is currently no way to verify that all of the CHECK constraints are mutually exclusive.
Care is required by the database designer.
There is currently no simple way to specify that rows must not be inserted into the master
table. A CHECK (false) constraint on the master table would be inherited by all child tables, so
that cannot be used for this purpose. One possibility is to set up an ON INSERT trigger on the
master table that always raises an error. (Alternatively, such a trigger could be used to
redirect the data into the proper child table, instead of using a set of rules as suggested
above.)
The following caveats apply to constraint exclusion:
Constraint exclusion only works when the query's WHERE clause contains constants. A
parameterized query will not be optimized, since the planner cannot know what partitions the
parameter value might select at run time. For the same reason, "stable" functions such as
CURRENT_DATE must be avoided.
Avoid cross-data type comparisons in the CHECK constraints, as the planner will currently fail
to prove such conditions false. For example, the following constraint will work if x is an integer
column, but not if x is a bigint:
CHECK ( x = 1 )
For a bigint column we must use a constraint like:
CHECK ( x = 1::bigint )
The problem is not limited to the bigint data type — it can occur whenever the default data
type of the constant does not match the data type of the column to which it is being
compared. Cross-data type comparisons in the supplied queries are usually OK, just not in the
CHECK conditions.
All constraints on all partitions of the master table are considered for constraint exclusion, so
large numbers of partitions are likely to increase query planning time considerably.
Don't forget that you still need to run ANALYZE on each partition individually. A command like
ANALYZE measurement;
will only process the master table.

Herança Acima Other Database Objects
Other Database Objects


Tables are the central objects in a relational database structure, because they hold your data. But
they are not the only objects that exist in a database. Many other kinds of objects can be created to
make the use and management of the data more efficient or convenient. They are not discussed in
this chapter, but we give you a list here so that you are aware of what is possible.
Views
Functions and operators
Data types and domains
Triggers and rewrite rules
Detailed information on these topics appears in Parte V.

Partitioning Acima Dependency Tracking
http://pgdocptbr.sourceforge.net/pg82/ddl-others.html[09/02/2018 17:57:38]
Dependency Tracking


When you create complex database structures involving many tables with foreign key constraints,
views, triggers, functions, etc. you will implicitly create a net of dependencies between the objects.
For instance, a table with a foreign key constraint depends on the table it references.
To ensure the integrity of the entire database structure, PostgreSQL makes sure that you cannot
drop objects that other objects still depend on. For example, attempting to drop the products table
we had considered in Seção 5.3.5, with the orders table depending on it, would result in an error
message such as this:
DROP TABLE products;

NOTICE: constraint orders_product_no_fkey on table orders depends on table products
ERROR: cannot drop table products because other objects depend on it
HINT: Use DROP ... CASCADE to drop the dependent objects too.
The error message contains a useful hint: if you do not want to bother deleting all the dependent
objects individually, you can run
DROP TABLE products CASCADE;
and all the dependent objects will be removed. In this case, it doesn't remove the orders table, it
only removes the foreign key constraint. (If you want to check what DROP ... CASCADE will do, run
DROP without CASCADE and read the NOTICE messages.)
All drop commands in PostgreSQL support specifying CASCADE. Of course, the nature of the
possible dependencies varies with the type of the object. You can also write RESTRICT instead of
CASCADE to get the default behavior, which is to prevent drops of objects that other objects
depend on.
Nota: According to the SQL standard, specifying either RESTRICT or CASCADE is

required. No database system actually enforces that rule, but whether the default
behavior is RESTRICT or CASCADE varies across systems.
Nota: Foreign key constraint dependencies and serial column dependencies from
PostgreSQL versions prior to 7.3 are not maintained or created during the upgrade
process. All other dependency types will be properly created during an upgrade from a
pre-7.3 database.

Other Database Objects Acima Data Manipulation
http://pgdocptbr.sourceforge.net/pg82/ddl-depend.html[09/02/2018 17:57:45]
Data Manipulation

Capítulo 6. Data Manipulation

Sumário
6.1. Inserting Data
6.2. Updating Data
6.3. Deleting Data
The previous chapter discussed how to create tables and other structures to hold your data. Now it
is time to fill the tables with data. This chapter covers how to insert, update, and delete table data.
We also introduce ways to effect automatic data changes when certain events occur: triggers and
rewrite rules. The chapter after this will finally explain how to extract your long-lost data back out
of the database.

Dependency Tracking Acima Inserting Data
http://pgdocptbr.sourceforge.net/pg82/dml.html[09/02/2018 17:57:53]
Inserting Data

Anterior Início Capítulo 6. Data Manipulation Fim Próxima
6.1. Inserting Data

When a table is created, it contains no data. The first thing to do before a database can be of much
use is to insert data. Data is conceptually inserted one row at a time. Of course you can also insert
more than one row, but there is no way to insert less than one row at a time. Even if you know only
some column values, a complete row must be created.
To create a new row, use the INSERT command. The command requires the table name and a value
for each of the columns of the table. For example, consider the products table from Capítulo 5:

product_no integer,
name text,
price numeric
);
An example command to insert a row would be:
INSERT INTO products VALUES (1, 'Cheese', 9.99);
The data values are listed in the order in which the columns appear in the table, separated by
commas. Usually, the data values will be literals (constants), but scalar expressions are also
allowed.
The above syntax has the drawback that you need to know the order of the columns in the table. To
avoid that you can also list the columns explicitly. For example, both of the following commands
have the same effect as the one above:
INSERT INTO products (product_no, name, price) VALUES (1, 'Cheese', 9.99);
INSERT INTO products (name, price, product_no) VALUES ('Cheese', 9.99, 1);
Many users consider it good practice to always list the column names.
If you don't have values for all the columns, you can omit some of them. In that case, the columns
will be filled with their default values. For example,
INSERT INTO products (product_no, name) VALUES (1, 'Cheese');

INSERT INTO products VALUES (1, 'Cheese');
The second form is a PostgreSQL extension. It fills the columns from the left with as many values as
are given, and the rest will be defaulted.
For clarity, you can also request default values explicitly, for individual columns or for the entire
row:
INSERT INTO products (product_no, name, price) VALUES (1, 'Cheese', DEFAULT);
INSERT INTO products DEFAULT VALUES;
You can insert multiple rows in a single command:
INSERT INTO products (product_no, name, price) VALUES
http://pgdocptbr.sourceforge.net/pg82/dml-insert.html[09/02/2018 17:58:37]
Inserting Data
(1, 'Cheese', 9.99),

(2, 'Bread', 1.99),
(3, 'Milk', 2.99);
Dica: When inserting a lot of data at the same time, considering using the COPY
command. It is not as flexible as the INSERT command, but is more efficient. Refer to
Seção 13.4 for more information on improving bulk loading performance.

Data Manipulation Acima Updating Data
http://pgdocptbr.sourceforge.net/pg82/dml-insert.html[09/02/2018 17:58:37]
Updating Data

6.2. Updating Data

The modification of data that is already in the database is referred to as updating. You can update
individual rows, all the rows in a table, or a subset of all rows. Each column can be updated
separately; the other columns are not affected.
To perform an update, you need three pieces of information:
1. The name of the table and column to update,
2. The new value of the column,
3. Which row(s) to update.
Recall from Capítulo 5 that SQL does not, in general, provide a unique identifier for rows. Therefore
it is not necessarily possible to directly specify which row to update. Instead, you specify which
conditions a row must meet in order to be updated. Only if you have a primary key in the table (no
matter whether you declared it or not) can you reliably address individual rows, by choosing a
condition that matches the primary key. Graphical database access tools rely on this fact to allow
you to update rows individually.
For example, this command updates all products that have a price of 5 to have a price of 10:
UPDATE products SET price = 10 WHERE price = 5;
This may cause zero, one, or many rows to be updated. It is not an error to attempt an update that
does not match any rows.
Let's look at that command in detail. First is the key word UPDATE followed by the table name. As
usual, the table name may be schema-qualified, otherwise it is looked up in the path. Next is the
key word SET followed by the column name, an equals sign and the new column value. The new
column value can be any scalar expression, not just a constant. For example, if you want to raise
the price of all products by 10% you could use:
UPDATE products SET price = price * 1.10;
As you see, the expression for the new value can refer to the existing value(s) in the row. We also
left out the WHERE clause. If it is omitted, it means that all rows in the table are updated. If it is
present, only those rows that match the WHERE condition are updated. Note that the equals sign in
the SET clause is an assignment while the one in the WHERE clause is a comparison, but this does
not create any ambiguity. Of course, the WHERE condition does not have to be an equality test.
Many other operators are available (see Capítulo 9). But the expression needs to evaluate to a
Boolean result.
You can update more than one column in an UPDATE command by listing more than one
assignment in the SET clause. For example:
UPDATE mytable SET a = 5, b = 3, c = 1 WHERE a > 0;
http://pgdocptbr.sourceforge.net/pg82/dml-update.html[09/02/2018 17:58:51]
Updating Data
Inserting Data Acima Deleting Data
http://pgdocptbr.sourceforge.net/pg82/dml-update.html[09/02/2018 17:58:51]
Deleting Data

6.3. Deleting Data

So far we have explained how to add data to tables and how to change data. What remains is to
discuss how to remove data that is no longer needed. Just as adding data is only possible in whole
rows, you can only remove entire rows from a table. In the previous section we explained that SQL
does not provide a way to directly address individual rows. Therefore, removing rows can only be
done by specifying conditions that the rows to be removed have to match. If you have a primary
key in the table then you can specify the exact row. But you can also remove groups of rows
matching a condition, or you can remove all rows in the table at once.
You use the DELETE command to remove rows; the syntax is very similar to the UPDATE command.
For instance, to remove all rows from the products table that have a price of 10, use
DELETE FROM products WHERE price = 10;
If you simply write
DELETE FROM products;
then all rows in the table will be deleted! Caveat programmer.

Updating Data Acima Queries
http://pgdocptbr.sourceforge.net/pg82/dml-delete.html[09/02/2018 17:59:01]
Queries

Capítulo 7. Queries
Sumário
7.1. Visão geral
7.2.1. The FROM Clause

7.2.2. The WHERE Clause
7.2.3. The GROUP BY and HAVING Clauses
7.3. Select Lists
7.3.1. Select-List Items

7.3.2. Column Labels
7.3.3. DISTINCT

7.5. Sorting Rows
7.7. VALUES Lists
The previous chapters explained how to create tables, how to fill them with data, and how to
manipulate that data. Now we finally discuss how to retrieve the data out of the database.

Deleting Data Acima Visão geral
http://pgdocptbr.sourceforge.net/pg82/queries.html[09/02/2018 17:59:18]
Visão geral

Anterior Início Capítulo 7. Queries Fim Próxima
7.1. Visão geral

The process of retrieving or the command to retrieve data from a database is called a query. In SQL
the SELECT command is used to specify queries. The general syntax of the SELECT command is
SELECT lista_de_seleção FROM expressão_de_tabela [especificação_de_classificação]
The following sections describe the details of the select list, the table expression, and the sort
specification.
A simple kind of query has the form
SELECT * FROM table1;
Assuming that there is a table called table1, this command would retrieve all rows and all columns
from table1. (The method of retrieval depends on the client application. For example, the psql
program will display an ASCII-art table on the screen, while client libraries will offer functions to
extract individual values from the query result.) The select list specification * means all columns
that the table expression happens to provide. A select list can also select a subset of the available
columns or make calculations using the columns. For example, if table1 has columns named a, b,
and c (and perhaps others) you can make the following query:
SELECT a, b + c FROM table1;
(assuming that b and c are of a numerical data type). See Seção 7.3 for more details.
FROM table1 is a particularly simple kind of table expression: it reads just one table. In general,
table expressions can be complex constructs of base tables, joins, and subqueries. But you can also
omit the table expression entirely and use the SELECT command as a calculator:
SELECT 3 * 4;
This is more useful if the expressions in the select list return varying results. For example, you
could call a function this way:
SELECT random();

Queries Acima Table Expressions
http://pgdocptbr.sourceforge.net/pg82/queries-overview.html[09/02/2018 17:59:44]
Table Expressions


A table expression computes a table. The table expression contains a FROM clause that is optionally
followed by WHERE, GROUP BY, and HAVING clauses. Trivial table expressions simply refer to a
table on disk, a so-called base table, but more complex expressions can be used to modify or
combine base tables in various ways.
The optional WHERE, GROUP BY, and HAVING clauses in the table expression specify a pipeline of
successive transformations performed on the table derived in the FROM clause. All these
transformations produce a virtual table that provides the rows that are passed to the select list to
compute the output rows of the query.
7.2.1. The FROM Clause
The Cláusula FROM derives a table from one or more other tables given in a comma-separated table
reference list.
FROM referência_de_tabela [, referência_de_tabela [, ...]]
A table reference may be a table name (possibly schema-qualified), or a derived table such as a
subquery, a table join, or complex combinations of these. If more than one table reference is listed
in the FROM clause they are cross-joined (see below) to form the intermediate virtual table that
may then be subject to transformations by the WHERE, GROUP BY, and HAVING clauses and is
finally the result of the overall table expression.
When a table reference names a table that is the parent of a table inheritance hierarchy, the table
reference produces rows of not only that table but all of its descendant tables, unless the key word
ONLY precedes the table name. However, the reference produces only the columns that appear in
the named table — any columns added in subtables are ignored.
7.2.1.1. Joined Tables
A joined table is a table derived from two other (real or derived) tables according to the rules of the
particular join type. Inner, outer, and cross-joins are available.
Join Types
Cross join
T1 CROSS JOIN T2
For each combination of rows from T1 and T2, the derived table will contain a row consisting
of all columns in T1 followed by all columns in T2. If the tables have N and M rows
respectively, the joined table will have N * M rows.
FROM T1 CROSS JOIN T2 is equivalent to FROM T1, T2. It is also equivalent to FROM T1
INNER JOIN T2 ON TRUE (see below).
Qualified joins
T1 { [INNER] | { LEFT | RIGHT | FULL } [OUTER] } JOIN T2 ON expressão_booleana
T1 { [INNER] | { LEFT | RIGHT | FULL } [OUTER] } JOIN T2 USING (
lista_de_colunas_de_junção )
T1 NATURAL { [INNER] | { LEFT | RIGHT | FULL } [OUTER] } JOIN T2
http://pgdocptbr.sourceforge.net/pg82/queries-table-expressions.html[09/02/2018 18:00:02]
Table Expressions
The words INNER and OUTER are optional in all forms. INNER is the default; LEFT, RIGHT, and
FULL imply an outer join.
The join condition is specified in the ON or USING clause, or implicitly by the word NATURAL.
The join condition determines which rows from the two source tables are considered to
"match", as explained in detail below.
The ON clause is the most general kind of join condition: it takes a Boolean value expression
of the same kind as is used in a WHERE clause. A pair of rows from T1 and T2 match if the ON
expression evaluates to true for them.
USING is a shorthand notation: it takes a comma-separated list of column names, which the
joined tables must have in common, and forms a join condition specifying equality of each of
these pairs of columns. Furthermore, the output of a JOIN USING has one column for each of
the equated pairs of input columns, followed by all of the other columns from each table.
Thus, USING (a, b, c) is equivalent to ON (t1.a = t2.a AND t1.b = t2.b AND t1.c = t2.c) with
the exception that if ON is used there will be two columns a, b, and c in the result, whereas
with USING there will be only one of each.
Finally, NATURAL is a shorthand form of USING: it forms a USING list consisting of exactly
those column names that appear in both input tables. As with USING, these columns appear
only once in the output table.
The possible types of qualified join are:
INNER JOIN
For each row R1 of T1, the joined table has a row for each row in T2 that satisfies the
join condition with R1.
LEFT OUTER JOIN
First, an inner join is performed. Then, for each row in T1 that does not satisfy the join
condition with any row in T2, a joined row is added with null values in columns of T2.
Thus, the joined table unconditionally has at least one row for each row in T1.
RIGHT OUTER JOIN
This is the converse of a left join: the result table will unconditionally have a row for
each row in T2.
FULL OUTER JOIN
Also, for each row of T2 that does not satisfy the join condition with any row in T1, a
joined row with null values in the columns of T1 is added.
Joins of all types can be chained together or nested: either or both of T1 and T2 may be joined
tables. Parentheses may be used around JOIN clauses to control the join order. In the absence of
parentheses, JOIN clauses nest left-to-right.
To put this together, assume we have tables t1
num | name
-----+------
1 | a
2 | b
3 | c
and t2
Table Expressions
num | value
-----+-------
1 | xxx
3 | yyy
5 | zzz
then we get the following results for the various joins:
=> SELECT * FROM t1 CROSS JOIN t2;

num | name | num | value
-----+------+-----+-------
1 | a | 1 | xxx
1 | a | 3 | yyy
1 | a | 5 | zzz
2 | b | 1 | xxx
2 | b | 3 | yyy
2 | b | 5 | zzz
3 | c | 1 | xxx
3 | c | 3 | yyy
3 | c | 5 | zzz
(9 rows)
=> SELECT * FROM t1 INNER JOIN t2 ON t1.num = t2.num;
-----+------+-----+-------
1 | a | 1 | xxx
3 | c | 3 | yyy
(2 rows)
=> SELECT * FROM t1 INNER JOIN t2 USING (num);
num | name | value
-----+------+-------
1 | a | xxx
3 | c | yyy
(2 rows)
=> SELECT * FROM t1 NATURAL INNER JOIN t2;
num | name | value
-----+------+-------
1 | a | xxx
3 | c | yyy
(2 rows)
=> SELECT * FROM t1 LEFT JOIN t2 ON t1.num = t2.num;
-----+------+-----+-------
1 | a | 1 | xxx
2 | b | |
3 | c | 3 | yyy
(3 rows)
=> SELECT * FROM t1 LEFT JOIN t2 USING (num);
num | name | value
-----+------+-------
1 | a | xxx
2 | b |
3 | c | yyy
(3 rows)
=> SELECT * FROM t1 RIGHT JOIN t2 ON t1.num = t2.num;
-----+------+-----+-------
1 | a | 1 | xxx
3 | c | 3 | yyy
| | 5 | zzz
(3 rows)
=> SELECT * FROM t1 FULL JOIN t2 ON t1.num = t2.num;
-----+------+-----+-------
1 | a | 1 | xxx
2 | b | |
3 | c | 3 | yyy
| | 5 | zzz
(4 rows)
The join condition specified with ON can also contain conditions that do not relate directly to the
join. This can prove useful for some queries but needs to be thought out carefully. For example:
=> SELECT * FROM t1 LEFT JOIN t2 ON t1.num = t2.num AND t2.value = 'xxx';
-----+------+-----+-------
1 | a | 1 | xxx
2 | b | |
3 | c | |
(3 rows)
7.2.1.2. Table and Column Aliases
A temporary name can be given to tables and complex table references to be used for references to
Table Expressions
the derived table in the rest of the query. This is called a table alias.
To create a table alias, write

FROM referência_de_tabela AS aliás
or
FROM referência_de_tabela aliás
The AS key word is noise. aliás can be any identifier.
A typical application of table aliases is to assign short identifiers to long table names to keep the
join clauses readable. For example:
SELECT * FROM some_very_long_table_name s JOIN another_fairly_long_name a ON s.id = a.num;
The alias becomes the new name of the table reference for the current query — it is no longer
possible to refer to the table by the original name. Thus
SELECT * FROM my_table AS m WHERE my_table.a > 5;
is not valid according to the SQL standard. In PostgreSQL this will draw an error if the
add_missing_from configuration variable is off (as it is by default). If it is on, an implicit table
reference will be added to the FROM clause, so the query is processed as if it were written as
SELECT * FROM my_table AS m, my_table AS my_table WHERE my_table.a > 5;
That will result in a cross join, which is usually not what you want.
Table aliases are mainly for notational convenience, but it is necessary to use them when joining a
table to itself, e.g.,
SELECT * FROM people AS mother JOIN people AS child ON mother.id = child.mother_id;
Additionally, an alias is required if the table reference is a subquery (see Seção 7.2.1.3).
Parentheses are used to resolve ambiguities. In the following example, the first statement assigns
the alias b to the second instance of my_table, but the second statement assigns the alias to the
result of the join:
SELECT * FROM my_table AS a CROSS JOIN my_table AS b ...

SELECT * FROM (my_table AS a CROSS JOIN my_table) AS b ...
Another form of table aliasing gives temporary names to the columns of the table, as well as the
table itself:
FROM referência_de_tabela [AS] aliás ( coluna1 [, coluna2 [, ...]] )
If fewer column aliases are specified than the actual table has columns, the remaining columns are
not renamed. This syntax is especially useful for self-joins or subqueries.
When an alias is applied to the output of a JOIN clause, using any of these forms, the alias hides
the original names within the JOIN. For example,
SELECT a.* FROM my_table AS a JOIN your_table AS b ON ...
is valid SQL, but
Table Expressions
SELECT a.* FROM (my_table AS a JOIN your_table AS b ON ...) AS c
is not valid: the table alias a is not visible outside the alias c.
7.2.1.3. Subqueries
Subqueries specifying a derived table must be enclosed in parentheses and must be assigned a
table alias name. (See Seção 7.2.1.2.) For example:
FROM (SELECT * FROM table1) AS alias_name
This example is equivalent to FROM table1 AS alias_name. More interesting cases, which can't be
reduced to a plain join, arise when the subquery involves grouping or aggregation.
A subquery can also be a VALUES list:
FROM (VALUES ('anne', 'smith'), ('bob', 'jones'), ('joe', 'blow'))

AS names(first, last)
Again, a table alias is required. Assigning alias names to the columns of the VALUES list is optional,
but is good practice. For more information see Seção 7.7.
7.2.1.4. Table Functions
Table functions are functions that produce a set of rows, made up of either base data types (scalar
types) or composite data types (table rows). They are used like a table, view, or subquery in the
FROM clause of a query. Columns returned by table functions may be included in SELECT, JOIN, or
WHERE clauses in the same manner as a table, view, or subquery column.
If a table function returns a base data type, the single result column is named like the function. If
the function returns a composite type, the result columns get the same names as the individual
attributes of the type.
A table function may be aliased in the FROM clause, but it also may be left unaliased. If a function
is used in the FROM clause with no alias, the function name is used as the resulting table name.
Some examples:
CREATE TABLE foo (fooid int, foosubid int, fooname text);

CREATE FUNCTION getfoo(int) RETURNS SETOF foo AS $$
SELECT * FROM foo WHERE fooid = $1;
$$ LANGUAGE SQL;
SELECT * FROM getfoo(1) AS t1;
SELECT * FROM foo
WHERE foosubid IN (select foosubid from getfoo(foo.fooid) z
where z.fooid = foo.fooid);
CREATE VIEW vw_getfoo AS SELECT * FROM getfoo(1);
SELECT * FROM vw_getfoo;
In some cases it is useful to define table functions that can return different column sets depending
on how they are invoked. To support this, the table function can be declared as returning the
pseudotype record. When such a function is used in a query, the expected row structure must be
specified in the query itself, so that the system can know how to parse and plan the query. Consider
this example:
SELECT *
FROM dblink('dbname=mydb', 'select proname, prosrc from pg_proc')
AS t1(proname name, prosrc text)
WHERE proname LIKE 'bytea%';
Table Expressions
The dblink function executes a remote query (see contrib/dblink). It is declared to return record
since it might be used for any kind of query. The actual column set must be specified in the calling
query so that the parser knows, for example, what * should expand to.
7.2.2. The WHERE Clause
The syntax of the Cláusula WHERE is

WHERE condição_de_pesquisa
where condição_de_pesquisa is any value expression (see Seção 4.2) that returns a value of type
boolean.
After the processing of the FROM clause is done, each row of the derived virtual table is checked
against the search condition. If the result of the condition is true, the row is kept in the output
table, otherwise (that is, if the result is false or null) it is discarded. The search condition typically
references at least some column of the table generated in the FROM clause; this is not required, but
otherwise the WHERE clause will be fairly useless.
Nota: The join condition of an inner join can be written either in the WHERE clause or in
the JOIN clause. For example, these table expressions are equivalent:
FROM a, b WHERE a.id = b.id AND b.val > 5
and
FROM a INNER JOIN b ON (a.id = b.id) WHERE b.val > 5
or perhaps even
FROM a NATURAL JOIN b WHERE b.val > 5
Which one of these you use is mainly a matter of style. The JOIN syntax in the FROM
clause is probably not as portable to other SQL database management systems. For
outer joins there is no choice in any case: they must be done in the FROM clause. An
ON/USING clause of an outer join is not equivalent to a WHERE condition, because it
determines the addition of rows (for unmatched input rows) as well as the removal of
rows from the final result.
Here are some examples of WHERE clauses:
SELECT ... FROM fdt WHERE c1 > 5

SELECT ... FROM fdt WHERE c1 IN (1, 2, 3)
SELECT ... FROM fdt WHERE c1 IN (SELECT c1 FROM t2)
SELECT ... FROM fdt WHERE c1 IN (SELECT c3 FROM t2 WHERE c2 = fdt.c1 + 10)
SELECT ... FROM fdt WHERE c1 BETWEEN (SELECT c3 FROM t2 WHERE c2 = fdt.c1 + 10) AND 100
SELECT ... FROM fdt WHERE EXISTS (SELECT c1 FROM t2 WHERE c2 > fdt.c1)
fdt is the table derived in the FROM clause. Rows that do not meet the search condition of the
WHERE clause are eliminated from fdt. Notice the use of scalar subqueries as value expressions.
Just like any other query, the subqueries can employ complex table expressions. Notice also how
fdt is referenced in the subqueries. Qualifying c1 as fdt.c1 is only necessary if c1 is also the name of
a column in the derived input table of the subquery. But qualifying the column name adds clarity
even when it is not needed. This example shows how the column naming scope of an outer query
extends into its inner queries.
7.2.3. The GROUP BY and HAVING Clauses
Table Expressions
After passing the WHERE filter, the derived input table may be subject to grouping, using the
GROUP BY clause, and elimination of group rows using the HAVING clause.
SELECT lista_de_seleção
FROM ...
[WHERE ...]
GROUP BY referência_a_coluna_de_agrupamento [, referência_a_coluna_de_agrupamento]...
The Cláusula GROUP BY is used to group together those rows in a table that share the same values in
all the columns listed. The order in which the columns are listed does not matter. The effect is to
combine each set of rows sharing common values into one group row that is representative of all
rows in the group. This is done to eliminate redundancy in the output and/or compute aggregates
that apply to these groups. For instance:
=> SELECT * FROM test1;

x | y
---+---
a | 3
c | 2
b | 5
a | 1
(4 rows)
=> SELECT x FROM test1 GROUP BY x;
x
---
a
b
c
(3 rows)
In the second query, we could not have written SELECT * FROM test1 GROUP BY x, because there is
no single value for the column y that could be associated with each group. The grouped-by columns
can be referenced in the select list since they have a single value in each group.
In general, if a table is grouped, columns that are not used in the grouping cannot be referenced
except in aggregate expressions. An example with aggregate expressions is:
=> SELECT x, sum(y) FROM test1 GROUP BY x;

x | sum
---+-----
a | 4
b | 5
c | 2
(3 rows)
Here sum is an aggregate function that computes a single value over the entire group. More
information about the available aggregate functions can be found in Seção 9.15.
Dica: Grouping without aggregate expressions effectively calculates the set of distinct
values in a column. This can also be achieved using the DISTINCT clause (see Seção
7.3.3).
Here is another example: it calculates the total sales for each product (rather than the total sales
on all products).
SELECT product_id, p.name, (sum(s.units) * p.price) AS sales

FROM products p LEFT JOIN sales s USING (product_id)
GROUP BY product_id, p.name, p.price;
In this example, the columns product_id, p.name, and p.price must be in the GROUP BY clause
since they are referenced in the query select list. (Depending on how exactly the products table is
set up, name and price may be fully dependent on the product ID, so the additional groupings could
theoretically be unnecessary, but this is not implemented yet.) The column s.units does not have to
be in the GROUP BY list since it is only used in an aggregate expression (sum(...)), which
represents the sales of a product. For each product, the query returns a summary row about all
sales of the product.
In strict SQL, GROUP BY can only group by columns of the source table but PostgreSQL extends this
Table Expressions
to also allow GROUP BY to group by columns in the select list. Grouping by value expressions
instead of simple column names is also allowed.
If a table has been grouped using a GROUP BY clause, but then only certain groups are of interest,
the HAVING clause can be used, much like a WHERE clause, to eliminate groups from a grouped
table. The syntax is:
SELECT lista_de_seleção FROM ... [WHERE ...] GROUP BY ... HAVING expressão_booleana
Expressions in the HAVING clause can refer both to grouped expressions and to ungrouped
expressions (which necessarily involve an aggregate function).
Example:
=> SELECT x, sum(y) FROM test1 GROUP BY x HAVING sum(y) > 3;

x | sum
---+-----
a | 4
b | 5
(2 rows)
=> SELECT x, sum(y) FROM test1 GROUP BY x HAVING x < 'c';
x | sum
---+-----
a | 4
b | 5
(2 rows)
Again, a more realistic example:
SELECT product_id, p.name, (sum(s.units) * (p.price - p.cost)) AS profit

FROM products p LEFT JOIN sales s USING (product_id)
WHERE s.date > CURRENT_DATE - INTERVAL '4 weeks'
GROUP BY product_id, p.name, p.price, p.cost
HAVING sum(p.price * s.units) > 5000;
In the example above, the WHERE clause is selecting rows by a column that is not grouped (the
expression is only true for sales during the last four weeks), while the HAVING clause restricts the
output to groups with total gross sales over 5000. Note that the aggregate expressions do not
necessarily need to be the same in all parts of the query.

Visão geral Acima Select Lists
Select Lists

7.3. Select Lists

As shown in the previous section, the table expression in the SELECT command constructs an
intermediate virtual table by possibly combining tables, views, eliminating rows, grouping, etc. This
table is finally passed on to processing by the select list. The select list determines which columns
of the intermediate table are actually output.
7.3.1. Select-List Items
The simplest kind of select list is * which emits all columns that the table expression produces.
Otherwise, a select list is a comma-separated list of value expressions (as defined in Seção 4.2). For
instance, it could be a list of column names:
SELECT a, b, c FROM ...
The columns names a, b, and c are either the actual names of the columns of tables referenced in
the FROM clause, or the aliases given to them as explained in Seção 7.2.1.2. The name space
available in the select list is the same as in the WHERE clause, unless grouping is used, in which
case it is the same as in the HAVING clause.
If more than one table has a column of the same name, the table name must also be given, as in
SELECT tbl1.a, tbl2.a, tbl1.b FROM ...
When working with multiple tables, it can also be useful to ask for all the columns of a particular
table:
SELECT tbl1.*, tbl2.a FROM ...
(See also Seção 7.2.2.)
If an arbitrary value expression is used in the select list, it conceptually adds a new virtual column
to the returned table. The value expression is evaluated once for each result row, with the row's
values substituted for any column references. But the expressions in the select list do not have to
reference any columns in the table expression of the FROM clause; they could be constant
arithmetic expressions as well, for instance.
7.3.2. Column Labels
The entries in the select list can be assigned names for further processing. The "further processing"
in this case is an optional sort specification and the client application (e.g., column headers for
display). For example:
SELECT a AS value, b + c AS sum FROM ...
If no output column name is specified using AS, the system assigns a default name. For simple
http://pgdocptbr.sourceforge.net/pg82/queries-select-lists.html[09/02/2018 18:01:49]
Select Lists
column references, this is the name of the referenced column. For function calls, this is the name of
the function. For complex expressions, the system will generate a generic name.
Nota: The naming of output columns here is different from that done in the FROM
clause (see Seção 7.2.1.2). This pipeline will in fact allow you to rename the same
column twice, but the name chosen in the select list is the one that will be passed on.
7.3.3. DISTINCT
After the select list has been processed, the result table may optionally be subject to the elimination
of duplicate rows. The DISTINCT key word is written directly after SELECT to specify this:
SELECT DISTINCT lista_de_seleção ...
(Instead of DISTINCT the key word ALL can be used to specify the default behavior of retaining all
rows.)
Obviously, two rows are considered distinct if they differ in at least one column value. Null values
are considered equal in this comparison.
Alternatively, an arbitrary expression can determine what rows are to be considered distinct:
SELECT DISTINCT ON (expressão [, expressão ...]) lista_de_seleção ...
Here expressão is an arbitrary value expression that is evaluated for all rows. A set of rows for
which all the expressions are equal are considered duplicates, and only the first row of the set is
kept in the output. Note that the "first row" of a set is unpredictable unless the query is sorted on
enough columns to guarantee a unique ordering of the rows arriving at the DISTINCT filter.
(DISTINCT ON processing occurs after ORDER BY sorting.)
The DISTINCT ON clause is not part of the SQL standard and is sometimes considered bad style
because of the potentially indeterminate nature of its results. With judicious use of GROUP BY and
subqueries in FROM the construct can be avoided, but it is often the most convenient alternative.

Table Expressions Acima Combining Queries
http://pgdocptbr.sourceforge.net/pg82/queries-select-lists.html[09/02/2018 18:01:49]
Combining Queries


The results of two queries can be combined using the set operations union, intersection, and
difference. The syntax is
comando1 UNION [ALL] comando2
comando1 INTERSECT [ALL] comando2
comando1 EXCEPT [ALL] comando2
comando1 and comando2 are queries that can use any of the features discussed up to this point.
Set operations can also be nested and chained, for example
comando1 UNION comando2 UNION comando3
which really says

(comando1 UNION comando2) UNION comando3
UNION effectively appends the result of comando2 to the result of comando1 (although there is no
guarantee that this is the order in which the rows are actually returned). Furthermore, it eliminates
duplicate rows from its result, in the same way as DISTINCT, unless UNION ALL is used.
INTERSECT returns all rows that are both in the result of comando1 and in the result of comando2.
Duplicate rows are eliminated unless INTERSECT ALL is used.
EXCEPT returns all rows that are in the result of comando1 but not in the result of comando2. (This
is sometimes called the difference between two queries.) Again, duplicates are eliminated unless
EXCEPT ALL is used.
In order to calculate the union, intersection, or difference of two queries, the two queries must be
"union compatible", which means that they return the same number of columns and the
corresponding columns have compatible data types, as described in Seção 10.5.

Select Lists Acima Sorting Rows
http://pgdocptbr.sourceforge.net/pg82/queries-union.html[09/02/2018 18:02:09]
Sorting Rows

7.5. Sorting Rows

After a query has produced an output table (after the select list has been processed) it can
optionally be sorted. If sorting is not chosen, the rows will be returned in an unspecified order. The
actual order in that case will depend on the scan and join plan types and the order on disk, but it
must not be relied on. A particular output ordering can only be guaranteed if the sort step is
explicitly chosen.
The ORDER BY clause specifies the sort order:

FROM expressão_de_tabela
ORDER BY expressão_de_classificação1 [ASC | DESC] [, expressão_de_classificação2 [ASC |
DESC] ...]
The sort expression(s) can be any expression that would be valid in the query's select list. An
example is
SELECT a, b FROM table1 ORDER BY a + b, c;
When more than one expression is specified, the later values are used to sort rows that are equal
according to the earlier values. Each expression may be followed by an optional ASC or DESC
keyword to set the sort direction to ascending or descending. ASC order is the default. Ascending
order puts smaller values first, where "smaller" is defined in terms of the < operator. Similarly,
descending order is determined with the > operator. [1]
For backwards compatibility with the SQL92 version of the standard, a expressão_de_classificação
can instead be the name or number of an output column, as in
SELECT a + b AS sum, c FROM table1 ORDER BY sum;

SELECT a, max(b) FROM table1 GROUP BY a ORDER BY 1;
both of which sort by the first output column. Note that an output column name has to stand alone,
it's not allowed as part of an expression — for example, this is not correct:
SELECT a + b AS sum, c FROM table1 ORDER BY sum + c; -- wrong
This restriction is made to reduce ambiguity. There is still ambiguity if an ORDER BY item is a
simple name that could match either an output column name or a column from the table
expression. The output column is used in such cases. This would only cause confusion if you use AS
to rename an output column to match some other table column's name.
ORDER BY can be applied to the result of a UNION, INTERSECT, or EXCEPT combination, but in this
case it is only permitted to sort by output column names or numbers, not by expressions.
Notas
[1]
Actually, PostgreSQL uses the default B-tree operator class for the expression's data type to
determine the sort ordering for ASC and DESC. Conventionally, data types will be set up so that the
< and > operators correspond to this sort ordering, but a user-defined data type's designer could
choose to do something different.
http://pgdocptbr.sourceforge.net/pg82/queries-order.html[09/02/2018 18:02:17]
Sorting Rows

Combining Queries Acima LIMIT and OFFSET
http://pgdocptbr.sourceforge.net/pg82/queries-order.html[09/02/2018 18:02:17]
LIMIT and OFFSET


LIMIT and OFFSET allow you to retrieve just a portion of the rows that are generated by the rest of
the query:
FROM expressão_de_tabela
[ ORDER BY expressão_de_classificação1 [ASC | DESC] [, expressão_de_classificação2 [ASC |
DESC] ...] ]
[ LIMIT { número | ALL } ] [ OFFSET número ]
If a limit count is given, no more than that many rows will be returned (but possibly less, if the
query itself yields less rows). LIMIT ALL is the same as omitting the LIMIT clause.
OFFSET says to skip that many rows before beginning to return rows. OFFSET 0 is the same as
omitting the OFFSET clause. If both OFFSET and LIMIT appear, then OFFSET rows are skipped
before starting to count the LIMIT rows that are returned.
When using LIMIT, it is important to use an ORDER BY clause that constrains the result rows into a
unique order. Otherwise you will get an unpredictable subset of the query's rows. You may be
asking for the tenth through twentieth rows, but tenth through twentieth in what ordering? The
ordering is unknown, unless you specified ORDER BY.
The query optimizer takes LIMIT into account when generating a query plan, so you are very likely
to get different plans (yielding different row orders) depending on what you give for LIMIT and
OFFSET. Thus, using different LIMIT/OFFSET values to select different subsets of a query result will
give inconsistent results unless you enforce a predictable result ordering with ORDER BY. This is not
a bug; it is an inherent consequence of the fact that SQL does not promise to deliver the results of
a query in any particular order unless ORDER BY is used to constrain the order.
The rows skipped by an OFFSET clause still have to be computed inside the server; therefore a
large OFFSET can be inefficient.

Sorting Rows Acima VALUES Lists
http://pgdocptbr.sourceforge.net/pg82/queries-limit.html[09/02/2018 18:02:28]
VALUES Lists

7.7. VALUES Lists

VALUES provides a way to generate a "constant table" that can be used in a query without having
to actually create and populate a table on-disk. The syntax is
VALUES ( expressão [, ...] ) [, ...]
Each parenthesized list of expressions generates a row in the table. The lists must all have the
same number of elements (i.e., the number of columns in the table), and corresponding entries in
each list must have compatible data types. The actual data type assigned to each column of the
result is determined using the same rules as for UNION (see Seção 10.5).
As an example,
VALUES (1, 'one'), (2, 'two'), (3, 'three');
will return a table of two columns and three rows. It's effectively equivalent to
SELECT 1 AS column1, 'one' AS column2

UNION ALL
SELECT 2, 'two'
UNION ALL
SELECT 3, 'three';
By default, PostgreSQL assigns the names column1, column2, etc. to the columns of a VALUES
table. The column names are not specified by the SQL standard and different database systems do
it differently, so it's usually better to override the default names with a table alias list.
Syntactically, VALUES followed by expression lists is treated as equivalent to

SELECT lista_de_seleção FROM expressão_de_tabela
and can appear anywhere a SELECT can. For example, you can use it as an arm of a UNION, or
attach a especificação_de_classificação (ORDER BY, LIMIT, and/or OFFSET) to it. VALUES is most
commonly used as the data source in an INSERT command, and next most commonly as a
subquery.
For more information see VALUES.

LIMIT and OFFSET Acima Data Types
http://pgdocptbr.sourceforge.net/pg82/queries-values.html[09/02/2018 18:02:36]
Data Types

Capítulo 8. Data Types

Sumário
8.1. Numeric Types
8.1.1. Integer Types

8.1.2. Arbitrary Precision Numbers
8.1.3. Floating-Point Types
8.1.4. Serial Types
8.2. Monetary Types

8.5.1. Date/Time Input

8.5.2. Date/Time Output
8.5.3. Time Zones
8.5.4. Internals
8.6. Boolean Type

8.7.1. Points
8.7.2. Line Segments
8.7.3. Boxes
8.7.4. Paths
8.7.5. Polygons
8.7.6. Circles
8.8.1. inet
8.8.2. cidr
8.8.3. inet vs. cidr
8.8.4. macaddr

8.10. Arrays
8.10.1. Declaration of Array Types

8.10.2. Array Value Input
8.10.3. Accessing Arrays
8.10.4. Modifying Arrays
8.10.5. Searching in Arrays
8.10.6. Array Input and Output Syntax
8.11.1. Declaration of Composite Types

8.11.2. Composite Value Input
8.11.3. Accessing Composite Types
8.11.4. Modifying Composite Types
http://pgdocptbr.sourceforge.net/pg82/datatype.html[09/02/2018 18:02:45]
Data Types
8.11.5. Composite Type Input and Output Syntax

8.13. Pseudo-Types
PostgreSQL has a rich set of native data types available to users. Users may add new types to
PostgreSQL using the CREATE TYPE command.
Tabela 8-1 shows all the built-in general-purpose data types. Most of the alternative names listed in
the "Aliases" column are the names used internally by PostgreSQL for historical reasons. In
addition, some internally used or deprecated types are available, but they are not listed here.
Tabela 8-1. Data Types
Name Aliases Description

bigint int8 signed eight-byte integer
bigserial serial8 autoincrementing eight-byte integer
bit [ (n) ] fixed-length bit string
bit varying [ (n) ] varbit variable-length bit string
boolean bool logical Boolean (true/false)
box rectangular box in the plane
bytea binary data ("byte array")
character varying [ (n) ] varchar [ (n) ] variable-length character string
character [ (n) ] char [ (n) ] fixed-length character string
cidr IPv4 or IPv6 network address
circle circle in the plane
date calendar date (year, month, day)
double precision float8 double precision floating-point number
inet IPv4 or IPv6 host address
integer int, int4 signed four-byte integer
interval [ (p) ] time span
line infinite line in the plane
lseg line segment in the plane
macaddr MAC address
money currency amount
numeric [ (p, s) ] decimal [ (p, s) ] exact numeric of selectable precision
path geometric path in the plane
point geometric point in the plane
polygon closed geometric path in the plane
real float4 single precision floating-point number
smallint int2 signed two-byte integer
serial serial4 autoincrementing four-byte integer
text variable-length character string
time [ (p) ] [ without time zone ] time of day
time [ (p) ] with time zone timetz time of day, including time zone
timestamp [ (p) ] [ without time zone ] date and time
timestamp [ (p) ] with time zone timestamptz date and time, including time zone
Compatibilidade: The following types (or spellings thereof) are specified by SQL: bit,
bit varying, boolean, char, character varying, character, varchar, date, double precision,
integer, interval, numeric, decimal, real, smallint, time (with or without time zone),
Data Types
timestamp (with or without time zone).
Each data type has an external representation determined by its input and output functions. Many
of the built-in types have obvious external formats. However, several types are either unique to
PostgreSQL, such as geometric paths, or have several possibilities for formats, such as the date and
time types. Some of the input and output functions are not invertible. That is, the result of an
output function may lose accuracy when compared to the original input.

VALUES Lists Acima Numeric Types
Numeric Types

Anterior Início Capítulo 8. Data Types Fim Próxima
8.1. Numeric Types

Numeric types consist of two-, four-, and eight-byte integers, four- and eight-byte floating-point
numbers, and selectable-precision decimals. Tabela 8-2 lists the available types.
Tabela 8-2. Numeric Types
Storage
Name Description Range
Size
smallint 2 bytes small-range integer -32768 to +32767
integer 4 bytes usual choice for integer -2147483648 to +2147483647
bigint 8 bytes large-range integer -9223372036854775808 to
9223372036854775807
decimal variable user-specified precision, no limit
exact
numeric variable user-specified precision, no limit
exact
real 4 bytes variable-precision, inexact 6 decimal digits precision
double 8 bytes variable-precision, inexact 15 decimal digits precision
precision
serial 4 bytes autoincrementing integer 1 to 2147483647
bigserial 8 bytes large autoincrementing 1 to 9223372036854775807
integer
The syntax of constants for the numeric types is described in Seção 4.1.2. The numeric types have a
full set of corresponding arithmetic operators and functions. Refer to Capítulo 9 for more
information. The following sections describe the types in detail.
8.1.1. Integer Types
The types smallint, integer, and bigint store whole numbers, that is, numbers without fractional
components, of various ranges. Attempts to store values outside of the allowed range will result in
an error.
The type integer is the usual choice, as it offers the best balance between range, storage size, and
performance. The smallint type is generally only used if disk space is at a premium. The bigint type
should only be used if the integer range is not sufficient, because the latter is definitely faster.
The bigint type may not function correctly on all platforms, since it relies on compiler support for
eight-byte integers. On a machine without such support, bigint acts the same as integer (but still
takes up eight bytes of storage). However, we are not aware of any reasonable platform where this
is actually the case.
SQL only specifies the integer types integer (or int) and smallint. The type bigint, and the type
names int2, int4, and int8 are extensions, which are shared with various other SQL database
systems.
8.1.2. Arbitrary Precision Numbers
http://pgdocptbr.sourceforge.net/pg82/datatype-numeric.html[09/02/2018 18:02:54]
Numeric Types
The type numeric can store numbers with up to 1000 digits of precision and perform calculations
exactly. It is especially recommended for storing monetary amounts and other quantities where
exactness is required. However, arithmetic on numeric values is very slow compared to the integer
types, or to the floating-point types described in the next section.
In what follows we use these terms: The scale of a numeric is the count of decimal digits in the
fractional part, to the right of the decimal point. The precision of a numeric is the total count of
significant digits in the whole number, that is, the number of digits to both sides of the decimal
point. So the number 23.5141 has a precision of 6 and a scale of 4. Integers can be considered to
have a scale of zero.
Both the maximum precision and the maximum scale of a numeric column can be configured. To
declare a column of type numeric use the syntax
NUMERIC(precisão, escala)
The precision must be positive, the scale zero or positive. Alternatively,
NUMERIC(precisão)
selects a scale of 0. Specifying
NUMERIC
without any precision or scale creates a column in which numeric values of any precision and scale
can be stored, up to the implementation limit on precision. A column of this kind will not coerce
input values to any particular scale, whereas numeric columns with a declared scale will coerce
input values to that scale. (The SQL standard requires a default scale of 0, i.e., coercion to integer
precision. We find this a bit useless. If you're concerned about portability, always specify the
precision and scale explicitly.)
If the scale of a value to be stored is greater than the declared scale of the column, the system will
round the value to the specified number of fractional digits. Then, if the number of digits to the left
of the decimal point exceeds the declared precision minus the declared scale, an error is raised.
Numeric values are physically stored without any extra leading or trailing zeroes. Thus, the declared
precision and scale of a column are maximums, not fixed allocations. (In this sense the numeric
type is more akin to varchar(n) than to char(n).) The actual storage requirement is two bytes for
each group of four decimal digits, plus eight bytes overhead.
In addition to ordinary numeric values, the numeric type allows the special value NaN, meaning
"not-a-number". Any operation on NaN yields another NaN. When writing this value as a constant in
a SQL command, you must put quotes around it, for example UPDATE table SET x = 'NaN'. On
input, the string NaN is recognized in a case-insensitive manner.
The types decimal and numeric are equivalent. Both types are part of the SQL standard.
8.1.3. Floating-Point Types
The data types real and double precision are inexact, variable-precision numeric types. In practice,
these types are usually implementations of IEEE Standard 754 for Binary Floating-Point Arithmetic
(single and double precision, respectively), to the extent that the underlying processor, operating
system, and compiler support it.
Inexact means that some values cannot be converted exactly to the internal format and are stored
as approximations, so that storing and printing back out a value may show slight discrepancies.
Managing these errors and how they propagate through calculations is the subject of an entire
Numeric Types
branch of mathematics and computer science and will not be discussed further here, except for the
following points:
If you require exact storage and calculations (such as for monetary amounts), use the
numeric type instead.
If you want to do complicated calculations with these types for anything important, especially
if you rely on certain behavior in boundary cases (infinity, underflow), you should evaluate the
implementation carefully.
Comparing two floating-point values for equality may or may not work as expected.
On most platforms, the real type has a range of at least 1E-37 to 1E+37 with a precision of at least
6 decimal digits. The double precision type typically has a range of around 1E-307 to 1E+308 with a
precision of at least 15 digits. Values that are too large or too small will cause an error. Rounding
may take place if the precision of an input number is too high. Numbers too close to zero that are
not representable as distinct from zero will cause an underflow error.
In addition to ordinary numeric values, the floating-point types have several special values:
Infinity
-Infinity
NaN
These represent the IEEE 754 special values "infinity", "negative infinity", and "not-a-number",
respectively. (On a machine whose floating-point arithmetic does not follow IEEE 754, these values
will probably not work as expected.) When writing these values as constants in a SQL command,
you must put quotes around them, for example UPDATE table SET x = 'Infinity'. On input, these
strings are recognized in a case-insensitive manner.
PostgreSQL also supports the SQL-standard notations float and float(p) for specifying inexact
numeric types. Here, p specifies the minimum acceptable precision in binary digits. PostgreSQL
accepts float(1) to float(24) as selecting the real type, while float(25) to float(53) select double
precision. Values of p outside the allowed range draw an error. float with no precision specified is
taken to mean double precision.
Nota: Prior to PostgreSQL 7.4, the precision in float(p) was taken to mean so many
decimal digits. This has been corrected to match the SQL standard, which specifies that
the precision is measured in binary digits. The assumption that real and double precision
have exactly 24 and 53 bits in the mantissa respectively is correct for IEEE-standard
floating point implementations. On non-IEEE platforms it may be off a little, but for
simplicity the same ranges of p are used on all platforms.
8.1.4. Serial Types
The data types serial and bigserial are not true types, but merely a notational convenience for
setting up unique identifier columns (similar to the AUTO_INCREMENT property supported by some
other databases). In the current implementation, specifying
CREATE TABLE nome_da_tabela (

nome_da_coluna SERIAL
);
is equivalent to specifying:
CREATE SEQUENCE nome_da_tabela_nome_da_coluna_seq;

CREATE TABLE nome_da_tabela (
nome_da_coluna integer NOT NULL DEFAULT nextval('nome_da_tabela_nome_da_coluna_seq')
);
ALTER SEQUENCE nome_da_tabela_nome_da_coluna_seq OWNED BY nome_da_tabela.nome_da_coluna;
Thus, we have created an integer column and arranged for its default values to be assigned from a
Numeric Types
sequence generator. A NOT NULL constraint is applied to ensure that a null value cannot be
explicitly inserted, either. (In most cases you would also want to attach a UNIQUE or PRIMARY KEY
constraint to prevent duplicate values from being inserted by accident, but this is not automatic.)
Lastly, the sequence is marked as "owned by" the column, so that it will be dropped if the column
or table is dropped.
Nota: Prior to PostgreSQL 7.3, serial implied UNIQUE. This is no longer automatic. If
you wish a serial column to be in a unique constraint or a primary key, it must now be
specified, same as with any other data type.
To insert the next value of the sequence into the serial column, specify that the serial column
should be assigned its default value. This can be done either by excluding the column from the list
of columns in the INSERT statement, or through the use of the DEFAULT key word.
The type names serial and serial4 are equivalent: both create integer columns. The type names
bigserial and serial8 work just the same way, except that they create a bigint column. bigserial
should be used if you anticipate the use of more than 231 identifiers over the lifetime of the table.
The sequence created for a serial column is automatically dropped when the owning column is
dropped. You can drop the sequence without dropping the column, but this will force removal of the
column default expression.

Data Types Acima Monetary Types
Monetary Types

8.2. Monetary Types

Nota: The money type is deprecated. Use numeric or decimal instead, in combination
with the to_char function.
The money type stores a currency amount with a fixed fractional precision; see Tabela 8-3. Input is
accepted in a variety of formats, including integer and floating-point literals, as well as "typical"
currency formatting, such as '$1,000.00'. Output is generally in the latter form but depends on the
locale.
Tabela 8-3. Monetary Types
Name Storage Size Description Range

money 4 bytes currency amount -21474836.48 to +21474836.47

Numeric Types Acima Character Types
http://pgdocptbr.sourceforge.net/pg82/datatype-money.html[09/02/2018 18:03:02]
Character Types


Tabela 8-4. Character Types
Name Description
character varying(n), varchar(n) variable-length with limit
character(n), char(n) fixed-length, blank padded
text variable unlimited length
Tabela 8-4 shows the general-purpose character types available in PostgreSQL.
SQL defines two primary character types: character varying(n) and character(n), where n is a
positive integer. Both of these types can store strings up to n characters in length. An attempt to
store a longer string into a column of these types will result in an error, unless the excess
characters are all spaces, in which case the string will be truncated to the maximum length. (This
somewhat bizarre exception is required by the SQL standard.) If the string to be stored is shorter
than the declared length, values of type character will be space-padded; values of type character
varying will simply store the shorter string.
If one explicitly casts a value to character varying(n) or character(n), then an over-length value will
be truncated to n characters without raising an error. (This too is required by the SQL standard.)
The notations varchar(n) and char(n) are aliases for character varying(n) and character(n),
respectively. character without length specifier is equivalent to character(1). If character varying is
used without length specifier, the type accepts strings of any size. The latter is a PostgreSQL
extension.
In addition, PostgreSQL provides the text type, which stores strings of any length. Although the
type text is not in the SQL standard, several other SQL database management systems have it as
well.
Values of type character are physically padded with spaces to the specified width n, and are stored
and displayed that way. However, the padding spaces are treated as semantically insignificant.
Trailing spaces are disregarded when comparing two values of type character, and they will be
removed when converting a character value to one of the other string types. Note that trailing
spaces are semantically significant in character varying and text values.
The storage requirement for data of these types is 4 bytes plus the actual string, and in case of
character plus the padding. Long strings are compressed by the system automatically, so the
physical requirement on disk may be less. Long values are also stored in background tables so they
do not interfere with rapid access to the shorter column values. In any case, the longest possible
character string that can be stored is about 1 GB. (The maximum value that will be allowed for n in
the data type declaration is less than that. It wouldn't be very useful to change this because with
multibyte character encodings the number of characters and bytes can be quite different anyway. If
you desire to store long strings with no specific upper limit, use text or character varying without a
length specifier, rather than making up an arbitrary length limit.)
Dica: There are no performance differences between these three types, apart from the
increased storage size when using the blank-padded type. While character(n) has
performance advantages in some other database systems, it has no such advantages in
PostgreSQL. In most situations text or character varying should be used instead.
http://pgdocptbr.sourceforge.net/pg82/datatype-character.html[09/02/2018 18:03:16]
Character Types
Refer to Seção 4.1.2.1 for information about the syntax of string literals, and to Capítulo 9 for
information about available operators and functions. The database character set determines the
character set used to store textual values; for more information on character set support, refer to
Seção 21.2.
Exemplo 8-1. Using the character types
CREATE TABLE test1 (a character(4));

INSERT INTO test1 VALUES ('ok');
SELECT a, char_length(a) FROM test1; -- (1)
a | char_length
------+-------------
ok | 2
CREATE TABLE test2 (b varchar(5));
INSERT INTO test2 VALUES ('ok');
INSERT INTO test2 VALUES ('good ');
INSERT INTO test2 VALUES ('too long');
ERROR: value too long for type character varying(5)
INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation
SELECT b, char_length(b) FROM test2;
b | char_length
-------+-------------
ok | 2
good | 5
too l | 5
(1)
The char_length function is discussed in Seção 9.4.
There are two other fixed-length character types in PostgreSQL, shown in Tabela 8-5. The name
type exists only for storage of identifiers in the internal system catalogs and is not intended for use
by the general user. Its length is currently defined as 64 bytes (63 usable characters plus
terminator) but should be referenced using the constant NAMEDATALEN. The length is set at
compile time (and is therefore adjustable for special uses); the default maximum length may
change in a future release. The type "char" (note the quotes) is different from char(1) in that it only
uses one byte of storage. It is internally used in the system catalogs as a poor-man's enumeration
type.
Tabela 8-5. Special Character Types
Name Storage Size Description

"char" 1 byte single-character internal type
name 64 bytes internal type for object names

Monetary Types Acima Binary Data Types
http://pgdocptbr.sourceforge.net/pg82/datatype-character.html[09/02/2018 18:03:16]
Binary Data Types


The bytea data type allows storage of binary strings; see Tabela 8-6.
Tabela 8-6. Binary Data Types

bytea 4 bytes plus the actual binary string variable-length binary string
A binary string is a sequence of octets (or bytes). Binary strings are distinguished from character
strings by two characteristics: First, binary strings specifically allow storing octets of value zero and
other "non-printable" octets (usually, octets outside the range 32 to 126). Character strings
disallow zero octets, and also disallow any other octet values and sequences of octet values that are
invalid according to the database's selected character set encoding. Second, operations on binary
strings process the actual bytes, whereas the processing of character strings depends on locale
settings. In short, binary strings are appropriate for storing data that the programmer thinks of as
"raw bytes", whereas character strings are appropriate for storing text.
When entering bytea values, octets of certain values must be escaped (but all octet values can be
escaped) when used as part of a string literal in an SQL statement. In general, to escape an octet,
it is converted into the three-digit octal number equivalent of its decimal octet value, and preceded
by two backslashes (or one backslash if standard_conforming_strings is off). Tabela 8-7 shows the
characters that must be escaped, and gives the alternate escape sequences where applicable.
Tabela 8-7. bytea Literal Escaped Octets
Decimal Octet Escaped Input Output

Description Example
Value Representation Representation
0 zero octet '\\000' SELECT \000
'\\000'::bytea;
39 single quote '\'' or '\\047' SELECT '
'\''::bytea;
92 backslash '\\\\' or '\\134' SELECT \\
'\\\\'::bytea;
0 to 31 and 127 "non-printable" '\\xxx' (octal value) SELECT \001
to 255 octets '\\001'::bytea;
The requirement to escape "non-printable" octets actually varies depending on locale settings. In
some instances you can get away with leaving them unescaped. Note that the result in each of the
examples in Tabela 8-7 was exactly one octet in length, even though the output representation of
the zero octet and backslash are more than one character.
The reason that you have to write so many backslashes, as shown in Tabela 8-7, is that an input
string written as a string literal must pass through two parse phases in the PostgreSQL server. The
first backslash of each pair is interpreted as an escape character by the string-literal parser
(assuming standard_conforming_strings is off) and is therefore consumed, leaving the second
backslash of the pair. The remaining backslash is then recognized by the bytea input function as
starting either a three digit octal value or escaping another backslash. For example, a string literal
passed to the server as '\\001' becomes \001 after passing through the string-literal parser. The
\001 is then sent to the bytea input function, where it is converted to a single octet with a decimal
http://pgdocptbr.sourceforge.net/pg82/datatype-binary.html[09/02/2018 18:03:24]
Binary Data Types
value of 1. Note that the apostrophe character is not treated specially by bytea, so it follows the
normal rules for string literals. (See also Seção 4.1.2.1.)
Bytea octets are also escaped in the output. In general, each "non-printable" octet is converted into
its equivalent three-digit octal value and preceded by one backslash. Most "printable" octets are
represented by their standard representation in the client character set. The octet with decimal
value 92 (backslash) has a special alternative output representation. Details are in Tabela 8-8.
Tabela 8-8. bytea Output Escaped Octets
Decimal Octet Escaped Output Output

Description Example
Value Representation Result
92 backslash \\ SELECT \\
'\\134'::bytea;
0 to 31 and 127 to "non-printable" \xxx (octal value) SELECT \001
255 octets '\\001'::bytea;
32 to 126 "printable" octets client character set SELECT ~
representation '\\176'::bytea;
Depending on the front end to PostgreSQL you use, you may have additional work to do in terms of
escaping and unescaping bytea strings. For example, you may also have to escape line feeds and
carriage returns if your interface automatically translates these.
The SQL standard defines a different binary string type, called BLOB or BINARY LARGE OBJECT. The
input format is different from bytea, but the provided functions and operators are mostly the same.

Character Types Acima Date/Time Types
http://pgdocptbr.sourceforge.net/pg82/datatype-binary.html[09/02/2018 18:03:24]
Date/Time Types


PostgreSQL supports the full set of SQL date and time types, shown in Tabela 8-9. The operations
available on these data types are described in Seção 9.9.
Tabela 8-9. Date/Time Types
Storage High
Name Description Low Value Resolution
Size Value
timestamp [ (p) ] [ 8 bytes both date and time 4713 BC 5874897 1
without time zone ] AD microsecond
/ 14 digits
timestamp [ (p) ] with 8 bytes both date and time, 4713 BC 5874897 1
time zone with time zone AD microsecond
/ 14 digits
interval [ (p) ] 12 bytes time intervals -178000000 178000000 1
years years microsecond
/ 14 digits
date 4 bytes dates only 4713 BC 5874897 1 day
AD
time [ (p) ] [ without 8 bytes times of day only 00:00:00 24:00:00 1
time zone ] microsecond
/ 14 digits
time [ (p) ] with time 12 bytes times of day only, with 00:00:00+1459 24:00:00- 1
zone time zone 1459 microsecond
/ 14 digits
Nota: Prior to PostgreSQL 7.3, writing just timestamp was equivalent to timestamp with
time zone. This was changed for SQL compliance.
time, timestamp, and interval accept an optional precision value p which specifies the number of
fractional digits retained in the seconds field. By default, there is no explicit bound on precision. The
allowed range of p is from 0 to 6 for the timestamp and interval types.
Nota: When timestamp values are stored as double precision floating-point numbers
(currently the default), the effective limit of precision may be less than 6. timestamp
values are stored as seconds before or after midnight 2000-01-01. Microsecond
precision is achieved for dates within a few years of 2000-01-01, but the precision
degrades for dates further away. When timestamp values are stored as eight-byte
integers (a compile-time option), microsecond precision is available over the full range
of values. However eight-byte integer timestamps have a more limited range of dates
than shown above: from 4713 BC up to 294276 AD. The same compile-time option also
determines whether time and interval values are stored as floating-point or eight-byte
integers. In the floating-point case, large interval values degrade in precision as the size
of the interval increases.
For the time types, the allowed range of p is from 0 to 6 when eight-byte integer storage is used, or
from 0 to 10 when floating-point storage is used.
The type time with time zone is defined by the SQL standard, but the definition exhibits properties
which lead to questionable usefulness. In most cases, a combination of date, time, timestamp
http://pgdocptbr.sourceforge.net/pg82/datatype-datetime.html[09/02/2018 18:03:34]
Date/Time Types
without time zone, and timestamp with time zone should provide a complete range of date/time
functionality required by any application.
The types abstime and reltime are lower precision types which are used internally. You are
discouraged from using these types in new applications and are encouraged to move any old ones
over when appropriate. Any or all of these internal types might disappear in a future release.
8.5.1. Date/Time Input
Date and time input is accepted in almost any reasonable format, including ISO 8601, SQL-
compatible, traditional POSTGRES, and others. For some formats, ordering of month, day, and year
in date input is ambiguous and there is support for specifying the expected ordering of these fields.
Set the DateStyle parameter to MDY to select month-day-year interpretation, DMY to select day-
month-year interpretation, or YMD to select year-month-day interpretation.
PostgreSQL is more flexible in handling date/time input than the SQL standard requires. See
Apêndice B for the exact parsing rules of date/time input and for the recognized text fields including
months, days of the week, and time zones.
Remember that any date or time literal input needs to be enclosed in single quotes, like text
strings. Refer to Seção 4.1.2.5 for more information. SQL requires the following syntax
tipo [ (p) ] 'valor'
where p in the optional precision specification is an integer corresponding to the number of

fractional digits in the seconds field. Precision can be specified for time, timestamp, and interval
types. The allowed values are mentioned above. If no precision is specified in a constant
specification, it defaults to the precision of the literal value.
8.5.1.1. Dates
Tabela 8-10 shows some possible inputs for the date type.
Tabela 8-10. Date Input
Example Description
January 8, unambiguous in any datestyle input mode
1999
1999-01-08 ISO 8601; January 8 in any mode (recommended format)
1/8/1999 January 8 in MDY mode; August 1 in DMY mode
1/18/1999 January 18 in MDY mode; rejected in other modes
01/02/03 January 2, 2003 in MDY mode; February 1, 2003 in DMY mode; February 3, 2001 in
YMD mode
1999-Jan-08 January 8 in any mode
Jan-08-1999 January 8 in any mode
08-Jan-1999 January 8 in any mode
99-Jan-08 January 8 in YMD mode, else error
08-Jan-99 January 8, except error in YMD mode
Jan-08-99 January 8, except error in YMD mode
19990108 ISO 8601; January 8, 1999 in any mode
990108 ISO 8601; January 8, 1999 in any mode
1999.008 year and day of year
J2451187 Julian day
January 8, 99 year 99 before the Common Era
BC
8.5.1.2. Times
Date/Time Types
The time-of-day types are time [ (p) ] without time zone and time [ (p) ] with time zone. Writing
just time is equivalent to time without time zone.
Valid input for these types consists of a time of day followed by an optional time zone. (See Tabela
8-11 and Tabela 8-12.) If a time zone is specified in the input for time without time zone, it is
silently ignored. You can also specify a date but it will be ignored, except when you use a time zone
name that involves a daylight-savings rule, such as America/New_York. In this case specifying the
date is required in order to determine whether standard or daylight-savings time applies. The
appropriate time zone offset is recorded in the time with time zone value.
Tabela 8-11. Time Input
Example Description
04:05:06.789 ISO 8601
04:05:06 ISO 8601
04:05 ISO 8601
040506 ISO 8601
04:05 AM same as 04:05; AM does not affect value
04:05 PM same as 16:05; input hour must be <= 12
04:05:06.789-8 ISO 8601
04:05:06-08:00 ISO 8601
04:05-08:00 ISO 8601
040506-08 ISO 8601
04:05:06 PST time zone specified by abbreviation
2003-04-12 04:05:06 America/New_York time zone specified by full name
Tabela 8-12. Time Zone Input
Example Description
PST Abbreviation (for Pacific Standard Time)
America/New_York Full time zone name
PST8PDT POSIX-style time zone specification
-8:00 ISO-8601 offset for PST
-800 ISO-8601 offset for PST
-8 ISO-8601 offset for PST
zulu Military abbreviation for UTC
z Short form of zulu
Refer to Seção 8.5.3 for more information on how to specify time zones.
8.5.1.3. Time Stamps
Valid input for the time stamp types consists of a concatenation of a date and a time, followed by
an optional time zone, followed by an optional AD or BC. (Alternatively, AD/BC can appear before
the time zone, but this is not the preferred ordering.) Thus
1999-01-08 04:05:06
and
1999-01-08 04:05:06 -8:00
Date/Time Types
are valid values, which follow the ISO 8601 standard. In addition, the wide-spread format
January 8 04:05:06 1999 PST
is supported.
The SQL standard differentiates timestamp without time zone and timestamp with time zone literals
by the presence of a "+" or "-". Hence, according to the standard,
TIMESTAMP '2004-10-19 10:23:54'
is a timestamp without time zone, while
TIMESTAMP '2004-10-19 10:23:54+02'
is a timestamp with time zone. PostgreSQL never examines the content of a literal string before
determining its type, and therefore will treat both of the above as timestamp without time zone. To
ensure that a literal is treated as timestamp with time zone, give it the correct explicit type:
TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
In a literal that has been decided to be timestamp without time zone, PostgreSQL will silently ignore
any time zone indication. That is, the resulting value is derived from the date/time fields in the
input value, and is not adjusted for time zone.
For timestamp with time zone, the internally stored value is always in UTC (Universal Coordinated
Time, traditionally known as Greenwich Mean Time, GMT). An input value that has an explicit time
zone specified is converted to UTC using the appropriate offset for that time zone. If no time zone is
stated in the input string, then it is assumed to be in the time zone indicated by the system's
timezone parameter, and is converted to UTC using the offset for the timezone zone.
When a timestamp with time zone value is output, it is always converted from UTC to the current
timezone zone, and displayed as local time in that zone. To see the time in another time zone,
either change timezone or use the AT TIME ZONE construct (see Seção 9.9.3).
Conversions between timestamp without time zone and timestamp with time zone normally assume
that the timestamp without time zone value should be taken or given as timezone local time. A
different zone reference can be specified for the conversion using AT TIME ZONE.
8.5.1.4. Intervals
interval values can be written with the following syntax:
[@] quantidade unidade [quantidade unidade...] [direção]
Where: quantidade is a number (possibly signed); unidade is second, minute, hour, day, week,
month, year, decade, century, millennium, or abbreviations or plurals of these units; direção can be
ago or empty. The at sign (@) is optional noise. The amounts of different units are implicitly added
up with appropriate sign accounting.
Quantities of days, hours, minutes, and seconds can be specified without explicit unit markings. For
example, '1 12:59:10' is read the same as '1 day 12 hours 59 min 10 sec'.
The optional subsecond precision p should be between 0 and 6, and defaults to the precision of the
input literal.
Internally interval values are stored as months, days, and seconds. This is done because the
number of days in a month varies, and a day can have 23 or 25 hours if a daylight savings time
Date/Time Types
adjustment is involved. Because intervals are usually created from constant strings or timestamp
subtraction, this storage method works well in most cases. Functions justify_days and justify_hours
are available for adjusting days and hours that overflow their normal periods.
8.5.1.5. Special Values
PostgreSQL supports several special date/time input values for convenience, as shown in Tabela 8-
13. The values infinity and -infinity are specially represented inside the system and will be displayed
the same way; but the others are simply notational shorthands that will be converted to ordinary
date/time values when read. (In particular, now and related strings are converted to a specific time
value as soon as they are read.) All of these values need to be written in single quotes when used
as constants in SQL commands.
Tabela 8-13. Special Date/Time Inputs
Input String Valid Types Description

epoch date, timestamp 1970-01-01 00:00:00+00 (Unix system time zero)
infinity timestamp later than all other time stamps
-infinity timestamp earlier than all other time stamps
now date, time, timestamp current transaction's start time
today date, timestamp midnight today
tomorrow date, timestamp midnight tomorrow
yesterday date, timestamp midnight yesterday
allballs time 00:00:00.00 UTC
The following SQL-compatible functions can also be used to obtain the current time value for the
corresponding data type: CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP, LOCALTIME,
LOCALTIMESTAMP. The latter four accept an optional subsecond precision specification. (See Seção
9.9.4.) Note however that these are SQL functions and are not recognized as data input strings.
8.5.2. Date/Time Output
The output format of the date/time types can be set to one of the four styles ISO 8601, SQL
(Ingres), traditional POSTGRES, and German, using the command SET datestyle. The default is the
ISO format. (The SQL standard requires the use of the ISO 8601 format. The name of the "SQL"
output format is a historical accident.) Tabela 8-14 shows examples of each output style. The output
of the date and time types is of course only the date or time part in accordance with the given
examples.
Tabela 8-14. Date/Time Output Styles
Style Specification Description Example

ISO ISO 8601/SQL standard 1997-12-17 07:37:16-08
SQL traditional style 12/17/1997 07:37:16.00 PST
POSTGRES original style Wed Dec 17 07:37:16 1997 PST
German regional style 17.12.1997 07:37:16.00 PST
In the SQL and POSTGRES styles, day appears before month if DMY field ordering has been
specified, otherwise month appears before day. (See Seção 8.5.1 for how this setting also affects
interpretation of input values.) Tabela 8-15 shows an example.
Tabela 8-15. Date Order Conventions
datestyle Setting Input Ordering Example Output
Date/Time Types
SQL, DMY dia/mês/ano 17/12/1997 15:37:16.00 CET

SQL, MDY mês/dia/ano 12/17/1997 07:37:16.00 PST
Postgres, DMY dia/mês/ano Wed 17 Dec 07:37:16 1997 PST
interval output looks like the input format, except that units like century or week are converted to
years and days and ago is converted to an appropriate sign. In ISO mode the output looks like
[ quantidade unidade [ ... ] ] [ dias ] [ horas:minutos:segundos ]
The date/time styles can be selected by the user using the SET datestyle command, the DateStyle
parameter in the postgresql.conf configuration file, or the PGDATESTYLE environment variable on
the server or client. The formatting function to_char (see Seção 9.8) is also available as a more
flexible way to format the date/time output.
8.5.3. Time Zones
Time zones, and time-zone conventions, are influenced by political decisions, not just earth
geometry. Time zones around the world became somewhat standardized during the 1900's, but
continue to be prone to arbitrary changes, particularly with respect to daylight-savings rules.
PostgreSQL currently supports daylight-savings rules over the time period 1902 through 2038
(corresponding to the full range of conventional Unix system time). Times outside that range are
taken to be in "standard time" for the selected time zone, no matter what part of the year they fall
in.
PostgreSQL endeavors to be compatible with the SQL standard definitions for typical usage.
However, the SQL standard has an odd mix of date and time types and capabilities. Two obvious
problems are:
Although the date type does not have an associated time zone, the time type can. Time zones
in the real world have little meaning unless associated with a date as well as a time, since the
offset may vary through the year with daylight-saving time boundaries.
The default time zone is specified as a constant numeric offset from UTC. It is therefore not
possible to adapt to daylight-saving time when doing date/time arithmetic across DST
boundaries.
To address these difficulties, we recommend using date/time types that contain both date and time
when using time zones. We recommend not using the type time with time zone (though it is
supported by PostgreSQL for legacy applications and for compliance with the SQL standard).
PostgreSQL assumes your local time zone for any type containing only date or time.
All timezone-aware dates and times are stored internally in UTC. They are converted to local time in
the zone specified by the timezone configuration parameter before being displayed to the client.
PostgreSQL allows you to specify time zones in three different forms:
A full time zone name, for example America/New_York. The recognized time zone names are
listed in the pg_timezone_names view (see Seção 43.49). PostgreSQL uses the widely-used zic
time zone data for this purpose, so the same names are also recognized by much other
software.
A time zone abbreviation, for example PST. Such a specification merely defines a particular
offset from UTC, in contrast to full time zone names which may imply a set of daylight savings
transition-date rules as well. The recognized abbreviations are listed in the
pg_timezone_abbrevs view (see Seção 43.48). You cannot set the configuration parameter
timezone using a time zone abbreviation, but you can use abbreviations in date/time input
values and with the AT TIME ZONE operator.
In addition to the timezone names and abbreviations, PostgreSQL will accept POSIX-style time
zone specifications of the form STDdeslocamento or STDdeslocamentoDST, where STD is a
Date/Time Types
zone abbreviation, deslocamento is a numeric offset in hours west from UTC, and DST is an
optional daylight-savings zone abbreviation, assumed to stand for one hour ahead of the
given offset. For example, if EST5EDT were not already a recognized zone name, it would be
accepted and would be functionally equivalent to USA East Coast time. When a daylight-
savings zone name is present, it is assumed to be used according to USA time zone rules, so
this feature is of limited use outside North America. One should also be wary that this
provision can lead to silently accepting bogus input, since there is no check on the
reasonableness of the zone abbreviations. For example, SET TIMEZONE TO FOOBAR0 will
work, leaving the system effectively using a rather peculiar abbreviation for GMT.
There is a conceptual and practical difference between the abbreviations and the full names:
abbreviations always represent a fixed offset from UTC, whereas most of the full names imply a
local daylight-savings time rule and so have two possible UTC offsets.
In all cases, timezone names are recognized case-insensitively. (This is a change from PostgreSQL
versions prior to 8.2, which were case-sensitive in some contexts and not others.)
Neither full names nor abbreviations are hard-wired into the server; they are obtained from
configuration files stored under .../share/timezone/ and .../share/timezonesets/ of the installation
directory (see Seção B.3).
The timezone configuration parameter can be set in the file postgresql.conf, or in any of the other
standard ways described in Capítulo 17. There are also several special ways to set it:
If timezone is not specified in postgresql.conf nor as a server command-line option, the server
attempts to use the value of the TZ environment variable as the default time zone. If TZ is not
defined or is not any of the time zone names known to PostgreSQL, the server attempts to
determine the operating system's default time zone by checking the behavior of the C library
function localtime(). The default time zone is selected as the closest match among
PostgreSQL's known time zones.
The SQL command SET TIME ZONE sets the time zone for the session. This is an alternative
spelling of SET TIMEZONE TO with a more SQL-spec-compatible syntax.
The PGTZ environment variable, if set at the client, is used by libpq applications to send a SET
TIME ZONE command to the server upon connection.
8.5.4. Internals
PostgreSQL uses Julian dates for all date/time calculations. They have the nice property of correctly
predicting/calculating any date more recent than 4713 BC to far into the future, using the
assumption that the length of the year is 365.2425 days.
Date conventions before the 19th century make for interesting reading, but are not consistent
enough to warrant coding into a date/time handler.

Binary Data Types Acima Boolean Type
Boolean Type

8.6. Boolean Type

PostgreSQL provides the standard SQL type boolean. boolean can have one of only two states:
"true" or "false". A third state, "unknown", is represented by the SQL null value.
Valid literal values for the "true" state are:
TRUE
't'
'true'
'y'
'yes'
'1'
For the "false" state, the following values can be used:
FALSE
'f'
'false'
'n'
'no'
'0'
Using the key words TRUE and FALSE is preferred (and SQL-compliant).
Exemplo 8-2. Using the boolean type
CREATE TABLE test1 (a boolean, b text);

INSERT INTO test1 VALUES (TRUE, 'sic est');
INSERT INTO test1 VALUES (FALSE, 'non est');
SELECT * FROM test1;
a | b
---+---------
t | sic est
f | non est
SELECT * FROM test1 WHERE a;
a | b
---+---------
t | sic est
Exemplo 8-2 shows that boolean values are output using the letters t and f.
boolean uses 1 byte of storage.

Date/Time Types Acima Geometric Types
http://pgdocptbr.sourceforge.net/pg82/datatype-boolean.html[09/02/2018 18:03:45]
Geometric Types


Geometric data types represent two-dimensional spatial objects. Tabela 8-16 shows the geometric
types available in PostgreSQL. The most fundamental type, the point, forms the basis for all of the
other types.
Tabela 8-16. Geometric Types
Name Storage Size Representation Description

point 16 bytes Point on the plane (x,y)
line 32 bytes Infinite line (not fully implemented) ((x1,y1),(x2,y2))
lseg 32 bytes Finite line segment ((x1,y1),(x2,y2))
box 32 bytes Rectangular box ((x1,y1),(x2,y2))
path 16+16n bytes Closed path (similar to polygon) ((x1,y1),...)
path 16+16n bytes Open path [(x1,y1),...]
polygon 40+16n bytes Polygon (similar to closed path) ((x1,y1),...)
circle 24 bytes Circle <(x,y),r> (center and radius)
A rich set of functions and operators is available to perform various geometric operations such as
scaling, translation, rotation, and determining intersections. They are explained in Seção 9.10.
8.7.1. Points
Points are the fundamental two-dimensional building block for geometric types. Values of type point
are specified using the following syntax:
( x , y )
x , y
where x and y are the respective coordinates as floating-point numbers.
8.7.2. Line Segments
Line segments (lseg) are represented by pairs of points. Values of type lseg are specified using the
following syntax:
( ( x1 , y1 ) , ( x2 , y2 ) )
( x1 , y1 ) , ( x2 , y2 )
x1 , y1 , x2 , y2
where (x1,y1) and (x2,y2) are the end points of the line segment.
8.7.3. Boxes
Boxes are represented by pairs of points that are opposite corners of the box. Values of type box
are specified using the following syntax:
( ( x1 , y1 ) , ( x2 , y2 ) )
( x1 , y1 ) , ( x2 , y2 )
x1 , y1 , x2 , y2
http://pgdocptbr.sourceforge.net/pg82/datatype-geometric.html[09/02/2018 18:03:53]
Geometric Types
where (x1,y1) and (x2,y2) are any two opposite corners of the box.
Boxes are output using the first syntax. The corners are reordered on input to store the upper right
corner, then the lower left corner. Other corners of the box can be entered, but the lower left and
upper right corners are determined from the input and stored.
8.7.4. Paths
Paths are represented by lists of connected points. Paths can be open, where the first and last
points in the list are not considered connected, or closed, where the first and last points are
considered connected.
Values of type path are specified using the following syntax:

( ( x1 , y1 ) , ... , ( xn , yn ) )
[ ( x1 , y1 ) , ... , ( xn , yn ) ]
( x1 , y1 ) , ... , ( xn , yn )
( x1 , y1 , ... , xn , yn )
x1 , y1 , ... , xn , yn
where the points are the end points of the line segments comprising the path. Square brackets ([])
indicate an open path, while parentheses (()) indicate a closed path.
Paths are output using the first syntax.
8.7.5. Polygons
Polygons are represented by lists of points (the vertexes of the polygon). Polygons should probably
be considered equivalent to closed paths, but are stored differently and have their own set of
support routines.
Values of type polygon are specified using the following syntax:

( ( x1 , y1 ) , ... , ( xn , yn ) )
( x1 , y1 ) , ... , ( xn , yn )
( x1 , y1 , ... , xn , yn )
x1 , y1 , ... , xn , yn
where the points are the end points of the line segments comprising the boundary of the polygon.
Polygons are output using the first syntax.
8.7.6. Circles
Circles are represented by a center point and a radius. Values of type circle are specified using the
following syntax:
< ( x , y ) , r >
( ( x , y ) , r )
( x , y ) , r
x , y , r
where (x,y) is the center and r is the radius of the circle.
Circles are output using the first syntax.

Boolean Type Acima Network Address Types
http://pgdocptbr.sourceforge.net/pg82/datatype-geometric.html[09/02/2018 18:03:53]
Network Address Types


PostgreSQL offers data types to store IPv4, IPv6, and MAC addresses, as shown in Tabela 8-17. It is
preferable to use these types instead of plain text types to store network addresses, because these types
offer input error checking and several specialized operators and functions (see Seção 9.11).
Tabela 8-17. Network Address Types

cidr 12 or 24 bytes IPv4 and IPv6 networks
inet 12 or 24 bytes IPv4 and IPv6 hosts and networks
macaddr 6 bytes MAC addresses
When sorting inet or cidr data types, IPv4 addresses will always sort before IPv6 addresses, including
IPv4 addresses encapsulated or mapped into IPv6 addresses, such as ::10.2.3.4 or ::ffff::10.4.3.2.
8.8.1. inet
The inet type holds an IPv4 or IPv6 host address, and optionally the identity of the subnet it is in, all in
one field. The subnet identity is represented by stating how many bits of the host address represent the
network address (the "netmask"). If the netmask is 32 and the address is IPv4, then the value does not
indicate a subnet, only a single host. In IPv6, the address length is 128 bits, so 128 bits specify a unique
host address. Note that if you want to accept networks only, you should use the cidr type rather than
inet.
The input format for this type is endereço/y where endereço is an IPv4 or IPv6 address and y is the
number of bits in the netmask. If the /y part is left off, then the netmask is 32 for IPv4 and 128 for IPv6,
so the value represents just a single host. On display, the /y portion is suppressed if the netmask
specifies a single host.
8.8.2. cidr
The cidr type holds an IPv4 or IPv6 network specification. Input and output formats follow Classless
Internet Domain Routing conventions. The format for specifying networks is address/y where address is
the network represented as an IPv4 or IPv6 address, and y is the number of bits in the netmask. If y is
omitted, it is calculated using assumptions from the older classful network numbering system, except
that it will be at least large enough to include all of the octets written in the input. It is an error to specify
a network address that has bits set to the right of the specified netmask.
Tabela 8-18 shows some examples.
Tabela 8-18. cidr Type Input Examples
cidr Input cidr Output abbrev(cidr)

192.168.100.128/25 192.168.100.128/25 192.168.100.128/25
192.168/24 192.168.0.0/24 192.168.0/24
192.168/25 192.168.0.0/25 192.168.0.0/25
192.168.1 192.168.1.0/24 192.168.1/24
192.168 192.168.0.0/24 192.168.0/24
http://pgdocptbr.sourceforge.net/pg82/datatype-net-types.html[09/02/2018 18:04:04]
Network Address Types
128.1 128.1.0.0/16 128.1/16

128 128.0.0.0/16 128.0/16
128.1.2 128.1.2.0/24 128.1.2/24
10.1.2 10.1.2.0/24 10.1.2/24
10.1 10.1.0.0/16 10.1/16
10 10.0.0.0/8 10/8
10.1.2.3/32 10.1.2.3/32 10.1.2.3/32
2001:4f8:3:ba::/64 2001:4f8:3:ba::/64 2001:4f8:3:ba::/64
2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128 2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128 2001:4f8:3:ba:2e0:81ff:fe22:d1f1
::ffff:1.2.3.0/120 ::ffff:1.2.3.0/120 ::ffff:1.2.3/120
::ffff:1.2.3.0/128 ::ffff:1.2.3.0/128 ::ffff:1.2.3.0/128
8.8.3. inet vs. cidr
The essential difference between inet and cidr data types is that inet accepts values with nonzero bits to
the right of the netmask, whereas cidr does not.
Dica: If you do not like the output format for inet or cidr values, try the functions host, text,
and abbrev.
8.8.4. macaddr
The macaddr type stores MAC addresses, i.e., Ethernet card hardware addresses (although MAC
addresses are used for other purposes as well). Input is accepted in various customary formats, including
'08002b:010203'
'08002b-010203'
'0800.2b01.0203'
'08-00-2b-01-02-03'
'08:00:2b:01:02:03'
which would all specify the same address. Upper and lower case is accepted for the digits a through f.
Output is always in the last of the forms shown.

Geometric Types Acima Bit String Types
http://pgdocptbr.sourceforge.net/pg82/datatype-net-types.html[09/02/2018 18:04:04]
Bit String Types


Bit strings are strings of 1's and 0's. They can be used to store or visualize bit masks. There are two
SQL bit types: bit(n) and bit varying(n), where n is a positive integer.
bit type data must match the length n exactly; it is an error to attempt to store shorter or longer bit
strings. bit varying data is of variable length up to the maximum length n; longer strings will be
rejected. Writing bit without a length is equivalent to bit(1), while bit varying without a length
specification means unlimited length.
Nota: If one explicitly casts a bit-string value to bit(n), it will be truncated or zero-
padded on the right to be exactly n bits, without raising an error. Similarly, if one
explicitly casts a bit-string value to bit varying(n), it will be truncated on the right if it is
more than n bits.
Refer to Seção 4.1.2.3 for information about the syntax of bit string constants. Bit-logical operators
and string manipulation functions are available; see Seção 9.6.
Exemplo 8-3. Using the bit string types
CREATE TABLE test (a BIT(3), b BIT VARYING(5));

INSERT INTO test VALUES (B'101', B'00');
INSERT INTO test VALUES (B'10', B'101');
ERROR: bit string length 2 does not match type bit(3)
INSERT INTO test VALUES (B'10'::bit(3), B'101');
SELECT * FROM test;
a | b
-----+-----
101 | 00
100 | 101

Network Address Types Acima Arrays
http://pgdocptbr.sourceforge.net/pg82/datatype-bit.html[09/02/2018 18:04:12]
Arrays

8.10. Arrays
PostgreSQL allows columns of a table to be defined as variable-length multidimensional arrays.
Arrays of any built-in or user-defined base type can be created. (Arrays of composite types or
domains are not yet supported, however.)
8.10.1. Declaration of Array Types
To illustrate the use of array types, we create this table:
CREATE TABLE sal_emp (

name text,
pay_by_quarter integer[],
schedule text[][]
);
As shown, an array data type is named by appending square brackets ([]) to the data type name of
the array elements. The above command will create a table named sal_emp with a column of type
text (name), a one-dimensional array of type integer (pay_by_quarter), which represents the
employee's salary by quarter, and a two-dimensional array of text (schedule), which represents the
employee's weekly schedule.
The syntax for CREATE TABLE allows the exact size of arrays to be specified, for example:
CREATE TABLE tictactoe (

squares integer[3][3]
);
However, the current implementation does not enforce the array size limits — the behavior is the
same as for arrays of unspecified length.
Actually, the current implementation does not enforce the declared number of dimensions either.
Arrays of a particular element type are all considered to be of the same type, regardless of size or
number of dimensions. So, declaring number of dimensions or sizes in CREATE TABLE is simply
documentation, it does not affect run-time behavior.
An alternative syntax, which conforms to the SQL standard, may be used for one-dimensional
arrays. pay_by_quarter could have been defined as:
pay_by_quarter integer ARRAY[4],
This syntax requires an integer constant to denote the array size. As before, however, PostgreSQL
does not enforce the size restriction.
8.10.2. Array Value Input
To write an array value as a literal constant, enclose the element values within curly braces and
separate them by commas. (If you know C, this is not unlike the C syntax for initializing structures.)
You may put double quotes around any element value, and must do so if it contains commas or
curly braces. (More details appear below.) Thus, the general format of an array constant is the
following:
http://pgdocptbr.sourceforge.net/pg82/arrays.html[09/02/2018 18:04:30]
Arrays
'{ valor1 delimitador valor2 delimitador ... }'
where delimitador is the delimiter character for the type, as recorded in its pg_type entry. Among
the standard data types provided in the PostgreSQL distribution, type box uses a semicolon (;) but
all the others use comma (,). Each valor is either a constant of the array element type, or a
subarray. An example of an array constant is
'{{1,2,3},{4,5,6},{7,8,9}}'
This constant is a two-dimensional, 3-by-3 array consisting of three subarrays of integers.
To set an element of an array constant to NULL, write NULL for the element value. (Any upper- or
lower-case variant of NULL will do.) If you want an actual string value "NULL", you must put double
quotes around it.
(These kinds of array constants are actually only a special case of the generic type constants
discussed in Seção 4.1.2.5. The constant is initially treated as a string and passed to the array input
conversion routine. An explicit type specification might be necessary.)
Now we can show some INSERT statements.
INSERT INTO sal_emp

VALUES ('Bill',
'{10000, 10000, 10000, 10000}',
'{{"meeting", "lunch"}, {"training", "presentation"}}');
INSERT INTO sal_emp
VALUES ('Carol',
'{20000, 25000, 25000, 25000}',
'{{"breakfast", "consulting"}, {"meeting", "lunch"}}');
The result of the previous two inserts looks like this:
SELECT * FROM sal_emp;

name | pay_by_quarter | schedule
-------+---------------------------+-------------------------------------------
Bill | {10000,10000,10000,10000} | {{meeting,lunch},{training,presentation}}
Carol | {20000,25000,25000,25000} | {{breakfast,consulting},{meeting,lunch}}
(2 rows)
The ARRAY constructor syntax may also be used:
INSERT INTO sal_emp

VALUES ('Bill',
ARRAY[10000, 10000, 10000, 10000],
ARRAY[['meeting', 'lunch'], ['training', 'presentation']]);
INSERT INTO sal_emp
VALUES ('Carol',
ARRAY[20000, 25000, 25000, 25000],
ARRAY[['breakfast', 'consulting'], ['meeting', 'lunch']]);
Notice that the array elements are ordinary SQL constants or expressions; for instance, string
literals are single quoted, instead of double quoted as they would be in an array literal. The ARRAY
constructor syntax is discussed in more detail in Seção 4.2.10.
Multidimensional arrays must have matching extents for each dimension. A mismatch causes an
error report, for example:
INSERT INTO sal_emp

VALUES ('Bill',
'{10000, 10000, 10000, 10000}',
'{{"meeting", "lunch"}, {"meeting"}}');
ERROR: multidimensional arrays must have array expressions with matching dimensions
8.10.3. Accessing Arrays
Arrays
Now, we can run some queries on the table. First, we show how to access a single element of an
array at a time. This query retrieves the names of the employees whose pay changed in the second
quarter:
SELECT name FROM sal_emp WHERE pay_by_quarter[1] <> pay_by_quarter[2];

name
-------
Carol
(1 row)
The array subscript numbers are written within square brackets. By default PostgreSQL uses the
one-based numbering convention for arrays, that is, an array of n elements starts with array[1] and
ends with array[n].
This query retrieves the third quarter pay of all employees:
SELECT pay_by_quarter[3] FROM sal_emp;

pay_by_quarter
----------------
10000
25000
(2 rows)
We can also access arbitrary rectangular slices of an array, or subarrays. An array slice is denoted
by writing limite_inferior:limite_superior for one or more array dimensions. For example, this query
retrieves the first item on Bill's schedule for the first two days of the week:
SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';

schedule
------------------------
{{meeting},{training}}
(1 row)
We could also have written
SELECT schedule[1:2][1] FROM sal_emp WHERE name = 'Bill';
with the same result. An array subscripting operation is always taken to represent an array slice if
any of the subscripts are written in the form lower:superior. A lower bound of 1 is assumed for any
subscript where only one value is specified, as in this example:
SELECT schedule[1:2][2] FROM sal_emp WHERE name = 'Bill';

schedule
-------------------------------------------
{{meeting,lunch},{training,presentation}}
(1 row)
An array subscript expression will return null if either the array itself or any of the subscript
expressions are null. Also, null is returned if a subscript is outside the array bounds (this case does
not raise an error). For example, if schedule currently has the dimensions [1:3][1:2] then
referencing schedule[3][3] yields NULL. Similarly, an array reference with the wrong number of
subscripts yields a null rather than an error.
An array slice expression likewise yields null if the array itself or any of the subscript expressions
are null. However, in other corner cases such as selecting an array slice that is completely outside
the current array bounds, a slice expression yields an empty (zero-dimensional) array instead of
null. If the requested slice partially overlaps the array bounds, then it is silently reduced to just the
overlapping region.
The current dimensions of any array value can be retrieved with the array_dims function:
SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol';
Arrays
array_dims
------------
[1:2][1:1]
(1 row)
array_dims produces a text result, which is convenient for people to read but perhaps not so
convenient for programs. Dimensions can also be retrieved with array_upper and array_lower,
which return the upper and lower bound of a specified array dimension, respectively.
SELECT array_upper(schedule, 1) FROM sal_emp WHERE name = 'Carol';

array_upper
-------------
2
(1 row)
8.10.4. Modifying Arrays
An array value can be replaced completely:
UPDATE sal_emp SET pay_by_quarter = '{25000,25000,27000,27000}'

WHERE name = 'Carol';
or using the ARRAY expression syntax:
UPDATE sal_emp SET pay_by_quarter = ARRAY[25000,25000,27000,27000]

An array may also be updated at a single element:
UPDATE sal_emp SET pay_by_quarter[4] = 15000

WHERE name = 'Bill';
or updated in a slice:
UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}'

A stored array value can be enlarged by assigning to element(s) not already present. Any positions
between those previously present and the newly assigned element(s) will be filled with nulls. For
example, if array myarray currently has 4 elements, it will have six elements after an update that
assigns to myarray[6], and myarray[5] will contain a null. Currently, enlargement in this fashion is
only allowed for one-dimensional arrays, not multidimensional arrays.
Subscripted assignment allows creation of arrays that do not use one-based subscripts. For example
one might assign to myarray[-2:7] to create an array with subscript values running from -2 to 7.
New array values can also be constructed by using the concatenation operator, ||.
SELECT ARRAY[1,2] || ARRAY[3,4];

?column?
-----------
{1,2,3,4}
(1 row)
SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
?column?
---------------------
{{5,6},{1,2},{3,4}}
(1 row)
The concatenation operator allows a single element to be pushed on to the beginning or end of a
one-dimensional array. It also accepts two N-dimensional arrays, or an N-dimensional and an N+1-
dimensional array.
Arrays
When a single element is pushed on to either the beginning or end of a one-dimensional array, the
result is an array with the same lower bound subscript as the array operand. For example:
SELECT array_dims(1 || '[0:1]={2,3}'::int[]);

array_dims
------------
[0:2]
(1 row)
SELECT array_dims(ARRAY[1,2] || 3);
array_dims
------------
[1:3]
(1 row)
When two arrays with an equal number of dimensions are concatenated, the result retains the lower
bound subscript of the left-hand operand's outer dimension. The result is an array comprising every
element of the left-hand operand followed by every element of the right-hand operand. For
example:
SELECT array_dims(ARRAY[1,2] || ARRAY[3,4,5]);

array_dims
------------
[1:5]
(1 row)
SELECT array_dims(ARRAY[[1,2],[3,4]] || ARRAY[[5,6],[7,8],[9,0]]);
array_dims
------------
[1:5][1:2]
(1 row)
When an N-dimensional array is pushed on to the beginning or end of an N+1-dimensional array,

the result is analogous to the element-array case above. Each N-dimensional sub-array is
essentially an element of the N+1-dimensional array's outer dimension. For example:
SELECT array_dims(ARRAY[1,2] || ARRAY[[3,4],[5,6]]);

array_dims
------------
[1:3][1:2]
(1 row)
An array can also be constructed by using the functions array_prepend, array_append, or

array_cat. The first two only support one-dimensional arrays, but array_cat supports
multidimensional arrays. Note that the concatenation operator discussed above is preferred over
direct use of these functions. In fact, the functions exist primarily for use in implementing the
concatenation operator. However, they may be directly useful in the creation of user-defined
aggregates. Some examples:
SELECT array_prepend(1, ARRAY[2,3]);

array_prepend
---------------
{1,2,3}
(1 row)
SELECT array_append(ARRAY[1,2], 3);
array_append
--------------
{1,2,3}
(1 row)
SELECT array_cat(ARRAY[1,2], ARRAY[3,4]);
array_cat
-----------
{1,2,3,4}
(1 row)
SELECT array_cat(ARRAY[[1,2],[3,4]], ARRAY[5,6]);
array_cat
---------------------
{{1,2},{3,4},{5,6}}
(1 row)
SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]);
array_cat
---------------------
{{5,6},{1,2},{3,4}}
Arrays
8.10.5. Searching in Arrays
To search for a value in an array, you must check each value of the array. This can be done by
hand, if you know the size of the array. For example:
SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR

pay_by_quarter[2] = 10000 OR
pay_by_quarter[3] = 10000 OR
pay_by_quarter[4] = 10000;
However, this quickly becomes tedious for large arrays, and is not helpful if the size of the array is
uncertain. An alternative method is described in Seção 9.17. The above query could be replaced by:
SELECT * FROM sal_emp WHERE 10000 = ANY (pay_by_quarter);
In addition, you could find rows where the array had all values equal to 10000 with:
SELECT * FROM sal_emp WHERE 10000 = ALL (pay_by_quarter);
Dica: Arrays are not sets; searching for specific array elements may be a sign of
database misdesign. Consider using a separate table with a row for each item that would
be an array element. This will be easier to search, and is likely to scale up better to
large numbers of elements.
8.10.6. Array Input and Output Syntax
The external text representation of an array value consists of items that are interpreted according
to the I/O conversion rules for the array's element type, plus decoration that indicates the array
structure. The decoration consists of curly braces ({ and }) around the array value plus delimiter
characters between adjacent items. The delimiter character is usually a comma (,) but can be
something else: it is determined by the typdelim setting for the array's element type. (Among the
standard data types provided in the PostgreSQL distribution, type box uses a semicolon (;) but all
the others use comma.) In a multidimensional array, each dimension (row, plane, cube, etc.) gets
its own level of curly braces, and delimiters must be written between adjacent curly-braced entities
of the same level.
The array output routine will put double quotes around element values if they are empty strings,
contain curly braces, delimiter characters, double quotes, backslashes, or white space, or match the
word NULL. Double quotes and backslashes embedded in element values will be backslash-escaped.
For numeric data types it is safe to assume that double quotes will never appear, but for textual
data types one should be prepared to cope with either presence or absence of quotes.
By default, the lower bound index value of an array's dimensions is set to one. To represent arrays
with other lower bounds, the array subscript ranges can be specified explicitly before writing the
array contents. This decoration consists of square brackets ([]) around each array dimension's
lower and upper bounds, with a colon (:) delimiter character in between. The array dimension
decoration is followed by an equal sign (=). For example:
SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2

FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss;
e1 | e2
----+----
1 | 6
(1 row)
The array output routine will include explicit dimensions in its result only when there are one or
more lower bounds different from one.
If the value written for an element is NULL (in any case variant), the element is taken to be NULL.
The presence of any quotes or backslashes disables this and allows the literal string value "NULL" to
Arrays
be entered. Also, for backwards compatibility with pre-8.2 versions of PostgreSQL, the array_nulls
configuration parameter may be turned off to suppress recognition of NULL as a NULL.
As shown previously, when writing an array value you may write double quotes around any
individual array element. You must do so if the element value would otherwise confuse the array-
value parser. For example, elements containing curly braces, commas (or whatever the delimiter
character is), double quotes, backslashes, or leading or trailing whitespace must be double-quoted.
Empty strings and strings matching the word NULL must be quoted, too. To put a double quote or
backslash in a quoted array element value, precede it with a backslash. Alternatively, you can use
backslash-escaping to protect all data characters that would otherwise be taken as array syntax.
You may write whitespace before a left brace or after a right brace. You may also write whitespace
before or after any individual item string. In all of these cases the whitespace will be ignored.
However, whitespace within double-quoted elements, or surrounded on both sides by non-
whitespace characters of an element, is not ignored.
Nota: Remember that what you write in an SQL command will first be interpreted as a
string literal, and then as an array. This doubles the number of backslashes you need.
For example, to insert a text array value containing a backslash and a double quote,
you'd need to write
INSERT ... VALUES ('{"\\\\","\\""}');
The string-literal processor removes one level of backslashes, so that what arrives at the
array-value parser looks like {"\\","\""}. In turn, the strings fed to the text data type's
input routine become \ and " respectively. (If we were working with a data type whose
input routine also treated backslashes specially, bytea for example, we might need as
many as eight backslashes in the command to get one backslash into the stored array
element.) Dollar quoting (see Seção 4.1.2.2) may be used to avoid the need to double
backslashes.
Dica: The ARRAY constructor syntax (see Seção 4.2.10) is often easier to work with than
the array-literal syntax when writing array values in SQL commands. In ARRAY,
individual element values are written the same way they would be written when not
members of an array.

Bit String Types Acima Composite Types
Composite Types


A composite type describes the structure of a row or record; it is in essence just a list of field names
and their data types. PostgreSQL allows values of composite types to be used in many of the same
ways that simple types can be used. For example, a column of a table can be declared to be of a
composite type.
8.11.1. Declaration of Composite Types
Here are two simple examples of defining composite types:
CREATE TYPE complex AS (

r double precision,
i double precision
);
CREATE TYPE inventory_item AS (
name text,
supplier_id integer,
price numeric
);
The syntax is comparable to CREATE TABLE, except that only field names and types can be
specified; no constraints (such as NOT NULL) can presently be included. Note that the AS keyword
is essential; without it, the system will think a quite different kind of CREATE TYPE command is
meant, and you'll get odd syntax errors.
Having defined the types, we can use them to create tables:
CREATE TABLE on_hand (

item inventory_item,
count integer
);
INSERT INTO on_hand VALUES (ROW('fuzzy dice', 42, 1.99), 1000);
or functions:
CREATE FUNCTION price_extension(inventory_item, integer) RETURNS numeric

AS 'SELECT $1.price * $2' LANGUAGE SQL;
SELECT price_extension(item, 10) FROM on_hand;
Whenever you create a table, a composite type is also automatically created, with the same name
as the table, to represent the table's row type. For example, had we said
CREATE TABLE inventory_item (

name text,
supplier_id integer REFERENCES suppliers,
price numeric CHECK (price > 0)
);
then the same inventory_item composite type shown above would come into being as a byproduct,
and could be used just as above. Note however an important restriction of the current
implementation: since no constraints are associated with a composite type, the constraints shown
in the table definition do not apply to values of the composite type outside the table. (A partial
workaround is to use domain types as members of composite types.)
http://pgdocptbr.sourceforge.net/pg82/rowtypes.html[09/02/2018 18:04:46]
Composite Types
8.11.2. Composite Value Input
To write a composite value as a literal constant, enclose the field values within parentheses and
separate them by commas. You may put double quotes around any field value, and must do so if it
contains commas or parentheses. (More details appear below.) Thus, the general format of a
composite constant is the following:
'( valor1 , valor2 , ... )'
An example is
'("fuzzy dice",42,1.99)'
which would be a valid value of the inventory_item type defined above. To make a field be NULL,
write no characters at all in its position in the list. For example, this constant specifies a NULL third
field:
'("fuzzy dice",42,)'
If you want an empty string rather than NULL, write double quotes:
'("",42,)'
Here the first field is a non-NULL empty string, the third is NULL.
(These constants are actually only a special case of the generic type constants discussed in Seção
4.1.2.5. The constant is initially treated as a string and passed to the composite-type input
conversion routine. An explicit type specification might be necessary.)
The ROW expression syntax may also be used to construct composite values. In most cases this is
considerably simpler to use than the string-literal syntax, since you don't have to worry about
multiple layers of quoting. We already used this method above:
ROW('fuzzy dice', 42, 1.99)

ROW('', 42, NULL)
The ROW keyword is actually optional as long as you have more than one field in the expression, so
these can simplify to
('fuzzy dice', 42, 1.99)

('', 42, NULL)
The ROW expression syntax is discussed in more detail in Seção 4.2.11.
8.11.3. Accessing Composite Types
To access a field of a composite column, one writes a dot and the field name, much like selecting a
field from a table name. In fact, it's so much like selecting from a table name that you often have to
use parentheses to keep from confusing the parser. For example, you might try to select some
subfields from our on_hand example table with something like:
SELECT item.name FROM on_hand WHERE item.price > 9.99;
This will not work since the name item is taken to be a table name, not a field name, per SQL
syntax rules. You must write it like this:
Composite Types
SELECT (item).name FROM on_hand WHERE (item).price > 9.99;
or if you need to use the table name as well (for instance in a multitable query), like this:
SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99;
Now the parenthesized object is correctly interpreted as a reference to the item column, and then
the subfield can be selected from it.
Similar syntactic issues apply whenever you select a field from a composite value. For instance, to
select just one field from the result of a function that returns a composite value, you'd need to write
something like
SELECT (my_func(...)).field FROM ...
Without the extra parentheses, this will provoke a syntax error.
8.11.4. Modifying Composite Types
Here are some examples of the proper syntax for inserting and updating composite columns. First,
inserting or updating a whole column:
INSERT INTO mytab (complex_col) VALUES((1.1,2.2));

UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...;
The first example omits ROW, the second uses it; we could have done it either way.
We can update an individual subfield of a composite column:
UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...;
Notice here that we don't need to (and indeed cannot) put parentheses around the column name
appearing just after SET, but we do need parentheses when referencing the same column in the
expression to the right of the equal sign.
And we can specify subfields as targets for INSERT, too:
INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
Had we not supplied values for all the subfields of the column, the remaining subfields would have
been filled with null values.
8.11.5. Composite Type Input and Output Syntax
The external text representation of a composite value consists of items that are interpreted
according to the I/O conversion rules for the individual field types, plus decoration that indicates the
composite structure. The decoration consists of parentheses (( and )) around the whole value, plus
commas (,) between adjacent items. Whitespace outside the parentheses is ignored, but within the
parentheses it is considered part of the field value, and may or may not be significant depending on
the input conversion rules for the field data type. For example, in
'( 42)'
the whitespace will be ignored if the field type is integer, but not if it is text.
As shown previously, when writing a composite value you may write double quotes around any
Composite Types
individual field value. You must do so if the field value would otherwise confuse the composite-value
parser. In particular, fields containing parentheses, commas, double quotes, or backslashes must
be double-quoted. To put a double quote or backslash in a quoted composite field value, precede it
with a backslash. (Also, a pair of double quotes within a double-quoted field value is taken to
represent a double quote character, analogously to the rules for single quotes in SQL literal strings.)
Alternatively, you can use backslash-escaping to protect all data characters that would otherwise be
taken as composite syntax.
A completely empty field value (no characters at all between the commas or parentheses)
represents a NULL. To write a value that is an empty string rather than NULL, write "".
The composite output routine will put double quotes around field values if they are empty strings or
contain parentheses, commas, double quotes, backslashes, or white space. (Doing so for white
space is not essential, but aids legibility.) Double quotes and backslashes embedded in field values
will be doubled.
Nota: Remember that what you write in an SQL command will first be interpreted as a
string literal, and then as a composite. This doubles the number of backslashes you
need. For example, to insert a text field containing a double quote and a backslash in a
composite value, you'd need to write
INSERT ... VALUES ('("\\"\\\\")');
The string-literal processor removes one level of backslashes, so that what arrives at the
composite-value parser looks like ("\"\\"). In turn, the string fed to the text data type's
input routine becomes "\. (If we were working with a data type whose input routine also
treated backslashes specially, bytea for example, we might need as many as eight
backslashes in the command to get one backslash into the stored composite field.)
Dollar quoting (see Seção 4.1.2.2) may be used to avoid the need to double backslashes.
Dica: The ROW constructor syntax is usually easier to work with than the composite-
literal syntax when writing composite values in SQL commands. In ROW, individual field
values are written the same way they would be written when not members of a
composite.

Arrays Acima Object Identifier Types
Object Identifier Types


Object identifiers (OIDs) are used internally by PostgreSQL as primary keys for various system
tables. OIDs are not added to user-created tables, unless WITH OIDS is specified when the table is
created, or the default_with_oids configuration variable is enabled. Type oid represents an object
identifier. There are also several alias types for oid: regproc, regprocedure, regoper, regoperator,
regclass, and regtype. Tabela 8-19 shows an overview.
The oid type is currently implemented as an unsigned four-byte integer. Therefore, it is not large
enough to provide database-wide uniqueness in large databases, or even in large individual tables.
So, using a user-created table's OID column as a primary key is discouraged. OIDs are best used
only for references to system tables.
The oid type itself has few operations beyond comparison. It can be cast to integer, however, and
then manipulated using the standard integer operators. (Beware of possible signed-versus-unsigned
confusion if you do this.)
The OID alias types have no operations of their own except for specialized input and output
routines. These routines are able to accept and display symbolic names for system objects, rather
than the raw numeric value that type oid would use. The alias types allow simplified lookup of OID
values for objects. For example, to examine the pg_attribute rows related to a table mytable, one
could write
SELECT * FROM pg_attribute WHERE attrelid = 'mytable'::regclass;
rather than
SELECT * FROM pg_attribute

WHERE attrelid = (SELECT oid FROM pg_class WHERE relname = 'mytable');
While that doesn't look all that bad by itself, it's still oversimplified. A far more complicated sub-
select would be needed to select the right OID if there are multiple tables named mytable in
different schemas. The regclass input converter handles the table lookup according to the schema
path setting, and so it does the "right thing" automatically. Similarly, casting a table's OID to
regclass is handy for symbolic display of a numeric OID.
Tabela 8-19. Object Identifier Types
Name References Description Value Example

oid any numeric object identifier 564182
regproc pg_proc function name sum
regprocedure pg_proc function with argument types sum(int4)
regoper pg_operator operator name +
regoperator pg_operator operator with argument types *(integer,integer) or -(NONE,integer)
regclass pg_class relation name pg_type
regtype pg_type data type name integer
All of the OID alias types accept schema-qualified names, and will display schema-qualified names
on output if the object would not be found in the current search path without being qualified. The
http://pgdocptbr.sourceforge.net/pg82/datatype-oid.html[09/02/2018 18:04:56]
Object Identifier Types
regproc and regoper alias types will only accept input names that are unique (not overloaded), so
they are of limited use; for most uses regprocedure or regoperator is more appropriate. For
regoperator, unary operators are identified by writing NONE for the unused operand.
An additional property of the OID alias types is that if a constant of one of these types appears in a
stored expression (such as a column default expression or view), it creates a dependency on the
referenced object. For example, if a column has a default expression nextval('my_seq'::regclass),
PostgreSQL understands that the default expression depends on the sequence my_seq; the system
will not let the sequence be dropped without first removing the default expression.
Another identifier type used by the system is xid, or transaction (abbreviated xact) identifier. This is
the data type of the system columns xmin and xmax. Transaction identifiers are 32-bit quantities.
A third identifier type used by the system is cid, or command identifier. This is the data type of the
system columns cmin and cmax. Command identifiers are also 32-bit quantities.
A final identifier type used by the system is tid, or tuple identifier (row identifier). This is the data
type of the system column ctid. A tuple ID is a pair (block number, tuple index within block) that
identifies the physical location of the row within its table.
(The system columns are further explained in Seção 5.4.)

Composite Types Acima Pseudo-Types
http://pgdocptbr.sourceforge.net/pg82/datatype-oid.html[09/02/2018 18:04:56]
Pseudo-Types

8.13. Pseudo-Types
The PostgreSQL type system contains a number of special-purpose entries that are collectively
called pseudo-types. A pseudo-type cannot be used as a column data type, but it can be used to
declare a function's argument or result type. Each of the available pseudo-types is useful in
situations where a function's behavior does not correspond to simply taking or returning a value of
a specific SQL data type. Tabela 8-20 lists the existing pseudo-types.
Tabela 8-20. Pseudo-Types
Name Description
any Indicates that a function accepts any input data type whatever.
anyarray Indicates that a function accepts any array data type (see Seção 33.2.5).
anyelement Indicates that a function accepts any data type (see Seção 33.2.5).
cstring Indicates that a function accepts or returns a null-terminated C string.
internal Indicates that a function accepts or returns a server-internal data type.
language_handler A procedural language call handler is declared to return language_handler.
record Identifies a function returning an unspecified row type.
trigger A trigger function is declared to return trigger.
void Indicates that a function returns no value.
opaque An obsolete type name that formerly served all the above purposes.
Functions coded in C (whether built-in or dynamically loaded) may be declared to accept or return
any of these pseudo data types. It is up to the function author to ensure that the function will
behave safely when a pseudo-type is used as an argument type.
Functions coded in procedural languages may use pseudo-types only as allowed by their
implementation languages. At present the procedural languages all forbid use of a pseudo-type as
argument type, and allow only void and record as a result type (plus trigger when the function is
used as a trigger). Some also support polymorphic functions using the types anyarray and
anyelement.
The internal pseudo-type is used to declare functions that are meant only to be called internally by
the database system, and not by direct invocation in a SQL query. If a function has at least one
internal-type argument then it cannot be called from SQL. To preserve the type safety of this
restriction it is important to follow this coding rule: do not create any function that is declared to
return internal unless it has at least one internal argument.

Object Identifier Types Acima XML Document Support
http://pgdocptbr.sourceforge.net/pg82/datatype-pseudo.html[09/02/2018 18:05:04]
XML Document Support


XML (Extensible Markup Language) support is not one capability, but a variety of features
supported by a database system. These capabilities include storage, import/export, validation,
indexing, efficiency of modification, searching, transforming, and XML to SQL mapping. PostgreSQL
supports some but not all of these XML capabilities. Future releases of PostgreSQL will continue to
improve XML support. For an overview of XML use in databases, see
http://www.rpbourret.com/xml/XMLAndDatabases.htm.
Storage
PostgreSQL does not have a specialized XML data type. Users should store XML documents in
ordinary TEXT fields. If you need the document split apart into its component parts so each
element is stored separately, you must use a middle-ware solution to do that, but once done,
the data becomes relational and has to be processed accordingly.
Import/Export
There is no facility for mapping XML to relational tables. An external tool must be used for
this. One simple way to export XML is to use psql in HTML mode (\pset format html), and
convert the XHTML output to XML using an external tool.
Validation
/contrib/xml2 has a function called xml_is_well_formed() that can be used in a CHECK

constraint to enforce that a field contains well-formed XML. It does not support validation
against a specific XML schema. A server-side language with XML capabilities could be used to
do schema-specific XML checks.
Indexing
/contrib/xml2 functions can be used in expression indexes to index specific XML fields. To
index the full contents of XML documents, the full-text indexing tool /contrib/tsearch2 can be
used. Of course, Tsearch2 indexes have no XML awareness so additional /contrib/xml2 checks
should be added to queries.
Modification
If an UPDATE does not modify an XML field, the XML data is shared between the old and new
rows. However, if the UPDATE modifies an XML field, a full modified copy of the XML field
must be created internally.
Searching
XPath searches are implemented using /contrib/xml2. It processes XML text documents and
returns results based on the requested query.
Transforming
/contrib/xml2 supports XSLT (Extensible Stylesheet Language Transformation).
XML to SQL Mapping
This involves converting XML data to and from relational structures. PostgreSQL has no
http://pgdocptbr.sourceforge.net/pg82/datatype-xml.html[09/02/2018 18:05:14]
XML Document Support
internal support for such mapping, and relies on external tools to do such conversions.
Missing Features
Missing features include XQuery, SQL/XML syntax (ISO/IEC 9075-14), and an XML data type
optimized for XML storage.

Pseudo-Types Acima Functions and Operators
http://pgdocptbr.sourceforge.net/pg82/datatype-xml.html[09/02/2018 18:05:14]
Functions and Operators

Capítulo 9. Functions and Operators

Sumário
9.7.1. LIKE
9.7.2. SIMILAR TO Regular Expressions
9.7.3. POSIX Regular Expressions

9.9.1. EXTRACT, date_part

9.9.2. date_trunc
9.9.3. AT TIME ZONE
9.9.4. Current Date/Time
9.9.5. Delaying Execution

9.13.1. CASE
9.13.2. COALESCE
9.13.3. NULLIF
9.13.4. GREATEST and LEAST

9.16.1. EXISTS
9.16.2. IN
9.16.3. NOT IN
9.16.4. ANY/SOME
9.16.5. ALL
9.16.6. Row-wise Comparison
9.17.1. IN
9.17.2. NOT IN
9.17.3. ANY/SOME (array)
9.17.4. ALL (array)
http://pgdocptbr.sourceforge.net/pg82/functions.html[09/02/2018 18:05:23]
Functions and Operators

PostgreSQL provides a large number of functions and operators for the built-in data types. Users
can also define their own functions and operators, as described in Parte V. The psql commands \df
and \do can be used to show the list of all actually available functions and operators, respectively.
If you are concerned about portability then take note that most of the functions and operators
described in this chapter, with the exception of the most trivial arithmetic and comparison operators
and some explicitly marked functions, are not specified by the SQL standard. Some of the extended
functionality is present in other SQL database management systems, and in many cases this
functionality is compatible and consistent between the various implementations. This chapter is also
not exhaustive; additional functions appear in relevant sections of the manual.

XML Document Support Acima Logical Operators
http://pgdocptbr.sourceforge.net/pg82/functions.html[09/02/2018 18:05:23]
Logical Operators

Anterior Início Capítulo 9. Functions and Operators Fim Próxima

The usual logical operators are available:
AND
OR
NOT
SQL uses a three-valued Boolean logic where the null value represents "unknown". Observe the
following truth tables:
a b a AND b a OR b
TRUE TRUE TRUE TRUE
TRUE FALSE FALSE TRUE
TRUE NULL NULL TRUE
FALSE FALSE FALSE FALSE
FALSE NULL FALSE NULL
NULL NULL NULL NULL
a NOT a
TRUE FALSE
FALSE TRUE
NULL NULL
The operators AND and OR are commutative, that is, you can switch the left and right operand
without affecting the result. But see Seção 4.2.12 for more information about the order of evaluation
of subexpressions.

Functions and Operators Acima Comparison Operators
http://pgdocptbr.sourceforge.net/pg82/functions-logical.html[09/02/2018 18:05:40]
Comparison Operators


The usual comparison operators are available, shown in Tabela 9-1.
Tabela 9-1. Comparison Operators
Operator Description
< less than
> greater than
<= less than or equal to
>= greater than or equal to
= equal
<> or != not equal
Nota: The != operator is converted to <> in the parser stage. It is not possible to
implement != and <> operators that do different things.
Comparison operators are available for all data types where this makes sense. All comparison
operators are binary operators that return values of type boolean; expressions like 1 < 2 < 3 are
not valid (because there is no < operator to compare a Boolean value with 3).
In addition to the comparison operators, the special BETWEEN construct is available.

a BETWEEN x AND y
is equivalent to
a >= x AND a <= y
Similarly,
a NOT BETWEEN x AND y
is equivalent to
a < x OR a > y
There is no difference between the two respective forms apart from the CPU cycles required to
rewrite the first one into the second one internally. BETWEEN SYMMETRIC is the same as BETWEEN
except there is no requirement that the argument to the left of AND be less than or equal to the
argument on the right; the proper range is automatically determined.
To check whether a value is or is not null, use the constructs

expressão IS NULL
expressão IS NOT NULL
or the equivalent, but nonstandard, constructs

expressão ISNULL
expressão NOTNULL
Do not write expressão = NULL because NULL is not "equal to" NULL. (The null value represents an
unknown value, and it is not known whether two unknown values are equal.) This behavior
conforms to the SQL standard.
http://pgdocptbr.sourceforge.net/pg82/functions-comparison.html[09/02/2018 18:05:56]
Comparison Operators
Dica: Some applications may expect that expressão = NULL returns true if expressão
evaluates to the null value. It is highly recommended that these applications be modified
to comply with the SQL standard. However, if that cannot be done the
transform_null_equals configuration variable is available. If it is enabled, PostgreSQL will
convert x = NULL clauses to x IS NULL. This was the default behavior in PostgreSQL
releases 6.5 through 7.1.
Nota: If the expressão is row-valued, then IS NULL is true when the row expression
itself is null or when all the row's fields are null, while IS NOT NULL is true when the row
expression itself is non-null and all the row's fields are non-null. This definition conforms
to the SQL standard, and is a change from the inconsistent behavior exhibited by
PostgreSQL versions prior to 8.2.
The ordinary comparison operators yield null (signifying "unknown") when either input is null.
Another way to do comparisons is with the IS [ NOT ] DISTINCT FROM construct:
expressão IS DISTINCT FROM expressão
expressão IS NOT DISTINCT FROM expressão
For non-null inputs, IS DISTINCT FROM is the same as the <> operator. However, when both inputs
are null it will return false, and when just one input is null it will return true. Similarly, IS NOT
DISTINCT FROM is identical to = for non-null inputs, but it returns true when both inputs are null,
and false when only one input is null. Thus, these constructs effectively act as though null were a
normal data value, rather than "unknown".
Boolean values can also be tested using the constructs

expressão IS TRUE
expressão IS NOT TRUE
expressão IS FALSE
expressão IS NOT FALSE
expressão IS UNKNOWN
expressão IS NOT UNKNOWN
These will always return true or false, never a null value, even when the operand is null. A null
input is treated as the logical value "unknown". Notice that IS UNKNOWN and IS NOT UNKNOWN
are effectively the same as IS NULL and IS NOT NULL, respectively, except that the input
expression must be of Boolean type.

Logical Operators Acima Mathematical Functions and
Operators
http://pgdocptbr.sourceforge.net/pg82/functions-comparison.html[09/02/2018 18:05:56]
Mathematical Functions and Operators


Mathematical operators are provided for many PostgreSQL types. For types without common
mathematical conventions for all possible permutations (e.g., date/time types) we describe the
actual behavior in subsequent sections.
Tabela 9-2 shows the available mathematical operators.
Tabela 9-2. Mathematical Operators
Operator Description Example Result

+ addition 2+3 5
- subtraction 2-3 -1
* multiplication 2*3 6
/ division (integer division truncates results) 4 / 2 2
% modulo (remainder) 5%4 1
^ exponentiation 2.0 ^ 3.0 8
|/ square root |/ 25.0 5
||/ cube root ||/ 27.0 3
! factorial 5! 120
!! factorial (prefix operator) !! 5 120
@ absolute value @ -5.0 5
& bitwise AND 91 & 15 11
| bitwise OR 32 | 3 35
# bitwise XOR 17 # 5 20
~ bitwise NOT ~1 -2
<< bitwise shift left 1 << 4 16
>> bitwise shift right 8 >> 2 2
The bitwise operators work only on integral data types, whereas the others are available for all
numeric data types. The bitwise operators are also available for the bit string types bit and bit
varying, as shown in Tabela 9-10.
Tabela 9-3 shows the available mathematical functions. In the table, dp indicates double precision.
Many of these functions are provided in multiple forms with different argument types. Except where
noted, any given form of a function returns the same data type as its argument. The functions
working with double precision data are mostly implemented on top of the host system's C library;
accuracy and behavior in boundary cases may therefore vary depending on the host system.
Tabela 9-3. Mathematical Functions
Return
Function Description Example Result
Type
abs(x) (same as absolute value abs(-17.4) 17.4
x)
cbrt(dp) dp cube root cbrt(27.0) 3
http://pgdocptbr.sourceforge.net/pg82/functions-math.html[09/02/2018 18:06:04]
ceil(dp or numeric) (same as smallest integer not less than ceil(-42.8) -42
input) argument
ceiling(dp or (same as smallest integer not less than ceiling(-95.3) -95
numeric) input) argument (alias for ceil)
degrees(dp) dp radians to degrees degrees(0.5) 28.6478897565412
exp(dp or numeric) (same as exponential exp(1.0) 2.71828182845905
input)
floor(dp or (same as largest integer not greater floor(-42.8) -43
numeric) input) than argument
ln(dp or numeric) (same as natural logarithm ln(2.0) 0.693147180559945
input)
log(dp or numeric) (same as base 10 logarithm log(100.0) 2
input)
log(b numeric, x numeric logarithm to base b log(2.0, 64.0) 6.0000000000
numeric)
mod(y, x) (same as remainder of y/x mod(9,4) 1
argument
types)
pi() dp "π" constant pi() 3.14159265358979
power(a dp, b dp) dp a raised to the power of b power(9.0, 3.0) 729
power(a numeric, b numeric a raised to the power of b power(9.0, 3.0) 729
numeric)
radians(dp) dp degrees to radians radians(45.0) 0.785398163397448
random() dp random value between 0.0 random()
and 1.0
round(dp or (same as round to nearest integer round(42.4) 42
numeric) input)
round(v numeric, s numeric round to s decimal places round(42.4382, 2) 42.44
int)
setseed(dp) int set seed for subsequent setseed(0.54823) 1177314959
random() calls (value
between 0 and 1.0)
sign(dp or numeric) (same as sign of the argument (-1, 0, sign(-8.4) -1
input) +1)
sqrt(dp or numeric) (same as square root sqrt(2.0) 1.4142135623731
input)
trunc(dp or (same as truncate toward zero trunc(42.8) 42
numeric) input)
trunc(v numeric, s numeric truncate to s decimal places trunc(42.4382, 2) 42.43
int)
width_bucket(op int return the bucket to which width_bucket(5.35, 3
numeric, b1 operand would be assigned in 0.024, 10.06, 5)
numeric, b2 an equidepth histogram with
numeric, count int) count buckets, in the range
b1 to b2
Finally, Tabela 9-4 shows the available trigonometric functions. All trigonometric functions take
arguments and return values of type double precision.
Tabela 9-4. Trigonometric Functions
Function Description
acos(x) inverse cosine
asin(x) inverse sine
atan(x) inverse tangent
atan2(x, y) inverse tangent of x/y
cos(x) cosine
cot(x) cotangent
sin(x) sine
tan(x) tangent

Comparison Operators Acima String Functions and Operators
String Functions and Operators


This section describes functions and operators for examining and manipulating string values.
Strings in this context include values of all the types character, character varying, and text. Unless
otherwise noted, all of the functions listed below work on all of these types, but be wary of potential
effects of the automatic padding when using the character type. Generally, the functions described
here also work on data of non-string types by converting that data to a string representation first.
Some functions also exist natively for the bit-string types.
SQL defines some string functions with a special syntax where certain key words rather than
commas are used to separate the arguments. Details are in Tabela 9-5. These functions are also
implemented using the regular syntax for function invocation. (See Tabela 9-6.)
Tabela 9-5. SQL String Functions and Operators
Return
Type
string || string text String concatenation 'Post' || 'greSQL' PostgreSQL
bit_length(string) int Number of bits in string bit_length('jose') 32
char_length(string) or int Number of characters in string char_length('jose') 4
character_length(string)
convert(string using text Change encoding using specified convert('PostgreSQL' 'PostgreSQL'
conversion_name) conversion name. Conversions using in UTF8
can be defined by CREATE iso_8859_1_to_utf8) (Unicode, 8-
CONVERSION. Also there are bit)
some pre-defined conversion encoding
names. See Tabela 9-7 for
available conversion names.
lower(string) text Convert string to lower case lower('TOM') tom
octet_length(string) int Number of bytes in string octet_length('jose') 4
overlay(string placing text Replace substring overlay('Txxxxas' Thomas
string from int [for int]) placing 'hom' from 2
for 4)
position(substring in int Location of specified substring position('om' in 3
string) 'Thomas')
substring(string [from text Extract substring substring('Thomas' hom
int] [for int]) from 2 for 3)
substring(string from text Extract substring matching POSIX substring('Thomas' mas
padrão) regular expression. See Seção 9.7 from '...$')
for more information on pattern
matching.
substring(string from text Extract substring matching SQL substring('Thomas' oma
padrão for escape) regular expression. See Seção 9.7 from '%#"o_a#"_'
for more information on pattern for '#')
matching.
trim([leading | trailing | text Remove the longest string trim(both 'x' from Tom
both] [characters] from containing only the characters (a 'xTomxx')
string) space by default) from the
start/end/both ends of the string
http://pgdocptbr.sourceforge.net/pg82/functions-string.html[09/02/2018 18:06:15]
upper(string) text Convert string to uppercase upper('tom') TOM
Additional string manipulation functions are available and are listed in Tabela 9-6. Some of them are
used internally to implement the SQL-standard string functions listed in Tabela 9-5.
Tabela 9-6. Other String Functions
Return
Type
ascii(string) int ASCII code of the ascii('x') 120
first byte of the
argument
btrim(string text [, text Remove the btrim('xyxtrimyyx', 'xy') trim
characters text]) longest string
consisting only of
characters in
characters (a
space by default)
from the start and
end of string
chr(int) text Character with chr(65) A
the given ASCII
code
convert(string text, text Convert string to convert( 'text_in_utf8', 'UTF8', text_in_utf8
[src_encoding name,] dest_encoding. 'LATIN1') represented in ISO
dest_encoding name) The original 8859-1 encoding
encoding is
specified by
src_encoding. If
src_encoding is
omitted, database
encoding is
assumed.
decode(string text, bytea Decode binary decode('MTIzAAE=', 'base64') 123\000\001
type text) data from string
previously
encoded with
encode.
Parameter type is
same as in
encode.
encode(data bytea, text Encode binary encode( '123\\000\\001', MTIzAAE=
type text) data to ASCII- 'base64')
only
representation.
Supported types
are: base64, hex,
escape.
initcap(string) text Convert the first initcap('hi THOMAS') Hi Thomas
letter of each
word to
uppercase and
the rest to
lowercase. Words
are sequences of
alphanumeric
characters
separated by non-
alphanumeric
characters.
length(string) int Number of length('jose') 4
characters in
string
lpad(string text, text Fill up the string lpad('hi', 5, 'xy') xyxhi
length int [, fill text]) to length length
by prepending the
characters fill (a
space by default).
If the string is
already longer
than length then
it is truncated (on
the right).
ltrim(string text [, text Remove the ltrim('zzzytrim', 'xyz') trim
containing only
characters from
characters (a
space by default)
from the start of
string
md5(string) text Calculates the md5('abc') 900150983cd24fb0
MD5 hash of d6963f7d28e17f72
string, returning
the result in
hexadecimal
pg_client_encoding() name Current client pg_client_encoding() SQL_ASCII
encoding name
quote_ident(string) text Return the given quote_ident('Foo bar') "Foo bar"
string suitably
quoted to be used
as an identifier in
an SQL statement
string. Quotes are
added only if
necessary (i.e., if
the string
contains non-
identifier
characters or
would be case-
folded).
Embedded quotes
are properly
doubled.
quote_literal(string) text Return the given quote_literal( 'O\'Reilly') 'O''Reilly'
string suitably
quoted to be used
as a string literal
in an SQL
statement string.
Embedded quotes
and backslashes
are properly
doubled.
regexp_replace(string text Replace substring regexp_replace('Thomas', '. ThM
text, pattern text, matching POSIX [mN]a.', 'M')
replacement text regular
[,flags text]) expression. See
Seção 9.7 for more
information on
pattern matching.
repeat(string text, text Repeat string the repeat('Pg', 4) PgPgPgPg
number int) specified number

of times
replace(string text, text Replace all replace( 'abcdefabcdef', 'cd', abXXefabXXef
from text, to text) occurrences in 'XX')
string of substring
from with
substring to
rpad(string text, text Fill up the string rpad('hi', 5, 'xy') hixyx
length int [, fill text]) to length length
by appending the
characters fill (a
space by default).
If the string is
already longer
than length then
it is truncated.
rtrim(string text [, text Remove the rtrim('trimxxxx', 'x') trim
containing only
characters from
characters (a
space by default)
from the end of
string
split_part(string text, text Split string on split_part('abc~@~def~@~ghi', def
delimiter text, field delimiter and '~@~', 2)
int) return the given
field (counting
from one)
strpos(string, int Location of strpos('high', 'ig') 2
substring) specified
substring (same
as
position(substring
in string), but
note the reversed
argument order)
substr(string, from [, text Extract substring substr('alphabet', 3, 2) ph
count]) (same as
substring(string
from from for
count))
to_ascii(string text [, text Convert string to to_ascii('Karel') Karel
encoding text]) ASCII from
another encoding
(only supports
conversion from
LATIN1, LATIN2,
LATIN9, and
WIN1250
encodings)
to_hex(number int or text Convert number to_hex(2147483647) 7fffffff
bigint) to its equivalent
hexadecimal
representation
translate(string text, text Any character in translate('12345', '14', 'ax') a23x5
from text, to text) string that
matches a
character in the
from set is
replaced by the
corresponding
character in the to
set
Tabela 9-7. Built-in Conversions
Conversion Name [a] Source Encoding Destination Encoding

ascii_to_mic SQL_ASCII MULE_INTERNAL
ascii_to_utf8 SQL_ASCII UTF8
big5_to_euc_tw BIG5 EUC_TW
big5_to_mic BIG5 MULE_INTERNAL
big5_to_utf8 BIG5 UTF8
euc_cn_to_mic EUC_CN MULE_INTERNAL
euc_cn_to_utf8 EUC_CN UTF8
euc_jp_to_mic EUC_JP MULE_INTERNAL
euc_jp_to_sjis EUC_JP SJIS
euc_jp_to_utf8 EUC_JP UTF8
euc_kr_to_mic EUC_KR MULE_INTERNAL
euc_kr_to_utf8 EUC_KR UTF8
euc_tw_to_big5 EUC_TW BIG5
euc_tw_to_mic EUC_TW MULE_INTERNAL
euc_tw_to_utf8 EUC_TW UTF8
gb18030_to_utf8 GB18030 UTF8
gbk_to_utf8 GBK UTF8
iso_8859_10_to_utf8 LATIN6 UTF8
iso_8859_1_to_mic LATIN1 MULE_INTERNAL
iso_8859_2_to_windows_1250 LATIN2 WIN1250
iso_8859_5_to_koi8_r ISO_8859_5 KOI8
iso_8859_5_to_mic ISO_8859_5 MULE_INTERNAL
iso_8859_5_to_utf8 ISO_8859_5 UTF8
iso_8859_5_to_windows_1251 ISO_8859_5 WIN1251
iso_8859_5_to_windows_866 ISO_8859_5 WIN866
johab_to_utf8 JOHAB UTF8
koi8_r_to_iso_8859_5 KOI8 ISO_8859_5
koi8_r_to_mic KOI8 MULE_INTERNAL
koi8_r_to_utf8 KOI8 UTF8
koi8_r_to_windows_1251 KOI8 WIN1251

koi8_r_to_windows_866 KOI8 WIN866
mic_to_ascii MULE_INTERNAL SQL_ASCII
mic_to_big5 MULE_INTERNAL BIG5
mic_to_euc_cn MULE_INTERNAL EUC_CN
mic_to_euc_jp MULE_INTERNAL EUC_JP
mic_to_euc_kr MULE_INTERNAL EUC_KR
mic_to_euc_tw MULE_INTERNAL EUC_TW
mic_to_iso_8859_1 MULE_INTERNAL LATIN1
mic_to_iso_8859_5 MULE_INTERNAL ISO_8859_5
mic_to_koi8_r MULE_INTERNAL KOI8
mic_to_sjis MULE_INTERNAL SJIS
mic_to_windows_1250 MULE_INTERNAL WIN1250
sjis_to_euc_jp SJIS EUC_JP
sjis_to_mic SJIS MULE_INTERNAL
sjis_to_utf8 SJIS UTF8
tcvn_to_utf8 WIN1258 UTF8
uhc_to_utf8 UHC UTF8
utf8_to_ascii UTF8 SQL_ASCII
utf8_to_big5 UTF8 BIG5
utf8_to_euc_cn UTF8 EUC_CN
utf8_to_euc_jp UTF8 EUC_JP
utf8_to_euc_kr UTF8 EUC_KR
utf8_to_euc_tw UTF8 EUC_TW
utf8_to_gb18030 UTF8 GB18030
utf8_to_gbk UTF8 GBK
utf8_to_iso_8859_1 UTF8 LATIN1
utf8_to_iso_8859_5 UTF8 ISO_8859_5
utf8_to_johab UTF8 JOHAB
utf8_to_koi8_r UTF8 KOI8
utf8_to_sjis UTF8 SJIS
utf8_to_tcvn UTF8 WIN1258
utf8_to_uhc UTF8 UHC

utf8_to_windows_1250 UTF8 WIN1250
windows_1250_to_iso_8859_2 WIN1250 LATIN2
windows_1250_to_mic WIN1250 MULE_INTERNAL
windows_1250_to_utf8 WIN1250 UTF8
windows_1251_to_iso_8859_5 WIN1251 ISO_8859_5
windows_1251_to_koi8_r WIN1251 KOI8
windows_1251_to_windows_866 WIN1251 WIN866
windows_866_to_iso_8859_5 WIN866 ISO_8859_5
windows_866_to_koi8_r WIN866 KOI8
windows_866_to_windows_1251 WIN866 WIN
Notas:
a. The conversion names follow a standard naming scheme: The official name of the source encoding
with all non-alphanumeric characters replaced by underscores followed by _to_ followed by the equally
processed destination encoding name. Therefore the names might deviate from the customary
encoding names.

Mathematical Functions and Acima Binary String Functions and
Operators Operators
Binary String Functions and Operators


This section describes functions and operators for examining and manipulating values of type bytea.
SQL defines some string functions with a special syntax where certain key words rather than
commas are used to separate the arguments. Details are in Tabela 9-8. Some functions are also
implemented using the regular syntax for function invocation. (See Tabela 9-9.)
Tabela 9-8. SQL Binary String Functions and Operators
Return
Type
string || string bytea String concatenation '\\\\Post'::bytea || \\Post'gres\000
'\\047gres\\000'::bytea
get_bit(string, int Extract bit from string get_bit('Th\\000omas'::bytea, 1
offset) 45)
get_byte(string, int Extract byte from string get_byte('Th\\000omas'::bytea, 109
offset) 4)
octet_length(string) int Number of bytes in octet_length( 5
binary string 'jo\\000se'::bytea)
position(substring int Location of specified position('\\000om'::bytea in 3
in string) substring 'Th\\000omas'::bytea)
set_bit(string, bytea Set bit in string set_bit('Th\\000omas'::bytea, Th\000omAs
offset, newvalue) 45, 0)
set_byte(string, bytea Set byte in string set_byte('Th\\000omas'::bytea, Th\000o@as
offset, newvalue) 4, 64)
substring(string bytea Extract substring substring('Th\\000omas'::bytea h\000o
[from int] [for int]) from 2 for 3)
trim([both] bytes bytea Remove the longest trim('\\000'::bytea from Tom
from string) string containing only '\\000Tom\\000'::bytea)
the bytes in bytes from
the start and end of
string
Additional binary string manipulation functions are available and are listed in Tabela 9-9. Some of
them are used internally to implement the SQL-standard string functions listed in Tabela 9-8.
Tabela 9-9. Other Binary String Functions
Return
Type
btrim(string bytea Remove the longest string btrim('\\000trim\\000'::bytea, trim
bytea, bytes consisting only of bytes in '\\000'::bytea)
bytea) bytes from the start and
end of string
decode(string bytea Decode binary string from decode('123\\000456', 123\000456
text, type string previously encoded 'escape')
text) with encode. Parameter
type is same as in encode.
http://pgdocptbr.sourceforge.net/pg82/functions-binarystring.html[09/02/2018 18:06:24]
Binary String Functions and Operators
encode(string text Encode binary string to encode('123\\000456'::bytea, 123\000456

bytea, type ASCII-only representation. 'escape')
text) Supported types are:
base64, hex, escape.
length(string) int Length of binary string length('jo\\000se'::bytea) 5
md5(string) text Calculates the MD5 hash of md5('Th\\000omas'::bytea) 8ab2d3c9689aaf18
string, returning the result b4958c334c82d8b1
in hexadecimal

String Functions and Operators Acima Bit String Functions and Operators
http://pgdocptbr.sourceforge.net/pg82/functions-binarystring.html[09/02/2018 18:06:24]
Bit String Functions and Operators


This section describes functions and operators for examining and manipulating bit strings, that is
values of the types bit and bit varying. Aside from the usual comparison operators, the operators
shown in Tabela 9-10 can be used. Bit string operands of &, |, and # must be of equal length. When
bit shifting, the original length of the string is preserved, as shown in the examples.
Tabela 9-10. Bit String Operators

|| concatenation B'10001' || B'011' 10001011
& bitwise AND B'10001' & B'01101' 00001
| bitwise OR B'10001' | B'01101' 11101
# bitwise XOR B'10001' # B'01101' 11100
~ bitwise NOT ~ B'10001' 01110
<< bitwise shift left B'10001' << 3 01000
>> bitwise shift right B'10001' >> 2 00100
The following SQL-standard functions work on bit strings as well as character strings: length,
bit_length, octet_length, position, substring.
In addition, it is possible to cast integral values to and from type bit. Some examples:
44::bit(10) 0000101100
44::bit(3) 100
cast(-44 as bit(12)) 111111010100
'1110'::bit(4)::integer 14
Note that casting to just "bit" means casting to bit(1), and so it will deliver only the least significant
bit of the integer.
Nota: Prior to PostgreSQL 8.0, casting an integer to bit(n) would copy the leftmost n
bits of the integer, whereas now it copies the rightmost n bits. Also, casting an integer
to a bit string width wider than the integer itself will sign-extend on the left.

Binary String Functions and Acima Pattern Matching
Operators
http://pgdocptbr.sourceforge.net/pg82/functions-bitstring.html[09/02/2018 18:06:32]
Pattern Matching


There are three separate approaches to pattern matching provided by PostgreSQL: the traditional
SQL LIKE operator, the more recent SIMILAR TO operator (added in SQL:1999), and POSIX-style
regular expressions. Additionally, a pattern matching function, substring, is available, using either
SIMILAR TO-style or POSIX-style regular expressions.
Dica: If you have pattern matching needs that go beyond this, consider writing a user-
defined function in Perl or Tcl.
9.7.1. LIKE
cadeia_de_caracteres LIKE padrão [ESCAPE caractere_de_escape]

cadeia_de_caracteres NOT LIKE padrão [ESCAPE caractere_de_escape]
Every padrão defines a set of strings. The LIKE expression returns true if the cadeia_de_caracteres
is contained in the set of strings represented by padrão. (As expected, the NOT LIKE expression
returns false if LIKE returns true, and vice versa. An equivalent expression is NOT
(cadeia_de_caracteres LIKE padrão).)
If padrão does not contain percent signs or underscore, then the pattern only represents the string
itself; in that case LIKE acts like the equals operator. An underscore (_) in padrão stands for
(matches) any single character; a percent sign (%) matches any string of zero or more characters.
Some examples:
'abc' LIKE 'abc' true

'abc' LIKE 'a%' true
'abc' LIKE '_b_' true
'abc' LIKE 'c' false
LIKE pattern matches always cover the entire string. To match a sequence anywhere within a
string, the pattern must therefore start and end with a percent sign.
To match a literal underscore or percent sign without matching other characters, the respective
character in padrão must be preceded by the escape character. The default escape character is the
backslash but a different one may be selected by using the ESCAPE clause. To match the escape
character itself, write two escape characters.
Note that the backslash already has a special meaning in string literals, so to write a pattern
constant that contains a backslash you must write two backslashes in an SQL statement. Thus,
writing a pattern that actually matches a literal backslash means writing four backslashes in the
statement. You can avoid this by selecting a different escape character with ESCAPE; then a
backslash is not special to LIKE anymore. (But it is still special to the string literal parser, so you
still need two of them.)
It's also possible to select no escape character by writing ESCAPE ''. This effectively disables the
escape mechanism, which makes it impossible to turn off the special meaning of underscore and
percent signs in the pattern.
The key word ILIKE can be used instead of LIKE to make the match case-insensitive according to
the active locale. This is not in the SQL standard but is a PostgreSQL extension.
http://pgdocptbr.sourceforge.net/pg82/functions-matching.html[09/02/2018 18:06:49]
Pattern Matching
The operator ~~ is equivalent to LIKE, and ~~* corresponds to ILIKE. There are also !~~ and
!~~* operators that represent NOT LIKE and NOT ILIKE, respectively. All of these operators are
PostgreSQL-specific.
9.7.2. SIMILAR TO Regular Expressions
cadeia_de_caracteres SIMILAR TO padrão [ESCAPE caractere_de_escape]

cadeia_de_caracteres NOT SIMILAR TO padrão [ESCAPE caractere_de_escape]
The SIMILAR TO operator returns true or false depending on whether its pattern matches the given
string. It is much like LIKE, except that it interprets the pattern using the SQL standard's definition
of a regular expression. SQL regular expressions are a curious cross between LIKE notation and
common regular expression notation.
Like LIKE, the SIMILAR TO operator succeeds only if its pattern matches the entire string; this is
unlike common regular expression practice, wherein the pattern may match any part of the string.
Also like LIKE, SIMILAR TO uses _ and % as wildcard characters denoting any single character and
any string, respectively (these are comparable to . and .* in POSIX regular expressions).
In addition to these facilities borrowed from LIKE, SIMILAR TO supports these pattern-matching
metacharacters borrowed from POSIX regular expressions:
| denotes alternation (either of two alternatives).
* denotes repetition of the previous item zero or more times.
+ denotes repetition of the previous item one or more times.
Parentheses () may be used to group items into a single logical item.
A bracket expression [...] specifies a character class, just as in POSIX regular expressions.
Notice that bounded repetition (? and {...}) are not provided, though they exist in POSIX. Also, the
dot (.) is not a metacharacter.
As with LIKE, a backslash disables the special meaning of any of these metacharacters; or a
different escape character can be specified with ESCAPE.
Some examples:
'abc' SIMILAR TO 'abc' true

'abc' SIMILAR TO 'a' false
'abc' SIMILAR TO '%(b|d)%' true
'abc' SIMILAR TO '(b|c)%' false
The substring function with three parameters, substring(cadeia_de_caracteres from padrão for
caractere_de_escape), provides extraction of a substring that matches an SQL regular expression
pattern. As with SIMILAR TO, the specified pattern must match to the entire data string, else the
function fails and returns null. To indicate the part of the pattern that should be returned on
success, the pattern must contain two occurrences of the escape character followed by a double
quote ("). The text matching the portion of the pattern between these markers is returned.
Some examples:
substring('foobar' from '%#"o_b#"%' for '#') oob

substring('foobar' from '#"o_b#"%' for '#') NULL
9.7.3. POSIX Regular Expressions
Tabela 9-11 lists the available operators for pattern matching using POSIX regular expressions.
Pattern Matching
Tabela 9-11. Regular Expression Match Operators
Operator Description Example

~ Matches regular expression, case sensitive 'thomas' ~ '.*thomas.*'
~* Matches regular expression, case insensitive 'thomas' ~* '.*Thomas.*'
!~ Does not match regular expression, case sensitive 'thomas' !~ '.*Thomas.*'
!~* Does not match regular expression, case insensitive 'thomas' !~* '.*vadim.*'
POSIX regular expressions provide a more powerful means for pattern matching than the LIKE and
SIMILAR TO operators. Many Unix tools such as egrep, sed, or awk use a pattern matching
language that is similar to the one described here.
A regular expression is a character sequence that is an abbreviated definition of a set of strings (a

regular set). A string is said to match a regular expression if it is a member of the regular set
described by the regular expression. As with LIKE, pattern characters match string characters
exactly unless they are special characters in the regular expression language — but regular
expressions use different special characters than LIKE does. Unlike LIKE patterns, a regular
expression is allowed to match anywhere within a string, unless the regular expression is explicitly
anchored to the beginning or end of the string.
Some examples:
'abc' ~ 'abc' true

'abc' ~ '^a' true
'abc' ~ '(b|d)' true
'abc' ~ '^(b|c)' false
The substring function with two parameters, substring(cadeia_de_caracteres from padrão), provides
extraction of a substring that matches a POSIX regular expression pattern. It returns null if there is
no match, otherwise the portion of the text that matched the pattern. But if the pattern contains
any parentheses, the portion of the text that matched the first parenthesized subexpression (the
one whose left parenthesis comes first) is returned. You can put parentheses around the whole
expression if you want to use parentheses within it without triggering this exception. If you need
parentheses in the pattern before the subexpression you want to extract, see the non-capturing
parentheses described below.
Some examples:
substring('foobar' from 'o.b') oob

substring('foobar' from 'o(.)b') o
The regexp_replace function provides substitution of new text for substrings that match POSIX
regular expression patterns. It has the syntax regexp_replace(origem, padrão, substituição [,
sinalizadores ]). The origem string is returned unchanged if there is no match to the padrão. If
there is a match, the origem string is returned with the substituição string substituted for the
matching substring. The substituição string can contain \n, where n is 1 through 9, to indicate that
the source substring matching the n'th parenthesized subexpression of the pattern should be
inserted, and it can contain \& to indicate that the substring matching the entire pattern should be
inserted. Write \\ if you need to put a literal backslash in the replacement text. (As always,
remember to double backslashes written in literal constant strings.) The sinalizadores parameter is
an optional text string containing zero or more single-letter flags that change the function's
behavior. Flag i specifies case-insensitive matching, while flag g specifies replacement of each
matching substring rather than only the first one.
Some examples:
regexp_replace('foobarbaz', 'b..', 'X')

fooXbaz
regexp_replace('foobarbaz', 'b..', 'X', 'g')
fooXX
regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
fooXarYXazY
Pattern Matching
PostgreSQL's regular expressions are implemented using a package written by Henry Spencer.
Much of the description of regular expressions below is copied verbatim from his manual entry.
9.7.3.1. Regular Expression Details
Regular expressions (REs), as defined in POSIX 1003.2, come in two forms: extended REs or EREs
(roughly those of egrep), and basic REs or BREs (roughly those of ed). PostgreSQL supports both
forms, and also implements some extensions that are not in the POSIX standard, but have become
widely used anyway due to their availability in programming languages such as Perl and Tcl. REs
using these non-POSIX extensions are called advanced REs or AREs in this documentation. AREs are
almost an exact superset of EREs, but BREs have several notational incompatibilities (as well as
being much more limited). We first describe the ARE and ERE forms, noting features that apply only
to AREs, and then describe how BREs differ.
Nota: The form of regular expressions accepted by PostgreSQL can be chosen by setting
the regex_flavor run-time parameter. The usual setting is advanced, but one might
choose extended for maximum backwards compatibility with pre-7.4 releases of
PostgreSQL.
A regular expression is defined as one or more branches, separated by |. It matches anything that
matches one of the branches.
A branch is zero or more quantified atoms or constraints, concatenated. It matches a match for the
first, followed by a match for the second, etc; an empty branch matches the empty string.
A quantified atom is an atom possibly followed by a single quantifier. Without a quantifier, it

matches a match for the atom. With a quantifier, it can match some number of matches of the
atom. An atom can be any of the possibilities shown in Tabela 9-12. The possible quantifiers and
their meanings are shown in Tabela 9-13.
A constraint matches an empty string, but matches only when specific conditions are met. A
constraint can be used where an atom could be used, except it may not be followed by a quantifier.
The simple constraints are shown in Tabela 9-14; some more constraints are described later.
Tabela 9-12. Regular Expression Atoms
Atom Description
(er) (where er is any regular expression) matches a match for er, with the match noted for
possible reporting
(?:er) as above, but the match is not noted for reporting (a "non-capturing" set of parentheses)
(AREs only)
. matches any single character
[caracteres] a bracket expression, matching any one of the caracteres (see Seção 9.7.3.2 for more
detail)
\k (where k is a non-alphanumeric character) matches that character taken as an ordinary
character, e.g. \\ matches a backslash character
\c where c is alphanumeric (possibly followed by other characters) is an escape, see Seção
9.7.3.3 (AREs only; in EREs and BREs, this matches c)
{ when followed by a character other than a digit, matches the left-brace character {;
when followed by a digit, it is the beginning of a limite (see below)
x where x is a single character with no other significance, matches that character
An RE may not end with \.
Nota: Remember that the backslash (\) already has a special meaning in PostgreSQL
string literals. To write a pattern constant that contains a backslash, you must write two
backslashes in the statement.
Tabela 9-13. Regular Expression Quantifiers
Pattern Matching
Quantifier Matches
* a sequence of 0 or more matches of the atom
+ a sequence of 1 or more matches of the atom
? a sequence of 0 or 1 matches of the atom
{m} a sequence of exactly m matches of the atom
{m,} a sequence of m or more matches of the atom
{m,n} a sequence of m through n (inclusive) matches of the atom; m may not exceed n
*? non-greedy version of *
+? non-greedy version of +
?? non-greedy version of ?
{m}? non-greedy version of {m}
{m,}? non-greedy version of {m,}
{m,n}? non-greedy version of {m,n}
The forms using {...} are known as bounds. The numbers m and n within a bound are unsigned
decimal integers with permissible values from 0 to 255 inclusive.
Non-greedy quantifiers (available in AREs only) match the same possibilities as their corresponding
normal (greedy) counterparts, but prefer the smallest number rather than the largest number of
matches. See Seção 9.7.3.5 for more detail.
Nota: A quantifier cannot immediately follow another quantifier. A quantifier cannot

begin an expression or subexpression or follow ^ or |.
Tabela 9-14. Regular Expression Constraints
Constraint Description
^ matches at the beginning of the string
$ matches at the end of the string
(?=er) positive lookahead matches at any point where a substring matching er begins (AREs
only)
(?!er) negative lookahead matches at any point where no substring matching er begins (AREs
only)
Lookahead constraints may not contain back references (see Seção 9.7.3.3), and all parentheses
within them are considered non-capturing.
9.7.3.2. Bracket Expressions
A bracket expression is a list of characters enclosed in []. It normally matches any single character
from the list (but see below). If the list begins with ^, it matches any single character not from the
rest of the list. If two characters in the list are separated by -, this is shorthand for the full range of
characters between those two (inclusive) in the collating sequence, e.g. [0-9] in ASCII matches any
decimal digit. It is illegal for two ranges to share an endpoint, e.g. a-c-e. Ranges are very collating-
sequence-dependent, so portable programs should avoid relying on them.
To include a literal ] in the list, make it the first character (following a possible ^). To include a
literal -, make it the first or last character, or the second endpoint of a range. To use a literal - as
the first endpoint of a range, enclose it in [. and .] to make it a collating element (see below). With
the exception of these characters, some combinations using [ (see next paragraphs), and escapes
(AREs only), all other special characters lose their special significance within a bracket expression.
In particular, \ is not special when following ERE or BRE rules, though it is special (as introducing an
escape) in AREs.
Within a bracket expression, a collating element (a character, a multiple-character sequence that

collates as if it were a single character, or a collating-sequence name for either) enclosed in [. and
.] stands for the sequence of characters of that collating element. The sequence is a single element
Pattern Matching
of the bracket expression's list. A bracket expression containing a multiple-character collating

element can thus match more than one character, e.g. if the collating sequence includes a ch
collating element, then the RE [[.ch.]]*c matches the first five characters of chchcc.
Nota: PostgreSQL currently has no multicharacter collating elements. This information

describes possible future behavior.
Within a bracket expression, a collating element enclosed in [= and =] is an equivalence class,

standing for the sequences of characters of all collating elements equivalent to that one, including
itself. (If there are no other equivalent collating elements, the treatment is as if the enclosing
delimiters were [. and .].) For example, if o and ^ are the members of an equivalence class, then
[[=o=]], [[=^=]], and [o^] are all synonymous. An equivalence class may not be an endpoint of a
range.
Within a bracket expression, the name of a character class enclosed in [: and :] stands for the list
of all characters belonging to that class. Standard character class names are: alnum, alpha, blank,
cntrl, digit, graph, lower, print, punct, space, upper, xdigit. These stand for the character classes
defined in ctype. A locale may provide others. A character class may not be used as an endpoint of
a range.
There are two special cases of bracket expressions: the bracket expressions [[:<:]] and [[:>:]] are
constraints, matching empty strings at the beginning and end of a word respectively. A word is
defined as a sequence of word characters that is neither preceded nor followed by word characters.
A word character is an alnum character (as defined by ctype) or an underscore. This is an
extension, compatible with but not specified by POSIX 1003.2, and should be used with caution in
software intended to be portable to other systems. The constraint escapes described below are
usually preferable (they are no more standard, but are certainly easier to type).
9.7.3.3. Regular Expression Escapes
Escapes are special sequences beginning with \ followed by an alphanumeric character. Escapes
come in several varieties: character entry, class shorthands, constraint escapes, and back
references. A \ followed by an alphanumeric character but not constituting a valid escape is illegal
in AREs. In EREs, there are no escapes: outside a bracket expression, a \ followed by an
alphanumeric character merely stands for that character as an ordinary character, and inside a
bracket expression, \ is an ordinary character. (The latter is the one actual incompatibility between
EREs and AREs.)
Character-entry escapes exist to make it easier to specify non-printing and otherwise inconvenient
characters in REs. They are shown in Tabela 9-15.
Class-shorthand escapes provide shorthands for certain commonly-used character classes. They are
shown in Tabela 9-16.
A constraint escape is a constraint, matching the empty string if specific conditions are met, written
as an escape. They are shown in Tabela 9-17.
A back reference (\n) matches the same string matched by the previous parenthesized
subexpression specified by the number n (see Tabela 9-18). For example, ([bc])\1 matches bb or cc
but not bc or cb. The subexpression must entirely precede the back reference in the RE.
Subexpressions are numbered in the order of their leading parentheses. Non-capturing parentheses
do not define subexpressions.
Nota: Keep in mind that an escape's leading \ will need to be doubled when entering the
pattern as an SQL string constant. For example:
'123' ~ '^\\d{3}' true
Tabela 9-15. Regular Expression Character-Entry Escapes
Escape Description
Pattern Matching
\a alert (bell) character, as in C

\b backspace, as in C
\B synonym for \ to help reduce the need for backslash doubling
\cX (where X is any character) the character whose low-order 5 bits are the same as those of
X, and whose other bits are all zero
\e the character whose collating-sequence name is ESC, or failing that, the character with
octal value 033
\f form feed, as in C
\n newline, as in C
\r carriage return, as in C
\t horizontal tab, as in C
\uwxyz (where wxyz is exactly four hexadecimal digits) the UTF16 (Unicode, 16-bit) character
U+wxyz in the local byte ordering
\Ustuvwxyz (where stuvwxyz is exactly eight hexadecimal digits) reserved for a somewhat-
hypothetical Unicode extension to 32 bits
\v vertical tab, as in C
\xhhh (where hhh is any sequence of hexadecimal digits) the character whose hexadecimal
value is 0xhhh (a single character no matter how many hexadecimal digits are used)
\0 the character whose value is 0
\xy (where xy is exactly two octal digits, and is not a back reference) the character whose
octal value is 0xy
\xyz (where xyz is exactly three octal digits, and is not a back reference) the character whose
octal value is 0xyz
Hexadecimal digits are 0-9, a-f, and A-F. Octal digits are 0-7.
The character-entry escapes are always taken as ordinary characters. For example, \135 is ] in
ASCII, but \135 does not terminate a bracket expression.
Tabela 9-16. Regular Expression Class-Shorthand Escapes
Escape Description
\d [[:digit:]]
\s [[:space:]]
\w [[:alnum:]_] (note underscore is included)
\D [^[:digit:]]
\S [^[:space:]]
\W [^[:alnum:]_] (note underscore is included)
Within bracket expressions, \d, \s, and \w lose their outer brackets, and \D, \S, and \W are illegal.
(So, for example, [a-c\d] is equivalent to [a-c[:digit:]]. Also, [a-c\D], which is equivalent to [a-
c^[:digit:]], is illegal.)
Tabela 9-17. Regular Expression Constraint Escapes
Escape Description
\A matches only at the beginning of the string (see Seção 9.7.3.5 for how this differs from ^)
\m matches only at the beginning of a word
\M matches only at the end of a word
\y matches only at the beginning or end of a word
\Y matches only at a point that is not the beginning or end of a word
\Z matches only at the end of the string (see Seção 9.7.3.5 for how this differs from $)
A word is defined as in the specification of [[:<:]] and [[:>:]] above. Constraint escapes are illegal
Pattern Matching
within bracket expressions.
Tabela 9-18. Regular Expression Back References
Escape Description
\m (where m is a nonzero digit) a back reference to the m'th subexpression
\mnn (where m is a nonzero digit, and nn is some more digits, and the decimal value mnn is not
greater than the number of closing capturing parentheses seen so far) a back reference to
the mnn'th subexpression
Nota: There is an inherent historical ambiguity between octal character-entry escapes

and back references, which is resolved by heuristics, as hinted at above. A leading zero
always indicates an octal escape. A single non-zero digit, not followed by another digit,
is always taken as a back reference. A multidigit sequence not starting with a zero is
taken as a back reference if it comes after a suitable subexpression (i.e. the number is
in the legal range for a back reference), and otherwise is taken as octal.
9.7.3.4. Regular Expression Metasyntax
In addition to the main syntax described above, there are some special forms and miscellaneous
syntactic facilities available.
Normally the flavor of RE being used is determined by regex_flavor. However, this can be
overridden by a director prefix. If an RE begins with ***:, the rest of the RE is taken as an ARE
regardless of regex_flavor. If an RE begins with ***=, the rest of the RE is taken to be a literal
string, with all characters considered ordinary characters.
An ARE may begin with embedded options: a sequence (?xyz) (where xyz is one or more alphabetic
characters) specifies options affecting the rest of the RE. These options override any previously
determined options (including both the RE flavor and case sensitivity). The available option letters
are shown in Tabela 9-19.
Tabela 9-19. ARE Embedded-Option Letters
Option Description
b rest of RE is a BRE
c case-sensitive matching (overrides operator type)
e rest of RE is an ERE
i case-insensitive matching (see Seção 9.7.3.5) (overrides operator type)
m historical synonym for n
n newline-sensitive matching (see Seção 9.7.3.5)
p partial newline-sensitive matching (see Seção 9.7.3.5)
q rest of RE is a literal ("quoted") string, all ordinary characters
s non-newline-sensitive matching (default)
t tight syntax (default; see below)
w inverse partial newline-sensitive ("weird") matching (see Seção 9.7.3.5)
x expanded syntax (see below)
Embedded options take effect at the ) terminating the sequence. They may appear only at the start
of an ARE (after the ***: director if any).
In addition to the usual (tight) RE syntax, in which all characters are significant, there is an
expanded syntax, available by specifying the embedded x option. In the expanded syntax, white-
space characters in the RE are ignored, as are all characters between a # and the following newline
(or the end of the RE). This permits paragraphing and commenting a complex RE. There are three
exceptions to that basic rule:
a white-space character or # preceded by \ is retained
Pattern Matching
white space or # within a bracket expression is retained
white space and comments cannot appear within multicharacter symbols, such as (?:
For this purpose, white-space characters are blank, tab, newline, and any character that belongs to
the espaço character class.
Finally, in an ARE, outside bracket expressions, the sequence (?#ttt) (where ttt is any text not
containing a )) is a comment, completely ignored. Again, this is not allowed between the characters
of multicharacter symbols, like (?:. Such comments are more a historical artifact than a useful
facility, and their use is deprecated; use the expanded syntax instead.
None of these metasyntax extensions is available if an initial ***= director has specified that the
user's input be treated as a literal string rather than as an RE.
9.7.3.5. Regular Expression Matching Rules
In the event that an RE could match more than one substring of a given string, the RE matches the
one starting earliest in the string. If the RE could match more than one substring starting at that
point, either the longest possible match or the shortest possible match will be taken, depending on
whether the RE is greedy or non-greedy.
Whether an RE is greedy or not is determined by the following rules:
Most atoms, and all constraints, have no greediness attribute (because they cannot match
variable amounts of text anyway).
Adding parentheses around an RE does not change its greediness.
A quantified atom with a fixed-repetition quantifier ({m} or {m}?) has the same greediness
(possibly none) as the atom itself.
A quantified atom with other normal quantifiers (including {m,n} with m equal to n) is greedy
(prefers longest match).
A quantified atom with a non-greedy quantifier (including {m,n}? with m equal to n) is non-
greedy (prefers shortest match).
A branch — that is, an RE that has no top-level | operator — has the same greediness as the
first quantified atom in it that has a greediness attribute.
An RE consisting of two or more branches connected by the | operator is always greedy.
The above rules associate greediness attributes not only with individual quantified atoms, but with
branches and entire REs that contain quantified atoms. What that means is that the matching is
done in such a way that the branch, or whole RE, matches the longest or shortest possible substring
as a whole. Once the length of the entire match is determined, the part of it that matches any
particular subexpression is determined on the basis of the greediness attribute of that
subexpression, with subexpressions starting earlier in the RE taking priority over ones starting later.
An example of what this means:
SELECT SUBSTRING('XY1234Z', 'Y*([0-9]{1,3})');

Result: 123
SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
Result: 1
In the first case, the RE as a whole is greedy because Y* is greedy. It can match beginning at the Y,
and it matches the longest possible string starting there, i.e., Y123. The output is the parenthesized
part of that, or 123. In the second case, the RE as a whole is non-greedy because Y*? is non-
greedy. It can match beginning at the Y, and it matches the shortest possible string starting there,
i.e., Y1. The subexpression [0-9]{1,3} is greedy but it cannot change the decision as to the overall
match length; so it is forced to match just 1.
Pattern Matching
In short, when an RE contains both greedy and non-greedy subexpressions, the total match length
is either as long as possible or as short as possible, according to the attribute assigned to the whole
RE. The attributes assigned to the subexpressions only affect how much of that match they are
allowed to "eat" relative to each other.
The quantifiers {1,1} and {1,1}? can be used to force greediness or non-greediness, respectively,
on a subexpression or a whole RE.
Match lengths are measured in characters, not collating elements. An empty string is considered
longer than no match at all. For example: bb* matches the three middle characters of abbbc;
(week|wee)(night|knights) matches all ten characters of weeknights; when (.*).* is matched
against abc the parenthesized subexpression matches all three characters; and when (a*)* is
matched against bc both the whole RE and the parenthesized subexpression match an empty string.
If case-independent matching is specified, the effect is much as if all case distinctions had vanished
from the alphabet. When an alphabetic that exists in multiple cases appears as an ordinary
character outside a bracket expression, it is effectively transformed into a bracket expression
containing both cases, e.g. x becomes [xX]. When it appears inside a bracket expression, all case
counterparts of it are added to the bracket expression, e.g. [x] becomes [xX] and [^x] becomes
[^xX].
If newline-sensitive matching is specified, . and bracket expressions using ^ will never match the
newline character (so that matches will never cross newlines unless the RE explicitly arranges it)
and ^and $ will match the empty string after and before a newline respectively, in addition to
matching at beginning and end of string respectively. But the ARE escapes \A and \Z continue to
match beginning or end of string only.
If partial newline-sensitive matching is specified, this affects . and bracket expressions as with
newline-sensitive matching, but not ^ and $.
If inverse partial newline-sensitive matching is specified, this affects ^ and $ as with newline-
sensitive matching, but not . and bracket expressions. This isn't very useful but is provided for
symmetry.
9.7.3.6. Limits and Compatibility
No particular limit is imposed on the length of REs in this implementation. However, programs
intended to be highly portable should not employ REs longer than 256 bytes, as a POSIX-compliant
implementation can refuse to accept such REs.
The only feature of AREs that is actually incompatible with POSIX EREs is that \ does not lose its
special significance inside bracket expressions. All other ARE features use syntax which is illegal or
has undefined or unspecified effects in POSIX EREs; the *** syntax of directors likewise is outside
the POSIX syntax for both BREs and EREs.
Many of the ARE extensions are borrowed from Perl, but some have been changed to clean them
up, and a few Perl extensions are not present. Incompatibilities of note include \b, \B, the lack of
special treatment for a trailing newline, the addition of complemented bracket expressions to the
things affected by newline-sensitive matching, the restrictions on parentheses and back references
in lookahead constraints, and the longest/shortest-match (rather than first-match) matching
semantics.
Two significant incompatibilities exist between AREs and the ERE syntax recognized by pre-7.4
releases of PostgreSQL:
In AREs, \ followed by an alphanumeric character is either an escape or an error, while in

previous releases, it was just another way of writing the alphanumeric. This should not be
much of a problem because there was no reason to write such a sequence in earlier releases.
In AREs, \ remains a special character within [], so a literal \ within a bracket expression must
be written \\.
While these differences are unlikely to create a problem for most applications, you can avoid them if
Pattern Matching
necessary by setting regex_flavor to extended.
9.7.3.7. Basic Regular Expressions
BREs differ from EREs in several respects. |, +, and ? are ordinary characters and there is no
equivalent for their functionality. The delimiters for bounds are \{ and \}, with { and } by
themselves ordinary characters. The parentheses for nested subexpressions are $ and $, with (
and ) by themselves ordinary characters. ^ is an ordinary character except at the beginning of the
RE or the beginning of a parenthesized subexpression, $ is an ordinary character except at the end
of the RE or the end of a parenthesized subexpression, and * is an ordinary character if it appears
at the beginning of the RE or the beginning of a parenthesized subexpression (after a possible
leading ^). Finally, single-digit back references are available, and \< and \> are synonyms for [[:
<:]] and [[:>:]] respectively; no other escapes are available.

Bit String Functions and Operators Acima Data Type Formatting Functions
Data Type Formatting Functions


The PostgreSQL formatting functions provide a powerful set of tools for converting various data
types (date/time, integer, floating point, numeric) to formatted strings and for converting from
formatted strings to specific data types. Tabela 9-20 lists them. These functions all follow a common
calling convention: the first argument is the value to be formatted and the second argument is a
template that defines the output or input format.
The to_timestamp function can also take a single double precision argument to convert from Unix
epoch to timestamp with time zone. (Integer Unix epochs are implicitly cast to double precision.)
Tabela 9-20. Formatting Functions
Function Return Type Description Example

to_char(timestamp, text convert time stamp to to_char(current_timestamp,
text) string 'HH12:MI:SS')
to_char(interval, text) text convert interval to string to_char(interval '15h 2m 12s',
'HH24:MI:SS')
to_char(int, text) text convert integer to string to_char(125, '999')
to_char(double text convert real/double to_char(125.8::real, '999D9')
precision, text) precision to string
to_char(numeric, text convert numeric to string to_char(-125.8, '999D99S')
text)
to_date(text, text) date convert string to date to_date('05 Dec 2000',
'DD Mon YYYY')
to_number(text, text) numeric convert string to numeric to_number('12,454.8-',
'99G999D9S')
to_timestamp(text, timestamp with convert string to time to_timestamp('05 Dec 2000',
text) time zone stamp 'DD Mon YYYY')
to_timestamp(double timestamp with convert UNIX epoch to to_timestamp(200120400)
precision) time zone time stamp
In an output template string (for to_char), there are certain patterns that are recognized and
replaced with appropriately-formatted data from the value to be formatted. Any text that is not a
template pattern is simply copied verbatim. Similarly, in an input template string (for anything but
to_char), template patterns identify the parts of the input data string to be looked at and the values
to be found there.
Tabela 9-21 shows the template patterns available for formatting date and time values.
Tabela 9-21. Template Patterns for Date/Time Formatting
Pattern Description
HH hour of day (01-12)
HH12 hour of day (01-12)
HH24 hour of day (00-23)
MI minute (00-59)
SS second (00-59)
http://pgdocptbr.sourceforge.net/pg82/functions-formatting.html[09/02/2018 18:07:05]
MS millisecond (000-999)
US microsecond (000000-999999)
SSSS seconds past midnight (0-86399)
AM or A.M. or PM or meridian indicator (uppercase)
P.M.
am or a.m. or pm or meridian indicator (lowercase)
p.m.
Y,YYY year (4 and more digits) with comma
YYYY year (4 and more digits)
YYY last 3 digits of year
YY last 2 digits of year
Y last digit of year
IYYY ISO year (4 and more digits)
IYY last 3 digits of ISO year
IY last 2 digits of ISO year
I last digits of ISO year
BC or B.C. or AD or A.D. era indicator (uppercase)
bc or b.c. or ad or a.d. era indicator (lowercase)
MONTH full uppercase month name (blank-padded to 9 chars)
Month full mixed-case month name (blank-padded to 9 chars)
month full lowercase month name (blank-padded to 9 chars)
MON abbreviated uppercase month name (3 chars in English, localized lengths
vary)
Mon abbreviated mixed-case month name (3 chars in English, localized lengths
vary)
mon abbreviated lowercase month name (3 chars in English, localized lengths
vary)
MM month number (01-12)
DAY full uppercase day name (blank-padded to 9 chars)
Day full mixed-case day name (blank-padded to 9 chars)
day full lowercase day name (blank-padded to 9 chars)
DY abbreviated uppercase day name (3 chars in English, localized lengths vary)
Dy abbreviated mixed-case day name (3 chars in English, localized lengths
vary)
dy abbreviated lowercase day name (3 chars in English, localized lengths vary)
DDD day of year (001-366)
DD day of month (01-31)
D day of week (1-7; Sunday is 1)
W week of month (1-5) (The first week starts on the first day of the month.)
WW week number of year (1-53) (The first week starts on the first day of the
year.)
IW ISO week number of year (The first Thursday of the new year is in week 1.)
CC century (2 digits)
J Julian Day (days since January 1, 4712 BC)
Q quarter
RM month in Roman numerals (I-XII; I=January) (uppercase)
rm month in Roman numerals (i-xii; i=January) (lowercase)
TZ time-zone name (uppercase)
tz time-zone name (lowercase)
Certain modifiers may be applied to any template pattern to alter its behavior. For example,
FMMonth is the Month pattern with the FM modifier. Tabela 9-22 shows the modifier patterns for
date/time formatting.
Tabela 9-22. Template Pattern Modifiers for Date/Time Formatting
Modifier Description Example

FM prefix fill mode (suppress padding blanks and zeroes) FMMonth
TH suffix uppercase ordinal number suffix DDTH
th suffix lowercase ordinal number suffix DDth
FX prefix fixed format global option (see usage notes) FX Month DD Day
TM prefix translation mode (print localized day and month names based on TMMonth
lc_messages)
SP suffix spell mode (not yet implemented) DDSP
Usage notes for date/time formatting:
FM suppresses leading zeroes and trailing blanks that would otherwise be added to make the
output of a pattern be fixed-width.
TM does not include trailing blanks.
to_timestamp and to_date skip multiple blank spaces in the input string if the FX option is not
used. FX must be specified as the first item in the template. For example
to_timestamp('2000 JUN', 'YYYY MON') is correct, but to_timestamp('2000 JUN', 'FXYYYY
MON') returns an error, because to_timestamp expects one space only.
Ordinary text is allowed in to_char templates and will be output literally. You can put a
substring in double quotes to force it to be interpreted as literal text even if it contains pattern
key words. For example, in '"Hello Year "YYYY', the YYYY will be replaced by the year data, but
the single Y in Year will not be.
If you want to have a double quote in the output you must precede it with a backslash, for
example '\\"YYYY Month\\"'. (Two backslashes are necessary because the backslash already
has a special meaning in a string constant.)
The YYYY conversion from string to timestamp or date has a restriction if you use a year with
more than 4 digits. You must use some non-digit character or template after YYYY, otherwise
the year is always interpreted as 4 digits. For example (with the year 20000):
to_date('200001131', 'YYYYMMDD') will be interpreted as a 4-digit year; instead use a non-
digit separator after the year, like to_date('20000-1131', 'YYYY-MMDD') or
to_date('20000Nov31', 'YYYYMonDD').
In conversions from string to timestamp or date, the CC field is ignored if there is a YYY, YYYY
or Y,YYY field. If CC is used with YY or Y then the year is computed as (CC-1)*100+YY.
Millisecond (MS) and microsecond (US) values in a conversion from string to timestamp are
used as part of the seconds after the decimal point. For example to_timestamp('12:3',
'SS:MS') is not 3 milliseconds, but 300, because the conversion counts it as 12 + 0.3 seconds.
This means for the format SS:MS, the input values 12:3, 12:30, and 12:300 specify the same
number of milliseconds. To get three milliseconds, one must use 12:003, which the conversion
counts as 12 + 0.003 = 12.003 seconds.
Here is a more complex example: to_timestamp('15:12:02.020.001230', 'HH:MI:SS.MS.US')

is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds + 1230 microseconds = 2.021230
seconds.
to_char's day of the week numbering (see the 'D' formatting pattern) is different from that of
the extract function.
to_char(interval) formats HH and HH12 as hours in a single day, while HH24 can output hours
exceeding a single day, e.g. >24.
Tabela 9-23 shows the template patterns available for formatting numeric values.
Tabela 9-23. Template Patterns for Numeric Formatting
Pattern Description
9 value with the specified number of digits
0 value with leading zeros
. (period) decimal point
, (comma) group (thousand) separator
PR negative value in angle brackets
S sign anchored to number (uses locale)
L currency symbol (uses locale)
D decimal point (uses locale)
G group separator (uses locale)
MI minus sign in specified position (if number < 0)
PL plus sign in specified position (if number > 0)
SG plus/minus sign in specified position
RN roman numeral (input between 1 and 3999)
TH or th ordinal number suffix
V shift specified number of digits (see notes)
EEEE scientific notation (not implemented yet)
Usage notes for numeric formatting:
A sign formatted using SG, PL, or MI is not anchored to the number; for example,
to_char(-12, 'S9999') produces ' -12', but to_char(-12, 'MI9999') produces '- 12'. The Oracle
implementation does not allow the use of MI ahead of 9, but rather requires that 9 precede
MI.
9 results in a value with the same number of digits as there are 9s. If a digit is not available it
outputs a space.
TH does not convert values less than zero and does not convert fractional numbers.
PL, SG, and TH are PostgreSQL extensions.
V effectively multiplies the input values by 10^n, where n is the number of digits following V.
to_char does not support the use of V combined with a decimal point. (E.g., 99.9V99 is not
allowed.)
Tabela 9-24 shows some examples of the use of the to_char function.
Tabela 9-24. to_char Examples
Expression Result
to_char(current_timestamp, 'Day, DD HH12:MI:SS') 'Tuesday , 06 05:39:18'
to_char(current_timestamp, 'FMDay, FMDD HH12:MI:SS') 'Tuesday, 6 05:39:18'
to_char(-0.1, '99.99') ' -.10'
to_char(-0.1, 'FM9.99') '-.1'
to_char(0.1, '0.9') ' 0.1'
to_char(12, '9990999.9') ' 0012.0'
to_char(12, 'FM9990999.9') '0012.'
to_char(485, '999') ' 485'
to_char(-485, '999') '-485'
to_char(485, '9 9 9') ' 4 8 5'
to_char(1485, '9,999') ' 1,485'

to_char(1485, '9G999') ' 1 485'
to_char(148.5, '999.999') ' 148.500'
to_char(148.5, 'FM999.999') '148.5'
to_char(148.5, 'FM999.990') '148.500'
to_char(148.5, '999D999') ' 148,500'
to_char(3148.5, '9G999D999') ' 3 148,500'
to_char(-485, '999S') '485-'
to_char(-485, '999MI') '485-'
to_char(485, '999MI') '485 '
to_char(485, 'FM999MI') '485'
to_char(485, 'PL999') '+485'
to_char(485, 'SG999') '+485'
to_char(-485, 'SG999') '-485'
to_char(-485, '9SG99') '4-85'
to_char(-485, '999PR') '<485>'
to_char(485, 'L999') 'DM 485
to_char(485, 'RN') ' CDLXXXV'
to_char(485, 'FMRN') 'CDLXXXV'
to_char(5.2, 'FMRN') 'V'
to_char(482, '999th') ' 482nd'
to_char(485, '"Good number:"999') 'Good number: 485'
to_char(485.8, '"Pre:"999" Post:" .999') 'Pre: 485 Post: .800'
to_char(12, '99V999') ' 12000'
to_char(12.4, '99V999') ' 12400'
to_char(12.45, '99V9') ' 125'

Pattern Matching Acima Date/Time Functions and Operators
Date/Time Functions and Operators


Tabela 9-26 shows the available functions for date/time value processing, with details appearing in
the following subsections. Tabela 9-25 illustrates the behaviors of the basic arithmetic operators (+,
*, etc.). For formatting functions, refer to Seção 9.8. You should be familiar with the background
information on date/time data types from Seção 8.5.
All the functions and operators described below that take time or timestamp inputs actually come in
two variants: one that takes time with time zone or timestamp with time zone, and one that takes
time without time zone or timestamp without time zone. For brevity, these variants are not shown
separately. Also, the + and * operators come in commutative pairs (for example both date +
integer and integer + date); we show only one of each such pair.
Tabela 9-25. Date/Time Operators
Operator Example Result

+ date '2001-09-28' + integer '7' date '2001-10-05'
+ date '2001-09-28' + interval '1 hour' timestamp '2001-09-28
01:00:00'
+ date '2001-09-28' + time '03:00' timestamp '2001-09-28
03:00:00'
+ interval '1 day' + interval '1 hour' interval '1 day 01:00:00'
+ timestamp '2001-09-28 01:00' + interval '23 hours' timestamp '2001-09-29
00:00:00'
+ time '01:00' + interval '3 hours' time '04:00:00'
- - interval '23 hours' interval '-23:00:00'
- date '2001-10-01' - date '2001-09-28' integer '3'
- date '2001-10-01' - integer '7' date '2001-09-24'
- date '2001-09-28' - interval '1 hour' timestamp '2001-09-27
23:00:00'
- time '05:00' - time '03:00' interval '02:00:00'
- time '05:00' - interval '2 hours' time '03:00:00'
- timestamp '2001-09-28 23:00' - interval '23 hours' timestamp '2001-09-28
00:00:00'
- interval '1 day' - interval '1 hour' interval '1 day -01:00:00'
- timestamp '2001-09-29 03:00' - timestamp '2001-09-27 interval '1 day 15:00:00'
12:00'
* 900 * interval '1 second' interval '00:15:00'
* 21 * interval '1 day' interval '21 days'
* double precision '3.5' * interval '1 hour' interval '03:30:00'
/ interval '1 hour' / double precision '1.5' interval '00:40:00'
Tabela 9-26. Date/Time Functions
Return
Type
http://pgdocptbr.sourceforge.net/pg82/functions-datetime.html[09/02/2018 18:07:23]
age(timestamp, interval Subtract arguments, producing age(timestamp '2001- 43 years

timestamp) a "symbolic" result that uses 04-10', timestamp 9 mons
years and months '1957-06-13') 27 days
age(timestamp) interval Subtract from current_date age(timestamp '1957- 43 years
06-13') 8 mons 3
days
clock_timestamp() timestamp Current date and time
with time (changes during statement
zone execution); see Seção 9.9.4
current_date date Current date; see Seção 9.9.4
current_time time with Current time of day; see Seção
time zone 9.9.4
current_timestamp timestamp Current date and time (start of
with time current transaction); see Seção
zone 9.9.4
date_part(text, double Get subfield (equivalent to date_part('hour', 20
timestamp) precision extract); see Seção 9.9.1 timestamp '2001-02-
16 20:38:40')
date_part(text, interval) double Get subfield (equivalent to date_part('month', 3
precision extract); see Seção 9.9.1 interval '2 years 3
months')
date_trunc(text, timestamp Truncate to specified precision; date_trunc('hour', 2001-02-
timestamp) see also Seção 9.9.2 timestamp '2001-02- 16
16 20:38:40') 20:00:00
extract(field from double Get subfield; see Seção 9.9.1 extract(hour from 20
timestamp) precision timestamp '2001-02-
16 20:38:40')
extract(field from double Get subfield; see Seção 9.9.1 extract(month from 3
interval) precision interval '2 years 3
months')
isfinite(timestamp) boolean Test for finite time stamp (not isfinite(timestamp true
equal to infinity) '2001-02-16
21:28:30')
isfinite(interval) boolean Test for finite interval isfinite(interval '4 true
hours')
justify_days(interval) interval Adjust interval so 30-day time justify_days(interval 1 month
periods are represented as '30 days')
months
justify_hours(interval) interval Adjust interval so 24-hour time justify_hours(interval 1 day
periods are represented as '24 hours')
days
justify_interval(interval) interval Adjust interval using justify_interval(interval 29 days
justify_days and justify_hours, '1 mon -1 hour') 23:00:00
with additional sign
adjustments
localtime time Current time of day; see Seção
9.9.4
localtimestamp timestamp Current date and time (start of
current transaction); see Seção
9.9.4
now() timestamp Current date and time (start of
zone 9.9.4
statement_timestamp() timestamp Current date and time (start of
with time current statement); see Seção
zone 9.9.4
timeofday() text Current date and time (like
clock_timestamp, but as a text
string); see Seção 9.9.4
transaction_timestamp() timestamp Current date and time (start of

zone 9.9.4
In addition to these functions, the SQL OVERLAPS operator is supported:

(início1, fim1) OVERLAPS (início2, fim2)
(início1, comprimento1) OVERLAPS (início2, comprimento2)
This expression yields true when two time periods (defined by their endpoints) overlap, false when
they do not overlap. The endpoints can be specified as pairs of dates, times, or time stamps; or as
a date, time, or time stamp followed by an interval.
SELECT (DATE '2001-02-16', DATE '2001-12-21') OVERLAPS

(DATE '2001-10-30', DATE '2002-10-30');
Result: true
SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS
(DATE '2001-10-30', DATE '2002-10-30');
Result: false
When adding an interval value to (or subtracting an interval value from) a timestamp with time
zone value, the days component advances (or decrements) the date of the timestamp with time
zone by the indicated number of days. Across daylight saving time changes (with the session time
zone set to a time zone that recognizes DST), this means interval '1 day' does not necessarily equal
interval '24 hours'. For example, with the session time zone set to CST7CDT, timestamp with time
zone '2005-04-02 12:00-07' + interval '1 day' will produce timestamp with time zone '2005-04-03
12:00-06', while adding interval '24 hours' to the same initial timestamp with time zone produces
timestamp with time zone '2005-04-03 13:00-06', as there is a change in daylight saving time at
2005-04-03 02:00 in time zone CST7CDT.
9.9.1. EXTRACT, date_part
EXTRACT(campo FROM origem)
The extract function retrieves subfields such as year or hour from date/time values. origem must be
a value expression of type timestamp, time, or interval. (Expressions of type date will be cast to
timestamp and can therefore be used as well.) campo is an identifier or string that selects what
field to extract from the source value. The extract function returns values of type double precision.
The following are valid field names:
century
The century
SELECT EXTRACT(CENTURY FROM TIMESTAMP '2000-12-16 12:21:13');

Result: 20
SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 21
The first century starts at 0001-01-01 00:00:00 AD, although they did not know it at the
time. This definition applies to all Gregorian calendar countries. There is no century number 0,
you go from -1 to 1. If you disagree with this, please write your complaint to: Pope, Cathedral
Saint-Peter of Roma, Vatican.
PostgreSQL releases before 8.0 did not follow the conventional numbering of centuries, but
just returned the year field divided by 100.
day
The day (of the month) field (1 - 31)
SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 16
decade
The year field divided by 10
SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 200
dow
The day of the week (0 - 6; Sunday is 0) (for timestamp values only)
SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 5
Note that extract's day of the week numbering is different from that of the to_char function.
doy
The day of the year (1 - 365/366) (for timestamp values only)
SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 47
epoch
For date and timestamp values, the number of seconds since 1970-01-01 00:00:00-00 (can
be negative); for interval values, the total number of seconds in the interval
SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-08');

Result: 982384720
SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
Result: 442800
Here is how you can convert an epoch value back to a time stamp:
SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720 * INTERVAL '1 second';
hour
The hour field (0 - 23)
SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 20
microseconds
The seconds field, including fractional parts, multiplied by 1 000 000. Note that this includes
full seconds.
SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');

Result: 28500000
millennium
The millennium
SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 3
Years in the 1900s are in the second millennium. The third millennium starts January 1, 2001.
PostgreSQL releases before 8.0 did not follow the conventional numbering of millennia, but
just returned the year field divided by 1000.
milliseconds
The seconds field, including fractional parts, multiplied by 1000. Note that this includes full
seconds.
SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');

Result: 28500
minute
The minutes field (0 - 59)
SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 38
month
For timestamp values, the number of the month within the year (1 - 12) ; for interval values
the number of months, modulo 12 (0 - 11)
SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 2
SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months');
Result: 3
SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months');
Result: 1
quarter
The quarter of the year (1 - 4) that the day is in (for timestamp values only)
SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 1
second
The seconds field, including fractional parts (0 - 59[1])
SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 40
SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
Result: 28.5
timezone
The time zone offset from UTC, measured in seconds. Positive values correspond to time
zones east of UTC, negative values to zones west of UTC.
timezone_hour
The hour component of the time zone offset
timezone_minute
The minute component of the time zone offset
week
The number of the week of the year that the day is in. By definition (ISO 8601), the first week
of a year contains January 4 of that year. (The ISO-8601 week starts on Monday.) In other
words, the first Thursday of a year is in week 1 of that year. (for timestamp values only)
Because of this, it is possible for early January dates to be part of the 52nd or 53rd week of
the previous year. For example, 2005-01-01 is part of the 53rd week of year 2004, and 2006-
01-01 is part of the 52nd week of year 2005.
SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 7
year
The year field. Keep in mind there is no 0 AD, so subtracting BC years from AD years should
be done with care.
SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');

Result: 2001
The extract function is primarily intended for computational processing. For formatting date/time
values for display, see Seção 9.8.
The date_part function is modeled on the traditional Ingres equivalent to the SQL-standard function
extract:
date_part('campo', origem)
Note that here the campo parameter needs to be a string value, not a name. The valid field names
for date_part are the same as for extract.
SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');

Result: 16
SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
Result: 4
9.9.2. date_trunc
The function date_trunc is conceptually similar to the trunc function for numbers.
date_trunc('campo', origem)
origem is a value expression of type timestamp or interval. (Values of type date and time are cast
automatically, to timestamp or interval respectively.) campo selects to which precision to truncate
the input value. The return value is of type timestamp or interval with all fields that are less
significant than the selected one set to zero (or one, for day and month).
Valid values for campo are:
microseconds
milliseconds
second
minute
hour
day
week
month
quarter
year
decade
century
millennium
Examples:
SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');

Result: 2001-02-16 20:00:00
SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
Result: 2001-01-01 00:00:00
9.9.3. AT TIME ZONE
The AT TIME ZONE construct allows conversions of time stamps to different time zones. Tabela 9-27
shows its variants.
Tabela 9-27. AT TIME ZONE Variants
Expression Return Type Description

timestamp without time zone timestamp with Treat given time stamp without time zone as
AT TIME ZONE zona time zone located in the specified time zone
timestamp with time zone AT timestamp Convert given time stamp with time zone to the
TIME ZONE zona without time zone new time zone
time with time zone AT TIME time with time Convert given time with time zone to the new time
ZONE zona zone zone
In these expressions, the desired time zone zona can be specified either as a text string (e.g.,
'PST') or as an interval (e.g., INTERVAL '-08:00'). In the text case, a time zone name may be
specified in any of the ways described in Seção 8.5.3.
Examples (supposing that the local time zone is PST8PDT):
SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'MST';

Result: 2001-02-16 19:38:40-08
SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
Result: 2001-02-16 18:38:40
The first example takes a time stamp without time zone and interprets it as MST time (UTC-7),
which is then converted to PST (UTC-8) for display. The second example takes a time stamp
specified in EST (UTC-5) and converts it to local time in MST (UTC-7).
The function timezone(zona, carimbo_do_tempo) is equivalent to the SQL-conforming construct

carimbo_do_tempo AT TIME ZONE zona.
9.9.4. Current Date/Time
PostgreSQL provides a number of functions that return values related to the current date and time.
These SQL-standard functions all return values based on the start time of the current transaction:
CURRENT_DATE
CURRENT_TIME
CURRENT_TIMESTAMP
CURRENT_TIME(precisão)
CURRENT_TIMESTAMP(precisão)
LOCALTIME
LOCALTIMESTAMP
LOCALTIME(precisão)
LOCALTIMESTAMP(precisão)
CURRENT_TIME and CURRENT_TIMESTAMP deliver values with time zone; LOCALTIME and
LOCALTIMESTAMP deliver values without time zone.
CURRENT_TIME, CURRENT_TIMESTAMP, LOCALTIME, and LOCALTIMESTAMP can optionally be given

a precision parameter, which causes the result to be rounded to that many fractional digits in the
seconds field. Without a precision parameter, the result is given to the full available precision.
Some examples:
SELECT CURRENT_TIME;
Result: 14:39:53.662522-05
SELECT CURRENT_DATE;
Result: 2001-12-23
SELECT CURRENT_TIMESTAMP;
Result: 2001-12-23 14:39:53.662522-05
SELECT CURRENT_TIMESTAMP(2);
Result: 2001-12-23 14:39:53.66-05
SELECT LOCALTIMESTAMP;
Result: 2001-12-23 14:39:53.662522
Since these functions return the start time of the current transaction, their values do not change
during the transaction. This is considered a feature: the intent is to allow a single transaction to
have a consistent notion of the "current" time, so that multiple modifications within the same
transaction bear the same time stamp.
Nota: Other database systems may advance these values more frequently.
PostgreSQL also provides functions that return the start time of the current statement, as well as
the actual current time at the instant the function is called. The complete list of non-SQL-standard
time functions is:
now()
transaction_timestamp()
statement_timestamp()
clock_timestamp()
timeofday()
now() is a traditional PostgreSQL equivalent to CURRENT_TIMESTAMP. transaction_timestamp() is

likewise equivalent to CURRENT_TIMESTAMP, but is named to clearly reflect what it returns.
statement_timestamp() returns the start time of the current statement (more specifically, the time
of receipt of the latest command message from the client). statement_timestamp() and
transaction_timestamp() return the same value during the first command of a transaction, but may
differ during subsequent commands. clock_timestamp() returns the actual current time, and
therefore its value changes even within a single SQL command. timeofday() is a historical
PostgreSQL function. Like clock_timestamp(), it returns the actual current time, but as a formatted
text string rather than a timestamp with time zone value.
All the date/time data types also accept the special literal value now to specify the current date and
time (again, interpreted as the transaction start time). Thus, the following three all return the same
result:
SELECT CURRENT_TIMESTAMP;
SELECT now();
SELECT TIMESTAMP 'now'; -- incorrect for use with DEFAULT
Dica: You do not want to use the third form when specifying a DEFAULT clause while
creating a table. The system will convert now to a timestamp as soon as the constant is
parsed, so that when the default value is needed, the time of the table creation would be
used! The first two forms will not be evaluated until the default value is used, because
they are function calls. Thus they will give the desired behavior of defaulting to the time
of row insertion.
9.9.5. Delaying Execution
The following function is available to delay execution of the server process:

pg_sleep(segundos)
pg_sleep makes the current session's process sleep until segundos seconds have elapsed. segundos
is a value of type double precision, so fractional-second delays can be specified. For example:
SELECT pg_sleep(1.5);
Nota: The effective resolution of the sleep interval is platform-specific; 0.01 seconds is
a common value. The sleep delay will be at least as long as specified. It may be longer
depending on factors such as server load.
Atenção
Make sure that your session does not hold more locks than necessary when calling pg_sleep. Otherwise
other sessions might have to wait for your sleeping process, slowing down the entire system.
Notas
[1]
60 if leap seconds are implemented by the operating system

Data Type Formatting Functions Acima Geometric Functions and Operators
Geometric Functions and Operators


The geometric types point, box, lseg, line, path, polygon, and circle have a large set of native
support functions and operators, shown in Tabela 9-28, Tabela 9-29, and Tabela 9-30.
Cuidado
Note that the "same as" operator, ~=, represents the usual notion of equality for the point, box, polygon,
and circle types. Some of these types also have an = operator, but = compares for equal areas only. The
other scalar comparison operators (<= and so on) likewise compare areas for these types.
Tabela 9-28. Geometric Operators

+ Translation box '((0,0),(1,1))' + point '(2.0,0)'
- Translation box '((0,0),(1,1))' - point '(2.0,0)'
* Scaling/rotation box '((0,0),(1,1))' * point '(2.0,0)'
/ Scaling/rotation box '((0,0),(2,2))' / point '(2.0,0)'
# Point or box of intersection '((1,-1),(-1,1))' # '((1,1),(-1,-1))'
# Number of points in path or polygon # '((1,0),(0,1),(-1,0))'
@-@ Length or circumference @-@ path '((0,0),(1,0))'
@@ Center @@ circle '((0,0),10)'
## Closest point to first operand on second point '(0,0)' ## lseg '((2,0),(0,2))'
operand
<-> Distance between circle '((0,0),1)' <-> circle '((5,0),1)'
&& Overlaps? box '((0,0),(1,1))' && box '((0,0),(2,2))'
<< Is strictly left of? circle '((0,0),1)' << circle '((5,0),1)'
>> Is strictly right of? circle '((5,0),1)' >> circle '((0,0),1)'
&< Does not extend to the right of? box '((0,0),(1,1))' &< box '((0,0),(2,2))'
&> Does not extend to the left of? box '((0,0),(3,3))' &> box '((0,0),(2,2))'
<<| Is strictly below? box '((0,0),(3,3))' <<| box '((3,4),(5,5))'
|>> Is strictly above? box '((3,4),(5,5))' |>> box '((0,0),(3,3))'
&<| Does not extend above? box '((0,0),(1,1))' &<| box '((0,0),(2,2))'
|&> Does not extend below? box '((0,0),(3,3))' |&> box '((0,0),(2,2))'
<^ Is below (allows touching)? circle '((0,0),1)' <^ circle '((0,5),1)'
>^ Is above (allows touching)? circle '((0,5),1)' >^ circle '((0,0),1)'
?# Intersects? lseg '((-1,0),(1,0))' ?# box '((-2,-2),(2,2))'
?- Is horizontal? ?- lseg '((-1,0),(1,0))'
?- Are horizontally aligned? point '(1,0)' ?- point '(0,0)'
?| Is vertical? ?| lseg '((-1,0),(1,0))'
?| Are vertically aligned? point '(0,1)' ?| point '(0,0)'
?-| Is perpendicular? lseg '((0,0),(0,1))' ?-| lseg '((0,0),(1,0))'
?|| Are parallel? lseg '((-1,0),(1,0))' ?|| lseg '((-1,2),(1,2))'
@> Contains? circle '((0,0),2)' @> point '(1,1)'
http://pgdocptbr.sourceforge.net/pg82/functions-geometry.html[09/02/2018 18:07:32]
<@ Contained in or on? point '(1,1)' <@ circle '((0,0),2)'

~= Same as? polygon '((0,0),(1,1))' ~= polygon '((1,1),
(0,0))'
Nota: Before PostgreSQL 8.2, the containment operators @> and <@ were respectively
called ~ and @. These names are still available, but are deprecated and will eventually
be retired.
Tabela 9-29. Geometric Functions
Function Return Type Description Example

area(objeto) double precision area area(box '((0,0),(1,1))')
center(objeto) point center center(box '((0,0),(1,2))')
diameter(circle) double precision diameter of circle diameter(circle '((0,0),2.0)')
height(box) double precision vertical size of box height(box '((0,0),(1,1))')
isclosed(path) boolean a closed path? isclosed(path '((0,0),(1,1),(2,0))')
isopen(path) boolean an open path? isopen(path '[(0,0),(1,1),(2,0)]')
length(objeto) double precision length length(path '((-1,0),(1,0))')
npoints(path) int number of points npoints(path '[(0,0),(1,1),(2,0)]')
npoints(polygon) int number of points npoints(polygon '((1,1),(0,0))')
pclose(path) path convert path to closed pclose(path '[(0,0),(1,1),(2,0)]')
popen(path) path convert path to open popen(path '((0,0),(1,1),(2,0))')
radius(circle) double precision radius of circle radius(circle '((0,0),2.0)')
width(box) double precision horizontal size of box width(box '((0,0),(1,1))')
Tabela 9-30. Geometric Type Conversion Functions
Return
Function Description Example
Type
box(circle) box circle to box box(circle '((0,0),2.0)')
box(point, point) box points to box box(point '(0,0)', point
'(1,1)')
box(polygon) box polygon to box box(polygon '((0,0),(1,1),
(2,0))')
circle(box) circle box to circle circle(box '((0,0),(1,1))')
circle(point, double precision) circle center and radius to circle(point '(0,0)', 2.0)
circle
circle(polygon) circle polygon to circle circle(polygon '((0,0),(1,1),
(2,0))')
lseg(box) lseg box diagonal to line lseg(box '((-1,0),(1,0))')
segment
lseg(point, point) lseg points to line segment lseg(point '(-1,0)', point
'(1,0)')
path(polygon) point polygon to path path(polygon '((0,0),(1,1),
(2,0))')
point(double precision, double point construct point point(23.4, -44.5)
precision)
point(box) point center of box point(box '((-1,0),(1,0))')
point(circle) point center of circle point(circle '((0,0),2.0)')
point(lseg) point center of line segment point(lseg '((-1,0),(1,0))')
point(polygon) point center of polygon point(polygon '((0,0),(1,1),
(2,0))')
polygon(box) polygon box to 4-point polygon polygon(box '((0,0),(1,1))')
polygon(circle) polygon circle to 12-point polygon(circle '((0,0),2.0)')

polygon
polygon(npts, circle) polygon circle to npts-point polygon(12, circle
polygon '((0,0),2.0)')
polygon(path) polygon path to polygon polygon(path '((0,0),(1,1),
(2,0))')
It is possible to access the two component numbers of a point as though it were an array with
indices 0 and 1. For example, if t.p is a point column then SELECT p[0] FROM t retrieves the X
coordinate and UPDATE t SET p[1] = ... changes the Y coordinate. In the same way, a value of type
box or lseg may be treated as an array of two point values.
The area function works for the types box, circle, and path. The area function only works on the
path data type if the points in the path are non-intersecting. For example, the path '((0,0),(0,1),
(2,1),(2,2),(1,2),(1,0),(0,0))'::PATH won't work, however, the following visually identical path
'((0,0),(0,1),(1,1),(1,2),(2,2),(2,1),(1,1),(1,0),(0,0))'::PATH will work. If the concept of an
intersecting versus non-intersecting path is confusing, draw both of the above paths side by side on
a piece of graph paper.

Date/Time Functions and Operators Acima Network Address Functions and
Operators
Network Address Functions and Operators


Tabela 9-31 shows the operators available for the cidr and inet types. The operators <<, <<=, >>,
and >>= test for subnet inclusion. They consider only the network parts of the two addresses,
ignoring any host part, and determine whether one network part is identical to or a subnet of the
other.
Tabela 9-31. cidr and inet Operators

< is less than inet '192.168.1.5' < inet '192.168.1.6'
<= is less than or equal inet '192.168.1.5' <= inet '192.168.1.5'
= equals inet '192.168.1.5' = inet '192.168.1.5'
>= is greater or equal inet '192.168.1.5' >= inet '192.168.1.5'
> is greater than inet '192.168.1.5' > inet '192.168.1.4'
<> is not equal inet '192.168.1.5' <> inet '192.168.1.4'
<< is contained within inet '192.168.1.5' << inet '192.168.1/24'
<<= is contained within or equals inet '192.168.1/24' <<= inet '192.168.1/24'
>> contains inet '192.168.1/24' >> inet '192.168.1.5'
>>= contains or equals inet '192.168.1/24' >>= inet '192.168.1/24'
~ bitwise NOT ~ inet '192.168.1.6'
& bitwise AND inet '192.168.1.6' & inet '0.0.0.255'
| bitwise OR inet '192.168.1.6' | inet '0.0.0.255'
+ addition inet '192.168.1.6' + 25
- subtraction inet '192.168.1.43' - 36
- subtraction inet '192.168.1.43' - inet '192.168.1.19'
Tabela 9-32 shows the functions available for use with the cidr and inet types. The host, text, and
abbrev functions are primarily intended to offer alternative display formats.
Tabela 9-32. cidr and inet Functions
Return
Type
abbrev(inet) text abbreviated abbrev(inet '10.1.0.0/16') 10.1.0.0/16
display format as
text
abbrev(cidr) text abbreviated abbrev(cidr '10.1.0.0/16') 10.1/16
display format as
text
broadcast(inet) inet broadcast address broadcast('192.168.1.5/24') 192.168.1.255/24
for network
family(inet) int extract family of family('::1') 6
address; 4 for
IPv4, 6 for IPv6
host(inet) text extract IP address host('192.168.1.5/24') 192.168.1.5
http://pgdocptbr.sourceforge.net/pg82/functions-net.html[09/02/2018 18:07:43]
Network Address Functions and Operators
as text
hostmask(inet) inet construct host hostmask('192.168.23.20/30') 0.0.0.3
mask for network
masklen(inet) int extract netmask masklen('192.168.1.5/24') 24
length
netmask(inet) inet construct netmask netmask('192.168.1.5/24') 255.255.255.0
for network
network(inet) cidr extract network network('192.168.1.5/24') 192.168.1.0/24
part of address
set_masklen(inet, inet set netmask set_masklen('192.168.1.5/24', 16) 192.168.1.5/16
int) length for inet
value
set_masklen(cidr, cidr set netmask set_masklen('192.168.1.0/24'::cidr, 192.168.0.0/16
int) length for cidr 16)
value
text(inet) text extract IP address text(inet '192.168.1.5') 192.168.1.5/32
and netmask
length as text
Any cidr value can be cast to inet implicitly or explicitly; therefore, the functions shown above as
operating on inet also work on cidr values. (Where there are separate functions for inet and cidr, it
is because the behavior should be different for the two cases.) Also, it is permitted to cast an inet
value to cidr. When this is done, any bits to the right of the netmask are silently zeroed to create a
valid cidr value. In addition, you can cast a text value to inet or cidr using normal casting syntax:
for example, inet(expressão) or nome_da_coluna::cidr.
Tabela 9-33 shows the functions available for use with the macaddr type. The function
trunc(macaddr) returns a MAC address with the last 3 bytes set to zero. This can be used to
associate the remaining prefix with a manufacturer.
Tabela 9-33. macaddr Functions
Return
Type
trunc(macaddr) macaddr set last 3 bytes to trunc(macaddr 12:34:56:00:00:00
zero '12:34:56:78:90:ab')
The macaddr type also supports the standard relational operators (>, <=, etc.) for lexicographical
ordering.

Geometric Functions and Operators Acima Sequence Manipulation Functions
http://pgdocptbr.sourceforge.net/pg82/functions-net.html[09/02/2018 18:07:43]
Sequence Manipulation Functions


This section describes PostgreSQL's functions for operating on sequence objects. Sequence objects
(also called sequence generators or just sequences) are special single-row tables created with
CREATE SEQUENCE. A sequence object is usually used to generate unique identifiers for rows of a
table. The sequence functions, listed in Tabela 9-34, provide simple, multiuser-safe methods for
obtaining successive sequence values from sequence objects.
Tabela 9-34. Sequence Functions
Return
Type
currval(regclass) bigint Return value most recently obtained with nextval for
specified sequence
nextval(regclass) bigint Advance sequence and return new value
setval(regclass, bigint) bigint Set sequence's current value
setval(regclass, bigint, bigint Set sequence's current value and is_called flag
boolean)
The sequence to be operated on by a sequence-function call is specified by a regclass argument,

which is just the OID of the sequence in the pg_class system catalog. You do not have to look up
the OID by hand, however, since the regclass data type's input converter will do the work for you.
Just write the sequence name enclosed in single quotes, so that it looks like a literal constant. To
achieve some compatibility with the handling of ordinary SQL names, the string will be converted to
lowercase unless it contains double quotes around the sequence name. Thus
nextval('foo') operates on sequence foo

nextval('FOO') operates on sequence foo
nextval('"Foo"') operates on sequence Foo
The sequence name can be schema-qualified if necessary:
nextval('myschema.foo') operates on myschema.foo

nextval('"myschema".foo') same as above
nextval('foo') searches search path for foo
See Seção 8.12 for more information about regclass.
Nota: Before PostgreSQL 8.1, the arguments of the sequence functions were of type
text, not regclass, and the above-described conversion from a text string to an OID
value would happen at run time during each call. For backwards compatibility, this
facility still exists, but internally it is now handled as an implicit coercion from text to
regclass before the function is invoked.
When you write the argument of a sequence function as an unadorned literal string, it
becomes a constant of type regclass. Since this is really just an OID, it will track the
originally identified sequence despite later renaming, schema reassignment, etc. This
"early binding" behavior is usually desirable for sequence references in column defaults
and views. But sometimes you will want "late binding" where the sequence reference is
resolved at run time. To get late-binding behavior, force the constant to be stored as a
http://pgdocptbr.sourceforge.net/pg82/functions-sequence.html[09/02/2018 18:08:01]
text constant instead of regclass:
nextval('foo'::text) foo is looked up at runtime
Note that late binding was the only behavior supported in PostgreSQL releases before
8.1, so you may need to do this to preserve the semantics of old applications.
Of course, the argument of a sequence function can be an expression as well as a

constant. If it is a text expression then the implicit coercion will result in a run-time
lookup.
The available sequence functions are:
nextval
Advance the sequence object to its next value and return that value. This is done atomically:
even if multiple sessions execute nextval concurrently, each will safely receive a distinct
sequence value.
currval
Return the value most recently obtained by nextval for this sequence in the current session.
(An error is reported if nextval has never been called for this sequence in this session.) Notice
that because this is returning a session-local value, it gives a predictable answer whether or
not other sessions have executed nextval since the current session did.
lastval
Return the value most recently returned by nextval in the current session. This function is
identical to currval, except that instead of taking the sequence name as an argument it
fetches the value of the last sequence that nextval was used on in the current session. It is an
error to call lastval if nextval has not yet been called in the current session.
setval
Reset the sequence object's counter value. The two-parameter form sets the sequence's
last_value field to the specified value and sets its is_called field to true, meaning that the next
nextval will advance the sequence before returning a value. In the three-parameter form,
is_called may be set either true or false. If it's set to false, the next nextval will return exactly
the specified value, and sequence advancement commences with the following nextval. For
example,
SELECT setval('foo', 42); Next nextval will return 43

SELECT setval('foo', 42, true); Same as above
SELECT setval('foo', 42, false); Next nextval will return 42
The result returned by setval is just the value of its second argument.
If a sequence object has been created with default parameters, nextval calls on it will return
successive values beginning with 1. Other behaviors can be obtained by using special parameters in
the CREATE SEQUENCE command; see its command reference page for more information.
Importante: To avoid blocking of concurrent transactions that obtain numbers from the
same sequence, a nextval operation is never rolled back; that is, once a value has been
fetched it is considered used, even if the transaction that did the nextval later aborts.
This means that aborted transactions may leave unused "holes" in the sequence of
assigned values. setval operations are never rolled back, either.

Network Address Functions and Acima Conditional Expressions
Operators
Conditional Expressions


This section describes the SQL-compliant conditional expressions available in PostgreSQL.
Dica: If your needs go beyond the capabilities of these conditional expressions you
might want to consider writing a stored procedure in a more expressive programming
language.
9.13.1. CASE
The SQL CASE expression is a generic conditional expression, similar to if/else statements in other
languages:
CASE WHEN condição THEN resultado
[WHEN ...]
[ELSE resultado]
END
CASE clauses can be used wherever an expression is valid. condição is an expression that returns a
boolean result. If the result is true then the value of the CASE expression is the resultado that
follows the condition. If the result is false any subsequent WHEN clauses are searched in the same
manner. If no WHEN condição is true then the value of the case expression is the resultado in the
ELSE clause. If the ELSE clause is omitted and no condition matches, the result is null.
An example:
SELECT * FROM test;

a
---
1
2
3
SELECT a,
CASE WHEN a=1 THEN 'one'
WHEN a=2 THEN 'two'
ELSE 'other'
END
FROM test;
a | case
---+-------
1 | one
2 | two
3 | other
The data types of all the resultado expressions must be convertible to a single output type. See
Seção 10.5 for more detail.
The following "simple" CASE expression is a specialized variant of the general form above:
CASE expressão
WHEN valor THEN resultado
[WHEN ...]
[ELSE resultado]
END
The expressão is computed and compared to all the valor specifications in the WHEN clauses until
one is found that is equal. If no match is found, the resultado in the ELSE clause (or a null value) is
returned. This is similar to the switch statement in C.
The example above can be written using the simple CASE syntax:
http://pgdocptbr.sourceforge.net/pg82/functions-conditional.html[09/02/2018 18:08:16]
SELECT a,
CASE a WHEN 1 THEN 'one'
WHEN 2 THEN 'two'
ELSE 'other'
END
FROM test;
a | case
---+-------
1 | one
2 | two
3 | other
A CASE expression does not evaluate any subexpressions that are not needed to determine the
result. For example, this is a possible way of avoiding a division-by-zero failure:
SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
9.13.2. COALESCE
COALESCE(valor [, ...])
The COALESCE function returns the first of its arguments that is not null. Null is returned only if all
arguments are null. It is often used to substitute a default value for null values when data is
retrieved for display, for example:
SELECT COALESCE(description, short_description, '(none)') ...
Like a CASE expression, COALESCE will not evaluate arguments that are not needed to determine
the result; that is, arguments to the right of the first non-null argument are not evaluated. This
SQL-standard function provides capabilities similar to NVL and IFNULL, which are used in some
other database systems.
9.13.3. NULLIF
NULLIF(valor1, valor2)
The NULLIF function returns a null value if valor1 and valor2 are equal; otherwise it returns valor1.
This can be used to perform the inverse operation of the COALESCE example given above:
SELECT NULLIF(value, '(none)') ...
If valor1 is (none), return a null, otherwise return valor1.
9.13.4. GREATEST and LEAST
GREATEST(valor [, ...])
LEAST(valor [, ...])
The GREATEST and LEAST functions select the largest or smallest value from a list of any number of
expressions. The expressions must all be convertible to a common data type, which will be the type
of the result (see Seção 10.5 for details). NULL values in the list are ignored. The result will be NULL
only if all the expressions evaluate to NULL.
Note that GREATEST and LEAST are not in the SQL standard, but are a common extension.

Sequence Manipulation Functions Acima Array Functions and Operators
Array Functions and Operators


Tabela 9-35 shows the operators available for array types.
Tabela 9-35. array Operators

= equal ARRAY[1.1,2.1,3.1]::int[] = t
ARRAY[1,2,3]
<> not equal ARRAY[1,2,3] <> ARRAY[1,2,4] t
< less than ARRAY[1,2,3] < ARRAY[1,2,4] t
> greater than ARRAY[1,4,3] > ARRAY[1,2,4] t
<= less than or equal ARRAY[1,2,3] <= ARRAY[1,2,3] t
>= greater than or equal ARRAY[1,4,3] >= ARRAY[1,4,3] t
@> contains ARRAY[1,4,3] @> ARRAY[3,1] t
<@ is contained by ARRAY[2,7] <@ ARRAY[1,7,4,2,6] t
&& overlap (have elements in ARRAY[1,4,3] && ARRAY[2,1] t
common)
|| array-to-array concatenation ARRAY[1,2,3] || ARRAY[4,5,6] {1,2,3,4,5,6}
|| array-to-array concatenation ARRAY[1,2,3] || ARRAY[[4,5,6], {{1,2,3},{4,5,6},
[7,8,9]] {7,8,9}}
|| element-to-array 3 || ARRAY[4,5,6] {3,4,5,6}
concatenation
|| array-to-element ARRAY[4,5,6] || 7 {4,5,6,7}
concatenation
Array comparisons compare the array contents element-by-element, using the default B-Tree
comparison function for the element data type. In multidimensional arrays the elements are visited
in row-major order (last subscript varies most rapidly). If the contents of two arrays are equal but
the dimensionality is different, the first difference in the dimensionality information determines the
sort order. (This is a change from versions of PostgreSQL prior to 8.2: older versions would claim
that two arrays with the same contents were equal, even if the number of dimensions or subscript
ranges were different.)
See Seção 8.10 for more details about array operator behavior.
Tabela 9-36 shows the functions available for use with array types. See Seção 8.10 for more
discussion and examples of the use of these functions.
Tabela 9-36. array Functions
Return
Type
array_append(anyarray, anyarray append an array_append(ARRAY[1,2], 3) {1,2,3}
anyelement) element to
the end of an
array
array_cat(anyarray, anyarray concatenate array_cat(ARRAY[1,2,3], {1,2,3,4,5}
http://pgdocptbr.sourceforge.net/pg82/functions-array.html[09/02/2018 18:08:25]
Array Functions and Operators
anyarray) two arrays ARRAY[4,5])

array_dims(anyarray) text returns a text array_dims(ARRAY[[1,2,3], [1:2][1:3]
representation [4,5,6]])
of array's
dimensions
array_lower(anyarray, int) int returns lower array_lower('[0:2]= 0
bound of the {1,2,3}'::int[], 1)
requested
array
dimension
array_prepend(anyelement, anyarray append an array_prepend(1, ARRAY[2,3]) {1,2,3}
anyarray) element to
the beginning
of an array
array_to_string(anyarray, text concatenates array_to_string(ARRAY[1, 2, 3], 1~^~2~^~3
text) array '~^~')
elements
using
provided
delimiter
array_upper(anyarray, int) int returns upper array_upper(ARRAY[1,2,3,4], 1) 4
bound of the
requested
array
dimension
string_to_array(text, text) text[] splits string string_to_array('xx~^~yy~^~zz', {xx,yy,zz}
into array '~^~')
elements
using
provided
delimiter

Conditional Expressions Acima Aggregate Functions
http://pgdocptbr.sourceforge.net/pg82/functions-array.html[09/02/2018 18:08:25]
Aggregate Functions


Aggregate functions compute a single result value from a set of input values. The built-in aggregate
functions are listed in Tabela 9-37 and Tabela 9-38. The special syntax considerations for aggregate
functions are explained in Seção 4.2.7. Consult Seção 2.7 for additional introductory information.
Tabela 9-37. General-Purpose Aggregate Functions
Argument
Function Return Type Description
Type
avg(expressão) smallint, int, numeric for any integer type argument, the average
bigint, real, double precision for a floating-point (arithmetic mean)
double precision, argument, otherwise the same as the of all input values
numeric, or argument data type
interval
bit_and(expressão) smallint, int, same as argument data type the bitwise AND
bigint, or bit of all non-null
input values, or
null if none
bit_or(expressão) smallint, int, same as argument data type the bitwise OR of
bigint, or bit all non-null input
values, or null if
none
bool_and(expressão) bool bool true if all input
values are true,
otherwise false
bool_or(expressão) bool bool true if at least
one input value is
true, otherwise
false
count(*) bigint number of input
rows
count(expressão) any bigint number of input
rows for which
the value of
expression is not
null
every(expressão) bool bool equivalent to
bool_and
max(expressão) any array, same as argument type maximum value
numeric, string, of expression
or date/time across all input
type values
min(expressão) any array, same as argument type minimum value of
numeric, string, expression across
or date/time all input values
type
sum(expressão) smallint, int, bigint for smallint or int arguments, numeric sum of expressão
bigint, real, for bigint arguments, double precision for across all input
double precision, floating-point arguments, otherwise the values
http://pgdocptbr.sourceforge.net/pg82/functions-aggregate.html[09/02/2018 18:08:34]
Aggregate Functions
numeric, or same as the argument data type

interval
It should be noted that except for count, these functions return a null value when no rows are
selected. In particular, sum of no rows returns null, not zero as one might expect. The coalesce
function may be used to substitute zero for null when necessary.
Nota: Boolean aggregates bool_and and bool_or correspond to standard SQL

aggregates every and any or some. As for any and some, it seems that there is an
ambiguity built into the standard syntax:
SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
Here ANY can be considered both as leading to a subquery or as an aggregate if the

select expression returns 1 row. Thus the standard name cannot be given to these
aggregates.
Nota: Users accustomed to working with other SQL database management systems may
be surprised by the performance of the count aggregate when it is applied to the entire
table. A query like:
SELECT count(*) FROM sometable;
will be executed by PostgreSQL using a sequential scan of the entire table.
Tabela 9-38 shows aggregate functions typically used in statistical analysis. (These are separated
out merely to avoid cluttering the listing of more-commonly-used aggregates.) Where the
description mentions N, it means the number of input rows for which all the input expressions are
non-null. In all cases, null is returned if the computation is meaningless, for example when N is
zero.
Tabela 9-38. Aggregate Functions for Statistics
Function Argument Type Return Type Description

corr(Y, X) double precision double precision correlation coefficient
covar_pop(Y, X) double precision double precision population covariance
covar_samp(Y, X) double precision double precision sample covariance
regr_avgx(Y, X) double precision double precision average of the independent
variable (sum(X)/N)
regr_avgy(Y, X) double precision double precision average of the dependent
variable (sum(Y)/N)
regr_count(Y, X) double precision bigint number of input rows in which
both expressions are nonnull
regr_intercept(Y, X) double precision double precision y-intercept of the least-squares-
fit linear equation determined by
the (X, Y) pairs
regr_r2(Y, X) double precision double precision square of the correlation
coefficient
regr_slope(Y, X) double precision double precision slope of the least-squares-fit
linear equation determined by
the (X, Y) pairs
regr_sxx(Y, X) double precision double precision sum(X^2) - sum(X)^2/N ("sum
of squares" of the independent
variable)
regr_sxy(Y, X) double precision double precision sum(X*Y) - sum(X) * sum(Y)/N
("sum of products" of
independent times dependent
Aggregate Functions
variable)
regr_syy(Y, X) double precision double precision sum(Y^2) - sum(Y)^2/N ("sum
of squares" of the dependent
variable)
stddev(expressão) smallint, int, double precision for historical alias for stddev_samp
bigint, real, double floating-point
precision, or arguments, otherwise
numeric numeric
stddev_pop(expressão) smallint, int, double precision for population standard deviation of
bigint, real, double floating-point the input values
numeric numeric
stddev_samp(expressão) smallint, int, double precision for sample standard deviation of the
bigint, real, double floating-point input values
numeric numeric
variance(expressão) smallint, int, double precision for historical alias for var_samp
bigint, real, double floating-point
numeric numeric
var_pop(expressão) smallint, int, double precision for population variance of the input
bigint, real, double floating-point values (square of the population
precision, or arguments, otherwise standard deviation)
numeric numeric
var_samp(expressão) smallint, int, double precision for sample variance of the input
bigint, real, double floating-point values (square of the sample
precision, or arguments, otherwise standard deviation)
numeric numeric

Array Functions and Operators Acima Subquery Expressions
Subquery Expressions


This section describes the SQL-compliant subquery expressions available in PostgreSQL. All of the
expression forms documented in this section return Boolean (true/false) results.
9.16.1. EXISTS
EXISTS (subconsulta)
The argument of EXISTS is an arbitrary SELECT statement, or subquery. The subquery is evaluated
to determine whether it returns any rows. If it returns at least one row, the result of EXISTS is
"true"; if the subquery returns no rows, the result of EXISTS is "false".
The subquery can refer to variables from the surrounding query, which will act as constants during
any one evaluation of the subquery.
The subquery will generally only be executed far enough to determine whether at least one row is
returned, not all the way to completion. It is unwise to write a subquery that has any side effects
(such as calling sequence functions); whether the side effects occur or not may be difficult to
predict.
Since the result depends only on whether any rows are returned, and not on the contents of those
rows, the output list of the subquery is normally uninteresting. A common coding convention is to
write all EXISTS tests in the form EXISTS(SELECT 1 WHERE ...). There are exceptions to this rule
however, such as subqueries that use INTERSECT.
This simple example is like an inner join on col2, but it produces at most one output row for each
tab1 row, even if there are multiple matching tab2 rows:
SELECT col1 FROM tab1

WHERE EXISTS(SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
9.16.2. IN
expressão IN (subconsulta)
The right-hand side is a parenthesized subquery, which must return exactly one column. The left-
hand expression is evaluated and compared to each row of the subquery result. The result of IN is
"true" if any equal subquery row is found. The result is "false" if no equal row is found (including
the special case where the subquery returns no rows).
Note that if the left-hand expression yields null, or if there are no equal right-hand values and at
least one right-hand row yields null, the result of the IN construct will be null, not false. This is in
accordance with SQL's normal rules for Boolean combinations of null values.
As with EXISTS, it's unwise to assume that the subquery will be evaluated completely.
construtor_de_linha IN (subconsulta)
The left-hand side of this form of IN is a row constructor, as described in Seção 4.2.11. The right-
hand side is a parenthesized subquery, which must return exactly as many columns as there are
expressions in the left-hand row. The left-hand expressions are evaluated and compared row-wise
to each row of the subquery result. The result of IN is "true" if any equal subquery row is found.
http://pgdocptbr.sourceforge.net/pg82/functions-subquery.html[09/02/2018 18:08:42]
The result is "false" if no equal row is found (including the special case where the subquery returns
no rows).
As usual, null values in the rows are combined per the normal rules of SQL Boolean expressions.
Two rows are considered equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal; otherwise the result of that
row comparison is unknown (null). If all the per-row results are either unequal or null, with at least
one null, then the result of IN is null.
9.16.3. NOT IN
expressão NOT IN (subconsulta)
hand expression is evaluated and compared to each row of the subquery result. The result of NOT
IN is "true" if only unequal subquery rows are found (including the special case where the subquery
returns no rows). The result is "false" if any equal row is found.
least one right-hand row yields null, the result of the NOT IN construct will be null, not true. This is
in accordance with SQL's normal rules for Boolean combinations of null values.
construtor_de_linha NOT IN (subconsulta)
The left-hand side of this form of NOT IN is a row constructor, as described in Seção 4.2.11. The
right-hand side is a parenthesized subquery, which must return exactly as many columns as there
are expressions in the left-hand row. The left-hand expressions are evaluated and compared row-
wise to each row of the subquery result. The result of NOT IN is "true" if only unequal subquery
rows are found (including the special case where the subquery returns no rows). The result is
"false" if any equal row is found.
As usual, null values in the rows are combined per the normal rules of SQL Boolean expressions.
Two rows are considered equal if all their corresponding members are non-null and equal; the rows
are unequal if any corresponding members are non-null and unequal; otherwise the result of that
row comparison is unknown (null). If all the per-row results are either unequal or null, with at least
one null, then the result of NOT IN is null.
9.16.4. ANY/SOME
expressão operador ANY (subconsulta)
expressão operador SOME (subconsulta)
hand expression is evaluated and compared to each row of the subquery result using the given
operador, which must yield a Boolean result. The result of ANY is "true" if any true result is
obtained. The result is "false" if no true result is found (including the special case where the
subquery returns no rows).
SOME is a synonym for ANY. IN is equivalent to = ANY.
Note that if there are no successes and at least one right-hand row yields null for the operator's
result, the result of the ANY construct will be null, not false. This is in accordance with SQL's normal
rules for Boolean combinations of null values.
construtor_de_linha operador ANY (subconsulta)
construtor_de_linha operador SOME (subconsulta)
The left-hand side of this form of ANY is a row constructor, as described in Seção 4.2.11. The right-
to each row of the subquery result, using the given operador. The result of ANY is "true" if the
comparison returns true for any subquery row. The result is "false" if the comparison returns false
for every subquery row (including the special case where the subquery returns no rows). The result
is NULL if the comparison does not return true for any row, and it returns NULL for at least one row.
See Seção 9.17.5 for details about the meaning of a row-wise comparison.
9.16.5. ALL
expressão operador ALL (subconsulta)
hand expression is evaluated and compared to each row of the subquery result using the given
operador, which must yield a Boolean result. The result of ALL is "true" if all rows yield true
(including the special case where the subquery returns no rows). The result is "false" if any false
result is found. The result is NULL if the comparison does not return false for any row, and it returns
NULL for at least one row.
NOT IN is equivalent to <> ALL.
construtor_de_linha operador ALL (subconsulta)
The left-hand side of this form of ALL is a row constructor, as described in Seção 4.2.11. The right-
to each row of the subquery result, using the given operador. The result of ALL is "true" if the
comparison returns true for all subquery rows (including the special case where the subquery
returns no rows). The result is "false" if the comparison returns false for any subquery row. The
result is NULL if the comparison does not return false for any subquery row, and it returns NULL for
at least one row.
construtor_de_linha operador (subconsulta)
The left-hand side is a row constructor, as described in Seção 4.2.11. The right-hand side is a
parenthesized subquery, which must return exactly as many columns as there are expressions in
the left-hand row. Furthermore, the subquery cannot return more than one row. (If it returns zero
rows, the result is taken to be null.) The left-hand side is evaluated and compared row-wise to the
single subquery result row.

Aggregate Functions Acima Row and Array Comparisons
Row and Array Comparisons


This section describes several specialized constructs for making multiple comparisons between
groups of values. These forms are syntactically related to the subquery forms of the previous
section, but do not involve subqueries. The forms involving array subexpressions are PostgreSQL
extensions; the rest are SQL-compliant. All of the expression forms documented in this section
return Boolean (true/false) results.
9.17.1. IN
expressão IN (valor [, ...])
The right-hand side is a parenthesized list of scalar expressions. The result is "true" if the left-hand
expression's result is equal to any of the right-hand expressions. This is a shorthand notation for
expressão = valor1
OR
expressão = valor2
OR
...
least one right-hand expression yields null, the result of the IN construct will be null, not false. This
is in accordance with SQL's normal rules for Boolean combinations of null values.
9.17.2. NOT IN
expressão NOT IN (valor [, ...])
The right-hand side is a parenthesized list of scalar expressions. The result is "true" if the left-hand
expression's result is unequal to all of the right-hand expressions. This is a shorthand notation for
expressão <> valor1
AND
expressão <> valor2
AND
...
least one right-hand expression yields null, the result of the NOT IN construct will be null, not true
as one might naively expect. This is in accordance with SQL's normal rules for Boolean
combinations of null values.
Dica: x NOT IN y is equivalent to NOT (x IN y) in all cases. However, null values are
much more likely to trip up the novice when working with NOT IN than when working
with IN. It's best to express your condition positively if possible.
9.17.3. ANY/SOME (array)

expressão operador ANY (expressão_de_matriz)
expressão operador SOME (expressão_de_matriz)
The right-hand side is a parenthesized expression, which must yield an array value. The left-hand
expression is evaluated and compared to each element of the array using the given operador, which
must yield a Boolean result. The result of ANY is "true" if any true result is obtained. The result is
"false" if no true result is found (including the special case where the array has zero elements).
If the array expression yields a null array, the result of ANY will be null. If the left-hand expression
http://pgdocptbr.sourceforge.net/pg82/functions-comparisons.html[09/02/2018 18:08:52]
yields null, the result of ANY is ordinarily null (though a non-strict comparison operator could
possibly yield a different result). Also, if the right-hand array contains any null elements and no
true comparison result is obtained, the result of ANY will be null, not false (again, assuming a strict
comparison operator). This is in accordance with SQL's normal rules for Boolean combinations of
null values.
SOME is a synonym for ANY.
9.17.4. ALL (array)

expressão operador ALL (expressão_de_matriz)
The right-hand side is a parenthesized expression, which must yield an array value. The left-hand
expression is evaluated and compared to each element of the array using the given operador, which
must yield a Boolean result. The result of ALL is "true" if all comparisons yield true (including the
special case where the array has zero elements). The result is "false" if any false result is found.
If the array expression yields a null array, the result of ALL will be null. If the left-hand expression
yields null, the result of ALL is ordinarily null (though a non-strict comparison operator could
possibly yield a different result). Also, if the right-hand array contains any null elements and no
false comparison result is obtained, the result of ALL will be null, not true (again, assuming a strict
comparison operator). This is in accordance with SQL's normal rules for Boolean combinations of
null values.

construtor_de_linha operador construtor_de_linha
Each side is a row constructor, as described in Seção 4.2.11. The two row values must have the
same number of fields. Each side is evaluated and they are compared row-wise. Row comparisons
are allowed when the operador is =, <>, <, <=, > or >=, or has semantics similar to one of these.
(To be specific, an operator can be a row comparison operator if it is a member of a B-Tree
operator class, or is the negator of the = member of a B-Tree operator class.)
The = and <> cases work slightly differently from the others. Two rows are considered equal if all
their corresponding members are non-null and equal; the rows are unequal if any corresponding
members are non-null and unequal; otherwise the result of the row comparison is unknown (null).
For the <, <=, > and >= cases, the row elements are compared left-to-right, stopping as soon as
an unequal or null pair of elements is found. If either of this pair of elements is null, the result of
the row comparison is unknown (null); otherwise comparison of this pair of elements determines
the result. For example, ROW(1,2,NULL) < ROW(1,3,0) yields true, not null, because the third pair
of elements are not considered.
Nota: Prior to PostgreSQL 8.2, the <, <=, > and >= cases were not handled per SQL
specification. A comparison like ROW(a,b) < ROW(c,d) was implemented as a < c AND b
< d whereas the correct behavior is equivalent to a < c OR (a = c AND b < d).
construtor_de_linha IS DISTINCT FROM construtor_de_linha
This construct is similar to a <> row comparison, but it does not yield null for null inputs. Instead,
any null value is considered unequal to (distinct from) any non-null value, and any two nulls are
considered equal (not distinct). Thus the result will always be either true or false, never null.
construtor_de_linha IS NOT DISTINCT FROM construtor_de_linha
This construct is similar to a = row comparison, but it does not yield null for null inputs. Instead,
any null value is considered unequal to (distinct from) any non-null value, and any two nulls are
considered equal (not distinct). Thus the result will always be either true or false, never null.

Subquery Expressions Acima Set Returning Functions
Set Returning Functions


This section describes functions that possibly return more than one row. Currently the only
functions in this class are series generating functions, as detailed in Tabela 9-39.
Tabela 9-39. Series Generating Functions
Argument
Function Return Type Description
Type
generate_series(start, int or bigint setof int or setof bigint Generate a series of values, from start
stop) (same as argument type) to stop with a step size of one
generate_series(start, int or bigint setof int or setof bigint Generate a series of values, from start
stop, step) (same as argument type) to stop with a step size of step
When step is positive, zero rows are returned if start is greater than stop. Conversely, when step is
negative, zero rows are returned if start is less than stop. Zero rows are also returned for NULL
inputs. It is an error for step to be zero. Some examples follow:
select * from generate_series(2,4);

generate_series
-----------------
2
3
4
(3 rows)
select * from generate_series(5,1,-2);
generate_series
-----------------
5
3
1
(3 rows)
select * from generate_series(4,3);
generate_series
-----------------
(0 rows)
select current_date + s.a as dates from generate_series(0,14,7) as s(a);
dates
------------
2004-02-05
2004-02-12
2004-02-19
(3 rows)

Row and Array Comparisons Acima System Information Functions
http://pgdocptbr.sourceforge.net/pg82/functions-srf.html[09/02/2018 18:09:07]
System Information Functions


Tabela 9-40 shows several functions that extract session and system information.
Tabela 9-40. Session Information Functions
Name Return Type Description

current_database() name name of current database
current_schema() name name of current schema
current_schemas(boolean) name[] names of schemas in search path optionally
including implicit schemas
current_user name user name of current execution context
inet_client_addr() inet address of the remote connection
inet_client_port() int port of the remote connection
inet_server_addr() inet address of the local connection
inet_server_port() int port of the local connection
pg_my_temp_schema() oid OID of session's temporary schema, or 0 if none
pg_is_other_temp_schema(oid) boolean is schema another session's temporary schema?
pg_postmaster_start_time() timestamp with server start time
time zone
session_user name session user name
user name equivalent to current_user
version() text PostgreSQL version information
The session_user is normally the user who initiated the current database connection; but
superusers can change this setting with SET SESSION AUTHORIZATION. The current_user is the user
identifier that is applicable for permission checking. Normally, it is equal to the session user, but it
can be changed with SET ROLE. It also changes during the execution of functions with the attribute
SECURITY DEFINER. In Unix parlance, the session user is the "real user" and the current user is the
"effective user".
Nota: current_user, session_user, and user have special syntactic status in SQL: they
must be called without trailing parentheses.
current_schema returns the name of the schema that is at the front of the search path (or a null
value if the search path is empty). This is the schema that will be used for any tables or other
named objects that are created without specifying a target schema. current_schemas(boolean)
returns an array of the names of all schemas presently in the search path. The Boolean option
determines whether or not implicitly included system schemas such as pg_catalog are included in
the search path returned.
Nota: The search path may be altered at run time. The command is:
SET search_path TO esquema [, esquema, ...]
inet_client_addr returns the IP address of the current client, and inet_client_port returns the port
http://pgdocptbr.sourceforge.net/pg82/functions-info.html[09/02/2018 18:09:15]
number. inet_server_addr returns the IP address on which the server accepted the current
connection, and inet_server_port returns the port number. All these functions return NULL if the
current connection is via a Unix-domain socket.
pg_my_temp_schema returns the OID of the current session's temporary schema, or 0 if it has
none (because it has not created any temporary tables). pg_is_other_temp_schema returns true if
the given OID is the OID of any other session's temporary schema. (This can be useful, for
example, to exclude other sessions' temporary tables from a catalog display.)
pg_postmaster_start_time returns the timestamp with time zone when the server started.
version returns a string describing the PostgreSQL server's version.
Tabela 9-41 lists functions that allow the user to query object access privileges programmatically.
See Seção 5.6 for more information about privileges.
Tabela 9-41. Access Privilege Inquiry Functions
Return
Name Description
Type
has_database_privilege(user, database, boolean does user have privilege for database
privilege)
has_database_privilege(database, privilege) boolean does current user have privilege for
database
has_function_privilege(user, function, boolean does user have privilege for function
privilege)
has_function_privilege(function, privilege) boolean does current user have privilege for
function
has_language_privilege(user, language, boolean does user have privilege for language
privilege)
has_language_privilege(language, privilege) boolean does current user have privilege for
language
has_schema_privilege(user, schema, boolean does user have privilege for schema
privilege)
has_schema_privilege(schema, privilege) boolean does current user have privilege for
schema
has_table_privilege(user, table, privilege) boolean does user have privilege for table
has_table_privilege(table, privilege) boolean does current user have privilege for table
has_tablespace_privilege(user, tablespace, boolean does user have privilege for tablespace
privilege)
has_tablespace_privilege(tablespace, boolean does current user have privilege for
privilege) tablespace
pg_has_role(user, role, privilege) boolean does user have privilege for role
pg_has_role(role, privilege) boolean does current user have privilege for role
has_database_privilege checks whether a user can access a database in a particular way. The
possibilities for its arguments are analogous to has_table_privilege. The desired access privilege
type must evaluate to CREATE, CONNECT, TEMPORARY, or TEMP (which is equivalent to
TEMPORARY).
has_function_privilege checks whether a user can access a function in a particular way. The
possibilities for its arguments are analogous to has_table_privilege. When specifying a function by a
text string rather than by OID, the allowed input is the same as for the regprocedure data type (see
Seção 8.12). The desired access privilege type must evaluate to EXECUTE. An example is:
SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
has_language_privilege checks whether a user can access a procedural language in a particular

way. The possibilities for its arguments are analogous to has_table_privilege. The desired access
privilege type must evaluate to USAGE.
has_schema_privilege checks whether a user can access a schema in a particular way. The
type must evaluate to CREATE or USAGE.
has_table_privilege checks whether a user can access a table in a particular way. The user can be
specified by name or by OID (pg_authid.oid), or if the argument is omitted current_user is
assumed. The table can be specified by name or by OID. (Thus, there are actually six variants of
has_table_privilege, which can be distinguished by the number and types of their arguments.)
When specifying by name, the name can be schema-qualified if necessary. The desired access
privilege type is specified by a text string, which must evaluate to one of the values SELECT,
INSERT, UPDATE, DELETE, REFERENCES, or TRIGGER. (Case of the string is not significant,
however.) An example is:
SELECT has_table_privilege('myschema.mytable', 'select');
has_tablespace_privilege checks whether a user can access a tablespace in a particular way. The
type must evaluate to CREATE.
pg_has_role checks whether a user can access a role in a particular way. The possibilities for its
arguments are analogous to has_table_privilege. The desired access privilege type must evaluate to
MEMBER or USAGE. MEMBER denotes direct or indirect membership in the role (that is, the right to
do SET ROLE), while USAGE denotes whether the privileges of the role are immediately available
without doing SET ROLE.
To test whether a user holds a grant option on the privilege, append WITH GRANT OPTION to the
privilege key word; for example 'UPDATE WITH GRANT OPTION'.
Tabela 9-42 shows functions that determine whether a certain object is visible in the current schema
search path. A table is said to be visible if its containing schema is in the search path and no table
of the same name appears earlier in the search path. This is equivalent to the statement that the
table can be referenced by name without explicit schema qualification. For example, to list the
names of all visible tables:
SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
Tabela 9-42. Schema Visibility Inquiry Functions

pg_conversion_is_visible(conversion_oid) boolean is conversion visible in search path
pg_function_is_visible(function_oid) boolean is function visible in search path
pg_operator_is_visible(operator_oid) boolean is operator visible in search path
pg_opclass_is_visible(opclass_oid) boolean is operator class visible in search path
pg_table_is_visible(table_oid) boolean is table visible in search path
pg_type_is_visible(type_oid) boolean is type (or domain) visible in search path
pg_conversion_is_visible, pg_function_is_visible, pg_operator_is_visible, pg_opclass_is_visible,

pg_table_is_visible, and pg_type_is_visible perform the visibility check for conversions, functions,
operators, operator classes, tables, and types. Note that pg_table_is_visible can also be used with
views, indexes and sequences; pg_type_is_visible can also be used with domains. For functions and
operators, an object in the search path is visible if there is no object of the same name and
argument data type(s) earlier in the path. For operator classes, both name and associated index
access method are considered.
All these functions require object OIDs to identify the object to be checked. If you want to test an
object by name, it is convenient to use the OID alias types (regclass, regtype, regprocedure, or
regoperator), for example
SELECT pg_type_is_visible('myschema.widget'::regtype);
Note that it would not make much sense to test an unqualified name in this way — if the name can
be recognized at all, it must be visible.
Tabela 9-43 lists functions that extract information from the system catalogs.
Tabela 9-43. System Catalog Information Functions
Return
Name Description
Type
format_type(type_oid, typemod) text get SQL name of a data type
pg_get_constraintdef(constraint_oid) text get definition of a constraint
pg_get_constraintdef(constraint_oid, text get definition of a constraint
pretty_bool)
pg_get_expr(expr_text, relation_oid) text decompile internal form of an expression,
assuming that any Vars in it refer to the relation
indicated by the second parameter
pg_get_expr(expr_text, relation_oid, text decompile internal form of an expression,
pretty_bool) assuming that any Vars in it refer to the relation
indicated by the second parameter
pg_get_indexdef(index_oid) text get CREATE INDEX command for index
pg_get_indexdef(index_oid, column_no, text get CREATE INDEX command for index, or
pretty_bool) definition of just one index column when
column_no is not zero
pg_get_ruledef(rule_oid) text get CREATE RULE command for rule
pg_get_ruledef(rule_oid, pretty_bool) text get CREATE RULE command for rule
pg_get_serial_sequence(table_name, text get name of the sequence that a serial or bigserial
column_name) column uses
pg_get_triggerdef(trigger_oid) text get CREATE [ CONSTRAINT ] TRIGGER command
for trigger
pg_get_userbyid(roleid) name get role name with given ID
pg_get_viewdef(view_name) text get underlying SELECT command for view
(deprecated)
pg_get_viewdef(view_name, pretty_bool) text get underlying SELECT command for view
(deprecated)
pg_get_viewdef(view_oid) text get underlying SELECT command for view
pg_get_viewdef(view_oid, pretty_bool) text get underlying SELECT command for view
pg_tablespace_databases(tablespace_oid) setof get the set of database OIDs that have objects in
oid the tablespace
format_type returns the SQL name of a data type that is identified by its type OID and possibly a
type modifier. Pass NULL for the type modifier if no specific modifier is known.
pg_get_constraintdef, pg_get_indexdef, pg_get_ruledef, and pg_get_triggerdef, respectively

reconstruct the creating command for a constraint, index, rule, or trigger. (Note that this is a
decompiled reconstruction, not the original text of the command.) pg_get_expr decompiles the
internal form of an individual expression, such as the default value for a column. It may be useful
when examining the contents of system catalogs. pg_get_viewdef reconstructs the SELECT query
that defines a view. Most of these functions come in two variants, one of which can optionally
"pretty-print" the result. The pretty-printed format is more readable, but the default format is more
likely to be interpreted the same way by future versions of PostgreSQL; avoid using pretty-printed
output for dump purposes. Passing false for the pretty-print parameter yields the same result as the
variant that does not have the parameter at all.
pg_get_serial_sequence fetches the name of the sequence associated with a column, or NULL if
there is no sequence associated with the column. The result is suitably formatted for passing to the
sequence functions (see Seção 9.12). This association can be modified or removed with ALTER
SEQUENCE OWNED BY. (The function probably should have been called pg_get_owned_sequence;
its name reflects the fact that it's typically used with serial or bigserial columns.)
pg_get_userbyid extracts a role's name given its OID.
pg_tablespace_databases allows a tablespace to be examined. It returns the set of OIDs of

databases that have objects stored in the tablespace. If this function returns any rows, the
tablespace is not empty and cannot be dropped. To display the specific objects populating the
tablespace, you will need to connect to the databases identified by pg_tablespace_databases and
query their pg_class catalogs.
The functions shown in Tabela 9-44 extract comments previously stored with the COMMENT
command. A null value is returned if no comment could be found matching the specified
parameters.
Tabela 9-44. Comment Information Functions
Return
Name Description
Type
col_description(table_oid, text get comment for a table column
column_number)
obj_description(object_oid, text get comment for a database object
catalog_name)
obj_description(object_oid) text get comment for a database object
(deprecated)
shobj_description(object_oid, text get comment for a shared database object
catalog_name)
col_description returns the comment for a table column, which is specified by the OID of its table
and its column number. obj_description cannot be used for table columns since columns do not
have OIDs of their own.
The two-parameter form of obj_description returns the comment for a database object specified by
its OID and the name of the containing system catalog. For example,
obj_description(123456,'pg_class') would retrieve the comment for a table with OID 123456. The
one-parameter form of obj_description requires only the object OID. It is now deprecated since
there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong
comment could be returned.
shobj_description is used just like obj_description only that it is used for retrieving comments on
shared objects. Some system catalogs are global to all databases within each cluster and their
descriptions are stored globally as well.

Set Returning Functions Acima System Administration Functions
System Administration Functions


Tabela 9-45 shows the functions available to query and alter run-time configuration parameters.
Tabela 9-45. Configuration Settings Functions

current_setting(setting_name) text current value of setting
set_config(setting_name, new_value, is_local) text set parameter and return new value
The function current_setting yields the current value of the setting setting_name. It corresponds to
the SQL command SHOW. An example:
SELECT current_setting('datestyle');
current_setting
-----------------
ISO, MDY
(1 row)
set_config sets the parameter setting_name to new_value. If is_local is true, the new value will
only apply to the current transaction. If you want the new value to apply for the current session,
use false instead. The function corresponds to the SQL command SET. An example:
SELECT set_config('log_statement_stats', 'off', false);

set_config
------------
off
(1 row)
The functions shown in Tabela 9-46 send control signals to other server processes. Use of these
functions is restricted to superusers.
Tabela 9-46. Server Signalling Functions

pg_cancel_backend(pid int) boolean Cancel a backend's current query
pg_reload_conf() boolean Cause server processes to reload their configuration files
pg_rotate_logfile() boolean Rotate server's log file
Each of these functions returns true if successful and false otherwise.
pg_cancel_backend sends a query cancel (SIGINT) signal to a backend process identified by process
ID. The process ID of an active backend can be found from the procpid column in the
pg_stat_activity view, or by listing the postgres processes on the server with ps.
pg_reload_conf sends a SIGHUP signal to the server, causing the configuration files to be reloaded
by all server processes.
pg_rotate_logfile signals the log-file manager to switch to a new output file immediately. This works
http://pgdocptbr.sourceforge.net/pg82/functions-admin.html[09/02/2018 18:09:24]
only when redirect_stderr is used for logging, since otherwise there is no log-file manager
subprocess.
The functions shown in Tabela 9-47 assist in making on-line backups. Use of the first three functions
is restricted to superusers.
Tabela 9-47. Backup Control Functions
Return
Name Description
Type
pg_start_backup(label text) text Set up for performing on-line backup
pg_stop_backup() text Finish performing on-line backup
pg_switch_xlog() text Force switch to a new transaction log file
pg_current_xlog_location() text Get current transaction log write location
pg_current_xlog_insert_location() text Get current transaction log insert location
pg_xlogfile_name_offset(location text, Convert transaction log location string to file name and
text) integer decimal byte offset within file
pg_xlogfile_name(location text) text Convert transaction log location string to file name
pg_start_backup accepts a single parameter which is an arbitrary user-defined label for the backup.
(Typically this would be the name under which the backup dump file will be stored.) The function
writes a backup label file into the database cluster's data directory, and then returns the backup's
starting transaction log location as text. The user need not pay any attention to this result value,
but it is provided in case it is of use.
postgres=# select pg_start_backup('label_goes_here');

pg_start_backup
-----------------
0/D4445B8
(1 row)
pg_stop_backup removes the label file created by pg_start_backup, and instead creates a backup
history file in the transaction log archive area. The history file includes the label given to
pg_start_backup, the starting and ending transaction log locations for the backup, and the starting
and ending times of the backup. The return value is the backup's ending transaction log location
(which again may be of little interest). After noting the ending location, the current transaction log
insertion point is automatically advanced to the next transaction log file, so that the ending
transaction log file can be archived immediately to complete the backup.
pg_switch_xlog moves to the next transaction log file, allowing the current file to be archived
(assuming you are using continuous archiving). The result is the ending transaction log location
within the just-completed transaction log file. If there has been no transaction log activity since the
last transaction log switch, pg_switch_xlog does nothing and returns the end location of the
previous transaction log file.
pg_current_xlog_location displays the current transaction log write location in the same format
used by the above functions. Similarly pg_current_xlog_insert_location displays the current
transaction log insertion point. The insertion point is the "logical" end of transaction log at any
instant, while the write location is the end of what has actually been written out from the server's
internal buffers. The write location is the end of what can be examined from outside the server, and
is usually what you want if you are interested in archiving partially-complete transaction log files.
The insertion point is made available primarily for server debugging purposes. These are both read-
only operations and do not require superuser permissions.
You can use pg_xlogfile_name_offset to extract the corresponding transaction log file name and
byte offset from the results of any of the above functions. For example:
postgres=# select * from pg_xlogfile_name_offset(pg_stop_backup());

file_name | file_offset
--------------------------+-------------
00000001000000000000000D | 4039624
(1 row)
Similarly, pg_xlogfile_name extracts just the transaction log file name. When the given transction
log location is exactly at an transaction log file boundary, both these functions return the name of
the preceding transaction log file. This is usually the desired behavior for managing transaction log
archiving behavior, since the preceding file is the last one that currently needs to be archived.
For details about proper usage of these functions, see Seção 23.3.
The functions shown in Tabela 9-48 calculate the actual disk space usage of database objects.
Tabela 9-48. Database Object Size Functions
Return
Name Description
Type
pg_column_size(any) int Number of bytes used to store a particular value (possibly
compressed)
pg_database_size(oid) bigint Disk space used by the database with the specified OID
pg_database_size(name) bigint Disk space used by the database with the specified name
pg_relation_size(oid) bigint Disk space used by the table or index with the specified OID
pg_relation_size(text) bigint Disk space used by the table or index with the specified name.
The table name may be qualified with a schema name
pg_size_pretty(bigint) text Converts a size in bytes into a human-readable format with size
units
pg_tablespace_size(oid) bigint Disk space used by the tablespace with the specified OID
pg_tablespace_size(name) bigint Disk space used by the tablespace with the specified name
pg_total_relation_size(oid) bigint Total disk space used by the table with the specified OID,
including indexes and toasted data
pg_total_relation_size(text) bigint Total disk space used by the table with the specified name,
including indexes and toasted data. The table name may be
qualified with a schema name
pg_column_size shows the space used to store any individual data value.
pg_database_size and pg_tablespace_size accept the OID or name of a database or tablespace, and
return the total disk space used therein.
pg_relation_size accepts the OID or name of a table, index or toast table, and returns the size in
bytes.
pg_size_pretty can be used to format the result of one of the other functions in a human-readable
way, using kB, MB, GB or TB as appropriate.
pg_total_relation_size accepts the OID or name of a table or toast table, and returns the size in
bytes of the data and all associated indexes and toast tables.
The functions shown in Tabela 9-49 provide native file access to files on the machine hosting the
server. Only files within the database cluster directory and the log_directory may be accessed. Use
a relative path for files within the cluster directory, and a path matching the log_directory
configuration setting for log files. Use of these functions is restricted to superusers.
Tabela 9-49. Generic File Access Functions

pg_ls_dir(dirname text) setof text List the contents of a directory
pg_read_file(filename text, offset bigint, length text Return the contents of a text file
bigint)
pg_stat_file(filename text) record Return information about a file
pg_ls_dir returns all the names in the specified directory, except the special entries "." and "..".
pg_read_file returns part of a text file, starting at the given offset, returning at most length bytes
(less if the end of file is reached first). If offset is negative, it is relative to the end of the file.
pg_stat_file returns a record containing the file size, last accessed time stamp, last modified time
stamp, last file status change time stamp (Unix platforms only), file creation time stamp (Windows
only), and a boolean indicating if it is a directory. Typical usages include:
SELECT * FROM pg_stat_file('filename');

SELECT (pg_stat_file('filename')).modification;
The functions shown in Tabela 9-50 manage advisory locks. For details about proper usage of these
functions, see Seção 12.3.4.
Tabela 9-50. Advisory Lock Functions
Return
Name Description
Type
pg_advisory_lock(key bigint) void Obtain exclusive advisory lock
pg_advisory_lock(key1 int, key2 int) void Obtain exclusive advisory lock
pg_advisory_lock_shared(key bigint) void Obtain shared advisory lock
pg_advisory_lock_shared(key1 int, key2 void Obtain shared advisory lock
int)
pg_try_advisory_lock(key bigint) boolean Obtain exclusive advisory lock if available
pg_try_advisory_lock(key1 int, key2 int) boolean Obtain exclusive advisory lock if available
pg_try_advisory_lock_shared(key bigint) boolean Obtain shared advisory lock if available
pg_try_advisory_lock_shared(key1 int, boolean Obtain shared advisory lock if available
key2 int)
pg_advisory_unlock(key bigint) boolean Release an exclusive advisory lock
pg_advisory_unlock(key1 int, key2 int) boolean Release an exclusive advisory lock
pg_advisory_unlock_shared(key bigint) boolean Release a shared advisory lock
pg_advisory_unlock_shared(key1 int, boolean Release a shared advisory lock
key2 int)
pg_advisory_unlock_all() void Release all advisory locks held by the current
session
pg_advisory_lock locks an application-defined resource, which may be identified either by a single

64-bit key value or two 32-bit key values (note that these two key spaces do not overlap). If
another session already holds a lock on the same resource, the function will wait until the resource
becomes available. The lock is exclusive. Multiple lock requests stack, so that if the same resource
is locked three times it must be also unlocked three times to be released for other sessions' use.
pg_advisory_lock_shared works the same as pg_advisory_lock, except the lock can be shared with
other sessions requesting shared locks. Only would-be exclusive lockers are locked out.
pg_try_advisory_lock is similar to pg_advisory_lock, except the function will not wait for the lock to
become available. It will either obtain the lock immediately and return true, or return false if the
lock cannot be acquired now.
pg_try_advisory_lock_shared works the same as pg_try_advisory_lock, except it attempts to

acquire shared rather than exclusive lock.
pg_advisory_unlock will release a previously-acquired exclusive advisory lock. It will return true if
the lock is successfully released. If the lock was in fact not held, it will return false, and in addition,
an SQL warning will be raised by the server.
pg_advisory_unlock_shared works the same as pg_advisory_unlock, except to release a shared

advisory lock.
pg_advisory_unlock_all will release all advisory locks held by the current session. (This function is
implicitly invoked at session end, even if the client disconnects ungracefully.)

System Information Functions Acima Type Conversion
Type Conversion

Capítulo 10. Type Conversion

Sumário
10.1. Visão geral
10.2. Operators
10.3. Functions
10.4. Value Storage
SQL statements can, intentionally or not, require mixing of different data types in the same
expression. PostgreSQL has extensive facilities for evaluating mixed-type expressions.
In many cases a user will not need to understand the details of the type conversion mechanism.
However, the implicit conversions done by PostgreSQL can affect the results of a query. When
necessary, these results can be tailored by using explicit type conversion.
This chapter introduces the PostgreSQL type conversion mechanisms and conventions. Refer to the
relevant sections in Capítulo 8 and Capítulo 9 for more information on specific data types and allowed
functions and operators.

System Administration Functions Acima Visão geral
http://pgdocptbr.sourceforge.net/pg82/typeconv.html[09/02/2018 18:09:36]
Visão geral

Anterior Início Capítulo 10. Type Conversion Fim Próxima
10.1. Visão geral

SQL is a strongly typed language. That is, every data item has an associated data type which
determines its behavior and allowed usage. PostgreSQL has an extensible type system that is much
more general and flexible than other SQL implementations. Hence, most type conversion behavior
in PostgreSQL is governed by general rules rather than by ad hoc heuristics. This allows mixed-type
expressions to be meaningful even with user-defined types.
The PostgreSQL scanner/parser divides lexical elements into only five fundamental categories:
integers, non-integer numbers, strings, identifiers, and key words. Constants of most non-numeric
types are first classified as strings. The SQL language definition allows specifying type names with
strings, and this mechanism can be used in PostgreSQL to start the parser down the correct path.
For example, the query
SELECT text 'Origin' AS "label", point '(0,0)' AS "value";

label | value
--------+-------
Origin | (0,0)
(1 row)
has two literal constants, of type text and point. If a type is not specified for a string literal, then
the placeholder type unknown is assigned initially, to be resolved in later stages as described below.
There are four fundamental SQL constructs requiring distinct type conversion rules in the
PostgreSQL parser:
Function calls
Much of the PostgreSQL type system is built around a rich set of functions. Functions can have
one or more arguments. Since PostgreSQL permits function overloading, the function name
alone does not uniquely identify the function to be called; the parser must select the right
function based on the data types of the supplied arguments.
Operators
PostgreSQL allows expressions with prefix and postfix unary (one-argument) operators, as
well as binary (two-argument) operators. Like functions, operators can be overloaded, and so
the same problem of selecting the right operator exists.
Value Storage
SQL INSERT and UPDATE statements place the results of expressions into a table. The
expressions in the statement must be matched up with, and perhaps converted to, the types
of the target columns.
UNION, CASE, and related constructs
Since all query results from a unionized SELECT statement must appear in a single set of
columns, the types of the results of each SELECT clause must be matched up and converted
to a uniform set. Similarly, the result expressions of a CASE construct must be converted to a
common type so that the CASE expression as a whole has a known output type. The same
holds for ARRAY constructs, and for the GREATEST and LEAST functions.
The system catalogs store information about which conversions, called casts, between data types
http://pgdocptbr.sourceforge.net/pg82/typeconv-overview.html[09/02/2018 18:10:16]
Visão geral
are valid, and how to perform those conversions. Additional casts can be added by the user with the
CREATE CAST command. (This is usually done in conjunction with defining new data types. The set
of casts between the built-in types has been carefully crafted and is best not altered.)
An additional heuristic is provided in the parser to allow better guesses at proper behavior for SQL
standard types. There are several basic type categories defined: boolean, numeric, string, bitstring,
datetime, timespan, geometric, network, and user-defined. Each category, with the exception of
user-defined, has one or more preferred types which are preferentially selected when there is
ambiguity. In the user-defined category, each type is its own preferred type. Ambiguous
expressions (those with multiple candidate parsing solutions) can therefore often be resolved when
there are multiple possible built-in types, but they will raise an error when there are multiple
choices for user-defined types.
All type conversion rules are designed with several principles in mind:
Implicit conversions should never have surprising or unpredictable outcomes.
User-defined types, of which the parser has no a priori knowledge, should be "higher" in the
type hierarchy. In mixed-type expressions, native types shall always be converted to a user-
defined type (of course, only if conversion is necessary).
User-defined types are not related. Currently, PostgreSQL does not have information available
to it on relationships between types, other than hardcoded heuristics for built-in types and
implicit relationships based on available functions and casts.
There should be no extra overhead from the parser or executor if a query does not need
implicit type conversion. That is, if a query is well formulated and the types already match up,
then the query should proceed without spending extra time in the parser and without
introducing unnecessary implicit conversion calls into the query.
Additionally, if a query usually requires an implicit conversion for a function, and if then the
user defines a new function with the correct argument types, the parser should use this new
function and will no longer do the implicit conversion using the old function.

Type Conversion Acima Operators
http://pgdocptbr.sourceforge.net/pg82/typeconv-overview.html[09/02/2018 18:10:16]
Operators

10.2. Operators
The specific operator to be used in an operator invocation is determined by following the procedure
below. Note that this procedure is indirectly affected by the precedence of the involved operators.
See Seção 4.1.6 for more information.
Operator Type Resolution
1. Select the operators to be considered from the pg_operator system catalog. If an unqualified
operator name was used (the usual case), the operators considered are those of the right
name and argument count that are visible in the current search path (see Seção 5.7.3). If a
qualified operator name was given, only operators in the specified schema are considered.
a. If the search path finds multiple operators of identical argument types, only the one
appearing earliest in the path is considered. But operators of different argument types
are considered on an equal footing regardless of search path position.
2. Check for an operator accepting exactly the input argument types. If one exists (there can be
only one exact match in the set of operators considered), use it.
a. If one argument of a binary operator invocation is of the unknown type, then assume it
is the same type as the other argument for this check. Other cases involving unknown
will never find a match at this step.
3. Look for the best match.
a. Discard candidate operators for which the input types do not match and cannot be
converted (using an implicit conversion) to match. unknown literals are assumed to be
convertible to anything for this purpose. If only one candidate remains, use it; else
continue to the next step.
b. Run through all candidates and keep those with the most exact matches on input types.
(Domains are considered the same as their base type for this purpose.) Keep all
candidates if none have any exact matches. If only one candidate remains, use it; else
c. Run through all candidates and keep those that accept preferred types (of the input data
type's type category) at the most positions where type conversion will be required. Keep
all candidates if none accept preferred types. If only one candidate remains, use it; else
d. If any input arguments are unknown, check the type categories accepted at those
argument positions by the remaining candidates. At each position, select the string
category if any candidate accepts that category. (This bias towards string is appropriate
since an unknown-type literal does look like a string.) Otherwise, if all the remaining
candidates accept the same type category, select that category; otherwise fail because
the correct choice cannot be deduced without more clues. Now discard candidates that
do not accept the selected type category. Furthermore, if any candidate accepts a
preferred type at a given argument position, discard candidates that accept non-
preferred types for that argument.
e. If only one candidate remains, use it. If no candidate or more than one candidate
remains, then fail.
http://pgdocptbr.sourceforge.net/pg82/typeconv-oper.html[09/02/2018 18:10:25]
Operators
Some examples follow.
Exemplo 10-1. Exponentiation Operator Type Resolution
There is only one exponentiation operator defined in the catalog, and it takes arguments of type
double precision. The scanner assigns an initial type of integer to both arguments of this query
expression:
SELECT 2 ^ 3 AS "exp";
exp
-----
8
(1 row)
So the parser does a type conversion on both operands and the query is equivalent to
SELECT CAST(2 AS double precision) ^ CAST(3 AS double precision) AS "exp";
Exemplo 10-2. String Concatenation Operator Type Resolution
A string-like syntax is used for working with string types as well as for working with complex
extension types. Strings with unspecified type are matched with likely operator candidates.
An example with one unspecified argument:
SELECT text 'abc' || 'def' AS "text and unknown";

text and unknown
------------------
abcdef
(1 row)
In this case the parser looks to see if there is an operator taking text for both arguments. Since
there is, it assumes that the second argument should be interpreted as of type text.
Here is a concatenation on unspecified types:
SELECT 'abc' || 'def' AS "unspecified";

unspecified
-------------
abcdef
(1 row)
In this case there is no initial hint for which type to use, since no types are specified in the
query. So, the parser looks for all candidate operators and finds that there are candidates
accepting both string-category and bit-string-category inputs. Since string category is preferred
when available, that category is selected, and then the preferred type for strings, text, is used
as the specific type to resolve the unknown literals to.
Exemplo 10-3. Absolute-Value and Negation Operator Type Resolution
The PostgreSQL operator catalog has several entries for the prefix operator @, all of which
implement absolute-value operations for various numeric data types. One of these entries is for
type float8, which is the preferred type in the numeric category. Therefore, PostgreSQL will use
that entry when faced with a non-numeric input:
SELECT @ '-4.5' AS "abs";

abs
-----
4.5
(1 row)
Operators
Here the system has performed an implicit conversion from text to float8 before applying the
chosen operator. We can verify that float8 and not some other type was used:
SELECT @ '-4.5e500' AS "abs";

ERROR: "-4.5e500" is out of range for type double precision
On the other hand, the prefix operator ~ (bitwise negation) is defined only for integer data
types, not for float8. So, if we try a similar case with ~, we get:
SELECT ~ '20' AS "negation";

ERROR: operator is not unique: ~ "unknown"
HINT: Could not choose a best candidate operator. You may need to add explicit
type casts.
This happens because the system can't decide which of the several possible ~ operators should
be preferred. We can help it out with an explicit cast:
SELECT ~ CAST('20' AS int8) AS "negation";

negation
----------
-21
(1 row)

Visão geral Acima Functions
Functions

10.3. Functions
The specific function to be used in a function invocation is determined according to the following
steps.
Function Type Resolution
1. Select the functions to be considered from the pg_proc system catalog. If an unqualified
function name was used, the functions considered are those of the right name and argument
count that are visible in the current search path (see Seção 5.7.3). If a qualified function name
was given, only functions in the specified schema are considered.
a. If the search path finds multiple functions of identical argument types, only the one
appearing earliest in the path is considered. But functions of different argument types
are considered on an equal footing regardless of search path position.
2. Check for a function accepting exactly the input argument types. If one exists (there can be
only one exact match in the set of functions considered), use it. (Cases involving unknown will
never find a match at this step.)
3. If no exact match is found, see whether the function call appears to be a trivial type
conversion request. This happens if the function call has just one argument and the function
name is the same as the (internal) name of some data type. Furthermore, the function
argument must be either an unknown-type literal or a type that is binary-compatible with the
named data type. When these conditions are met, the function argument is converted to the
named data type without any actual function call.
4. Look for the best match.
a. Discard candidate functions for which the input types do not match and cannot be
converted (using an implicit conversion) to match. unknown literals are assumed to be
convertible to anything for this purpose. If only one candidate remains, use it; else
b. Run through all candidates and keep those with the most exact matches on input types.
(Domains are considered the same as their base type for this purpose.) Keep all
candidates if none have any exact matches. If only one candidate remains, use it; else
c. Run through all candidates and keep those that accept preferred types (of the input data
type's type category) at the most positions where type conversion will be required. Keep
all candidates if none accept preferred types. If only one candidate remains, use it; else
d. If any input arguments are unknown, check the type categories accepted at those
argument positions by the remaining candidates. At each position, select the string
category if any candidate accepts that category. (This bias towards string is appropriate
since an unknown-type literal does look like a string.) Otherwise, if all the remaining
candidates accept the same type category, select that category; otherwise fail because
the correct choice cannot be deduced without more clues. Now discard candidates that
do not accept the selected type category. Furthermore, if any candidate accepts a
preferred type at a given argument position, discard candidates that accept non-
preferred types for that argument.
http://pgdocptbr.sourceforge.net/pg82/typeconv-func.html[09/02/2018 18:10:35]
Functions
e. If only one candidate remains, use it. If no candidate or more than one candidate
remains, then fail.
Note that the "best match" rules are identical for operator and function type resolution. Some
examples follow.
Exemplo 10-4. Rounding Function Argument Type Resolution
There is only one round function with two arguments. (The first is numeric, the second is
integer.) So the following query automatically converts the first argument of type integer to
numeric:
SELECT round(4, 4);

round
--------
4.0000
(1 row)
That query is actually transformed by the parser to
SELECT round(CAST (4 AS numeric), 4);
Since numeric constants with decimal points are initially assigned the type numeric, the
following query will require no type conversion and may therefore be slightly more efficient:
SELECT round(4.0, 4);
Exemplo 10-5. Substring Function Type Resolution
There are several substr functions, one of which takes types text and integer. If called with a
string constant of unspecified type, the system chooses the candidate function that accepts an
argument of the preferred category string (namely of type text).
SELECT substr('1234', 3);

substr
--------
34
(1 row)
If the string is declared to be of type varchar, as might be the case if it comes from a table, then
the parser will try to convert it to become text:
SELECT substr(varchar '1234', 3);

substr
--------
34
(1 row)
This is transformed by the parser to effectively become
SELECT substr(CAST (varchar '1234' AS text), 3);
Nota: The parser learns from the pg_cast catalog that text and varchar are binary-
compatible, meaning that one can be passed to a function that accepts the other
without doing any physical conversion. Therefore, no explicit type conversion call is
really inserted in this case.
And, if the function is called with an argument of type integer, the parser will try to convert that
Functions
to text:
SELECT substr(1234, 3);

substr
--------
34
(1 row)
This actually executes as
SELECT substr(CAST (1234 AS text), 3);
This automatic transformation can succeed because there is an implicitly invocable cast from
integer to text.

Operators Acima Value Storage
Value Storage

10.4. Value Storage

Values to be inserted into a table are converted to the destination column's data type according to
the following steps.
Value Storage Type Conversion
1. Check for an exact match with the target.
2. Otherwise, try to convert the expression to the target type. This will succeed if there is a
registered cast between the two types. If the expression is an unknown-type literal, the
contents of the literal string will be fed to the input conversion routine for the target type.
3. Check to see if there is a sizing cast for the target type. A sizing cast is a cast from that type
to itself. If one is found in the pg_cast catalog, apply it to the expression before storing into
the destination column. The implementation function for such a cast always takes an extra
parameter of type integer, which receives the destination column's declared length (actually,
its atttypmod value; the interpretation of atttypmod varies for different data types). The cast
function is responsible for applying any length-dependent semantics such as size checking or
truncation.
Exemplo 10-6. character Storage Type Conversion
For a target column declared as character(20) the following statement ensures that the stored
value is sized correctly:
CREATE TABLE vv (v character(20));

INSERT INTO vv SELECT 'abc' || 'def';
SELECT v, length(v) FROM vv;
v | length
----------------------+--------
abcdef | 20
(1 row)
What has really happened here is that the two unknown literals are resolved to text by default,
allowing the || operator to be resolved as text concatenation. Then the text result of the
operator is converted to bpchar ("blank-padded char", the internal name of the character data
type) to match the target column type. (Since the types text and bpchar are binary-compatible,
this conversion does not insert any real function call.) Finally, the sizing function bpchar(bpchar,
integer) is found in the system catalog and applied to the operator's result and the stored
column length. This type-specific function performs the required length check and addition of
padding spaces.

Functions Acima UNION, CASE, and Related
Constructs
http://pgdocptbr.sourceforge.net/pg82/typeconv-query.html[09/02/2018 18:10:43]
UNION, CASE, and Related Constructs


SQL UNION constructs must match up possibly dissimilar types to become a single result set. The
resolution algorithm is applied separately to each output column of a union query. The INTERSECT
and EXCEPT constructs resolve dissimilar types in the same way as UNION. The CASE, ARRAY,
VALUES, GREATEST and LEAST constructs use the identical algorithm to match up their component
expressions and select a result data type.
Type Resolution for UNION, CASE, and Related Constructs
1. If all inputs are of type unknown, resolve as type text (the preferred type of the string
category). Otherwise, ignore the unknown inputs while choosing the result type.
2. If the non-unknown inputs are not all of the same type category, fail.
3. Choose the first non-unknown input type which is a preferred type in that category or allows
all the non-unknown inputs to be implicitly converted to it.
4. Convert all inputs to the selected type.
Some examples follow.
Exemplo 10-7. Type Resolution with Underspecified Types in a Union
SELECT text 'a' AS "text" UNION SELECT 'b';

text
------
a
b
(2 rows)
Here, the unknown-type literal 'b' will be resolved as type text.
Exemplo 10-8. Type Resolution in a Simple Union
SELECT 1.2 AS "numeric" UNION SELECT 1;

numeric
---------
1
1.2
(2 rows)
The literal 1.2 is of type numeric, and the integer value 1 can be cast implicitly to numeric, so
that type is used.
Exemplo 10-9. Type Resolution in a Transposed Union
SELECT 1 AS "real" UNION SELECT CAST('2.2' AS REAL);

real
------
1
2.2
(2 rows)
http://pgdocptbr.sourceforge.net/pg82/typeconv-union-case.html[09/02/2018 18:10:51]
UNION, CASE, and Related Constructs
Here, since type real cannot be implicitly cast to integer, but integer can be implicitly cast to
real, the union result type is resolved as real.

Value Storage Acima Indexes
http://pgdocptbr.sourceforge.net/pg82/typeconv-union-case.html[09/02/2018 18:10:51]
Indexes

Capítulo 11. Indexes

Sumário
11.1. Introdução
11.2. Index Types
Indexes are a common way to enhance database performance. An index allows the database server
to find and retrieve specific rows much faster than it could do without an index. But indexes also
add overhead to the database system as a whole, so they should be used sensibly.

UNION, CASE, and Related Acima Introdução
Constructs
http://pgdocptbr.sourceforge.net/pg82/indexes.html[09/02/2018 18:11:05]
Introdução

Anterior Início Capítulo 11. Indexes Fim Próxima
11.1. Introdução
Suppose we have a table similar to this:
CREATE TABLE test1 (

id integer,
content varchar
);
and the application requires a lot of queries of the form
SELECT content FROM test1 WHERE id = constante;
With no advance preparation, the system would have to scan the entire test1 table, row by row, to
find all matching entries. If there are a lot of rows in test1 and only a few rows (perhaps only zero
or one) that would be returned by such a query, then this is clearly an inefficient method. But if the
system has been instructed to maintain an index on the id column, then it can use a more efficient
method for locating matching rows. For instance, it might only have to walk a few levels deep into a
search tree.
A similar approach is used in most books of non-fiction: terms and concepts that are frequently
looked up by readers are collected in an alphabetic index at the end of the book. The interested
reader can scan the index relatively quickly and flip to the appropriate page(s), rather than having
to read the entire book to find the material of interest. Just as it is the task of the author to
anticipate the items that the readers are likely to look up, it is the task of the database programmer
to foresee which indexes will be of advantage.
The following command would be used to create the index on the id column, as discussed:
CREATE INDEX test1_id_index ON test1 (id);
The name test1_id_index can be chosen freely, but you should pick something that enables you to
remember later what the index was for.
To remove an index, use the DROP INDEX command. Indexes can be added to and removed from
tables at any time.
Once an index is created, no further intervention is required: the system will update the index when
the table is modified, and it will use the index in queries when it thinks this would be more efficient
than a sequential table scan. But you may have to run the ANALYZE command regularly to update
statistics to allow the query planner to make educated decisions. See Capítulo 13 for information
about how to find out whether an index is used and when and why the planner may choose not to
use an index.
Indexes can also benefit UPDATE and DELETE commands with search conditions. Indexes can
moreover be used in join searches. Thus, an index defined on a column that is part of a join
condition can significantly speed up queries with joins.
Creating an index on a large table can take a long time. By default, PostgreSQL allows reads
(selects) to occur on the table in parallel with creation of an index, but writes (inserts, updates,
deletes) are blocked until the index build is finished. In production environments this is often
http://pgdocptbr.sourceforge.net/pg82/indexes-intro.html[09/02/2018 18:11:13]
Introdução
unacceptable. It is possible to allow writes to occur in parallel with index creation, but there are
several caveats to be aware of — for more information see Construção de índice CONCURRENTLY.
After an index is created, the system has to keep it synchronized with the table. This adds overhead
to data manipulation operations. Therefore indexes that are seldom or never used in queries should
be removed.

Indexes Acima Index Types
http://pgdocptbr.sourceforge.net/pg82/indexes-intro.html[09/02/2018 18:11:13]
Index Types

11.2. Index Types

PostgreSQL provides several index types: B-tree, Hash, GiST and GIN. Each index type uses a
different algorithm that is best suited to different types of queries. By default, the CREATE INDEX
command will create a B-tree index, which fits the most common situations.
B-trees can handle equality and range queries on data that can be sorted into some ordering. In
particular, the PostgreSQL query planner will consider using a B-tree index whenever an indexed
column is involved in a comparison using one of these operators:
<
<=
=
>=
>
Constructs equivalent to combinations of these operators, such as BETWEEN and IN, can also be
implemented with a B-tree index search. (But note that IS NULL is not equivalent to = and is not
indexable.)
The optimizer can also use a B-tree index for queries involving the pattern matching operators LIKE
and ~ if the pattern is a constant and is anchored to the beginning of the string — for example, col
LIKE 'foo%' or col ~ '^foo', but not col LIKE '%bar'. However, if your server does not use the C
locale you will need to create the index with a special operator class to support indexing of pattern-
matching queries. See Seção 11.8 below. It is also possible to use B-tree indexes for ILIKE and ~*,
but only if the pattern starts with non-alphabetic characters, i.e. characters that are not affected by
upper/lower case conversion.
Hash indexes can only handle simple equality comparisons. The query planner will consider using a
hash index whenever an indexed column is involved in a comparison using the = operator. The
following command is used to create a hash index:
CREATE INDEX nome ON tabela USING hash (coluna);
Nota: Testing has shown PostgreSQL's hash indexes to perform no better than B-tree
indexes, and the index size and build time for hash indexes is much worse. Furthermore,
hash index operations are not presently WAL-logged, so hash indexes may need to be
rebuilt with REINDEX after a database crash. For these reasons, hash index use is
presently discouraged.
GiST indexes are not a single kind of index, but rather an infrastructure within which many
different indexing strategies can be implemented. Accordingly, the particular operators with which a
GiST index can be used vary depending on the indexing strategy (the operator class). As an
example, the standard distribution of PostgreSQL includes GiST operator classes for several two-
dimensional geometric data types, which support indexed queries using these operators:
<<
&<
&>
>>
<<|
&<|
|&>
http://pgdocptbr.sourceforge.net/pg82/indexes-types.html[09/02/2018 18:11:35]
Index Types
|>>
@>
<@
~=
&&
(See Seção 9.10 for the meaning of these operators.) Many other GiST operator classes are available
in the contrib collection or as separate projects. For more information see Capítulo 50.
GIN indexes are inverted indexes which can handle values that contain more than one key, arrays
for example. Like GiST, GIN can support many different user-defined indexing strategies and the
particular operators with which a GIN index can be used vary depending on the indexing strategy.
As an example, the standard distribution of PostgreSQL includes GIN operator classes for one-
dimensional arrays, which support indexed queries using these operators:
<@
@>
=
&&
(See Seção 9.14 for the meaning of these operators.) Other GIN operator classes are available in the
contrib tsearch2 and intarray modules. For more information see Capítulo 51.

Introdução Acima Multicolumn Indexes
http://pgdocptbr.sourceforge.net/pg82/indexes-types.html[09/02/2018 18:11:35]
Multicolumn Indexes


An index can be defined on more than one column of a table. For example, if you have a table of
this form:
CREATE TABLE test2 (

major int,
minor int,
name varchar
);
(say, you keep your /dev directory in a database...) and you frequently make queries like
SELECT name FROM test2 WHERE major = constante AND minor = constante;
then it may be appropriate to define an index on the columns major and minor together, e.g.,
CREATE INDEX test2_mm_idx ON test2 (major, minor);
Currently, only the B-tree and GiST index types support multicolumn indexes. Up to 32 columns
may be specified. (This limit can be altered when building PostgreSQL; see the file
pg_config_manual.h.)
A multicolumn B-tree index can be used with query conditions that involve any subset of the index's
columns, but the index is most efficient when there are constraints on the leading (leftmost)
columns. The exact rule is that equality constraints on leading columns, plus any inequality
constraints on the first column that does not have an equality constraint, will be used to limit the
portion of the index that is scanned. Constraints on columns to the right of these columns are
checked in the index, so they save visits to the table proper, but they do not reduce the portion of
the index that has to be scanned. For example, given an index on (a, b, c) and a query condition
WHERE a = 5 AND b >= 42 AND c < 77, the index would have to be scanned from the first entry
with a = 5 and b = 42 up through the last entry with a = 5. Index entries with c >= 77 would be
skipped, but they'd still have to be scanned through. This index could in principle be used for
queries that have constraints on b and/or c with no constraint on a — but the entire index would
have to be scanned, so in most cases the planner would prefer a sequential table scan over using
the index.
A multicolumn GiST index can be used with query conditions that involve any subset of the index's
columns. Conditions on additional columns restrict the entries returned by the index, but the
condition on the first column is the most important one for determining how much of the index
needs to be scanned. A GiST index will be relatively ineffective if its first column has only a few
distinct values, even if there are many distinct values in additional columns.
Of course, each column must be used with operators appropriate to the index type; clauses that
involve other operators will not be considered.
Multicolumn indexes should be used sparingly. In most situations, an index on a single column is
sufficient and saves space and time. Indexes with more than three columns are unlikely to be
helpful unless the usage of the table is extremely stylized. See also Seção 11.4 for some discussion
of the merits of different index setups.
http://pgdocptbr.sourceforge.net/pg82/indexes-multicolumn.html[09/02/2018 18:11:48]
Multicolumn Indexes

Index Types Acima Combining Multiple Indexes
http://pgdocptbr.sourceforge.net/pg82/indexes-multicolumn.html[09/02/2018 18:11:48]
Combining Multiple Indexes


A single index scan can only use query clauses that use the index's columns with operators of its
operator class and are joined with AND. For example, given an index on (a, b) a query condition like
WHERE a = 5 AND b = 6 could use the index, but a query like WHERE a = 5 OR b = 6 could not
directly use the index.
Beginning in release 8.1, PostgreSQL has the ability to combine multiple indexes (including multiple
uses of the same index) to handle cases that cannot be implemented by single index scans. The
system can form AND and OR conditions across several index scans. For example, a query like
WHERE x = 42 OR x = 47 OR x = 53 OR x = 99 could be broken down into four separate scans of
an index on x, each scan using one of the query clauses. The results of these scans are then ORed
together to produce the result. Another example is that if we have separate indexes on x and y, one
possible implementation of a query like WHERE x = 5 AND y = 6 is to use each index with the
appropriate query clause and then AND together the index results to identify the result rows.
To combine multiple indexes, the system scans each needed index and prepares a bitmap in
memory giving the locations of table rows that are reported as matching that index's conditions.
The bitmaps are then ANDed and ORed together as needed by the query. Finally, the actual table
rows are visited and returned. The table rows are visited in physical order, because that is how the
bitmap is laid out; this means that any ordering of the original indexes is lost, and so a separate
sort step will be needed if the query has an ORDER BY clause. For this reason, and because each
additional index scan adds extra time, the planner will sometimes choose to use a simple index scan
even though additional indexes are available that could have been used as well.
In all but the simplest applications, there are various combinations of indexes that may be useful,
and the database developer must make trade-offs to decide which indexes to provide. Sometimes
multicolumn indexes are best, but sometimes it's better to create separate indexes and rely on the
index-combination feature. For example, if your workload includes a mix of queries that sometimes
involve only column x, sometimes only column y, and sometimes both columns, you might choose
to create two separate indexes on x and y, relying on index combination to process the queries that
use both columns. You could also create a multicolumn index on (x, y). This index would typically
be more efficient than index combination for queries involving both columns, but as discussed in
Seção 11.3, it would be almost useless for queries involving only y, so it could not be the only index.
A combination of the multicolumn index and a separate index on y would serve reasonably well. For
queries involving only x, the multicolumn index could be used, though it would be larger and hence
slower than an index on x alone. The last alternative is to create all three indexes, but this is
probably only reasonable if the table is searched much more often than it is updated and all three
types of query are common. If one of the types of query is much less common than the others,
you'd probably settle for creating just the two indexes that best match the common types.

Multicolumn Indexes Acima Unique Indexes
http://pgdocptbr.sourceforge.net/pg82/indexes-bitmap-scans.html[09/02/2018 18:11:59]
Unique Indexes


Indexes may also be used to enforce uniqueness of a column's value, or the uniqueness of the
combined values of more than one column.
CREATE UNIQUE INDEX nome ON tabela (coluna [, ...]);
Currently, only B-tree indexes can be declared unique.
When an index is declared unique, multiple table rows with equal indexed values will not be
allowed. Null values are not considered equal. A multicolumn unique index will only reject cases
where all of the indexed columns are equal in two rows.
PostgreSQL automatically creates a unique index when a unique constraint or a primary key is
defined for a table. The index covers the columns that make up the primary key or unique columns
(a multicolumn index, if appropriate), and is the mechanism that enforces the constraint.
Nota: The preferred way to add a unique constraint to a table is ALTER TABLE ... ADD
CONSTRAINT. The use of indexes to enforce unique constraints could be considered an
implementation detail that should not be accessed directly. One should, however, be
aware that there's no need to manually create indexes on unique columns; doing so
would just duplicate the automatically-created index.

Combining Multiple Indexes Acima Indexes on Expressions
http://pgdocptbr.sourceforge.net/pg82/indexes-unique.html[09/02/2018 18:12:25]
Indexes on Expressions


An index column need not be just a column of the underlying table, but can be a function or scalar
expression computed from one or more columns of the table. This feature is useful to obtain fast
access to tables based on the results of computations.
For example, a common way to do case-insensitive comparisons is to use the lower function:
SELECT * FROM test1 WHERE lower(col1) = 'value';
This query can use an index, if one has been defined on the result of the lower(col1) operation:
CREATE INDEX test1_lower_col1_idx ON test1 (lower(col1));
If we were to declare this index UNIQUE, it would prevent creation of rows whose col1 values differ
only in case, as well as rows whose col1 values are actually identical. Thus, indexes on expressions
can be used to enforce constraints that are not definable as simple unique constraints.
As another example, if one often does queries like this:
SELECT * FROM people WHERE (first_name || ' ' || last_name) = 'John Smith';
then it might be worth creating an index like this:
CREATE INDEX people_names ON people ((first_name || ' ' || last_name));
The syntax of the CREATE INDEX command normally requires writing parentheses around index
expressions, as shown in the second example. The parentheses may be omitted when the
expression is just a function call, as in the first example.
Index expressions are relatively expensive to maintain, because the derived expression(s) must be
computed for each row upon insertion and whenever it is updated. However, the index expressions
are not recomputed during an indexed search, since they are already stored in the index. In both
examples above, the system sees the query as just WHERE indexedcolumn = 'constant' and so the
speed of the search is equivalent to any other simple index query. Thus, indexes on expressions are
useful when retrieval speed is more important than insertion and update speed.

Unique Indexes Acima Partial Indexes
http://pgdocptbr.sourceforge.net/pg82/indexes-expressional.html[09/02/2018 18:15:22]
Partial Indexes


A partial index is an index built over a subset of a table; the subset is defined by a conditional
expression (called the predicate of the partial index). The index contains entries for only those table
rows that satisfy the predicate. Partial indexes are a specialized feature, but there are several
situations in which they are useful.
One major reason for using a partial index is to avoid indexing common values. Since a query
searching for a common value (one that accounts for more than a few percent of all the table rows)
will not use the index anyway, there is no point in keeping those rows in the index at all. This
reduces the size of the index, which will speed up queries that do use the index. It will also speed
up many table update operations because the index does not need to be updated in all cases.
Exemplo 11-1 shows a possible application of this idea.
Exemplo 11-1. Setting up a Partial Index to Exclude Common Values
Suppose you are storing web server access logs in a database. Most accesses originate from the
IP address range of your organization but some are from elsewhere (say, employees on dial-up
connections). If your searches by IP are primarily for outside accesses, you probably do not
need to index the IP range that corresponds to your organization's subnet.
Assume a table like this:
CREATE TABLE access_log (

url varchar,
client_ip inet,
...
);
To create a partial index that suits our example, use a command such as this:
CREATE INDEX access_log_client_ip_ix ON access_log (client_ip)

WHERE NOT (client_ip > inet '192.168.100.0' AND client_ip < inet '192.168.100.255');
A typical query that can use this index would be:
SELECT * FROM access_log WHERE url = '/index.html' AND client_ip = inet '212.78.10.32';
A query that cannot use this index is:
SELECT * FROM access_log WHERE client_ip = inet '192.168.100.23';
Observe that this kind of partial index requires that the common values be predetermined. If the
distribution of values is inherent (due to the nature of the application) and static (not changing
over time), this is not difficult, but if the common values are merely due to the coincidental data
load this can require a lot of maintenance work to change the index definition from time to time.
Another possible use for a partial index is to exclude values from the index that the typical query
workload is not interested in; this is shown in Exemplo 11-2. This results in the same advantages as
listed above, but it prevents the "uninteresting" values from being accessed via that index at all,
http://pgdocptbr.sourceforge.net/pg82/indexes-partial.html[09/02/2018 18:15:34]
Partial Indexes
even if an index scan might be profitable in that case. Obviously, setting up partial indexes for this
kind of scenario will require a lot of care and experimentation.
Exemplo 11-2. Setting up a Partial Index to Exclude Uninteresting Values
If you have a table that contains both billed and unbilled orders, where the unbilled orders take
up a small fraction of the total table and yet those are the most-accessed rows, you can improve
performance by creating an index on just the unbilled rows. The command to create the index
would look like this:
CREATE INDEX orders_unbilled_index ON orders (order_nr)

WHERE billed is not true;
A possible query to use this index would be
SELECT * FROM orders WHERE billed is not true AND order_nr < 10000;
However, the index can also be used in queries that do not involve order_nr at all, e.g.,
SELECT * FROM orders WHERE billed is not true AND amount > 5000.00;
This is not as efficient as a partial index on the amount column would be, since the system has
to scan the entire index. Yet, if there are relatively few unbilled orders, using this partial index
just to find the unbilled orders could be a win.
Note that this query cannot use this index:
SELECT * FROM orders WHERE order_nr = 3501;
The order 3501 may be among the billed or among the unbilled orders.
Exemplo 11-2 also illustrates that the indexed column and the column used in the predicate do not
need to match. PostgreSQL supports partial indexes with arbitrary predicates, so long as only
columns of the table being indexed are involved. However, keep in mind that the predicate must
match the conditions used in the queries that are supposed to benefit from the index. To be precise,
a partial index can be used in a query only if the system can recognize that the WHERE condition of
the query mathematically implies the predicate of the index. PostgreSQL does not have a
sophisticated theorem prover that can recognize mathematically equivalent expressions that are
written in different forms. (Not only is such a general theorem prover extremely difficult to create,
it would probably be too slow to be of any real use.) The system can recognize simple inequality
implications, for example "x < 1" implies "x < 2"; otherwise the predicate condition must exactly
match part of the query's WHERE condition or the index will not be recognized to be usable.
Matching takes place at query planning time, not at run time. As a result, parameterized query
clauses will not work with a partial index. For example a prepared query with a parameter might
specify "x < ?" which will never imply "x < 2" for all possible values of the parameter.
A third possible use for partial indexes does not require the index to be used in queries at all. The
idea here is to create a unique index over a subset of a table, as in Exemplo 11-3. This enforces
uniqueness among the rows that satisfy the index predicate, without constraining those that do not.
Exemplo 11-3. Setting up a Partial Unique Index
Suppose that we have a table describing test outcomes. We wish to ensure that there is only
one "successful" entry for a given subject and target combination, but there might be any
number of "unsuccessful" entries. Here is one way to do it:
CREATE TABLE tests (

subject text,
Partial Indexes
target text,
success boolean,
...
);
CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target)
WHERE success;
This is a particularly efficient way of doing it when there are few successful tests and many
unsuccessful ones.
Finally, a partial index can also be used to override the system's query plan choices. It may occur
that data sets with peculiar distributions will cause the system to use an index when it really should
not. In that case the index can be set up so that it is not available for the offending query.
Normally, PostgreSQL makes reasonable choices about index usage (e.g., it avoids them when
retrieving common values, so the earlier example really only saves index size, it is not required to
avoid index usage), and grossly incorrect plan choices are cause for a bug report.
Keep in mind that setting up a partial index indicates that you know at least as much as the query
planner knows, in particular you know when an index might be profitable. Forming this knowledge
requires experience and understanding of how indexes in PostgreSQL work. In most cases, the
advantage of a partial index over a regular index will not be much.
More information about partial indexes can be found in The case for partial indexes , Partial indexing in
POSTGRES: research project, and Generalized Partial Indexes .

Indexes on Expressions Acima Operator Classes
Operator Classes


An index definition may specify an operator class for each column of an index.
CREATE INDEX nome ON tabela (coluna classe_de_operadores [, ...]);
The operator class identifies the operators to be used by the index for that column. For example, a
B-tree index on the type int4 would use the int4_ops class; this operator class includes comparison
functions for values of type int4. In practice the default operator class for the column's data type is
usually sufficient. The main point of having operator classes is that for some data types, there could
be more than one meaningful index behavior. For example, we might want to sort a complex-
number data type either by absolute value or by real part. We could do this by defining two
operator classes for the data type and then selecting the proper class when making an index.
There are also some built-in operator classes besides the default ones:
The operator classes text_pattern_ops, varchar_pattern_ops, bpchar_pattern_ops, and

name_pattern_ops support B-tree indexes on the types text, varchar, char, and name,
respectively. The difference from the default operator classes is that the values are compared
strictly character by character rather than according to the locale-specific collation rules. This
makes these operator classes suitable for use by queries involving pattern matching
expressions (LIKE or POSIX regular expressions) when the server does not use the standard
"C" locale. As an example, you might index a varchar column like this:
CREATE INDEX test_index ON test_table (col varchar_pattern_ops);
Note that you should also create an index with the default operator class if you want queries
involving ordinary comparisons to use an index. Such queries cannot use the xxx_pattern_ops
operator classes. It is allowed to create multiple indexes on the same column with different
operator classes. If you do use the C locale, you do not need the xxx_pattern_ops operator
classes, because an index with the default operator class is usable for pattern-matching
queries in the C locale.
The following query shows all defined operator classes:
SELECT am.amname AS index_method,

opc.opcname AS opclass_name
FROM pg_am am, pg_opclass opc
WHERE opc.opcamid = am.oid
ORDER BY index_method, opclass_name;
It can be extended to show all the operators included in each class:
SELECT am.amname AS index_method,

opc.opcname AS opclass_name,
opr.oid::regoperator AS opclass_operator
FROM pg_am am, pg_opclass opc, pg_amop amop, pg_operator opr
WHERE opc.opcamid = am.oid AND
amop.amopclaid = opc.oid AND
amop.amopopr = opr.oid
ORDER BY index_method, opclass_name, opclass_operator;

Partial Indexes Acima Examining Index Usage
http://pgdocptbr.sourceforge.net/pg82/indexes-opclass.html[09/02/2018 18:15:47]
Operator Classes
http://pgdocptbr.sourceforge.net/pg82/indexes-opclass.html[09/02/2018 18:15:47]
Examining Index Usage


Although indexes in PostgreSQL do not need maintenance and tuning, it is still important to check
which indexes are actually used by the real-life query workload. Examining index usage for an
individual query is done with the EXPLAIN command; its application for this purpose is illustrated in
Seção 13.1. It is also possible to gather overall statistics about index usage in a running server, as
described in Seção 25.2.
It is difficult to formulate a general procedure for determining which indexes to set up. There are a
number of typical cases that have been shown in the examples throughout the previous sections. A
good deal of experimentation will be necessary in most cases. The rest of this section gives some
tips for that.
Always run ANALYZE first. This command collects statistics about the distribution of the values
in the table. This information is required to guess the number of rows returned by a query,
which is needed by the planner to assign realistic costs to each possible query plan. In
absence of any real statistics, some default values are assumed, which are almost certain to
be inaccurate. Examining an application's index usage without having run ANALYZE is
therefore a lost cause.
Use real data for experimentation. Using test data for setting up indexes will tell you what
indexes you need for the test data, but that is all.
It is especially fatal to use very small test data sets. While selecting 1000 out of 100000 rows
could be a candidate for an index, selecting 1 out of 100 rows will hardly be, because the 100
rows will probably fit within a single disk page, and there is no plan that can beat sequentially
fetching 1 disk page.
Also be careful when making up test data, which is often unavoidable when the application is
not in production use yet. Values that are very similar, completely random, or inserted in
sorted order will skew the statistics away from the distribution that real data would have.
When indexes are not used, it can be useful for testing to force their use. There are run-time
parameters that can turn off various plan types (see Seção 17.6.1). For instance, turning off
sequential scans (enable_seqscan) and nested-loop joins (enable_nestloop), which are the
most basic plans, will force the system to use a different plan. If the system still chooses a
sequential scan or nested-loop join then there is probably a more fundamental reason why the
index is not used; for example, the query condition does not match the index. (What kind of
query can use what kind of index is explained in the previous sections.)
If forcing index usage does use the index, then there are two possibilities: Either the system
is right and using the index is indeed not appropriate, or the cost estimates of the query plans
are not reflecting reality. So you should time your query with and without indexes. The
EXPLAIN ANALYZE command can be useful here.
If it turns out that the cost estimates are wrong, there are, again, two possibilities. The total
cost is computed from the per-row costs of each plan node times the selectivity estimate of
the plan node. The costs estimated for the plan nodes can be adjusted via run-time
parameters (described in Seção 17.6.2). An inaccurate selectivity estimate is due to insufficient
statistics. It may be possible to improve this by tuning the statistics-gathering parameters
(see ALTER TABLE).
If you do not succeed in adjusting the costs to be more appropriate, then you may have to
http://pgdocptbr.sourceforge.net/pg82/indexes-examine.html[09/02/2018 18:16:08]
Examining Index Usage
resort to forcing index usage explicitly. You may also want to contact the PostgreSQL
developers to examine the issue.

Operator Classes Acima Concurrency Control
http://pgdocptbr.sourceforge.net/pg82/indexes-examine.html[09/02/2018 18:16:08]
Concurrency Control

Capítulo 12. Concurrency Control

Sumário
12.1. Introdução
12.2.1. Read Committed Isolation Level

12.2.2. Serializable Isolation Level
12.3.1. Table-Level Locks

12.3.2. Row-Level Locks
12.3.3. Deadlocks
12.3.4. Advisory Locks

This chapter describes the behavior of the PostgreSQL database system when two or more sessions
try to access the same data at the same time. The goals in that situation are to allow efficient
access for all sessions while maintaining strict data integrity. Every developer of database
applications should be familiar with the topics covered in this chapter.

Examining Index Usage Acima Introdução
http://pgdocptbr.sourceforge.net/pg82/mvcc.html[09/02/2018 18:16:29]
Introdução

Anterior Início Capítulo 12. Concurrency Control Fim Próxima
12.1. Introdução
PostgreSQL provides a rich set of tools for developers to manage concurrent access to data.
Internally, data consistency is maintained by using a multiversion model (Multiversion Concurrency
Control, MVCC). This means that while querying a database each transaction sees a snapshot of
data (a database version) as it was some time ago, regardless of the current state of the underlying
data. This protects the transaction from viewing inconsistent data that could be caused by (other)
concurrent transaction updates on the same data rows, providing transaction isolation for each
database session. MVCC, by eschewing explicit locking methodologies of traditional database
systems, minimizes lock contention in order to allow for reasonable performance in multiuser
environments.
The main advantage to using the MVCC model of concurrency control rather than locking is that in
MVCC locks acquired for querying (reading) data do not conflict with locks acquired for writing data,
and so reading never blocks writing and writing never blocks reading.
Table- and row-level locking facilities are also available in PostgreSQL for applications that cannot
adapt easily to MVCC behavior. However, proper use of MVCC will generally provide better
performance than locks. In addition, application-defined advisory locks provide a mechanism for
acquiring locks that are not tied to a single transaction.

Concurrency Control Acima Transaction Isolation
http://pgdocptbr.sourceforge.net/pg82/mvcc-intro.html[09/02/2018 18:16:44]
Transaction Isolation


The SQL standard defines four levels of transaction isolation in terms of three phenomena that must
be prevented between concurrent transactions. These undesirable phenomena are:
dirty read
A transaction reads data written by a concurrent uncommitted transaction.
nonrepeatable read
A transaction re-reads data it has previously read and finds that data has been modified by
another transaction (that committed since the initial read).
phantom read
A transaction re-executes a query returning a set of rows that satisfy a search condition and
finds that the set of rows satisfying the condition has changed due to another recently-
committed transaction.
The four transaction isolation levels and the corresponding behaviors are described in Tabela 12-1.
Tabela 12-1. SQL Transaction Isolation Levels
Isolation Level Dirty Read Nonrepeatable Read Phantom Read

Read uncommitted Possible Possible Possible
Read committed Not possible Possible Possible
Repeatable read Not possible Not possible Possible
Serializable Not possible Not possible Not possible
In PostgreSQL, you can request any of the four standard transaction isolation levels. But internally,
there are only two distinct isolation levels, which correspond to the levels Read Committed and
Serializable. When you select the level Read Uncommitted you really get Read Committed, and
when you select Repeatable Read you really get Serializable, so the actual isolation level may be
stricter than what you select. This is permitted by the SQL standard: the four isolation levels only
define which phenomena must not happen, they do not define which phenomena must happen. The
reason that PostgreSQL only provides two isolation levels is that this is the only sensible way to
map the standard isolation levels to the multiversion concurrency control architecture. The behavior
of the available isolation levels is detailed in the following subsections.
To set the transaction isolation level of a transaction, use the command SET TRANSACTION.
12.2.1. Read Committed Isolation Level
Read Committed is the default isolation level in PostgreSQL. When a transaction runs on this
isolation level, a SELECT query sees only data committed before the query began; it never sees
either uncommitted data or changes committed during query execution by concurrent transactions.
(However, the SELECT does see the effects of previous updates executed within its own transaction,
even though they are not yet committed.) In effect, a SELECT query sees a snapshot of the
database as of the instant that that query begins to run. Notice that two successive SELECT
http://pgdocptbr.sourceforge.net/pg82/transaction-iso.html[09/02/2018 18:16:55]
commands can see different data, even though they are within a single transaction, if other
transactions commit changes during execution of the first SELECT.
UPDATE, DELETE, SELECT FOR UPDATE, and SELECT FOR SHARE commands behave the same as
SELECT in terms of searching for target rows: they will only find target rows that were committed
as of the command start time. However, such a target row may have already been updated (or
deleted or locked) by another concurrent transaction by the time it is found. In this case, the
would-be updater will wait for the first updating transaction to commit or roll back (if it is still in
progress). If the first updater rolls back, then its effects are negated and the second updater can
proceed with updating the originally found row. If the first updater commits, the second updater will
ignore the row if the first updater deleted it, otherwise it will attempt to apply its operation to the
updated version of the row. The search condition of the command (the WHERE clause) is re-
evaluated to see if the updated version of the row still matches the search condition. If so, the
second updater proceeds with its operation, starting from the updated version of the row. (In the
case of SELECT FOR UPDATE and SELECT FOR SHARE, that means it is the updated version of the
row that is locked and returned to the client.)
Because of the above rule, it is possible for an updating command to see an inconsistent snapshot:
it can see the effects of concurrent updating commands that affected the same rows it is trying to
update, but it does not see effects of those commands on other rows in the database. This behavior
makes Read Committed mode unsuitable for commands that involve complex search conditions.
However, it is just right for simpler cases. For example, consider updating bank balances with
transactions like
BEGIN;
UPDATE accounts SET balance = balance + 100.00 WHERE acctnum = 12345;
UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 7534;
COMMIT;
If two such transactions concurrently try to change the balance of account 12345, we clearly want
the second transaction to start from the updated version of the account's row. Because each
command is affecting only a predetermined row, letting it see the updated version of the row does
not create any troublesome inconsistency.
Since in Read Committed mode each new command starts with a new snapshot that includes all
transactions committed up to that instant, subsequent commands in the same transaction will see
the effects of the committed concurrent transaction in any case. The point at issue here is whether
or not within a single command we see an absolutely consistent view of the database.
The partial transaction isolation provided by Read Committed mode is adequate for many
applications, and this mode is fast and simple to use. However, for applications that do complex
queries and updates, it may be necessary to guarantee a more rigorously consistent view of the
database than the Read Committed mode provides.
12.2.2. Serializable Isolation Level
The level Serializable provides the strictest transaction isolation. This level emulates serial
transaction execution, as if transactions had been executed one after another, serially, rather than
concurrently. However, applications using this level must be prepared to retry transactions due to
serialization failures.
When a transaction is on the serializable level, a SELECT query sees only data committed before the
transaction began; it never sees either uncommitted data or changes committed during transaction
execution by concurrent transactions. (However, the SELECT does see the effects of previous
updates executed within its own transaction, even though they are not yet committed.) This is
different from Read Committed in that the SELECT sees a snapshot as of the start of the
transaction, not as of the start of the current query within the transaction. Thus, successive SELECT
commands within a single transaction always see the same data.
UPDATE, DELETE, SELECT FOR UPDATE, and SELECT FOR SHARE commands behave the same as
SELECT in terms of searching for target rows: they will only find target rows that were committed
as of the transaction start time. However, such a target row may have already been updated (or
deleted or locked) by another concurrent transaction by the time it is found. In this case, the
serializable transaction will wait for the first updating transaction to commit or roll back (if it is still
in progress). If the first updater rolls back, then its effects are negated and the serializable
transaction can proceed with updating the originally found row. But if the first updater commits
(and actually updated or deleted the row, not just locked it) then the serializable transaction will be
rolled back with the message
ERROR: could not serialize access due to concurrent update
because a serializable transaction cannot modify or lock rows changed by other transactions after
the serializable transaction began.
When the application receives this error message, it should abort the current transaction and then
retry the whole transaction from the beginning. The second time through, the transaction sees the
previously-committed change as part of its initial view of the database, so there is no logical conflict
in using the new version of the row as the starting point for the new transaction's update.
Note that only updating transactions may need to be retried; read-only transactions will never have
serialization conflicts.
The Serializable mode provides a rigorous guarantee that each transaction sees a wholly consistent
view of the database. However, the application has to be prepared to retry transactions when
concurrent updates make it impossible to sustain the illusion of serial execution. Since the cost of
redoing complex transactions may be significant, this mode is recommended only when updating
transactions contain logic sufficiently complex that they may give wrong answers in Read
Committed mode. Most commonly, Serializable mode is necessary when a transaction executes
several successive commands that must see identical views of the database.
12.2.2.1. Serializable Isolation versus True Serializability
The intuitive meaning (and mathematical definition) of "serializable" execution is that any two
successfully committed concurrent transactions will appear to have executed strictly serially, one
after the other — although which one appeared to occur first may not be predictable in advance. It
is important to realize that forbidding the undesirable behaviors listed in Tabela 12-1 is not sufficient
to guarantee true serializability, and in fact PostgreSQL's Serializable mode does not guarantee
serializable execution in this sense. As an example, consider a table mytab, initially containing
class | value
-------+-------
1 | 10
1 | 20
2 | 100
2 | 200
Suppose that serializable transaction A computes
SELECT SUM(value) FROM mytab WHERE class = 1;
and then inserts the result (30) as the value in a new row with class = 2. Concurrently, serializable
transaction B computes
SELECT SUM(value) FROM mytab WHERE class = 2;
and obtains the result 300, which it inserts in a new row with class = 1. Then both transactions
commit. None of the listed undesirable behaviors have occurred, yet we have a result that could not
have occurred in either order serially. If A had executed before B, B would have computed the sum
330, not 300, and similarly the other order would have resulted in a different sum computed by A.
To guarantee true mathematical serializability, it is necessary for a database system to enforce
predicate locking, which means that a transaction cannot insert or modify a row that would have
matched the WHERE condition of a query in another concurrent transaction. For example, once
transaction A has executed the query SELECT ... WHERE class = 1, a predicate-locking system
would forbid transaction B from inserting any new row with class 1 until A has committed. [1] Such
a locking system is complex to implement and extremely expensive in execution, since every
session must be aware of the details of every query executed by every concurrent transaction. And
this large expense is mostly wasted, since in practice most applications do not do the sorts of things
that could result in problems. (Certainly the example above is rather contrived and unlikely to
represent real software.) For these reasons, PostgreSQL does not implement predicate locking.
In those cases where the possibility of nonserializable execution is a real hazard, problems can be
prevented by appropriate use of explicit locking. Further discussion appears in the following
sections.
Notas
[1]
Essentially, a predicate-locking system prevents phantom reads by restricting what is written,
whereas MVCC prevents them by restricting what is read.

Introdução Acima Explicit Locking
Explicit Locking


PostgreSQL provides various lock modes to control concurrent access to data in tables. These
modes can be used for application-controlled locking in situations where MVCC does not give the
desired behavior. Also, most PostgreSQL commands automatically acquire locks of appropriate
modes to ensure that referenced tables are not dropped or modified in incompatible ways while the
command executes. (For example, ALTER TABLE cannot safely be executed concurrently with other
operations on the same table, so it obtains an exclusive lock on the table to enforce that.)
To examine a list of the currently outstanding locks in a database server, use the pg_locks system
view. For more information on monitoring the status of the lock manager subsystem, refer to
Capítulo 25.
12.3.1. Table-Level Locks
The list below shows the available lock modes and the contexts in which they are used
automatically by PostgreSQL. You can also acquire any of these locks explicitly with the command
LOCK. Remember that all of these lock modes are table-level locks, even if the name contains the
word "row"; the names of the lock modes are historical. To some extent the names reflect the
typical usage of each lock mode — but the semantics are all the same. The only real difference
between one lock mode and another is the set of lock modes with which each conflicts. Two
transactions cannot hold locks of conflicting modes on the same table at the same time. (However,
a transaction never conflicts with itself. For example, it may acquire ACCESS EXCLUSIVE lock and
later acquire ACCESS SHARE lock on the same table.) Non-conflicting lock modes may be held
concurrently by many transactions. Notice in particular that some lock modes are self-conflicting
(for example, an ACCESS EXCLUSIVE lock cannot be held by more than one transaction at a time)
while others are not self-conflicting (for example, an ACCESS SHARE lock can be held by multiple
transactions).
Table-level lock modes
ACCESS SHARE
Conflicts with the ACCESS EXCLUSIVE lock mode only.
The SELECT command acquires a lock of this mode on referenced tables. In general, any
query that only reads a table and does not modify it will acquire this lock mode.
ROW SHARE
Conflicts with the EXCLUSIVE and ACCESS EXCLUSIVE lock modes.
The SELECT FOR UPDATE and SELECT FOR SHARE commands acquire a lock of this mode on
the target table(s) (in addition to ACCESS SHARE locks on any other tables that are
referenced but not selected FOR UPDATE/FOR SHARE).
ROW EXCLUSIVE
Conflicts with the SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE, and ACCESS EXCLUSIVE lock
modes.
The commands UPDATE, DELETE, and INSERT acquire this lock mode on the target table (in
http://pgdocptbr.sourceforge.net/pg82/explicit-locking.html[09/02/2018 18:17:09]
Explicit Locking
addition to ACCESS SHARE locks on any other referenced tables). In general, this lock mode
will be acquired by any command that modifies the data in a table.
SHARE UPDATE EXCLUSIVE
Conflicts with the SHARE UPDATE EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE,
and ACCESS EXCLUSIVE lock modes. This mode protects a table against concurrent schema
changes and VACUUM runs.
Acquired by VACUUM (without FULL), ANALYZE, and CREATE INDEX CONCURRENTLY.
SHARE
Conflicts with the ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE ROW EXCLUSIVE,
EXCLUSIVE, and ACCESS EXCLUSIVE lock modes. This mode protects a table against
concurrent data changes.
Acquired by CREATE INDEX (without CONCURRENTLY).
SHARE ROW EXCLUSIVE
Conflicts with the ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE, SHARE ROW
EXCLUSIVE, EXCLUSIVE, and ACCESS EXCLUSIVE lock modes.
This lock mode is not automatically acquired by any PostgreSQL command.
EXCLUSIVE
Conflicts with the ROW SHARE, ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE, SHARE
ROW EXCLUSIVE, EXCLUSIVE, and ACCESS EXCLUSIVE lock modes. This mode allows only
concurrent ACCESS SHARE locks, i.e., only reads from the table can proceed in parallel with a
transaction holding this lock mode.
This lock mode is not automatically acquired on user tables by any PostgreSQL command.
However it is acquired on certain system catalogs in some operations.
ACCESS EXCLUSIVE
Conflicts with locks of all modes (ACCESS SHARE, ROW SHARE, ROW EXCLUSIVE, SHARE
UPDATE EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE, and ACCESS EXCLUSIVE).
This mode guarantees that the holder is the only transaction accessing the table in any way.
Acquired by the ALTER TABLE, DROP TABLE, TRUNCATE, REINDEX, CLUSTER, and VACUUM
FULL commands. This is also the default lock mode for LOCK TABLE statements that do not
specify a mode explicitly.
Dica: Only an ACCESS EXCLUSIVE lock blocks a SELECT (without FOR UPDATE/SHARE)
statement.
Once acquired, a lock is normally held till end of transaction. But if a lock is acquired after
establishing a savepoint, the lock is released immediately if the savepoint is rolled back to. This is
consistent with the principle that ROLLBACK cancels all effects of the commands since the
savepoint. The same holds for locks acquired within a PL/pgSQL exception block: an error escape
from the block releases locks acquired within it.
12.3.2. Row-Level Locks
In addition to table-level locks, there are row-level locks, which can be exclusive or shared locks.
An exclusive row-level lock on a specific row is automatically acquired when the row is updated or
deleted. The lock is held until the transaction commits or rolls back, in just the same way as for
table-level locks. Row-level locks do not affect data querying; they block writers to the same row
only.
To acquire an exclusive row-level lock on a row without actually modifying the row, select the row
Explicit Locking
with SELECT FOR UPDATE. Note that once the row-level lock is acquired, the transaction may
update the row multiple times without fear of conflicts.
To acquire a shared row-level lock on a row, select the row with SELECT FOR SHARE. A shared lock
does not prevent other transactions from acquiring the same shared lock. However, no transaction
is allowed to update, delete, or exclusively lock a row on which any other transaction holds a shared
lock. Any attempt to do so will block until the shared lock(s) have been released.
PostgreSQL doesn't remember any information about modified rows in memory, so it has no limit to
the number of rows locked at one time. However, locking a row may cause a disk write; thus, for
example, SELECT FOR UPDATE will modify selected rows to mark them locked, and so will result in
disk writes.
In addition to table and row locks, page-level share/exclusive locks are used to control read/write
access to table pages in the shared buffer pool. These locks are released immediately after a row is
fetched or updated. Application developers normally need not be concerned with page-level locks,
but we mention them for completeness.
12.3.3. Deadlocks
The use of explicit locking can increase the likelihood of deadlocks, wherein two (or more)
transactions each hold locks that the other wants. For example, if transaction 1 acquires an
exclusive lock on table A and then tries to acquire an exclusive lock on table B, while transaction 2
has already exclusive-locked table B and now wants an exclusive lock on table A, then neither one
can proceed. PostgreSQL automatically detects deadlock situations and resolves them by aborting
one of the transactions involved, allowing the other(s) to complete. (Exactly which transaction will
be aborted is difficult to predict and should not be relied on.)
Note that deadlocks can also occur as the result of row-level locks (and thus, they can occur even if
explicit locking is not used). Consider the case in which there are two concurrent transactions
modifying a table. The first transaction executes:
This acquires a row-level lock on the row with the specified account number. Then, the second
transaction executes:

The first UPDATE statement successfully acquires a row-level lock on the specified row, so it
succeeds in updating that row. However, the second UPDATE statement finds that the row it is
attempting to update has already been locked, so it waits for the transaction that acquired the lock
to complete. Transaction two is now waiting on transaction one to complete before it continues
execution. Now, transaction one executes:
Transaction one attempts to acquire a row-level lock on the specified row, but it cannot: transaction
two already holds such a lock. So it waits for transaction two to complete. Thus, transaction one is
blocked on transaction two, and transaction two is blocked on transaction one: a deadlock
condition. PostgreSQL will detect this situation and abort one of the transactions.
The best defense against deadlocks is generally to avoid them by being certain that all applications
using a database acquire locks on multiple objects in a consistent order. In the example above, if
both transactions had updated the rows in the same order, no deadlock would have occurred. One
should also ensure that the first lock acquired on an object in a transaction is the highest mode that
will be needed for that object. If it is not feasible to verify this in advance, then deadlocks may be
handled on-the-fly by retrying transactions that are aborted due to deadlock.
Explicit Locking
So long as no deadlock situation is detected, a transaction seeking either a table-level or row-level

lock will wait indefinitely for conflicting locks to be released. This means it is a bad idea for
applications to hold transactions open for long periods of time (e.g., while waiting for user input).
12.3.4. Advisory Locks
PostgreSQL provides a means for creating locks that have application-defined meanings. These are
called advisory locks, because the system does not enforce their use — it is up to the application to
use them correctly. Advisory locks can be useful for locking strategies that are an awkward fit for
the MVCC model. Once acquired, an advisory lock is held until explicitly released or the session
ends. Unlike standard locks, advisory locks do not honor transaction semantics: a lock acquired
during a transaction that is later rolled back will still be held following the rollback, and likewise an
unlock is effective even if the calling transaction fails later. The same lock can be acquired multiple
times by its owning process: for each lock request there must be a corresponding unlock request
before the lock is actually released. (If a session already holds a given lock, additional requests will
always succeed, even if other sessions are awaiting the lock.) Like all locks in PostgreSQL, a
complete list of advisory locks currently held by any session can be found in the pg_locks system
view.
Advisory locks are allocated out of a shared memory pool whose size is defined by the configuration
variables max_locks_per_transaction and max_connections. Care must be taken not to exhaust this
memory or the server will not be able to grant any locks at all. This imposes an upper limit on the
number of advisory locks grantable by the server, typically in the tens to hundreds of thousands
depending on how the server is configured.
A common use of advisory locks is to emulate pessimistic locking strategies typical of so called "flat
file" data management systems. While a flag stored in a table could be used for the same purpose,
advisory locks are faster, avoid MVCC bloat, and are automatically cleaned up by the server at the
end of the session. In certain cases using this method, especially in queries involving explicit
ordering and LIMIT clauses, care must be taken to control the locks acquired because of the order
in which SQL expressions are evaluated. For example:
SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- ok

SELECT pg_advisory_lock(id) FROM foo WHERE id > 12345 LIMIT 100; -- danger!
SELECT pg_advisory_lock(q.id) FROM
(
SELECT id FROM foo WHERE id > 12345 LIMIT 100;
) q; -- ok
In the above queries, the second form is dangerous because the LIMIT is not guaranteed to be
applied before the locking function is executed. This might cause some locks to be acquired that the
application was not expecting, and hence would fail to release (until it ends the session). From the
point of view of the application, such locks would be dangling, although still viewable in pg_locks.
The functions provided to manipulate advisory locks are described in Tabela 9-50.

Transaction Isolation Acima Data Consistency Checks at the
Application Level
Data Consistency Checks at the Application Level


Because readers in PostgreSQL do not lock data, regardless of transaction isolation level, data read
by one transaction can be overwritten by another concurrent transaction. In other words, if a row is
returned by SELECT it doesn't mean that the row is still current at the instant it is returned (i.e.,
sometime after the current query began). The row might have been modified or deleted by an
already-committed transaction that committed after this one started. Even if the row is still valid
"now", it could be changed or deleted before the current transaction does a commit or rollback.
Another way to think about it is that each transaction sees a snapshot of the database contents,
and concurrently executing transactions may very well see different snapshots. So the whole
concept of "now" is somewhat ill-defined anyway. This is not normally a big problem if the client
applications are isolated from each other, but if the clients can communicate via channels outside
the database then serious confusion may ensue.
To ensure the current validity of a row and protect it against concurrent updates one must use
SELECT FOR UPDATE, SELECT FOR SHARE, or an appropriate LOCK TABLE statement. (SELECT FOR
UPDATE or SELECT FOR SHARE locks just the returned rows against concurrent updates, while
LOCK TABLE locks the whole table.) This should be taken into account when porting applications to
PostgreSQL from other environments.
Global validity checks require extra thought under MVCC. For example, a banking application might
wish to check that the sum of all credits in one table equals the sum of debits in another table,
when both tables are being actively updated. Comparing the results of two successive SELECT
sum(...) commands will not work reliably under Read Committed mode, since the second query will
likely include the results of transactions not counted by the first. Doing the two sums in a single
serializable transaction will give an accurate picture of the effects of transactions that committed
before the serializable transaction started — but one might legitimately wonder whether the answer
is still relevant by the time it is delivered. If the serializable transaction itself applied some changes
before trying to make the consistency check, the usefulness of the check becomes even more
debatable, since now it includes some but not all post-transaction-start changes. In such cases a
careful person might wish to lock all tables needed for the check, in order to get an indisputable
picture of current reality. A SHARE mode (or higher) lock guarantees that there are no uncommitted
changes in the locked table, other than those of the current transaction.
Note also that if one is relying on explicit locking to prevent concurrent changes, one should use
Read Committed mode, or in Serializable mode be careful to obtain the lock(s) before performing
queries. A lock obtained by a serializable transaction guarantees that no other transactions
modifying the table are still running, but if the snapshot seen by the transaction predates obtaining
the lock, it may predate some now-committed changes in the table. A serializable transaction's
snapshot is actually frozen at the start of its first query or data-modification command (SELECT,
INSERT, UPDATE, or DELETE), so it's possible to obtain locks explicitly before the snapshot is
frozen.

Explicit Locking Acima Locking and Indexes
http://pgdocptbr.sourceforge.net/pg82/applevel-consistency.html[09/02/2018 18:17:24]
Locking and Indexes


Though PostgreSQL provides nonblocking read/write access to table data, nonblocking read/write
access is not currently offered for every index access method implemented in PostgreSQL. The
various index types are handled as follows:
B-tree and GiST indexes
Short-term share/exclusive page-level locks are used for read/write access. Locks are
released immediately after each index row is fetched or inserted. These index types provide
the highest concurrency without deadlock conditions.
Hash indexes
Share/exclusive hash-bucket-level locks are used for read/write access. Locks are released
after the whole bucket is processed. Bucket-level locks provide better concurrency than index-
level ones, but deadlock is possible since the locks are held longer than one index operation.
GIN indexes
Short-term share/exclusive page-level locks are used for read/write access. Locks are
released immediately after each index row is fetched or inserted. But note that a GIN-indexed
value insertion usually produces several index key insertions per row, so GIN may do
substantial work for a single value's insertion.
Currently, B-tree indexes offer the best performance for concurrent applications; since they also
have more features than hash indexes, they are the recommended index type for concurrent
applications that need to index scalar data. When dealing with non-scalar data, B-trees are not
useful, and GiST or GIN indexes should be used instead.

Data Consistency Checks at the Acima Performance Tips
Application Level
http://pgdocptbr.sourceforge.net/pg82/locking-indexes.html[09/02/2018 18:17:43]
Performance Tips

Capítulo 13. Performance Tips

Sumário
13.1. Using EXPLAIN
13.4.1. Disable Autocommit

13.4.2. Use COPY
13.4.3. Remove Indexes
13.4.4. Remove Foreign Key Constraints
13.4.5. Increase maintenance_work_mem
13.4.6. Increase checkpoint_segments
13.4.7. Run ANALYZE Afterwards
13.4.8. Some Notes About pg_dump
Query performance can be affected by many things. Some of these can be manipulated by the user,
while others are fundamental to the underlying design of the system. This chapter provides some
hints about understanding and tuning PostgreSQL performance.

Locking and Indexes Acima Using EXPLAIN
http://pgdocptbr.sourceforge.net/pg82/performance-tips.html[09/02/2018 18:18:01]
Using EXPLAIN

Anterior Início Capítulo 13. Performance Tips Fim Próxima
13.1. Using EXPLAIN

PostgreSQL devises a query plan for each query it is given. Choosing the right plan to match the
query structure and the properties of the data is absolutely critical for good performance, so the
system includes a complex planner that tries to select good plans. You can use the EXPLAIN
command to see what query plan the planner creates for any query. Plan-reading is an art that
deserves an extensive tutorial, which this is not; but here is some basic information.
The structure of a query plan is a tree of plan nodes. Nodes at the bottom level are table scan
nodes: they return raw rows from a table. There are different types of scan nodes for different table
access methods: sequential scans, index scans, and bitmap index scans. If the query requires
joining, aggregation, sorting, or other operations on the raw rows, then there will be additional
nodes "atop" the scan nodes to perform these operations. Again, there is usually more than one
possible way to do these operations, so different node types can appear here too. The output of
EXPLAIN has one line for each node in the plan tree, showing the basic node type plus the cost
estimates that the planner made for the execution of that plan node. The first line (topmost node)
has the estimated total execution cost for the plan; it is this number that the planner seeks to
minimize.
Here is a trivial example, just to show what the output looks like. [1]
EXPLAIN SELECT * FROM tenk1;

QUERY PLAN
-------------------------------------------------------------
Seq Scan on tenk1 (cost=0.00..458.00 rows=10000 width=244)
The numbers that are quoted by EXPLAIN are:
Estimated start-up cost (Time expended before output scan can start, e.g., time to do the
sorting in a sort node.)
Estimated total cost (If all rows were to be retrieved, which they may not be: for example, a
query with a LIMIT clause will stop short of paying the total cost of the Limit plan node's input
node.)
Estimated number of rows output by this plan node (Again, only if executed to completion.)
Estimated average width (in bytes) of rows output by this plan node
The costs are measured in arbitrary units determined by the planner's cost parameters (see Seção
17.6.2). Traditional practice is to measure the costs in units of disk page fetches; that is,
seq_page_cost is conventionally set to 1.0 and the other cost parameters are set relative to that.
The examples in this section are run with the default cost parameters.
It's important to note that the cost of an upper-level node includes the cost of all its child nodes.
It's also important to realize that the cost only reflects things that the planner cares about. In
particular, the cost does not consider the time spent transmitting result rows to the client, which
could be an important factor in the true elapsed time; but the planner ignores it because it cannot
change it by altering the plan. (Every correct plan will output the same row set, we trust.)
Rows output is a little tricky because it is not the number of rows processed or scanned by the plan
node. It is usually less, reflecting the estimated selectivity of any WHERE-clause conditions that are
being applied at the node. Ideally the top-level rows estimate will approximate the number of rows
http://pgdocptbr.sourceforge.net/pg82/using-explain.html[09/02/2018 18:18:14]
Using EXPLAIN
actually returned, updated, or deleted by the query.
Returning to our example:
EXPLAIN SELECT * FROM tenk1;

QUERY PLAN
-------------------------------------------------------------
This is about as straightforward as it gets. If you do
SELECT relpages, reltuples FROM pg_class WHERE relname = 'tenk1';
you will find out that tenk1 has 358 disk pages and 10000 rows. So the cost is estimated at 358
page reads, costing seq_page_cost apiece (1.0 by default), plus 10000 * cpu_tuple_cost which is 0.01
by default.
Now let's modify the query to add a WHERE condition:
EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 7000;

QUERY PLAN
------------------------------------------------------------
Filter: (unique1 < 7000)
Notice that the EXPLAIN output shows the WHERE clause being applied as a "filter" condition; this
means that the plan node checks the condition for each row it scans, and outputs only the ones that
pass the condition. The estimate of output rows has gone down because of the WHERE clause.
However, the scan will still have to visit all 10000 rows, so the cost hasn't decreased; in fact it has
gone up a bit to reflect the extra CPU time spent checking the WHERE condition.
The actual number of rows this query would select is 7000, but the rows estimate is only
approximate. If you try to duplicate this experiment, you will probably get a slightly different
estimate; moreover, it will change after each ANALYZE command, because the statistics produced
by ANALYZE are taken from a randomized sample of the table.
Now, let's make the condition more restrictive:

QUERY PLAN
------------------------------------------------------------------------------
Bitmap Heap Scan on tenk1 (cost=2.37..232.35 rows=106 width=244)
Recheck Cond: (unique1 < 100)
-> Bitmap Index Scan on tenk1_unique1 (cost=0.00..2.37 rows=106 width=0)
Index Cond: (unique1 < 100)
Here the planner has decided to use a two-step plan: the bottom plan node visits an index to find
the locations of rows matching the index condition, and then the upper plan node actually fetches
those rows from the table itself. Fetching the rows separately is much more expensive than
sequentially reading them, but because not all the pages of the table have to be visited, this is still
cheaper than a sequential scan. (The reason for using two levels of plan is that the upper plan node
sorts the row locations identified by the index into physical order before reading them, so as to
minimize the costs of the separate fetches. The "bitmap" mentioned in the node names is the
mechanism that does the sorting.)
If the WHERE condition is selective enough, the planner may switch to a "simple" index scan plan:

QUERY PLAN
------------------------------------------------------------------------------
Index Scan using tenk1_unique1 on tenk1 (cost=0.00..10.00 rows=2 width=244)
Using EXPLAIN
In this case the table rows are fetched in index order, which makes them even more expensive to
read, but there are so few that the extra cost of sorting the row locations is not worth it. You'll most
often see this plan type for queries that fetch just a single row, and for queries that request an
ORDER BY condition that matches the index order.
Add another condition to the WHERE clause:
EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 3 AND stringu1 = 'xxx';
QUERY PLAN
------------------------------------------------------------------------------
Index Scan using tenk1_unique1 on tenk1 (cost=0.00..10.01 rows=1 width=244)
Filter: (stringu1 = 'xxx'::name)
The added condition stringu1 = 'xxx' reduces the output-rows estimate, but not the cost because
we still have to visit the same set of rows. Notice that the stringu1 clause cannot be applied as an
index condition (since this index is only on the unique1 column). Instead it is applied as a filter on
the rows retrieved by the index. Thus the cost has actually gone up a little bit to reflect this extra
checking.
If there are indexes on several columns used in WHERE, the planner might choose to use an AND or
OR combination of the indexes:
EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 100 AND unique2 > 9000;
QUERY PLAN
-------------------------------------------------------------------------------------
Bitmap Heap Scan on tenk1 (cost=11.27..49.11 rows=11 width=244)
Recheck Cond: ((unique1 < 100) AND (unique2 > 9000))
-> BitmapAnd (cost=11.27..11.27 rows=11 width=0)
Index Cond: (unique2 > 9000)
But this requires visiting both indexes, so it's not necessarily a win compared to using just one
index and treating the other condition as a filter. If you vary the ranges involved you'll see the plan
change accordingly.
Let's try joining two tables, using the columns we have been discussing:
EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 < 100 AND t1.unique2 = t2.unique2;
QUERY PLAN
--------------------------------------------------------------------------------------
Nested Loop (cost=2.37..553.11 rows=106 width=488)
-> Bitmap Heap Scan on tenk1 t1 (cost=2.37..232.35 rows=106 width=244)
-> Index Scan using tenk2_unique2 on tenk2 t2 (cost=0.00..3.01 rows=1 width=244)
Index Cond: ("outer".unique2 = t2.unique2)
In this nested-loop join, the outer scan is the same bitmap index scan we saw earlier, and so its
cost and row count are the same because we are applying the WHERE clause unique1 < 100 at that
node. The t1.unique2 = t2.unique2 clause is not relevant yet, so it doesn't affect row count of the
outer scan. For the inner scan, the unique2 value of the current outer-scan row is plugged into the
inner index scan to produce an index condition like t2.unique2 = constante. So we get the same
inner-scan plan and costs that we'd get from, say, EXPLAIN SELECT * FROM tenk2 WHERE unique2
= 42. The costs of the loop node are then set on the basis of the cost of the outer scan, plus one
repetition of the inner scan for each outer row (106 * 3.01, here), plus a little CPU time for join
processing.
In this example the join's output row count is the same as the product of the two scans' row counts,
but that's not true in general, because in general you can have WHERE clauses that mention both
tables and so can only be applied at the join point, not to either input scan. For example, if we
added WHERE ... AND t1.hundred < t2.hundred, that would decrease the output row count of the
join node, but not change either input scan.
Using EXPLAIN
One way to look at variant plans is to force the planner to disregard whatever strategy it thought
was the winner, using the enable/disable flags described in Seção 17.6.1. (This is a crude tool, but
useful. See also Seção 13.3.)
SET enable_nestloop = off;

EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 < 100 AND t1.unique2 = t2.unique2;
QUERY PLAN
------------------------------------------------------------------------------------------
Hash Join (cost=232.61..741.67 rows=106 width=488)
Hash Cond: ("outer".unique2 = "inner".unique2)
-> Seq Scan on tenk2 t2 (cost=0.00..458.00 rows=10000 width=244)
-> Hash (cost=232.35..232.35 rows=106 width=244)
-> Bitmap Heap Scan on tenk1 t1 (cost=2.37..232.35 rows=106 width=244)
This plan proposes to extract the 100 interesting rows of tenk1 using that same old index scan,
stash them into an in-memory hash table, and then do a sequential scan of tenk2, probing into the
hash table for possible matches of t1.unique2 = t2.unique2 at each tenk2 row. The cost to read
tenk1 and set up the hash table is entirely start-up cost for the hash join, since we won't get any
rows out until we can start reading tenk2. The total time estimate for the join also includes a hefty
charge for the CPU time to probe the hash table 10000 times. Note, however, that we are not
charging 10000 times 232.35; the hash table setup is only done once in this plan type.
It is possible to check on the accuracy of the planner's estimated costs by using EXPLAIN ANALYZE.
This command actually executes the query, and then displays the true run time accumulated within
each plan node along with the same estimated costs that a plain EXPLAIN shows. For example, we
might get a result like this:
EXPLAIN ANALYZE SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 < 100 AND t1.unique2 =
t2.unique2;
QUERY PLAN
--------------------------------------------------------------------------------------------
--------------------------------------
Nested Loop (cost=2.37..553.11 rows=106 width=488) (actual time=1.392..12.700 rows=100
loops=1)
-> Bitmap Heap Scan on tenk1 t1 (cost=2.37..232.35 rows=106 width=244) (actual
time=0.878..2.367 rows=100 loops=1)
-> Bitmap Index Scan on tenk1_unique1 (cost=0.00..2.37 rows=106 width=0) (actual
time=0.546..0.546 rows=100 loops=1)
-> Index Scan using tenk2_unique2 on tenk2 t2 (cost=0.00..3.01 rows=1 width=244)
(actual time=0.067..0.078 rows=1 loops=100)
Index Cond: ("outer".unique2 = t2.unique2)
Total runtime: 14.452 ms
Note that the "actual time" values are in milliseconds of real time, whereas the "cost" estimates are
expressed in arbitrary units; so they are unlikely to match up. The thing to pay attention to is
whether the ratios of actual time and estimated costs are consistent.
In some query plans, it is possible for a subplan node to be executed more than once. For example,
the inner index scan is executed once per outer row in the above nested-loop plan. In such cases,
the "loops" value reports the total number of executions of the node, and the actual time and rows
values shown are averages per-execution. This is done to make the numbers comparable with the
way that the cost estimates are shown. Multiply by the "loops" value to get the total time actually
spent in the node.
The Total runtime shown by EXPLAIN ANALYZE includes executor start-up and shut-down time, as
well as time spent processing the result rows. It does not include parsing, rewriting, or planning
time. For a SELECT query, the total run time will normally be just a little larger than the total time
reported for the top-level plan node. For INSERT, UPDATE, and DELETE commands, the total run
time may be considerably larger, because it includes the time spent processing the result rows. In
these commands, the time for the top plan node essentially is the time spent computing the new
rows and/or locating the old ones, but it doesn't include the time spent applying the changes. Time
spent firing triggers, if any, is also outside the top plan node, and is shown separately for each
trigger.
It is worth noting that EXPLAIN results should not be extrapolated to situations other than the one
Using EXPLAIN
you are actually testing; for example, results on a toy-sized table can't be assumed to apply to
large tables. The planner's cost estimates are not linear and so it may well choose a different plan
for a larger or smaller table. An extreme example is that on a table that only occupies one disk
page, you'll nearly always get a sequential scan plan whether indexes are available or not. The
planner realizes that it's going to take one disk page read to process the table in any case, so
there's no value in expending additional page reads to look at an index.
Notas
[1]
Examples in this section are drawn from the regression test database after doing a VACUUM
ANALYZE, using 8.2 development sources. You should be able to get similar results if you try the
examples yourself, but your estimated costs and row counts will probably vary slightly because
ANALYZE's statistics are random samples rather than being exact.

Performance Tips Acima Statistics Used by the Planner
Statistics Used by the Planner


As we saw in the previous section, the query planner needs to estimate the number of rows retrieved by a query in order to make good choices of query plans. This section provides a quick look at
the statistics that the system uses for these estimates.
One component of the statistics is the total number of entries in each table and index, as well as the number of disk blocks occupied by each table and index. This information is kept in the table
pg_class, in the columns reltuples and relpages. We can look at it with queries similar to this one:
SELECT relname, relkind, reltuples, relpages FROM pg_class WHERE relname LIKE 'tenk1%';
relname | relkind | reltuples | relpages
----------------------+---------+-----------+----------
tenk1 | r | 10000 | 358
tenk1_hundred | i | 10000 | 30
tenk1_thous_tenthous | i | 10000 | 30
tenk1_unique1 | i | 10000 | 30
tenk1_unique2 | i | 10000 | 30
(5 rows)
Here we can see that tenk1 contains 10000 rows, as do its indexes, but the indexes are (unsurprisingly) much smaller than the table.
For efficiency reasons, reltuples and relpages are not updated on-the-fly, and so they usually contain somewhat out-of-date values. They are updated by VACUUM, ANALYZE, and a few DDL
commands such as CREATE INDEX. A stand-alone ANALYZE, that is one not part of VACUUM, generates an approximate reltuples value since it does not read every row of the table. The planner will
scale the values it finds in pg_class to match the current physical table size, thus obtaining a closer approximation.
Most queries retrieve only a fraction of the rows in a table, due to having WHERE clauses that restrict the rows to be examined. The planner thus needs to make an estimate of the selectivity of
WHERE clauses, that is, the fraction of rows that match each condition in the WHERE clause. The information used for this task is stored in the pg_statistic system catalog. Entries in pg_statistic are
updated by the ANALYZE and VACUUM ANALYZE commands, and are always approximate even when freshly updated.
Rather than look at pg_statistic directly, it's better to look at its view pg_stats when examining the statistics manually. pg_stats is designed to be more easily readable. Furthermore, pg_stats is
readable by all, whereas pg_statistic is only readable by a superuser. (This prevents unprivileged users from learning something about the contents of other people's tables from the statistics. The
pg_stats view is restricted to show only rows about tables that the current user can read.) For example, we might do:
SELECT attname, n_distinct, most_common_vals FROM pg_stats WHERE tablename = 'road';

attname | n_distinct |
most_common_vals
---------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------
name | -0.467008 | {"I- 580 Ramp","I- 880 Ramp","Sp Railroad ","I- 580 ","I- 680
Ramp","I- 80 Ramp","14th St ","5th St ","Mission Blvd","I- 880
"}
thepath | 20 | {"[(-122.089,37.71),(-122.0886,37.711)]"}
(2 rows)
pg_stats is described in detail in Seção 43.46.
The amount of information stored in pg_statistic, in particular the maximum number of entries in the most_common_vals and histogram_bounds arrays for each column, can be set on a column-by-
column basis using the ALTER TABLE SET STATISTICS command, or globally by setting the default_statistics_target configuration variable. The default limit is presently 10 entries. Raising the limit may
allow more accurate planner estimates to be made, particularly for columns with irregular data distributions, at the price of consuming more space in pg_statistic and slightly more time to compute
the estimates. Conversely, a lower limit may be appropriate for columns with simple data distributions.

Using EXPLAIN Acima Controlling the Planner with Explicit JOIN Clauses
http://pgdocptbr.sourceforge.net/pg82/planner-stats.html[09/02/2018 18:18:23]
Controlling the Planner with Explicit JOIN Clauses


It is possible to control the query planner to some extent by using the explicit JOIN syntax. To see
why this matters, we first need some background.
In a simple join query, such as
SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;
the planner is free to join the given tables in any order. For example, it could generate a query plan
that joins A to B, using the WHERE condition a.id = b.id, and then joins C to this joined table, using
the other WHERE condition. Or it could join B to C and then join A to that result. Or it could join A
to C and then join them with B — but that would be inefficient, since the full Cartesian product of A
and C would have to be formed, there being no applicable condition in the WHERE clause to allow
optimization of the join. (All joins in the PostgreSQL executor happen between two input tables, so
it's necessary to build up the result in one or another of these fashions.) The important point is that
these different join possibilities give semantically equivalent results but may have hugely different
execution costs. Therefore, the planner will explore all of them to try to find the most efficient query
plan.
When a query only involves two or three tables, there aren't many join orders to worry about. But
the number of possible join orders grows exponentially as the number of tables expands. Beyond
ten or so input tables it's no longer practical to do an exhaustive search of all the possibilities, and
even for six or seven tables planning may take an annoyingly long time. When there are too many
input tables, the PostgreSQL planner will switch from exhaustive search to a genetic probabilistic
search through a limited number of possibilities. (The switch-over threshold is set by the
geqo_threshold run-time parameter.) The genetic search takes less time, but it won't necessarily find
the best possible plan.
When the query involves outer joins, the planner has less freedom than it does for plain (inner)
joins. For example, consider
SELECT * FROM a LEFT JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id);
Although this query's restrictions are superficially similar to the previous example, the semantics
are different because a row must be emitted for each row of A that has no matching row in the join
of B and C. Therefore the planner has no choice of join order here: it must join B to C and then join
A to that result. Accordingly, this query takes less time to plan than the previous query. In other
cases, the planner may be able to determine that more than one join order is safe. For example,
given
SELECT * FROM a LEFT JOIN b ON (a.bid = b.id) LEFT JOIN c ON (a.cid = c.id);
it is valid to join A to either B or C first. Currently, only FULL JOIN completely constrains the join
order. Most practical cases involving LEFT JOIN or RIGHT JOIN can be rearranged to some extent.
Explicit inner join syntax (INNER JOIN, CROSS JOIN, or unadorned JOIN) is semantically the same
as listing the input relations in FROM, so it does not constrain the join order.
Even though most kinds of JOIN don't completely constrain the join order, it is possible to instruct
http://pgdocptbr.sourceforge.net/pg82/explicit-joins.html[09/02/2018 18:18:33]
the PostgreSQL query planner to treat all JOIN clauses as constraining the join order anyway. For
example, these three queries are logically equivalent:
SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;

SELECT * FROM a CROSS JOIN b CROSS JOIN c WHERE a.id = b.id AND b.ref = c.id;
SELECT * FROM a JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id);
But if we tell the planner to honor the JOIN order, the second and third take less time to plan than
the first. This effect is not worth worrying about for only three tables, but it can be a lifesaver with
many tables.
To force the planner to follow the join order laid out by explicit JOINs, set the join_collapse_limit run-
time parameter to 1. (Other possible values are discussed below.)
You do not need to constrain the join order completely in order to cut search time, because it's OK
to use JOIN operators within items of a plain FROM list. For example, consider
SELECT * FROM a CROSS JOIN b, c, d, e WHERE ...;
With join_collapse_limit = 1, this forces the planner to join A to B before joining them to other
tables, but doesn't constrain its choices otherwise. In this example, the number of possible join
orders is reduced by a factor of 5.
Constraining the planner's search in this way is a useful technique both for reducing planning time
and for directing the planner to a good query plan. If the planner chooses a bad join order by
default, you can force it to choose a better order via JOIN syntax — assuming that you know of a
better order, that is. Experimentation is recommended.
A closely related issue that affects planning time is collapsing of subqueries into their parent query.
For example, consider
SELECT *
FROM x, y,
(SELECT * FROM a, b, c WHERE something) AS ss
WHERE somethingelse;
This situation might arise from use of a view that contains a join; the view's SELECT rule will be
inserted in place of the view reference, yielding a query much like the above. Normally, the planner
will try to collapse the subquery into the parent, yielding
SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
This usually results in a better plan than planning the subquery separately. (For example, the outer
WHERE conditions might be such that joining X to A first eliminates many rows of A, thus avoiding
the need to form the full logical output of the subquery.) But at the same time, we have increased
the planning time; here, we have a five-way join problem replacing two separate three-way join
problems. Because of the exponential growth of the number of possibilities, this makes a big
difference. The planner tries to avoid getting stuck in huge join search problems by not collapsing a
subquery if more than from_collapse_limit FROM items would result in the parent query. You can
trade off planning time against quality of plan by adjusting this run-time parameter up or down.
from_collapse_limit and join_collapse_limit are similarly named because they do almost the same
thing: one controls when the planner will "flatten out" subselects, and the other controls when it will
flatten out explicit joins. Typically you would either set join_collapse_limit equal to
from_collapse_limit (so that explicit joins and subselects act similarly) or set join_collapse_limit to 1
(if you want to control join order with explicit joins). But you might set them differently if you are
trying to fine-tune the trade-off between planning time and run time.

Statistics Used by the Planner Acima Populating a Database
Populating a Database


One may need to insert a large amount of data when first populating a database. This section
contains some suggestions on how to make this process as efficient as possible.
13.4.1. Disable Autocommit
Turn off autocommit and just do one commit at the end. (In plain SQL, this means issuing BEGIN at
the start and COMMIT at the end. Some client libraries may do this behind your back, in which case
you need to make sure the library does it when you want it done.) If you allow each insertion to be
committed separately, PostgreSQL is doing a lot of work for each row that is added. An additional
benefit of doing all insertions in one transaction is that if the insertion of one row were to fail then
the insertion of all rows inserted up to that point would be rolled back, so you won't be stuck with
partially loaded data.
13.4.2. Use COPY
Use COPY to load all the rows in one command, instead of using a series of INSERT commands. The
COPY command is optimized for loading large numbers of rows; it is less flexible than INSERT, but
incurs significantly less overhead for large data loads. Since COPY is a single command, there is no
need to disable autocommit if you use this method to populate a table.
If you cannot use COPY, it may help to use PREPARE to create a prepared INSERT statement, and
then use EXECUTE as many times as required. This avoids some of the overhead of repeatedly
parsing and planning INSERT.
Note that loading a large number of rows using COPY is almost always faster than using INSERT,
even if PREPARE is used and multiple insertions are batched into a single transaction.
13.4.3. Remove Indexes
If you are loading a freshly created table, the fastest way is to create the table, bulk load the table's
data using COPY, then create any indexes needed for the table. Creating an index on pre-existing
data is quicker than updating it incrementally as each row is loaded.
If you are adding large amounts of data to an existing table, it may be a win to drop the index, load
the table, and then recreate the index. Of course, the database performance for other users may be
adversely affected during the time that the index is missing. One should also think twice before
dropping unique indexes, since the error checking afforded by the unique constraint will be lost
while the index is missing.
13.4.4. Remove Foreign Key Constraints
Just as with indexes, a foreign key constraint can be checked "in bulk" more efficiently than row-by-
row. So it may be useful to drop foreign key constraints, load data, and re-create the constraints.
Again, there is a trade-off between data load speed and loss of error checking while the constraint
is missing.
13.4.5. Increase maintenance_work_mem
http://pgdocptbr.sourceforge.net/pg82/populate.html[09/02/2018 18:18:50]
Populating a Database
Temporarily increasing the maintenance_work_mem configuration variable when loading large

amounts of data can lead to improved performance. This will help to speed up CREATE INDEX
commands and ALTER TABLE ADD FOREIGN KEY commands. It won't do much for COPY itself, so
this advice is only useful when you are using one or both of the above techniques.
13.4.6. Increase checkpoint_segments
Temporarily increasing the checkpoint_segments configuration variable can also make large data
loads faster. This is because loading a large amount of data into PostgreSQL will cause checkpoints
to occur more often than the normal checkpoint frequency (specified by the checkpoint_timeout
configuration variable). Whenever a checkpoint occurs, all dirty pages must be flushed to disk. By
increasing checkpoint_segments temporarily during bulk data loads, the number of checkpoints that
are required can be reduced.
13.4.7. Run ANALYZE Afterwards
Whenever you have significantly altered the distribution of data within a table, running ANALYZE is
strongly recommended. This includes bulk loading large amounts of data into the table. Running
ANALYZE (or VACUUM ANALYZE) ensures that the planner has up-to-date statistics about the table.
With no statistics or obsolete statistics, the planner may make poor decisions during query
planning, leading to poor performance on any tables with inaccurate or nonexistent statistics.
13.4.8. Some Notes About pg_dump
Dump scripts generated by pg_dump automatically apply several, but not all, of the above
guidelines. To reload a pg_dump dump as quickly as possible, you need to do a few extra things
manually. (Note that these points apply while restoring a dump, not while creating it. The same
points apply when using pg_restore to load from a pg_dump archive file.)
By default, pg_dump uses COPY, and when it is generating a complete schema-and-data dump, it is
careful to load data before creating indexes and foreign keys. So in this case the first several
guidelines are handled automatically. What is left for you to do is to set appropriate (i.e., larger
than normal) values for maintenance_work_mem and checkpoint_segments before loading the
dump script, and then to run ANALYZE afterwards.
A data-only dump will still use COPY, but it does not drop or recreate indexes, and it does not
normally touch foreign keys. [1] So when loading a data-only dump, it is up to you to drop and
recreate indexes and foreign keys if you wish to use those techniques. It's still useful to increase
checkpoint_segments while loading the data, but don't bother increasing maintenance_work_mem;
rather, you'd do that while manually recreating indexes and foreign keys afterwards. And don't
forget to ANALYZE when you're done.
Notas
[1]
You can get the effect of disabling foreign keys by using the --disable-triggers option — but realize
that that eliminates, rather than just postponing, foreign key validation, and so it is possible to insert
bad data if you use it.

Controlling the Planner with Explicit Acima Administração do servidor
JOIN Clauses
http://pgdocptbr.sourceforge.net/pg82/populate.html[09/02/2018 18:18:50]
Administração do servidor

III. Administração do servidor

Esta parte cobre tópicos que são de interesse do administrador de banco de dados do PostgreSQL.
Inclui a instalação do produto, configuração do servidor, gerenciamento de usuários e de bancos de
dados, e tarefas de manutenção. Todos que gerenciam um servidor PostgreSQL para uso pessoal
ou, especialmente, de produção, devem estar familiarizados com os tópicos cobertos nesta parte.
As informações estão dispostas, aproximadamente, na ordem pela qual um novo usuário deve lê-
las. Porém, os capítulos são auto-contidos podendo ser lidos individualmente conforme desejado. As
informações estão apresentadas sob forma narrativa, sendo cada unidade um tópico. Os leitores à
procura de uma descrição completa de um determinado comando devem consultar a Parte VI.
Os capítulos iniciais estão escritos de forma que possam ser entendidos sem pré-requisitos de
conhecimento e, portanto, os novos usuários com necessidade de instalar seus próprios servidores
podem começar a leitura por estes capítulos. O restante está relacionado com ajuste e
gerenciamento, pressupondo que o leitor esteja familiarizado com o uso geral do sistema de banco
de dados PostgreSQL. Incentivamos os leitores lerem a Parte I e a Parte II para obter informações
adicionais.
Sumário
14. Installation Instructions
14.1. Short Version

14.2. Requirements
14.3. Getting The Source
14.4. If You Are Upgrading
14.5. Installation Procedure
14.6. Post-Installation Setup
14.7. Supported Platforms
15. Client-Only Installation on Windows

16. Operating System Environment
16.1. The PostgreSQL User Account

16.2. Creating a Database Cluster
16.3. Starting the Database Server
16.4. Managing Kernel Resources
16.5. Shutting Down the Server
16.6. Encryption Options
16.7. Secure TCP/IP Connections with SSL
16.8. Secure TCP/IP Connections with SSH Tunnels
17. Server Configuration
17.1. Setting Parameters

17.2. File Locations
17.3. Connections and Authentication
17.4. Resource Consumption
17.5. Write Ahead Log
17.6. Query Planning
17.7. Error Reporting and Logging
17.8. Run-Time Statistics
17.9. Automatic Vacuuming
http://pgdocptbr.sourceforge.net/pg82/admin.html[09/02/2018 18:19:32]
17.10. Client Connection Defaults

17.11. Lock Management
17.12. Version and Platform Compatibility
17.13. Preset Options
17.14. Customized Options
17.15. Developer Options
17.16. Short Options
18. Database Roles and Privileges
18.1. Database Roles

18.2. Role Attributes
18.3. Privileges
18.4. Role Membership
18.5. Functions and Triggers
19. Managing Databases
19.1. Visão geral

19.2. Creating a Database
19.3. Template Databases
19.4. Database Configuration
19.5. Destroying a Database
19.6. Tablespaces
20. Client Authentication
20.1. The pg_hba.conf file

20.2. Authentication methods
20.3. Authentication problems
21. Localization
21.1. Locale Support

21.2. Character Set Support
22. Routine Database Maintenance Tasks
22.1. Routine Vacuuming

22.2. Routine Reindexing
22.3. Log File Maintenance
23. Backup and Restore
23.1. SQL Dump

23.2. File System Level Backup
23.3. Continuous Archiving and Point-In-Time Recovery (PITR)
23.4. Warm Standby Servers for High Availability
23.5. Migration Between Releases
24. High Availability and Load Balancing

25. Monitoring Database Activity
25.1. Standard Unix Tools

25.2. The Statistics Collector
25.3. Viewing Locks
25.4. Dynamic Tracing
26. Monitoring Disk Usage
26.1. Determining Disk Usage

26.2. Disk Full Failure
27. Reliability and the Write-Ahead Log
27.1. Reliability
27.2. Write-Ahead Logging (WAL)
27.3. WAL Configuration
27.4. WAL Internals
28. Regression Tests
28.1. Running the Tests

28.2. Test Evaluation
28.3. Variant Comparison Files

Populating a Database Installation Instructions
Installation Instructions

Capítulo 14. Installation Instructions

Sumário
14.1. Short Version
14.2. Requirements
14.6.1. Shared Libraries

14.6.2. Environment Variables
This chapter describes the installation of PostgreSQL from the source code distribution. (If you are
installing a pre-packaged distribution, such as an RPM or Debian package, ignore this chapter and
read the packager's instructions instead.)

Administração do servidor Acima Short Version
http://pgdocptbr.sourceforge.net/pg82/installation.html[09/02/2018 18:19:57]
Short Version

Anterior Início Capítulo 14. Installation Instructions Fim Próxima
14.1. Short Version

./configure
gmake
su
gmake install
adduser postgres
mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data >logfile 2>&1 &
/usr/local/pgsql/bin/createdb test
/usr/local/pgsql/bin/psql test
The long version is the rest of this chapter.

Installation Instructions Acima Requirements
http://pgdocptbr.sourceforge.net/pg82/install-short.html[09/02/2018 18:20:13]
Requirements

14.2. Requirements
In general, a modern Unix-compatible platform should be able to run PostgreSQL. The platforms
that had received specific testing at the time of release are listed in Seção 14.7 below. In the doc
subdirectory of the distribution there are several platform-specific FAQ documents you might wish
to consult if you are having trouble.
The following software packages are required for building PostgreSQL:
GNU make is required; other make programs will not work. GNU make is often installed
under the name gmake; this document will always refer to it by that name. (On some systems
GNU make is the default tool with the name make.) To test for GNU make enter
gmake --version
It is recommended to use version 3.76.1 or later.
You need an ISO/ANSI C compiler. Recent versions of GCC are recommendable, but
PostgreSQL is known to build with a wide variety of compilers from different vendors.
tar is required to unpack the source distribution in the first place, in addition to either gzip or
bzip2.
The GNU Readline library (for simple line editing and command history retrieval) is used by
default. If you don't want to use it then you must specify the --without-readline option for
configure. As an alternative, you can often use the BSD-licensed libedit library, originally
developed on NetBSD. The libedit library is GNU Readline-compatible and is used if libreadline
is not found, or if --with-libedit-preferred is used as an option to configure. If you are using a
package-based Linux distribution, be aware that you need both the readline and readline-
devel packages, if those are separate in your distribution.
The zlib compression library will be used by default. If you don't want to use it then you must
specify the --without-zlib option for configure. Using this option disables support for
compressed archives in pg_dump and pg_restore.
Additional software is needed to build PostgreSQL on Windows. You can build PostgreSQL for
NT-based versions of Windows (like Windows XP and 2003) using MinGW; see
doc/FAQ_MINGW for details. You can also build PostgreSQL using Cygwin; see
doc/FAQ_CYGWIN. A Cygwin-based build will work on older versions of Windows, but if you
have a choice, we recommend the MinGW approach. While these are the only tool sets
recommended for a complete build, it is possible to build just the C client library (libpq) and
the interactive terminal (psql) using other Windows tool sets. For details of that see Capítulo
15.
The following packages are optional. They are not required in the default configuration, but they are
needed when certain build options are enabled, as explained below.
To build the server programming language PL/Perl you need a full Perl installation, including
the libperl library and the header files. Since PL/Perl will be a shared library, the libperl library
must be a shared library also on most platforms. This appears to be the default in recent Perl
versions, but it was not in earlier versions, and in any case it is the choice of whomever
installed Perl at your site.
http://pgdocptbr.sourceforge.net/pg82/install-requirements.html[09/02/2018 18:20:27]
Requirements
If you don't have the shared library but you need one, a message like this will appear during
the build to point out this fact:
*** Cannot build PL/Perl because libperl is not a shared library.

*** You might have to rebuild your Perl installation. Refer to
*** the documentation for details.
(If you don't follow the on-screen output you will merely notice that the PL/Perl library object,
plperl.so or similar, will not be installed.) If you see this, you will have to rebuild and install
Perl manually to be able to build PL/Perl. During the configuration process for Perl, request a
shared library.
To build the PL/Python server programming language, you need a Python installation with the
header files and the distutils module. The distutils module is included by default with Python
1.6 and later; users of earlier versions of Python will need to install it.
Since PL/Python will be a shared library, the libpython library must be a shared library also on
most platforms. This is not the case in a default Python installation. If after building and
installing you have a file called plpython.so (possibly a different extension), then everything
went well. Otherwise you should have seen a notice like this flying by:
*** Cannot build PL/Python because libpython is not a shared library.

*** You might have to rebuild your Python installation. Refer to
*** the documentation for details.
That means you have to rebuild (part of) your Python installation to supply this shared library.
If you have problems, run Python 2.3 or later's configure using the --enable-shared flag. On
some operating systems you don't have to build a shared library, but you will have to
convince the PostgreSQL build system of this. Consult the Makefile in the src/pl/plpython
directory for details.
If you want to build the PL/Tcl procedural language, you of course need a Tcl installation.
To enable Native Language Support (NLS), that is, the ability to display a program's messages
in a language other than English, you need an implementation of the Gettext API. Some
operating systems have this built-in (e.g., Linux, NetBSD, Solaris), for other systems you can
download an add-on package from http://developer.postgresql.org/~petere/bsd-gettext/. If you
are using the Gettext implementation in the GNU C library then you will additionally need the
GNU Gettext package for some utility programs. For any of the other implementations you will
not need it.
Kerberos, OpenSSL, OpenLDAP, and/or PAM, if you want to support authentication or

encryption using these services.
If you are building from a CVS tree instead of using a released source package, or if you want to do
development, you also need the following packages:
GNU Flex and Bison are needed to build a CVS checkout or if you changed the actual scanner
and parser definition files. If you need them, be sure to get Flex 2.5.4 or later and Bison
1.875 or later. Other yacc programs can sometimes be used, but doing so requires extra
effort and is not recommended. Other lex programs will definitely not work.
If you need to get a GNU package, you can find it at your local GNU mirror site (see
http://www.gnu.org/order/ftp.html for a list) or at ftp://ftp.gnu.org/gnu/.
Also check that you have sufficient disk space. You will need about 65 MB for the source tree during
compilation and about 15 MB for the installation directory. An empty database cluster takes about
25 MB, databases take about five times the amount of space that a flat text file with the same data
would take. If you are going to run the regression tests you will temporarily need up to an extra 90
MB. Use the df command to check free disk space.
Requirements

Short Version Acima Getting The Source
Getting The Source


The PostgreSQL 8.2.0 sources can be obtained by anonymous FTP from
ftp://ftp.postgresql.org/pub/source/v8.2.0/postgresql-8.2.0.tar.gz. Other download options can be found
on our website: http://www.postgresql.org/download/. After you have obtained the file, unpack it:
gunzip postgresql-8.2.0.tar.gz
tar xf postgresql-8.2.0.tar
This will create a directory postgresql-8.2.0 under the current directory with the PostgreSQL
sources. Change into that directory for the rest of the installation procedure.

Requirements Acima If You Are Upgrading
http://pgdocptbr.sourceforge.net/pg82/install-getsource.html[09/02/2018 18:20:38]
If You Are Upgrading


The internal data storage format changes with new releases of PostgreSQL. Therefore, if you are
upgrading an existing installation that does not have a version number "8.2.x", you must back up
and restore your data as shown here. These instructions assume that your existing installation is
under the /usr/local/pgsql directory, and that the data area is in /usr/local/pgsql/data. Substitute
your paths appropriately.
1. Make sure that your database is not updated during or after the backup. This does not affect
the integrity of the backup, but the changed data would of course not be included. If
necessary, edit the permissions in the file /usr/local/pgsql/data/pg_hba.conf (or equivalent) to
disallow access from everyone except you.
2. To back up your database installation, type:
pg_dumpall > arquivo_de_saída
If you need to preserve OIDs (such as when using them as foreign keys), then use the -o
option when running pg_dumpall.
To make the backup, you can use the pg_dumpall command from the version you are
currently running. For best results, however, try to use the pg_dumpall command from
PostgreSQL 8.2.0, since this version contains bug fixes and improvements over older versions.
While this advice might seem idiosyncratic since you haven't installed the new version yet, it
is advisable to follow it if you plan to install the new version in parallel with the old version. In
that case you can complete the installation normally and transfer the data later. This will also
decrease the downtime.
3. If you are installing the new version at the same location as the old one then shut down the
old server, at the latest before you install the new files:
pg_ctl stop
On systems that have PostgreSQL started at boot time, there is probably a start-up file that
will accomplish the same thing. For example, on a Red Hat Linux system one might find that
/etc/rc.d/init.d/postgresql stop
works.
4. If you are installing in the same place as the old version then it is also a good idea to move
the old installation out of the way, in case you have trouble and need to revert to it. Use a
command like this:
mv /usr/local/pgsql /usr/local/pgsql.old
After you have installed PostgreSQL 8.2.0, create a new database directory and start the new
server. Remember that you must execute these commands while logged in to the special database
user account (which you already have if you are upgrading).
http://pgdocptbr.sourceforge.net/pg82/install-upgrading.html[09/02/2018 18:20:48]
If You Are Upgrading
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
Finally, restore your data with
/usr/local/pgsql/bin/psql -d postgres -f arquivo_de_saída
using the new psql.
Further discussion appears in Seção 23.5, which you are encouraged to read in any case.

Getting The Source Acima Installation Procedure
http://pgdocptbr.sourceforge.net/pg82/install-upgrading.html[09/02/2018 18:20:48]
Installation Procedure

1. Configuration
The first step of the installation procedure is to configure the source tree for your system and
choose the options you would like. This is done by running the configure script. For a default
installation simply enter
./configure
This script will run a number of tests to guess values for various system dependent variables
and detect some quirks of your operating system, and finally will create several files in the
build tree to record what it found. (You can also run configure in a directory outside the
source tree if you want to keep the build directory separate.)
The default configuration will build the server and utilities, as well as all client applications and
interfaces that require only a C compiler. All files will be installed under /usr/local/pgsql by
default.
You can customize the build and installation process by supplying one or more of the following
command line options to configure:
--prefix=PREFIXO
Install all files under the directory PREFIXO instead of /usr/local/pgsql. The actual files
will be installed into various subdirectories; no files will ever be installed directly into the
PREFIXO directory.
If you have special needs, you can also customize the individual subdirectories with the
following options. However, if you leave these with their defaults, the installation will be
relocatable, meaning you can move the directory after installation. (The man and doc
locations are not affected by this.)
For relocatable installs, you might want to use configure's --disable-rpath option. Also,
you will need to tell the operating system how to find the shared libraries.
--exec-prefix=EXEC-PREFIXO
You can install architecture-dependent files under a different prefix, EXEC-PREFIXO,

than what PREFIXO was set to. This can be useful to share architecture-independent
files between hosts. If you omit this, then EXEC-PREFIXO is set equal to PREFIXO and
both architecture-dependent and independent files will be installed under the same tree,
which is probably what you want.
--bindir=DIRETÓRIO
Specifies the directory for executable programs. The default is EXEC-PREFIXO/bin, which
normally means /usr/local/pgsql/bin.
--datadir=DIRETÓRIO
http://pgdocptbr.sourceforge.net/pg82/install-procedure.html[09/02/2018 18:20:57]
Sets the directory for read-only data files used by the installed programs. The default is
PREFIXO/share. Note that this has nothing to do with where your database files will be
placed.
--sysconfdir=DIRETÓRIO
The directory for various configuration files, PREFIXO/etc by default.
--libdir=DIRETÓRIO
The location to install libraries and dynamically loadable modules. The default is EXEC-
PREFIXO/lib.
--includedir=DIRETÓRIO
The directory for installing C and C++ header files. The default is PREFIXO/include.
--mandir=DIRETÓRIO
The man pages that come with PostgreSQL will be installed under this directory, in their
respective manx subdirectories. The default is PREFIXO/man.
--with-docdir=DIRETÓRIO
--without-docdir
Documentation files, except "man" pages, will be installed into this directory. The default
is PREFIXO/doc. If the option --without-docdir is specified, the documentation will not be
installed by make install. This is intended for packaging scripts that have special
methods for installing documentation.
Nota: Care has been taken to make it possible to install PostgreSQL into shared
installation locations (such as /usr/local/include) without interfering with the
namespace of the rest of the system. First, the string "/postgresql" is automatically
appended to datadir, sysconfdir, and docdir, unless the fully expanded directory
name already contains the string "postgres" or "pgsql". For example, if you choose
/usr/local as prefix, the documentation will be installed in
/usr/local/doc/postgresql, but if the prefix is /opt/postgres, then it will be in
/opt/postgres/doc. The public C header files of the client interfaces are installed
into includedir and are namespace-clean. The internal header files and the server
header files are installed into private directories under includedir. See the
documentation of each interface for information about how to get at the its header
files. Finally, a private subdirectory will also be created, if appropriate, under libdir
for dynamically loadable modules.
--with-includes=DIRETÓRIOS
DIRETÓRIOS is a colon-separated list of directories that will be added to the list the
compiler searches for header files. If you have optional packages (such as GNU
Readline) installed in a non-standard location, you have to use this option and probably
also the corresponding --with-libraries option.
Example: --with-includes=/opt/gnu/include:/usr/sup/include.
--with-libraries=DIRETÓRIOS
DIRETÓRIOS is a colon-separated list of directories to search for libraries. You will

probably have to use this option (and the corresponding --with-includes option) if you
have packages installed in non-standard locations.
Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.
--enable-nls[=IDIOMAS]
Enables Native Language Support (NLS), that is, the ability to display a program's
messages in a language other than English. IDIOMAS is a space-separated list of codes

of the languages that you want supported, for example --enable-nls='de fr'. (The
intersection between your list and the set of actually provided translations will be
computed automatically.) If you do not specify a list, then all available translations are
installed.
To use this option, you will need an implementation of the Gettext API; see above.
--with-pgport=NÚMERO
Set NÚMERO as the default port number for server and clients. The default is 5432. The
port can always be changed later on, but if you specify it here then both server and
clients will have the same default compiled in, which can be very convenient. Usually the
only good reason to select a non-default value is if you intend to run multiple
PostgreSQL servers on the same machine.
--with-perl
Build the PL/Perl server-side language.
--with-python
Build the PL/Python server-side language.
--with-tcl
Build the PL/Tcl server-side language.
--with-tclconfig=DIRETÓRIO
Tcl installs the file tclConfig.sh, which contains configuration information needed to build
modules interfacing to Tcl. This file is normally found automatically at a well-known
location, but if you want to use a different version of Tcl you can specify the directory in
which to look for it.
--with-krb5
Build with support for Kerberos 5 authentication. On many systems, the Kerberos
system is not installed in a location that is searched by default (e.g., /usr/include,
/usr/lib), so you must use the options --with-includes and --with-libraries in addition to
this option. configure will check for the required header files and libraries to make sure
that your Kerberos installation is sufficient before proceeding.
--with-krb-srvnam=NOME
The default name of the Kerberos service principal. postgres is the default. There's
usually no reason to change this.
--with-openssl
Build with support for SSL (encrypted) connections. This requires the OpenSSL package
to be installed. configure will check for the required header files and libraries to make
sure that your OpenSSL installation is sufficient before proceeding.
--with-pam
Build with PAM (Pluggable Authentication Modules) support.
--with-ldap
Build with LDAP support for authentication and connection parameter lookup (see Seção
29.15 and Seção 20.2.5 for more information). On Unix, this requires the OpenLDAP
package to be installed. configure will check for the required header files and libraries to
make sure that your OpenLDAP installation is sufficient before proceeding. On Windows,
the default WinLDAP library is used.
--without-readline
Prevents use of the Readline library (and libedit as well). This option disables command-
line editing and history in psql, so it is not recommended.
--with-libedit-preferred
Favors the use of the BSD-licensed libedit library rather than GPL-licensed Readline. This
option is significant only if you have both libraries installed; the default in that case is to
use Readline.
--with-bonjour
Build with Bonjour support. This requires Bonjour support in your operating system.
Recommended on Mac OS X.
--enable-integer-datetimes
Use 64-bit integer storage for datetimes and intervals, rather than the default floating-
point storage. This reduces the range of representable values but guarantees
microsecond precision across the full range (see Seção 8.5 for more information). Note
also that the integer datetimes code is newer than the floating-point code, and we still
find bugs in it from time to time.
--disable-spinlocks
Allow the build to succeed even if PostgreSQL has no CPU spinlock support for the
platform. The lack of spinlock support will result in poor performance; therefore, this
option should only be used if the build aborts and informs you that the platform lacks
spinlock support. If this option is required to build PostgreSQL on your platform, please
report the problem to the PostgreSQL developers.
--enable-thread-safety
Make the client libraries thread-safe. This allows concurrent threads in libpq and ECPG
programs to safely control their private connection handles. This option requires
adequate threading support in your operating system.
--without-zlib
Prevents use of the Zlib library. This disables support for compressed archives in
pg_dump and pg_restore. This option is only intended for those rare systems where this
library is not available.
--enable-debug
Compiles all programs and libraries with debugging symbols. This means that you can
run the programs through a debugger to analyze problems. This enlarges the size of the
installed executables considerably, and on non-GCC compilers it usually also disables
compiler optimization, causing slowdowns. However, having the symbols available is
extremely helpful for dealing with any problems that may arise. Currently, this option is
recommended for production installations only if you use GCC. But you should always
have it on if you are doing development work or running a beta version.
--enable-cassert
Enables assertion checks in the server, which test for many "can't happen" conditions.
This is invaluable for code development purposes, but the tests slow things down a little.
Also, having the tests turned on won't necessarily enhance the stability of your server!
The assertion checks are not categorized for severity, and so what might be a relatively
harmless bug will still lead to server restarts if it triggers an assertion failure. Currently,
this option is not recommended for production use, but you should have it on for
development work or when running a beta version.
--enable-depend
Enables automatic dependency tracking. With this option, the makefiles are set up so
that all affected object files will be rebuilt when any header file is changed. This is useful
if you are doing development work, but is just wasted overhead if you intend only to
compile once and install. At present, this option will work only if you use GCC.
--enable-dtrace
Compiles with support for the dynamic tracing tool DTrace. Operating system support
for DTrace is currently only available in Solaris.
To point to the dtrace program, the environment variable DTRACE can be set. This will
often be necessary because dtrace is typically installed under /usr/sbin, which might not
be in the path. Additional command-line options for the dtrace program can be specified
in the environment variable DTRACEFLAGS.
If you prefer a C compiler different from the one configure picks, you can set the environment
variable CC to the program of your choice. By default, configure will pick gcc if available, else
the platform's default (usually cc). Similarly, you can override the default compiler flags if
needed with the CFLAGS variable.
You can specify environment variables on the configure command line, for example:
./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'
Here is a list of the significant variables that can be set in this manner:
CC
C compiler
CFLAGS
options to pass to the C compiler
CPP
C preprocessor
CPPFLAGS
options to pass to the C preprocessor
DTRACE
location of the dtrace program
DTRACEFLAGS
options to pass to the dtrace program
LDFLAGS
options to pass to the link editor
LDFLAGS_SL
linker options for shared library linking
MSGFMT
msgfmt program for native language support
PERL
Full path to the Perl interpreter. This will be used to determine the dependencies for
building PL/Perl.
PYTHON
Full path to the Python interpreter. This will be used to determine the dependencies for
building PL/Python.
TCLSH
Full path to the Tcl interpreter. This wil be used to determine the dependencies for
building PL/Tcl.
YACC
Yacc program (bison -y if using Bison)
2. Build
To start the build, type
gmake
(Remember to use GNU make.) The build may take anywhere from 5 minutes to half an hour
depending on your hardware. The last line displayed should be
All of PostgreSQL is successfully made. Ready to install.
3. Regression Tests
If you want to test the newly built server before you install it, you can run the regression tests
at this point. The regression tests are a test suite to verify that PostgreSQL runs on your
machine in the way the developers expected it to. Type
gmake check
(This won't work as root; do it as an unprivileged user.) Capítulo 28 contains detailed

information about interpreting the test results. You can repeat this test at any later time by
issuing the same command.
4. Installing The Files
Nota: If you are upgrading an existing system and are going to install the new
files over the old ones, be sure to back up your data and shut down the old server
before proceeding, as explained in Seção 14.4 above.
To install PostgreSQL enter
gmake install
This will install files into the directories that were specified in passo 1. Make sure that you
have appropriate permissions to write into that area. Normally you need to do this step as
root. Alternatively, you could create the target directories in advance and arrange for
appropriate permissions to be granted.
You can use gmake install-strip instead of gmake install to strip the executable files and
libraries as they are installed. This will save some space. If you built with debugging support,
stripping will effectively remove the debugging support, so it should only be done if debugging
is no longer needed. install-strip tries to do a reasonable job saving space, but it does not
have perfect knowledge of how to strip every unneeded byte from an executable file, so if you
want to save all the disk space you possibly can, you will have to do manual work.
The standard installation provides all the header files needed for client application
development as well as for server-side program development, such as custom functions or
data types written in C. (Prior to PostgreSQL 8.0, a separate gmake install-all-headers
command was needed for the latter, but this step has been folded into the standard install.)
Client-only installation: If you want to install only the client applications and interface
libraries, then you can use these commands:
gmake -C src/bin install

gmake -C src/include install
gmake -C src/interfaces install
gmake -C doc install
Registering eventlog on Windows: To register a Windows eventlog library with the operating
system, issue this command after installation:
regsvr32 diretório_da_biblioteca_pgsql/pgevent.dll
This creates registry entries used by the event viewer.
Uninstallation: To undo the installation use the command gmake uninstall. However, this will not
remove any created directories.
Cleaning: After the installation you can make room by removing the built files from the source tree
with the command gmake clean. This will preserve the files made by the configure program, so that
you can rebuild everything with gmake later on. To reset the source tree to the state in which it was
distributed, use gmake distclean. If you are going to build for several platforms within the same
source tree you must do this and re-configure for each build. (Alternatively, use a separate build
tree for each platform, so that the source tree remains unmodified.)
If you perform a build and then discover that your configure options were wrong, or if you change
anything that configure investigates (for example, software upgrades), then it's a good idea to do
gmake distclean before reconfiguring and rebuilding. Without this, your changes in configuration
choices may not propagate everywhere they need to.

If You Are Upgrading Acima Post-Installation Setup
Post-Installation Setup


14.6.1. Shared Libraries
On some systems that have shared libraries (which most systems do) you need to tell your system
how to find the newly installed shared libraries. The systems on which this is not necessary include
BSD/OS, FreeBSD, HP-UX, IRIX, Linux, NetBSD, OpenBSD, Tru64 UNIX (formerly Digital UNIX), and
Solaris.
The method to set the shared library search path varies between platforms, but the most widely
usable method is to set the environment variable LD_LIBRARY_PATH like so: In Bourne shells (sh,
ksh, bash, zsh)
LD_LIBRARY_PATH=/usr/local/pgsql/lib
export LD_LIBRARY_PATH
or in csh or tcsh
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
Replace /usr/local/pgsql/lib with whatever you set --libdir to in passo 1. You should put these
commands into a shell start-up file such as /etc/profile or ~/.bash_profile. Some good information
about the caveats associated with this method can be found at
http://www.visi.com/~barr/ldpath.html.
On some systems it might be preferable to set the environment variable LD_RUN_PATH before
building.
On Cygwin, put the library directory in the PATH or move the .dll files into the bin directory.
If in doubt, refer to the manual pages of your system (perhaps ld.so or rld). If you later on get a
message like
psql: error in loading shared libraries

libpq.so.2.1: cannot open shared object file: No such file or directory
then this step was necessary. Simply take care of it then.
If you are on BSD/OS, Linux, or SunOS 4 and you have root access you can run
/sbin/ldconfig /usr/local/pgsql/lib
(or equivalent directory) after installation to enable the run-time linker to find the shared libraries
faster. Refer to the manual page of ldconfig for more information. On FreeBSD, NetBSD, and
OpenBSD the command is
/sbin/ldconfig -m /usr/local/pgsql/lib
http://pgdocptbr.sourceforge.net/pg82/install-post.html[09/02/2018 18:21:16]
Post-Installation Setup
instead. Other systems are not known to have an equivalent command.
14.6.2. Environment Variables
If you installed into /usr/local/pgsql or some other location that is not searched for programs by
default, you should add /usr/local/pgsql/bin (or whatever you set --bindir to in passo 1) into your
PATH. Strictly speaking, this is not necessary, but it will make the use of PostgreSQL much more
convenient.
To do this, add the following to your shell start-up file, such as ~/.bash_profile (or /etc/profile, if
you want it to affect every user):
PATH=/usr/local/pgsql/bin:$PATH
export PATH
If you are using csh or tcsh, then use this command:
set path = ( /usr/local/pgsql/bin $path )
To enable your system to find the man documentation, you need to add lines like the following to a
shell start-up file unless you installed into a location that is searched by default.
MANPATH=/usr/local/pgsql/man:$MANPATH
export MANPATH
The environment variables PGHOST and PGPORT specify to client applications the host and port of
the database server, overriding the compiled-in defaults. If you are going to run client applications
remotely then it is convenient if every user that plans to use the database sets PGHOST. This is not
required, however: the settings can be communicated via command line options to most client
programs.

Installation Procedure Acima Supported Platforms
http://pgdocptbr.sourceforge.net/pg82/install-post.html[09/02/2018 18:21:16]
Supported Platforms


PostgreSQL has been verified by the developer community to work on the platforms listed below. A
supported platform generally means that PostgreSQL builds and installs according to these
instructions and that the regression tests pass. "Build farm" entries refer to active test machines in
the PostgreSQL Build Farm. Platform entries that show an older version of PostgreSQL are those that
did not receive explicit testing at the time of release of version 8.2 but that we still expect to work.
Nota: If you are having problems with the installation on a supported platform, please
write to <pgsql-bugs@postgresql.org> or <pgsql-ports@postgresql.org> , not to the people
listed here.
OS Processor Version Reported Remarks

AIX PowerPC 8.2.0 Build farm grebe (5.3, gcc 4.0.1); kookaburra see doc/FAQ_AIX,
(5.2, cc 6.0); asp (5.2, gcc 3.3.2) particularly if
using AIX 5.3
ML3
AIX RS6000 8.0.0 Hans-Jürgen Schönig (<hs@cybertec.at> ), 2004- see doc/FAQ_AIX
12-06
BSD/OS x86 8.1.0 Bruce Momjian (<pgman@candle.pha.pa.us> ), 4.3.1
2005-10-26
Debian Alpha 8.2.0 Build farm hare (3.1, gcc 3.3.4)
GNU/Linux
Debian AMD64 8.2.0 Build farm shad (4.0, gcc 4.1.2); kite (3.1, gcc
GNU/Linux 4.0); panda (sid, gcc 3.3.5)
Debian ARM 8.2.0 Build farm penguin (3.1, gcc 3.3.4)
GNU/Linux
Debian Athlon XP 8.2.0 Build farm rook (3.1, gcc 3.3.5)
GNU/Linux
Debian IA64 8.2.0 Build farm dugong (unstable, icc 9.1.045)
GNU/Linux
Debian m68k 8.0.0 Noèl Köthe (<noel@debian.org> ), 2004-12-09 sid
GNU/Linux
Debian MIPS 8.2.0 Build farm otter (3.1, gcc 3.3.4)
GNU/Linux
Debian MIPSEL 8.2.0 Build farm lionfish (3.1, gcc 3.3.4); corgi (3.1, gcc
GNU/Linux 3.3.4)
Debian PA-RISC 8.2.0 Build farm manatee (3.1, gcc 4.0.1); kingfisher
GNU/Linux (3.1, gcc 3.3.5)
Debian PowerPC 8.0.0 Noèl Köthe (<noel@debian.org> ), 2004-12-15 sid
GNU/Linux
Debian Sparc 8.1.0 Build farm dormouse (3.1, gcc 3.2.5; 64-bit)
GNU/Linux
Debian x86 8.2.0 Build farm wildebeest (3.1, gcc 3.3.5)
GNU/Linux
Fedora AMD64 8.2.0 Build farm impala (FC6, gcc 4.1.1); bustard (FC5,
Linux gcc 4.1.0); wasp (FC5, gcc 4.1.0); viper (FC3, gcc
3.4.4)
http://pgdocptbr.sourceforge.net/pg82/supported-platforms.html[09/02/2018 18:21:28]
Supported Platforms
Fedora PowerPC 8.2.0 Build farm sponge (FC5, gcc 4.1.0)

Linux
Fedora x86 8.2.0 Build farm agouti (FC5, gcc 4.1.1); thrush (FC1,
Linux gcc 3.3.2)
FreeBSD AMD64 8.2.0 Build farm platypus (6, gcc 3.4.4); dove (6.1, gcc
3.4.4); ermine (6.1, gcc 3.4.4)
FreeBSD x86 8.2.0 Build farm minnow (6.1, gcc 3.4.4); echidna (6,
gcc 3.4.2); herring (6, Intel cc 7.1)
Gentoo AMD64 8.1.0 Build farm caribou (2.6.9, gcc 3.3.5)
Linux
Gentoo IA64 8.2.0 Build farm stoat (2.6, gcc 3.3)
Linux
Gentoo PowerPC 8.2.0 Build farm cobra (1.4.16, gcc 3.4.3)
Linux 64
Gentoo x86 8.2.0 Build farm mongoose (1.6.14, icc 9.0.032)
Linux
HP-UX IA64 8.2.0 Tom Lane (<tgl@sss.pgh.pa.us> ), 2006-10-23 11.23, gcc and
cc; see
doc/FAQ_HPUX
HP-UX PA-RISC 8.2.0 Tom Lane (<tgl@sss.pgh.pa.us> ), 2006-10-23 10.20 and 11.23,
gcc and cc; see
doc/FAQ_HPUX
IRIX MIPS 8.1.0 Kenneth Marshall (<ktm@is.rice.edu> ), 2005-11- 6.5, cc only
04
Kubuntu AMD64 8.2.0 Build farm rosella (5.10 "Breezy", gcc 4.0)
Linux
Mac OS X PowerPC 8.2.0 Build farm tuna (10.4.2, gcc 4.0)
Mac OS X x86 8.2.0 Build farm jackal (10.4.8, gcc 4.0.1)
Mandriva x86 8.2.0 Build farm gopher (Mandriva 2006, gcc 4.0.1)
Linux
NetBSD m68k 8.2.0 Build farm osprey (2.0, gcc 3.3.3)
NetBSD x86 8.2.0 Build farm gazelle (3.0, gcc 3.3.3); canary (1.6,
gcc 2.95.3)
OpenBSD AMD64 8.2.0 Build farm zebra (4.0, gcc 3.3.5)
OpenBSD Sparc 8.0.0 Chris Mair (<list@1006.org> ), 2005-01-10 3.3
OpenBSD Sparc64 8.2.0 Build farm spoonbill (3.9, gcc 3.3.5)
OpenBSD x86 8.2.0 Build farm emu (4.0, gcc 3.3.5); guppy (3.8, gcc minor ecpg test
3.3.5) failure on 3.8
Red Hat AMD64 8.1.0 Tom Lane (<tgl@sss.pgh.pa.us> ), 2005-10-23 RHEL 4
Linux
Red Hat IA64 8.1.0 Tom Lane (<tgl@sss.pgh.pa.us> ), 2005-10-23 RHEL 4
Linux
Red Hat PowerPC 8.1.0 Tom Lane (<tgl@sss.pgh.pa.us> ), 2005-10-23 RHEL 4
Linux
Red Hat PowerPC 8.1.0 Tom Lane (<tgl@sss.pgh.pa.us> ), 2005-10-23 RHEL 4
Linux 64
Red Hat S/390 8.1.0 Tom Lane (<tgl@sss.pgh.pa.us> ), 2005-10-23 RHEL 4
Linux
Red Hat S/390x 8.1.0 Tom Lane (<tgl@sss.pgh.pa.us> ), 2005-10-23 RHEL 4
Linux
Red Hat x86 8.1.0 Tom Lane (<tgl@sss.pgh.pa.us> ), 2005-10-23 RHEL 4
Linux
Slackware x86 8.1.0 Sergey Koposov (<math@sai.msu.ru> ), 2005-10- 10.0
Linux 24
Solaris Sparc 8.2.0 Build farm hyena (Solaris 10, gcc 3.4.3) see
Supported Platforms
doc/FAQ_Solaris
Solaris x86 8.2.0 Build farm dragonfly (Solaris 9, gcc 3.2.3); kudu see
(Solaris 9, cc 5.3) doc/FAQ_Solaris
SUSE AMD64 8.1.0 Josh Berkus (<josh@agliodbs.com> ), 2005-10-23 SLES 9.3
Linux
SUSE IA64 8.0.0 Reinhard Max (<max@suse.de> ), 2005-01-03 SLES 9
Linux
SUSE PowerPC 8.0.0 Reinhard Max (<max@suse.de> ), 2005-01-03 SLES 9
Linux
SUSE PowerPC 8.0.0 Reinhard Max (<max@suse.de> ), 2005-01-03 SLES 9
Linux 64
SUSE S/390 8.0.0 Reinhard Max (<max@suse.de> ), 2005-01-03 SLES 9
Linux
SUSE S/390x 8.0.0 Reinhard Max (<max@suse.de> ), 2005-01-03 SLES 9
Linux
SUSE x86 8.0.0 Reinhard Max (<max@suse.de> ), 2005-01-03 9.0, 9.1, 9.2,
Linux SLES 9
Tru64 Alpha 8.1.0 Honda Shigehiro (<fwif0083@mb.infoweb.ne.jp> ), 5.0, cc 6.1-011
UNIX 2005-11-01
Ubuntu x86 8.2.0 Build farm caracara (6.06, gcc 4.0.3)
Linux
UnixWare x86 8.2.0 Build farm warthog (7.1.4, cc 4.2) see doc/FAQ_SCO
Windows x86 8.2.0 Build farm yak (XP SP2, gcc 3.4.2); bandicoot see
(Windows 2000 Pro, gcc 3.4.2); snake (Windows doc/FAQ_MINGW
Server 2003 SP1, gcc 3.4.2); trout (Windows
Server 2000 SP4, gcc 3.4.2)
Windows x86 8.2.0 Build farm eel (W2K Server SP4, gcc 3.4.4) see
with doc/FAQ_CYGWIN
Cygwin
Yellow PowerPC 8.1.0 Build farm carp (4.0, gcc 3.3.3)
Dog Linux
Unsupported Platforms: The following platforms used to work but have not been tested recently.
We include these here to let you know that these platforms could be supported if given some
attention.
OS Processor Version Reported Remarks

Debian S/390 7.4 Noèl Köthe (<noel@debian.org> ),
GNU/Linux 2003-10-25
FreeBSD Alpha 7.4 Peter Eisentraut 4.8
(<peter_e@gmx.net> ), 2003-10-25
Linux PlayStation 8.0.0 Chris Mair (<list@1006.org> ), requires --disable-spinlocks
2 2005-01-09 (works, but very slow)
NetBSD Alpha 7.2 Thomas Thai 1.5W
(<tom@minnesota.com> ), 2001-
11-20
NetBSD arm32 7.4 Patrick Welche 1.6ZE/acorn32
(<prlw1@newn.cam.ac.uk> ), 2003-
11-12
NetBSD MIPS 7.2.1 Warwick Hunter 1.5.3
(<whunter@agile.tv> ), 2002-06-13
NetBSD PowerPC 7.2 Bill Studenmund 1.5
(<wrstuden@netbsd.org> ), 2001-
11-28
NetBSD Sparc 7.4.1 Peter Eisentraut 1.6.1, 32-bit
(<peter_e@gmx.net> ), 2003-11-26
Supported Platforms
NetBSD VAX 7.1 Tom I. Helbekkmo 1.5

(<tih@kpnQwest.no> ), 2001-03-30
SCO x86 7.3.1 Shibashish Satpathy 5.0.4, gcc; see also
OpenServer (<shib@postmark.net> ), 2002-12- doc/FAQ_SCO
11
SunOS 4 Sparc 7.2 Tatsuo Ishii (<t-ishii@sra.co.jp> ),
2001-12-04

Post-Installation Setup Acima Client-Only Installation on Windows
Client-Only Installation on Windows

Capítulo 15. Client-Only Installation on Windows

Although a complete PostgreSQL installation for Windows can only be built using MinGW or Cygwin,
the C client library (libpq) and the interactive terminal (psql) can be compiled using other Windows
tool sets. Makefiles are included in the source distribution for Microsoft Visual C++ and Borland
C++. It should be possible to compile the libraries manually for other configurations.
Dica: Using MinGW or Cygwin is preferred. If using one of those tool sets, see Capítulo
14.
To build everything that you can on Windows using Microsoft Visual C++, change into the src
directory and type the command
nmake /f win32.mak
This assumes that you have Visual C++ in your path.
To build everything using Borland C++, change into the src directory and type the command
make -N -DCFG=Release /f bcc32.mak
The following files will be built:
interfaces\libpq\Release\libpq.dll
The dynamically linkable frontend library
interfaces\libpq\Release\libpqdll.lib
Import library to link your programs to libpq.dll
interfaces\libpq\Release\libpq.lib
Static version of the frontend library
bin\pg_config\Release\pg_config.exe
bin\psql\Release\psql.exe
bin\pg_dump\Release\pg_dump.exe
bin\pg_dump\Release\pg_dumpall.exe
bin\pg_dump\Release\pg_restore.exe
bin\scripts\Release\clusterdb.exe
bin\scripts\Release\createdb.exe
bin\scripts\Release\createuser.exe
bin\scripts\Release\createlang.exe
bin\scripts\Release\dropdb.exe
bin\scripts\Release\dropuser.exe
bin\scripts\Release\droplang.exe
bin\scripts\Release\vacuumdb.exe
bin\scripts\Release\reindexdb.exe
The PostgreSQL client applications and utilities.
http://pgdocptbr.sourceforge.net/pg82/install-win32.html[09/02/2018 18:21:57]
Client-Only Installation on Windows
The only file that really needs to be installed is the libpq.dll library. This file should in most cases be
placed in the WINNT\SYSTEM32 directory (or in WINDOWS\SYSTEM on a Windows 95/98/ME
system). If this file is installed using a setup program, it should be installed with version checking
using the VERSIONINFO resource included in the file, to ensure that a newer version of the library is
not overwritten.
If you plan to do development using libpq on this machine, you will have to add the src\include and
src\interfaces\libpq subdirectories of the source tree to the include path in your compiler's settings.
To use the library, you must add the libpqdll.lib file to your project. (In Visual C++, just right-click
on the project and choose to add it.)
Free development tools from Microsoft can be downloaded from

http://msdn.microsoft.com/visualc/vctoolkit2003/. You will also need MSVCRT.lib from the platform
SDK from http://www.microsoft.com/msdownload/platformsdk/sdkupdate/. You can also download the
.NET framework from http://msdn.microsoft.com/netframework/downloads/updates/default.aspx. Once
installed, the toolkit binaries must be in your path, and you might need to add a /lib:<libpath> to
point to MSVCRT.lib. Free Borland C++ compiler tools can be downloaded from
http://www.borland.com/products/downloads/download_cbuilder.html#, and require similar setup.

Supported Platforms Acima Operating System Environment
http://pgdocptbr.sourceforge.net/pg82/install-win32.html[09/02/2018 18:21:57]
Operating System Environment

Capítulo 16. Operating System Environment

Sumário
16.3.1. Server Start-up Failures

16.3.2. Client Connection Problems
16.4.1. Shared Memory and Semaphores

16.4.2. Resource Limits
16.4.3. Linux Memory Overcommit

This chapter discusses how to set up and run the database server and its interactions with the
operating system.

Client-Only Installation on Windows Acima The PostgreSQL User Account
http://pgdocptbr.sourceforge.net/pg82/runtime.html[09/02/2018 18:22:06]
The PostgreSQL User Account

Anterior Início Capítulo 16. Operating System Environment Fim Próxima

As with any other server daemon that is accessible to the outside world, it is advisable to run
PostgreSQL under a separate user account. This user account should only own the data that is
managed by the server, and should not be shared with other daemons. (For example, using the
user nobody is a bad idea.) It is not advisable to install executables owned by this user because
compromised systems could then modify their own binaries.
To add a Unix user account to your system, look for a command useradd or adduser. The user
name postgres is often used, and is assumed throughout this book, but you can use another name
if you like.

Operating System Environment Acima Creating a Database Cluster
http://pgdocptbr.sourceforge.net/pg82/postgres-user.html[09/02/2018 18:22:23]
Creating a Database Cluster


Before you can do anything, you must initialize a database storage area on disk. We call this a
database cluster. (SQL uses the term catalog cluster.) A database cluster is a collection of
databases that is managed by a single instance of a running database server. After initialization, a
database cluster will contain a database named postgres, which is meant as a default database for
use by utilities, users and third party applications. The database server itself does not require the
postgres database to exist, but many external utility programs assume it exists. Another database
created within each cluster during initialization is called template1. As the name suggests, this will
be used as a template for subsequently created databases; it should not be used for actual work.
(See Capítulo 19 for information about creating new databases within a cluster.)
In file system terms, a database cluster will be a single directory under which all data will be stored.
We call this the data directory or data area. It is completely up to you where you choose to store
your data. There is no default, although locations such as /usr/local/pgsql/data or
/var/lib/pgsql/data are popular. To initialize a database cluster, use the command initdb, which is
installed with PostgreSQL. The desired file system location of your database cluster is indicated by
the -D option, for example
$ initdb -D /usr/local/pgsql/data
Note that you must execute this command while logged into the PostgreSQL user account, which is
described in the previous section.
Dica: As an alternative to the -D option, you can set the environment variable PGDATA.
initdb will attempt to create the directory you specify if it does not already exist. It is likely that it
will not have the permission to do so (if you followed our advice and created an unprivileged
account). In that case you should create the directory yourself (as root) and change the owner to
be the PostgreSQL user. Here is how this might be done:
root# mkdir /usr/local/pgsql/data

root# chown postgres /usr/local/pgsql/data
root# su postgres
postgres$ initdb -D /usr/local/pgsql/data
initdb will refuse to run if the data directory looks like it has already been initialized.
Because the data directory contains all the data stored in the database, it is essential that it be
secured from unauthorized access. initdb therefore revokes access permissions from everyone but
the PostgreSQL user.
However, while the directory contents are secure, the default client authentication setup allows any
local user to connect to the database and even become the database superuser. If you do not trust
other local users, we recommend you use one of initdb's -W, --pwprompt or --pwfile options to
assign a password to the database superuser. Also, specify -A md5 or -A password so that the
default trust authentication mode is not used; or modify the generated pg_hba.conf file after
running initdb, before you start the server for the first time. (Other reasonable approaches include
using ident authentication or file system permissions to restrict connections. See Capítulo 20 for
more information.)
initdb also initializes the default locale for the database cluster. Normally, it will just take the locale
http://pgdocptbr.sourceforge.net/pg82/creating-cluster.html[09/02/2018 18:22:34]
Creating a Database Cluster
settings in the environment and apply them to the initialized database. It is possible to specify a
different locale for the database; more information about that can be found in Seção 21.1. The sort
order used within a particular database cluster is set by initdb and cannot be changed later, short of
dumping all data, rerunning initdb, and reloading the data. There is also a performance impact for
using locales other than C or POSIX. Therefore, it is important to make this choice correctly the first
time.
initdb also sets the default character set encoding for the database cluster. Normally this should be
chosen to match the locale setting. For details see Seção 21.2.

The PostgreSQL User Account Acima Starting the Database Server
http://pgdocptbr.sourceforge.net/pg82/creating-cluster.html[09/02/2018 18:22:34]
Starting the Database Server


Before anyone can access the database, you must start the database server. The database server
program is called postgres. The postgres program must know where to find the data it is supposed
to use. This is done with the -D option. Thus, the simplest way to start the server is:
$ postgres -D /usr/local/pgsql/data
which will leave the server running in the foreground. This must be done while logged into the
PostgreSQL user account. Without -D, the server will try to use the data directory named by the
environment variable PGDATA. If that variable is not provided either, it will fail.
Normally it is better to start postgres in the background. For this, use the usual shell syntax:
$ postgres -D /usr/local/pgsql/data >logfile 2>&1 &
It is important to store the server's stdout and stderr output somewhere, as shown above. It will
help for auditing purposes and to diagnose problems. (See Seção 22.3 for a more thorough
discussion of log file handling.)
The postgres program also takes a number of other command-line options. For more information,
see the postgres reference page and Capítulo 17 below.
This shell syntax can get tedious quickly. Therefore the wrapper program pg_ctl is provided to
simplify some tasks. For example:
pg_ctl start -l logfile
will start the server in the background and put the output into the named log file. The -D option has
the same meaning here as for postgres. pg_ctl is also capable of stopping the server.
Normally, you will want to start the database server when the computer boots. Autostart scripts are
operating-system-specific. There are a few distributed with PostgreSQL in the contrib/start-scripts
directory. Installing one will require root privileges.
Different systems have different conventions for starting up daemons at boot time. Many systems
have a file /etc/rc.local or /etc/rc.d/rc.local. Others use rc.d directories. Whatever you do, the
server must be run by the PostgreSQL user account and not by root or any other user. Therefore
you probably should form your commands using su -c '...' postgres. For example:
su -c 'pg_ctl start -D /usr/local/pgsql/data -l serverlog' postgres
Here are a few more operating-system-specific suggestions. (In each case be sure to use the proper
installation directory and user name where we show generic values.)
For FreeBSD, look at the file contrib/start-scripts/freebsd in the PostgreSQL source

distribution.
On OpenBSD, add the following lines to the file /etc/rc.local:
http://pgdocptbr.sourceforge.net/pg82/server-start.html[09/02/2018 18:26:18]
if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then

su - -c '/usr/local/pgsql/bin/pg_ctl start -l /var/postgresql/log -s' postgres
echo -n ' postgresql'
fi
On Linux systems either add
/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data
to /etc/rc.d/rc.local or look at the file contrib/start-scripts/linux in the PostgreSQL source

distribution.
On NetBSD, either use the FreeBSD or Linux start scripts, depending on preference.
On Solaris, create a file called /etc/init.d/postgresql that contains the following line:
su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D

/usr/local/pgsql/data"
Then, create a symbolic link to it in /etc/rc3.d as S99postgresql.
While the server is running, its PID is stored in the file postmaster.pid in the data directory. This is
used to prevent multiple server instances from running in the same data directory and can also be
used for shutting down the server.
16.3.1. Server Start-up Failures
There are several common reasons the server might fail to start. Check the server's log file, or start
it by hand (without redirecting standard output or standard error) and see what error messages
appear. Below we explain some of the most common error messages in more detail.
LOG: could not bind IPv4 socket: Address already in use

HINT: Is another postmaster already running on port 5432? If not, wait a few seconds and
retry.
FATAL: could not create TCP/IP listen socket
This usually means just what it suggests: you tried to start another server on the same port where
one is already running. However, if the kernel error message is not Address already in use or some
variant of that, there may be a different problem. For example, trying to start a server on a
reserved port number may draw something like:
$ postgres -p 666
LOG: could not bind IPv4 socket: Permission denied
HINT: Is another postmaster already running on port 666? If not, wait a few seconds and
retry.
FATAL: could not create TCP/IP listen socket
A message like
FATAL: could not create shared memory segment: Invalid argument

DETAIL: Failed system call was shmget(key=5440001, size=4011376640, 03600).
probably means your kernel's limit on the size of shared memory is smaller than the work area
PostgreSQL is trying to create (4011376640 bytes in this example). Or it could mean that you do
not have System-V-style shared memory support configured into your kernel at all. As a temporary
workaround, you can try starting the server with a smaller-than-normal number of buffers
(shared_buffers). You will eventually want to reconfigure your kernel to increase the allowed shared
memory size. You may also see this message when trying to start multiple servers on the same
machine, if their total space requested exceeds the kernel limit.
An error like
FATAL: could not create semaphores: No space left on device

DETAIL: Failed system call was semget(5440126, 17, 03600).
does not mean you've run out of disk space. It means your kernel's limit on the number of System
V semaphores is smaller than the number PostgreSQL wants to create. As above, you may be able
to work around the problem by starting the server with a reduced number of allowed connections
(max_connections), but you'll eventually want to increase the kernel limit.
If you get an "illegal system call" error, it is likely that shared memory or semaphores are not
supported in your kernel at all. In that case your only option is to reconfigure the kernel to enable
these features.
Details about configuring System V IPC facilities are given in Seção 16.4.1.
16.3.2. Client Connection Problems
Although the error conditions possible on the client side are quite varied and application-dependent,
a few of them might be directly related to how the server was started up. Conditions other than
those shown below should be documented with the respective client application.
psql: could not connect to server: Connection refused

Is the server running on host "server.joe.com" and accepting
TCP/IP connections on port 5432?
This is the generic "I couldn't find a server to talk to" failure. It looks like the above when TCP/IP
communication is attempted. A common mistake is to forget to configure the server to allow TCP/IP
connections.
Alternatively, you'll get this when attempting Unix-domain socket communication to a local server:
psql: could not connect to server: No such file or directory

Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
The last line is useful in verifying that the client is trying to connect to the right place. If there is in
fact no server running there, the kernel error message will typically be either Connection refused or
No such file or directory, as illustrated. (It is important to realize that Connection refused in this
context does not mean that the server got your connection request and rejected it. That case will
produce a different message, as shown in Seção 20.3.) Other error messages such as Connection
timed out may indicate more fundamental problems, like lack of network connectivity.

Creating a Database Cluster Acima Managing Kernel Resources
Managing Kernel Resources


A large PostgreSQL installation can quickly exhaust various operating system resource limits. (On
some systems, the factory defaults are so low that you don't even need a really "large" installation.)
If you have encountered this kind of problem, keep reading.
16.4.1. Shared Memory and Semaphores
Shared memory and semaphores are collectively referred to as "System V IPC" (together with
message queues, which are not relevant for PostgreSQL). Almost all modern operating systems
provide these features, but not all of them have them turned on or sufficiently sized by default,
especially systems with BSD heritage. (For the Windows port, PostgreSQL provides its own
replacement implementation of these facilities.)
The complete lack of these facilities is usually manifested by an Illegal system call error upon server
start. In that case there's nothing left to do but to reconfigure your kernel. PostgreSQL won't work
without them.
When PostgreSQL exceeds one of the various hard IPC limits, the server will refuse to start and
should leave an instructive error message describing the problem encountered and what to do
about it. (See also Seção 16.3.1.) The relevant kernel parameters are named consistently across
different systems; Tabela 16-1 gives an overview. The methods to set them, however, vary.
Suggestions for some platforms are given below. Be warned that it is often necessary to reboot
your machine, and possibly even recompile the kernel, to change these settings.
Tabela 16-1. System V IPC parameters
Name Description Reasonable values

SHMMAX Maximum size of shared memory at least several megabytes (see text)
segment (bytes)
SHMMIN Minimum size of shared memory segment 1
(bytes)
SHMALL Total amount of shared memory available if bytes, same as SHMMAX; if pages,
(bytes or pages) ceil(SHMMAX/PAGE_SIZE)
SHMSEG Maximum number of shared memory only 1 segment is needed, but the default is much
segments per process higher
SHMMNI Maximum number of shared memory like SHMSEG plus room for other applications
segments system-wide
SEMMNI Maximum number of semaphore at least ceil(max_connections / 16)
identifiers (i.e., sets)
SEMMNS Maximum number of semaphores ceil(max_connections / 16) * 17 plus room for
system-wide other applications
SEMMSL Maximum number of semaphores per set at least 17
SEMMAP Number of entries in semaphore map see text
SEMVMX Maximum value of semaphore at least 1000 (The default is often 32767, don't
change unless forced to)
The most important shared memory parameter is SHMMAX, the maximum size, in bytes, of a
http://pgdocptbr.sourceforge.net/pg82/kernel-resources.html[09/02/2018 18:26:27]
shared memory segment. If you get an error message from shmget like Invalid argument, it is
likely that this limit has been exceeded. The size of the required shared memory segment varies
depending on several PostgreSQL configuration parameters, as shown in Tabela 16-2. You can, as a
temporary solution, lower some of those settings to avoid the failure. As a rough approximation,
you can estimate the required segment size as 500 kB plus the variable amounts shown in the
table. (Any error message you might get will include the exact size of the failed allocation request.)
While it is possible to get PostgreSQL to run with SHMMAX as small as 1 MB, you need at least 4 MB
for acceptable performance, and desirable settings are in the tens of megabytes.
Some systems also have a limit on the total amount of shared memory in the system (SHMALL).
Make sure this is large enough for PostgreSQL plus any other applications that are using shared
memory segments. (Caution: SHMALL is measured in pages rather than bytes on many systems.)
Less likely to cause problems is the minimum size for shared memory segments (SHMMIN), which
should be at most approximately 500 kB for PostgreSQL (it is usually just 1). The maximum number
of segments system-wide (SHMMNI) or per-process (SHMSEG) are unlikely to cause a problem
unless your system has them set to zero.
PostgreSQL uses one semaphore per allowed connection (max_connections), in sets of 16. Each such
set will also contain a 17th semaphore which contains a "magic number", to detect collision with
semaphore sets used by other applications. The maximum number of semaphores in the system is
set by SEMMNS, which consequently must be at least as high as max_connections plus one extra
for each 16 allowed connections (see the formula in Tabela 16-1). The parameter SEMMNI
determines the limit on the number of semaphore sets that can exist on the system at one time.
Hence this parameter must be at least ceil(max_connections / 16). Lowering the number of allowed
connections is a temporary workaround for failures, which are usually confusingly worded No space
left on device, from the function semget.
In some cases it might also be necessary to increase SEMMAP to be at least on the order of
SEMMNS. This parameter defines the size of the semaphore resource map, in which each
contiguous block of available semaphores needs an entry. When a semaphore set is freed it is either
added to an existing entry that is adjacent to the freed block or it is registered under a new map
entry. If the map is full, the freed semaphores get lost (until reboot). Fragmentation of the
semaphore space could over time lead to fewer available semaphores than there should be.
The SEMMSL parameter, which determines how many semaphores can be in a set, must be at least
17 for PostgreSQL.
Various other settings related to "semaphore undo", such as SEMMNU and SEMUME, are not of
concern for PostgreSQL.
BSD/OS
Shared Memory. By default, only 4 MB of shared memory is supported. Keep in mind that
shared memory is not pageable; it is locked in RAM. To increase the amount of shared
memory supported by your system, add something like the following to your kernel
configuration file:
options "SHMALL=8192"
options "SHMMAX=$SHMALL*PAGE_SIZE$"
SHMALL is measured in 4 kB pages, so a value of 1024 represents 4 MB of shared memory.

Therefore the above increases the maximum shared memory area to 32 MB. For those
running 4.3 or later, you will probably also need to increase KERNEL_VIRTUAL_MB above the
default 248. Once all changes have been made, recompile the kernel, and reboot.
For those running 4.0 and earlier releases, use bpatch to find the sysptsize value in the
current kernel. This is computed dynamically at boot time.
$ bpatch -r sysptsize
0x9 = 9
Next, add SYSPTSIZE as a hard-coded value in the kernel configuration file. Increase the
value you found using bpatch. Add 1 for every additional 4 MB of shared memory you desire.
options "SYSPTSIZE=16"
sysptsize cannot be changed by sysctl.
Semaphores. You will probably want to increase the number of semaphores as well; the
default system total of 60 will only allow about 50 PostgreSQL connections. Set the values you
want in your kernel configuration file, e.g.:
options "SEMMNI=40"
options "SEMMNS=240"
FreeBSD
The default settings are only suitable for small installations (for example, default SHMMAX is
32 MB). Changes can be made via the sysctl or loader interfaces. The following parameters
can be set using sysctl:
$ sysctl -w kern.ipc.shmall=32768
$ sysctl -w kern.ipc.shmmax=134217728
$ sysctl -w kern.ipc.semmap=256
To have these settings persist over reboots, modify /etc/sysctl.conf.
The remaining semaphore settings are read-only as far as sysctl is concerned, but can be
changed before boot using the loader prompt:
(loader) set kern.ipc.semmni=256

(loader) set kern.ipc.semmns=512
(loader) set kern.ipc.semmnu=256
Similarly these can be saved between reboots in /boot/loader.conf.
You might also want to configure your kernel to lock shared memory into RAM and prevent it
from being paged out to swap. This can be accomplished using the sysctl setting
kern.ipc.shm_use_phys.
If running in FreeBSD jails by enabling sysctl's security.jail.sysvipc_allowed, postmasters

running in different jails should be run by different operating system users. This improves
security because it prevents non-root users from interfering with shared memory or
semaphores in a different jail, and it allows the PostgreSQL IPC cleanup code to function
properly. (In FreeBSD 6.0 and later the IPC cleanup code doesn't properly detect processes in
other jails, preventing the running of postmasters on the same port in different jails.)
FreeBSD versions before 4.0 work like NetBSD and OpenBSD (see below).
NetBSD
OpenBSD
The options SYSVSHM and SYSVSEM need to be enabled when the kernel is compiled. (They
are by default.) The maximum size of shared memory is determined by the option
SHMMAXPGS (in pages). The following shows an example of how to set the various
parameters (OpenBSD uses option instead):
options SYSVSHM
options SHMMAXPGS=4096
options SHMSEG=256
options SYSVSEM
options SEMMNI=256
options SEMMNS=512
options SEMMNU=256
options SEMMAP=256
You might also want to configure your kernel to lock shared memory into RAM and prevent it
from being paged out to swap. This can be accomplished using the sysctl setting
kern.ipc.shm_use_phys.
HP-UX
The default settings tend to suffice for normal installations. On HP-UX 10, the factory default
for SEMMNS is 128, which might be too low for larger database sites.
IPC parameters can be set in the System Administration Manager (SAM) under Kernel
Configuration->Configurable Parameters. Hit Create A New Kernel when you're done.
Linux
The default settings are only suitable for small installations (the default max segment size is
32 MB). However the remaining defaults are quite generously sized, and usually do not
require changes. The max segment size can be changed via the sysctl interface. For example,
to allow 128 MB, and explicitly set the maximum total shared memory size to 2097152 pages
(the default):
$ sysctl -w kernel.shmmax=134217728
$ sysctl -w kernel.shmall=2097152
In addition these settings can be saved between reboots in /etc/sysctl.conf.
Older distributions may not have the sysctl program, but equivalent changes can be made by
manipulating the /proc file system:
$ echo 134217728 >/proc/sys/kernel/shmmax

$ echo 2097152 >/proc/sys/kernel/shmall
MacOS X
In OS X 10.2 and earlier, edit the file

/System/Library/StartupItems/SystemTuning/SystemTuning and change the values in the
following commands:
sysctl -w kern.sysv.shmmax
sysctl -w kern.sysv.shmmin
sysctl -w kern.sysv.shmmni
sysctl -w kern.sysv.shmseg
sysctl -w kern.sysv.shmall
In OS X 10.3 and later, these commands have been moved to /etc/rc and must be edited
there. Note that /etc/rc is usually overwritten by OS X updates (such as 10.3.6 to 10.3.7) so
you should expect to have to redo your editing after each update.
In OS X 10.3.9 and later, instead of editing /etc/rc you may create a file named
/etc/sysctl.conf, containing variable assignments such as
kern.sysv.shmmax=4194304
kern.sysv.shmmin=1
kern.sysv.shmmni=32
kern.sysv.shmseg=8
kern.sysv.shmall=1024
This method is better than editing /etc/rc because your changes will be preserved across
system updates. Note that all five shared-memory parameters must be set in /etc/sysctl.conf,
else the values will be ignored.
Beware that recent releases of OS X ignore attempts to set SHMMAX to a value that isn't an
exact multiple of 4096.
SHMALL is measured in 4 kB pages on this platform.
In all OS X versions, you'll need to reboot to make changes in the shared memory parameters
take effect.
SCO OpenServer
In the default configuration, only 512 kB of shared memory per segment is allowed. To
increase the setting, first change to the directory /etc/conf/cf.d. To display the current value
of SHMMAX, run
./configure -y SHMMAX
To set a new value for SHMMAX, run
./configure SHMMAX=valor
where valor is the new value you want to use (in bytes). After setting SHMMAX, rebuild the
kernel:
./link_unix
and reboot.
AIX
At least as of version 5.1, it should not be necessary to do any special configuration for such
parameters as SHMMAX, as it appears this is configured to allow all memory to be used as
shared memory. That is the sort of configuration commonly used for other databases such as
DB/2.
It may, however, be necessary to modify the global ulimit information in /etc/security/limits,

as the default hard limits for file sizes (fsize) and numbers of files (nofiles) may be too low.
Solaris
At least in version 2.6, the default maximum size of a shared memory segments is too low for
PostgreSQL. The relevant settings can be changed in /etc/system, for example:
set shmsys:shminfo_shmmax=0x2000000
set shmsys:shminfo_shmmin=1
set shmsys:shminfo_shmmni=256
set shmsys:shminfo_shmseg=256
set semsys:seminfo_semmap=256
set semsys:seminfo_semmni=512
set semsys:seminfo_semmns=512
set semsys:seminfo_semmsl=32
You need to reboot for the changes to take effect.
See also http://sunsite.uakom.sk/sunworldonline/swol-09-1997/swol-09-insidesolaris.html for

information on shared memory under Solaris.
UnixWare
On UnixWare 7, the maximum size for shared memory segments is only 512 kB in the default
configuration. To display the current value of SHMMAX, run
/etc/conf/bin/idtune -g SHMMAX
which displays the current, default, minimum, and maximum values. To set a new value for
SHMMAX, run
/etc/conf/bin/idtune SHMMAX valor
where valor is the new value you want to use (in bytes). After setting SHMMAX, rebuild the
kernel:
/etc/conf/bin/idbuild -B
and reboot.
Tabela 16-2. Configuration parameters affecting PostgreSQL's shared memory usage
Name Approximate multiplier (bytes per increment)

max_connections 400 + 270 * max_locks_per_transaction
max_prepared_transactions 600 + 270 * max_locks_per_transaction
shared_buffers 8300 (assuming 8K BLCKSZ)
wal_buffers 8200 (assuming 8K XLOG_BLCKSZ)
max_fsm_relations 70
max_fsm_pages 6
16.4.2. Resource Limits
Unix-like operating systems enforce various kinds of resource limits that might interfere with the
operation of your PostgreSQL server. Of particular importance are limits on the number of
processes per user, the number of open files per process, and the amount of memory available to
each process. Each of these have a "hard" and a "soft" limit. The soft limit is what actually counts
but it can be changed by the user up to the hard limit. The hard limit can only be changed by the
root user. The system call setrlimit is responsible for setting these parameters. The shell's built-in
command ulimit (Bourne shells) or limit (csh) is used to control the resource limits from the
command line. On BSD-derived systems the file /etc/login.conf controls the various resource limits
set during login. See the operating system documentation for details. The relevant parameters are
maxproc, openfiles, and datasize. For example:
default:\
...
:datasize-cur=256M:\
:maxproc-cur=256:\
:openfiles-cur=256:\
...
(-cur is the soft limit. Append -max to set the hard limit.)
Kernels can also have system-wide limits on some resources.
On Linux /proc/sys/fs/file-max determines the maximum number of open files that the kernel
will support. It can be changed by writing a different number into the file or by adding an
assignment in /etc/sysctl.conf. The maximum limit of files per process is fixed at the time the
kernel is compiled; see /usr/src/linux/Documentation/proc.txt for more information.
The PostgreSQL server uses one process per connection so you should provide for at least as many
processes as allowed connections, in addition to what you need for the rest of your system. This is
usually not a problem but if you run several servers on one machine things might get tight.
The factory default limit on open files is often set to "socially friendly" values that allow many users
to coexist on a machine without using an inappropriate fraction of the system resources. If you run
many servers on a machine this is perhaps what you want, but on dedicated servers you may want
to raise this limit.
On the other side of the coin, some systems allow individual processes to open large numbers of
files; if more than a few processes do so then the system-wide limit can easily be exceeded. If you
find this happening, and you do not want to alter the system-wide limit, you can set PostgreSQL's
max_files_per_process configuration parameter to limit the consumption of open files.
16.4.3. Linux Memory Overcommit
In Linux 2.4 and later, the default virtual memory behavior is not optimal for PostgreSQL. Because
of the way that the kernel implements memory overcommit, the kernel may terminate the
PostgreSQL server (the master server process) if the memory demands of another process cause
the system to run out of virtual memory.
If this happens, you will see a kernel message that looks like this (consult your system
documentation and configuration on where to look for such a message):
Out of Memory: Killed process 12345 (postgres).
This indicates that the postgres process has been terminated due to memory pressure. Although
existing database connections will continue to function normally, no new connections will be
accepted. To recover, PostgreSQL will need to be restarted.
One way to avoid this problem is to run PostgreSQL on a machine where you can be sure that other
processes will not run the machine out of memory.
On Linux 2.6 and later, a better solution is to modify the kernel's behavior so that it will not
"overcommit" memory. This is done by selecting strict overcommit mode via sysctl:
sysctl -w vm.overcommit_memory=2
or placing an equivalent entry in /etc/sysctl.conf. You may also wish to modify the related setting
vm.overcommit_ratio. For details see the kernel documentation file
Documentation/vm/overcommit-accounting.
Some vendors' Linux 2.4 kernels are reported to have early versions of the 2.6 overcommit sysctl
parameter. However, setting vm.overcommit_memory to 2 on a kernel that does not have the
relevant code will make things worse not better. It is recommended that you inspect the actual
kernel source code (see the function vm_enough_memory in the file mm/mmap.c) to verify what is
supported in your copy before you try this in a 2.4 installation. The presence of the overcommit-
accounting documentation file should not be taken as evidence that the feature is there. If in any
doubt, consult a kernel expert or your kernel vendor.

Starting the Database Server Acima Shutting Down the Server
Shutting Down the Server


There are several ways to shut down the database server. You control the type of shutdown by
sending different signals to the master postgres process.
SIGTERM
After receiving SIGTERM, the server disallows new connections, but lets existing sessions end
their work normally. It shuts down only after all of the sessions terminate normally. This is the
Smart Shutdown.
SIGINT
The server disallows new connections and sends all existing server processes SIGTERM, which
will cause them to abort their current transactions and exit promptly. It then waits for the
server processes to exit and finally shuts down. This is the Fast Shutdown.
SIGQUIT
This is the Immediate Shutdown, which will cause the master postgres process to send a
SIGQUIT to all child processes and exit immediately, without properly shutting itself down.
The child processes likewise exit immediately upon receiving SIGQUIT. This will lead to
recovery (by replaying the WAL log) upon next start-up. This is recommended only in
emergencies.
The pg_ctl program provides a convenient interface for sending these signals to shut down the
server.
Alternatively, you can send the signal directly using kill. The PID of the postgres process can be
found using the ps program, or from the file postmaster.pid in the data directory. For example, to
do a fast shutdown:
$ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
Importante: It is best not to use SIGKILL to shut down the server. Doing so will
prevent the server from releasing shared memory and semaphores, which may then
have to be done manually before a new server can be started. Furthermore, SIGKILL
kills the postgres process without letting it relay the signal to its subprocesses, so it will
be necessary to kill the individual subprocesses by hand as well.

Managing Kernel Resources Acima Encryption Options
http://pgdocptbr.sourceforge.net/pg82/server-shutdown.html[09/02/2018 18:26:37]
Encryption Options


PostgreSQL offers encryption at several levels, and provides flexibility in protecting data from
disclosure due to database server theft, unscrupulous administrators, and insecure networks.
Encryption might also be required to secure sensitive data such as medical records or financial
transactions.
Password Storage Encryption
By default, database user passwords are stored as MD5 hashes, so the administrator cannot
determine the actual password assigned to the user. If MD5 encryption is used for client
authentication, the unencrypted password is never even temporarily present on the server
because the client MD5 encrypts it before being sent across the network.
Encryption For Specific Columns
The /contrib function library pgcrypto allows certain fields to be stored encrypted. This is
useful if only some of the data is sensitive. The client supplies the decryption key and the data
is decrypted on the server and then sent to the client.
The decrypted data and the decryption key are present on the server for a brief time while it
is being decrypted and communicated between the client and server. This presents a brief
moment where the data and keys can be intercepted by someone with complete access to the
database server, such as the system administrator.
Data Partition Encryption
On Linux, encryption can be layered on top of a file system mount using a "loopback device".
This allows an entire file system partition be encrypted on disk, and decrypted by the
operating system. On FreeBSD, the equivalent facility is called GEOM Based Disk Encryption,
or gbde.
This mechanism prevents unencrypted data from being read from the drives if the drives or
the entire computer is stolen. This does not protect against attacks while the file system is
mounted, because when mounted, the operating system provides an unencrypted view of the
data. However, to mount the file system, you need some way for the encryption key to be
passed to the operating system, and sometimes the key is stored somewhere on the host that
mounts the disk.
Encrypting Passwords Across A Network
The MD5 authentication method double-encrypts the password on the client before sending it
to the server. It first MD5 encrypts it based on the user name, and then encrypts it based on
a random salt sent by the server when the database connection was made. It is this double-
encrypted value that is sent over the network to the server. Double-encryption not only
prevents the password from being discovered, it also prevents another connection from using
the same encrypted password to connect to the database server at a later time.
Encrypting Data Across A Network
SSL connections encrypt all data sent across the network: the password, the queries, and the
data returned. The pg_hba.conf file allows administrators to specify which hosts can use non-
encrypted connections (host) and which require SSL-encrypted connections (hostssl). Also,
http://pgdocptbr.sourceforge.net/pg82/encryption-options.html[09/02/2018 18:26:46]
Encryption Options
clients can specify that they connect to servers only via SSL. Stunnel or SSH can also be used
to encrypt transmissions.
SSL Host Authentication
It is possible for both the client and server to provide SSL keys or certificates to each other. It
takes some extra configuration on each side, but this provides stronger verification of identity
than the mere use of passwords. It prevents a computer from pretending to be the server just
long enough to read the password send by the client. It also helps prevent "man in the
middle" attacks where a computer between the client and server pretends to be the server
and reads and passes all data between the client and server.
Client-Side Encryption
If the system administrator cannot be trusted, it is necessary for the client to encrypt the
data; this way, unencrypted data never appears on the database server. Data is encrypted on
the client before being sent to the server, and database results have to be decrypted on the
client before being used.

Shutting Down the Server Acima Secure TCP/IP Connections with
SSL
http://pgdocptbr.sourceforge.net/pg82/encryption-options.html[09/02/2018 18:26:46]
Secure TCP/IP Connections with SSL


PostgreSQL has native support for using SSL connections to encrypt client/server communications
for increased security. This requires that OpenSSL is installed on both client and server systems and
that support in PostgreSQL is enabled at build time (see Capítulo 14).
With SSL support compiled in, the PostgreSQL server can be started with SSL enabled by setting
the parameter ssl to on in postgresql.conf. When starting in SSL mode, the server will look for the
files server.key and server.crt in the data directory, which must contain the server private key and
certificate, respectively. These files must be set up correctly before an SSL-enabled server can
start. If the private key is protected with a passphrase, the server will prompt for the passphrase
and will not start until it has been entered.
The server will listen for both standard and SSL connections on the same TCP port, and will
negotiate with any connecting client on whether to use SSL. By default, this is at the client's option;
see Seção 20.1 about how to set up the server to require use of SSL for some or all connections.
For details on how to create your server private key and certificate, refer to the OpenSSL
documentation. A self-signed certificate can be used for testing, but a certificate signed by a
certificate authority (CA) (either one of the global CAs or a local one) should be used in production
so the client can verify the server's identity. To create a quick self-signed certificate, use the
following OpenSSL command:
openssl req -new -text -out server.req
Fill out the information that openssl asks for. Make sure that you enter the local host name as
"Common Name"; the challenge password can be left blank. The program will generate a key that is
passphrase protected; it will not accept a passphrase that is less than four characters long. To
remove the passphrase (as you must if you want automatic start-up of the server), run the
commands
openssl rsa -in privkey.pem -out server.key

rm privkey.pem
Enter the old passphrase to unlock the existing key. Now do
openssl req -x509 -in server.req -text -key server.key -out server.crt
chmod og-rwx server.key
to turn the certificate into a self-signed certificate and to copy the key and certificate to where the
server will look for them.
If verification of client certificates is required, place the certificates of the CA(s) you wish to check
for in the file root.crt in the data directory. When present, a client certificate will be requested from
the client during SSL connection startup, and it must have been signed by one of the certificates
present in root.crt. Certificate Revocation List (CRL) entries are also checked if the file root.crl
exists.
When the root.crt file is not present, client certificates will not be requested or checked. In this
mode, SSL provides communication security but not authentication.
http://pgdocptbr.sourceforge.net/pg82/ssl-tcp.html[09/02/2018 18:26:55]
Secure TCP/IP Connections with SSL
The files server.key, server.crt, root.crt, and root.crl are only examined during server start; so you
must restart the server to make changes in them take effect.

Encryption Options Acima Secure TCP/IP Connections with
SSH Tunnels
http://pgdocptbr.sourceforge.net/pg82/ssl-tcp.html[09/02/2018 18:26:55]
Secure TCP/IP Connections with SSH Tunnels


One can use SSH to encrypt the network connection between clients and a PostgreSQL server. Done
properly, this provides an adequately secure network connection, even for non-SSL-capable clients.
First make sure that an SSH server is running properly on the same machine as the PostgreSQL
server and that you can log in using ssh as some user. Then you can establish a secure tunnel with
a command like this from the client machine:
ssh -L 3333:foo.com:5432 joe@foo.com
The first number in the -L argument, 3333, is the port number of your end of the tunnel; it can be
chosen freely. The second number, 5432, is the remote end of the tunnel: the port number your
server is using. The name or IP address between the port numbers is the host with the database
server you are going to connect to. In order to connect to the database server using this tunnel,
you connect to port 3333 on the local machine:
psql -h localhost -p 3333 postgres
To the database server it will then look as though you are really user joe@foo.com and it will use
whatever authentication procedure was configured for connections from this user and host. Note
that the server will not think the connection is SSL-encrypted, since in fact it is not encrypted
between the SSH server and the PostgreSQL server. This should not pose any extra security risk as
long as they are on the same machine.
In order for the tunnel setup to succeed you must be allowed to connect via ssh as joe@foo.com,
just as if you had attempted to use ssh to set up a terminal session.
Dica: Several other applications exist that can provide secure tunnels using a procedure
similar in concept to the one just described.

Secure TCP/IP Connections with Acima Server Configuration
SSL
http://pgdocptbr.sourceforge.net/pg82/ssh-tunnels.html[09/02/2018 18:27:04]
Server Configuration

Capítulo 17. Server Configuration

Sumário
17.3.1. Connection Settings

17.3.2. Security and Authentication
17.4.1. Memory
17.4.2. Free Space Map
17.4.3. Kernel Resource Usage
17.4.4. Cost-Based Vacuum Delay
17.4.5. Background Writer
17.5.1. Settings
17.5.2. Checkpoints
17.5.3. Archiving
17.6.1. Planner Method Configuration

17.6.2. Planner Cost Constants
17.6.3. Genetic Query Optimizer
17.6.4. Other Planner Options
17.7.1. Where To Log

17.7.2. When To Log
17.7.3. What To Log
17.8.1. Query and Index Statistics Collector

17.8.2. Statistics Monitoring

17.10.1. Statement Behavior

17.10.2. Locale and Formatting
17.10.3. Other Defaults

17.12.1. Previous PostgreSQL Versions

17.12.2. Platform and Client Compatibility
http://pgdocptbr.sourceforge.net/pg82/runtime-config.html[09/02/2018 18:27:37]
Server Configuration

There are many configuration parameters that affect the behavior of the database system. In the
first section of this chapter, we describe how to set configuration parameters. The subsequent
sections discuss each parameter in detail.

Secure TCP/IP Connections with Acima Setting Parameters
SSH Tunnels
http://pgdocptbr.sourceforge.net/pg82/runtime-config.html[09/02/2018 18:27:37]
Setting Parameters

Anterior Início Capítulo 17. Server Configuration Fim Próxima

All parameter names are case-insensitive. Every parameter takes a value of one of four types:
Boolean, integer, floating point, or string. Boolean values may be written as ON, OFF, TRUE, FALSE,
YES, NO, 1, 0 (all case-insensitive) or any unambiguous prefix of these.
Some settings specify a memory or time value. Each of these has an implicit unit, which is either
kilobytes, blocks (typically 8 kilobytes), milliseconds, seconds, or minutes. For convenience, a
(possibly different) unit can also be specified explicitly. Valid memory units are kB (kilobytes), MB
(megabytes), and GB (gigabytes); valid time units are ms (milliseconds), s (seconds), min
(minutes), h (hours), and d (days). Note that the multiplier for memory units is 1024, not 1000.
One way to set these parameters is to edit the file postgresql.conf, which is normally kept in the
data directory. (initdb installs a default copy there.) An example of what this file might look like is:
# This is a comment
log_connections = yes
log_destination = 'syslog'
search_path = '"$user", public'
shared_buffers = 128MB
One parameter is specified per line. The equal sign between name and value is optional. Whitespace
is insignificant and blank lines are ignored. Hash marks (#) introduce comments anywhere.
Parameter values that are not simple identifiers or numbers must be single-quoted. To embed a
single quote in a parameter value, write either two quotes (preferred) or backslash-quote.
In addition to parameter settings, the postgresql.conf file can contain include directives, which
specify another file to read and process as if it were inserted into the configuration file at this point.
Include directives simply look like
include 'filename'
If the file name is not an absolute path, it is taken as relative to the directory containing the
referencing configuration file. Inclusions can be nested.
The configuration file is reread whenever the main server process receives a SIGHUP signal (which
is most easily sent by means of pg_ctl reload). The main server process also propagates this signal
to all currently running server processes so that existing sessions also get the new value.
Alternatively, you can send the signal to a single server process directly. Some parameters can only
be set at server start; any changes to their entries in the configuration file will be ignored until the
server is restarted.
A second way to set these configuration parameters is to give them as a command-line option to
the postgres command, such as:
postgres -c log_connections=yes -c log_destination='syslog'
Command-line options override any conflicting settings in postgresql.conf. Note that this means you
won't be able to change the value on-the-fly by editing postgresql.conf, so while the command-line
method may be convenient, it can cost you flexibility later.
Occasionally it is useful to give a command line option to one particular session only. The
http://pgdocptbr.sourceforge.net/pg82/config-setting.html[09/02/2018 18:27:57]
Setting Parameters
environment variable PGOPTIONS can be used for this purpose on the client side:
env PGOPTIONS='-c geqo=off' psql
(This works for any libpq-based client application, not just psql.) Note that this won't work for
parameters that are fixed when the server is started or that must be specified in postgresql.conf.
Furthermore, it is possible to assign a set of parameter settings to a user or a database. Whenever

a session is started, the default settings for the user and database involved are loaded. The
commands ALTER USER and ALTER DATABASE, respectively, are used to configure these settings.
Per-database settings override anything received from the postgres command-line or the
configuration file, and in turn are overridden by per-user settings; both are overridden by per-
session settings.
Some parameters can be changed in individual SQL sessions with the SET command, for example:
SET ENABLE_SEQSCAN TO OFF;
If SET is allowed, it overrides all other sources of values for the parameter. Some parameters
cannot be changed via SET: for example, if they control behavior that cannot be changed without
restarting the entire PostgreSQL server. Also, some parameters can be modified via SET or ALTER
by superusers, but not by ordinary users.
The SHOW command allows inspection of the current values of all parameters.
The virtual table pg_settings (described in Seção 43.44) also allows displaying and updating session
run-time parameters. It is equivalent to SHOW and SET, but can be more convenient to use
because it can be joined with other tables, or selected from using any desired selection condition.

Server Configuration Acima File Locations
http://pgdocptbr.sourceforge.net/pg82/config-setting.html[09/02/2018 18:27:57]
File Locations


In addition to the postgresql.conf file already mentioned, PostgreSQL uses two other manually-
edited configuration files, which control client authentication (their use is discussed in Capítulo 20).
By default, all three configuration files are stored in the database cluster's data directory. The
parameters described in this section allow the configuration files to be placed elsewhere. (Doing so
can ease administration. In particular it is often easier to ensure that the configuration files are
properly backed-up when they are kept separate.)
data_directory (string)
Specifies the directory to use for data storage. This parameter can only be set at server start.
config_file (string)
Specifies the main server configuration file (customarily called postgresql.conf). This
parameter can only be set on the postgres command line.
hba_file (string)
Specifies the configuration file for host-based authentication (customarily called pg_hba.conf).
This parameter can only be set at server start.
ident_file (string)
Specifies the configuration file for ident authentication (customarily called pg_ident.conf). This
parameter can only be set at server start.
external_pid_file (string)
Specifies the name of an additional process-id (PID) file that the server should create for use
by server administration programs. This parameter can only be set at server start.
In a default installation, none of the above parameters are set explicitly. Instead, the data directory
is specified by the -D command-line option or the PGDATA environment variable, and the
configuration files are all found within the data directory.
If you wish to keep the configuration files elsewhere than the data directory, the postgres -D
command-line option or PGDATA environment variable must point to the directory containing the
configuration files, and the data_directory parameter must be set in postgresql.conf (or on the
command line) to show where the data directory is actually located. Notice that data_directory
overrides -D and PGDATA for the location of the data directory, but not for the location of the
configuration files.
If you wish, you can specify the configuration file names and locations individually using the
parameters config_file, hba_file and/or ident_file. config_file can only be specified on the postgres
command line, but the others can be set within the main configuration file. If all three parameters
plus data_directory are explicitly set, then it is not necessary to specify -D or PGDATA.
When setting any of these parameters, a relative path will be interpreted with respect to the
directory in which postgres is started.

Setting Parameters Acima Connections and Authentication
http://pgdocptbr.sourceforge.net/pg82/runtime-config-file-locations.html[09/02/2018 18:28:05]
File Locations
http://pgdocptbr.sourceforge.net/pg82/runtime-config-file-locations.html[09/02/2018 18:28:05]
Connections and Authentication


17.3.1. Connection Settings
listen_addresses (string)
Specifies the TCP/IP address(es) on which the server is to listen for connections from client
applications. The value takes the form of a comma-separated list of host names and/or
numeric IP addresses. The special entry * corresponds to all available IP interfaces. If the list
is empty, the server does not listen on any IP interface at all, in which case only Unix-domain
sockets can be used to connect to it. The default value is localhost, which allows only local
"loopback" connections to be made. This parameter can only be set at server start.
port (integer)
The TCP port the server listens on; 5432 by default. Note that the same port number is used
for all IP addresses the server listens on. This parameter can only be set at server start.
max_connections (integer)
Determines the maximum number of concurrent connections to the database server. The
default is typically 100, but may be less if your kernel settings will not support it (as
determined during initdb). This parameter can only be set at server start.
Increasing this parameter may cause PostgreSQL to request more System V shared memory
or semaphores than your operating system's default configuration allows. See Seção 16.4.1 for
information on how to adjust those parameters, if necessary.
superuser_reserved_connections (integer)
Determines the number of connection "slots" that are reserved for connections by PostgreSQL
superusers. At most max_connections connections can ever be active simultaneously.
Whenever the number of active concurrent connections is at least max_connections minus
superuser_reserved_connections, new connections will be accepted only for superusers.
The default value is 3. The value must be less than the value of max_connections. This
unix_socket_directory (string)
Specifies the directory of the Unix-domain socket on which the server is to listen for
connections from client applications. The default is normally /tmp, but can be changed at build
time. This parameter can only be set at server start.
unix_socket_group (string)
Sets the owning group of the Unix-domain socket. (The owning user of the socket is always
the user that starts the server.) In combination with the parameter unix_socket_permissions
this can be used as an additional access control mechanism for Unix-domain connections. By
default this is the empty string, which selects the default group for the current user. This
unix_socket_permissions (integer)
http://pgdocptbr.sourceforge.net/pg82/runtime-config-connection.html[09/02/2018 18:28:14]
Sets the access permissions of the Unix-domain socket. Unix-domain sockets use the usual
Unix file system permission set. The parameter value is expected to be a numeric mode
specification in the form accepted by the chmod and umask system calls. (To use the
customary octal format the number must start with a 0 (zero).)
The default permissions are 0777, meaning anyone can connect. Reasonable alternatives are
0770 (only user and group, see also unix_socket_group) and 0700 (only user). (Note that for
a Unix-domain socket, only write permission matters and so there is no point in setting or
revoking read or execute permissions.)
This access control mechanism is independent of the one described in Capítulo 20.
This parameter can only be set at server start.
bonjour_name (string)
Specifies the Bonjour broadcast name. The computer name is used if this parameter is set to
the empty string '' (which is the default). This parameter is ignored if the server was not
compiled with Bonjour support. This parameter can only be set at server start.
tcp_keepalives_idle (integer)
On systems that support the TCP_KEEPIDLE socket option, specifies the number of seconds
between sending keepalives on an otherwise idle connection. A value of 0 uses the system
default. If TCP_KEEPIDLE is not supported, this parameter must be 0. This parameter is
ignored for connections made via a Unix-domain socket.
tcp_keepalives_interval (integer)
On systems that support the TCP_KEEPINTVL socket option, specifies how long, in seconds, to
wait for a response to a keepalive before retransmitting. A value of 0 uses the system default.
If TCP_KEEPINTVL is not supported, this parameter must be 0. This parameter is ignored for
connections made via a Unix-domain socket.
tcp_keepalives_count (integer)
On systems that support the TCP_KEEPCNT socket option, specifies how many keepalives may
be lost before the connection is considered dead. A value of 0 uses the system default. If
TCP_KEEPCNT is not supported, this parameter must be 0. This parameter is ignored for
connections made via a Unix-domain socket.
17.3.2. Security and Authentication
authentication_timeout (integer)
Maximum time to complete client authentication, in seconds. If a would-be client has not
completed the authentication protocol in this much time, the server breaks the connection.
This prevents hung clients from occupying a connection indefinitely. The default is 60. This
parameter can only be set in the postgresql.conf file or on the server command line.
ssl (boolean)
Enables SSL connections. Please read Seção 16.7 before using this. The default is off. This
password_encryption (boolean)
When a password is specified in CREATE USER or ALTER USER without writing either
ENCRYPTED or UNENCRYPTED, this parameter determines whether the password is to be
encrypted. The default is on (encrypt the password).
krb_server_keyfile (string)
Sets the location of the Kerberos server key file. See Seção 20.2.3 for details. This parameter
can only be set at server start.
krb_srvname (string)
Sets the Kerberos service name. See Seção 20.2.3 for details. This parameter can only be set
at server start.
krb_server_hostname (string)
Sets the host name part of the service principal. This, combined with krb_srvname, is used to
generate the complete service principal, that is krb_srvname/krb_server_hostname@REALM.
If not set, the default is the server host name. See Seção 20.2.3 for details. This parameter
krb_caseins_users (boolean)
Sets whether Kerberos user names should be treated case-insensitively. The default is off
(case sensitive). This parameter can only be set at server start.
db_user_namespace (boolean)
This parameter enables per-database user names. It is off by default. This parameter can only
be set in the postgresql.conf file or on the server command line.
If this is on, you should create users as username@dbname. When username is passed by a
connecting client, @ and the database name are appended to the user name and that
database-specific user name is looked up by the server. Note that when you create users with
names containing @ within the SQL environment, you will need to quote the user name.
With this parameter enabled, you can still create ordinary global users. Simply append @
when specifying the user name in the client. The @ will be stripped off before the user name
is looked up by the server.
Nota: This feature is intended as a temporary measure until a complete solution is

found. At that time, this option will be removed.

File Locations Acima Resource Consumption
Resource Consumption


17.4.1. Memory
shared_buffers (integer)
Sets the number of shared memory buffers used by the database server. The default is
typically 4000, but may be less if your kernel settings will not support it (as determined
during initdb). Each buffer is 8192 bytes, unless a different value of BLCKSZ was chosen when
building the server. This setting must be at least 16, as well as at least twice the value of
max_connections; however, settings significantly higher than the minimum are usually needed
for good performance. Values of a few thousand are recommended for production
installations. This parameter can only be set at server start.
than your operating system's default configuration allows. See Seção 16.4.1 for information on
how to adjust those parameters, if necessary.
temp_buffers (integer)
Sets the maximum number of temporary buffers used by each database session. These are
session-local buffers used only for access to temporary tables. The default is 1000. The
setting can be changed within individual sessions, but only up until the first use of temporary
tables within a session; subsequent attempts to change the value will have no effect on that
session.
A session will allocate temporary buffers as needed up to the limit given by temp_buffers. The
cost of setting a large value in sessions that do not actually need a lot of temporary buffers is
only a buffer descriptor, or about 64 bytes, per increment in temp_buffers. However if a
buffer is actually used an additional 8192 bytes will be consumed for it (or in general, BLCKSZ
bytes).
max_prepared_transactions (integer)
Sets the maximum number of transactions that can be in the "prepared" state simultaneously
(see PREPARE TRANSACTION). Setting this parameter to zero disables the prepared-transaction
feature. The default is 5. This parameter can only be set at server start.
If you are not using prepared transactions, this parameter may as well be set to zero. If you
are using them, you will probably want max_prepared_transactions to be at least as large as
max_connections, to avoid unwanted failures at the prepare step.
work_mem (integer)
Specifies the amount of memory to be used by internal sort operations and hash tables before
switching to temporary disk files. The value is specified in kilobytes, and defaults to 1024
kilobytes (1 MB). Note that for a complex query, several sort or hash operations might be
running in parallel; each one will be allowed to use as much memory as this value specifies
before it starts to put data into temporary files. Also, several running sessions could be doing
http://pgdocptbr.sourceforge.net/pg82/runtime-config-resource.html[09/02/2018 18:28:24]
such operations concurrently. So the total memory used could be many times the value of
work_mem; it is necessary to keep this fact in mind when choosing the value. Sort operations
are used for ORDER BY, DISTINCT, and merge joins. Hash tables are used in hash joins, hash-
based aggregation, and hash-based processing of IN subqueries.
maintenance_work_mem (integer)
Specifies the maximum amount of memory to be used in maintenance operations, such as

VACUUM, CREATE INDEX, and ALTER TABLE ADD FOREIGN KEY. The value is specified in
kilobytes, and defaults to 16384 kilobytes (16 MB). Since only one of these operations can be
executed at a time by a database session, and an installation normally doesn't have very
many of them happening concurrently, it's safe to set this value significantly larger than
work_mem. Larger settings may improve performance for vacuuming and for restoring
database dumps.
max_stack_depth (integer)
Specifies the maximum safe depth of the server's execution stack. The ideal setting for this
parameter is the actual stack size limit enforced by the kernel (as set by ulimit -s or local
equivalent), less a safety margin of a megabyte or so. The safety margin is needed because
the stack depth is not checked in every routine in the server, but only in key potentially-
recursive routines such as expression evaluation. The default setting is 2048 kB (two
megabytes), which is conservatively small and unlikely to risk crashes. However, it may be
too small to allow execution of complex functions. Only superusers can change this setting.
Setting max_stack_depth higher than the actual kernel limit will mean that a runaway
recursive function can crash an individual backend process. On platforms where PostgreSQL
can determine the kernel limit, it will not let you set this variable to an unsafe value.
However, not all platforms provide the information, so caution is recommended in selecting a
value.
17.4.2. Free Space Map
These parameters control the size of the shared free space map, which tracks the locations of
unused space in the database. An undersized free space map may cause the database to consume
increasing amounts of disk space over time, because free space that is not in the map cannot be re-
used; instead PostgreSQL will request more disk space from the operating system when it needs to
store new data. The last few lines displayed by a database-wide VACUUM VERBOSE command can
help in determining if the current settings are adequate. A NOTICE message is also printed during
such an operation if the current settings are too low.
Increasing these parameters may cause PostgreSQL to request more System V shared memory
than your operating system's default configuration allows. See Seção 16.4.1 for information on how
to adjust those parameters, if necessary.
max_fsm_pages (integer)
Sets the maximum number of disk pages for which free space will be tracked in the shared
free-space map. Six bytes of shared memory are consumed for each page slot. This setting
must be more than 16 * max_fsm_relations. The default is chosen by initdb depending on the
amount of available memory, and can range from 20000 to 200000. This parameter can only
be set at server start.
max_fsm_relations (integer)
Sets the maximum number of relations (tables and indexes) for which free space will be
tracked in the shared free-space map. Roughly seventy bytes of shared memory are
consumed for each slot. The default is 1000. This parameter can only be set at server start.
17.4.3. Kernel Resource Usage
max_files_per_process (integer)
Sets the maximum number of simultaneously open files allowed to each server subprocess.
The default is 1000. If the kernel is enforcing a safe per-process limit, you don't need to worry
about this setting. But on some platforms (notably, most BSD systems), the kernel will allow
individual processes to open many more files than the system can really support when a large
number of processes all try to open that many files. If you find yourself seeing "Too many
open files" failures, try reducing this setting. This parameter can only be set at server start.
shared_preload_libraries (string)
This variable specifies one or more shared libraries that are to be preloaded at server start. If
more than one library is to be loaded, separate their names with commas. For example,
'$libdir/mylib' would cause mylib.so (or on some platforms, mylib.sl) to be preloaded from the
installation's standard library directory. This parameter can only be set at server start.
PostgreSQL procedural language libraries can be preloaded in this way, typically by using the
syntax '$libdir/plXXX' where XXX is pgsql, perl, tcl, or python.
By preloading a shared library, the library startup time is avoided when the library is first
used. However, the time to start each new server process may increase slightly, even if that
process never uses the library. So this parameter is recommended only for libraries that will
be used in most sessions.
If a specified library is not found, the server will fail to start.
Every PostgreSQL-supported library has a "magic block" that is checked to guarantee

compatibility. For this reason, non-PostgreSQL libraries cannot be loaded in this way.
17.4.4. Cost-Based Vacuum Delay
During the execution of VACUUM and ANALYZE commands, the system maintains an internal counter
that keeps track of the estimated cost of the various I/O operations that are performed. When the
accumulated cost reaches a limit (specified by vacuum_cost_limit), the process performing the
operation will sleep for a while (specified by vacuum_cost_delay). Then it will reset the counter and
continue execution.
The intent of this feature is to allow administrators to reduce the I/O impact of these commands on
concurrent database activity. There are many situations in which it is not very important that
maintenance commands like VACUUM and ANALYZE finish quickly; however, it is usually very
important that these commands do not significantly interfere with the ability of the system to
perform other database operations. Cost-based vacuum delay provides a way for administrators to
achieve this.
This feature is disabled by default. To enable it, set the vacuum_cost_delay variable to a nonzero
value.
vacuum_cost_delay (integer)
The length of time, in milliseconds, that the process will sleep when the cost limit has been
exceeded. The default value is 0, which disables the cost-based vacuum delay feature.
Positive values enable cost-based vacuuming. Note that on many systems, the effective
resolution of sleep delays is 10 milliseconds; setting vacuum_cost_delay to a value that is not
a multiple of 10 may have the same results as setting it to the next higher multiple of 10.
vacuum_cost_page_hit (integer)
The estimated cost for vacuuming a buffer found in the shared buffer cache. It represents the
cost to lock the buffer pool, lookup the shared hash table and scan the content of the page.
The default value is 1.
vacuum_cost_page_miss (integer)
The estimated cost for vacuuming a buffer that has to be read from disk. This represents the
effort to lock the buffer pool, lookup the shared hash table, read the desired block in from the
disk and scan its content. The default value is 10.
vacuum_cost_page_dirty (integer)
The estimated cost charged when vacuum modifies a block that was previously clean. It
represents the extra I/O required to flush the dirty block out to disk again. The default value
is 20.
vacuum_cost_limit (integer)
The accumulated cost that will cause the vacuuming process to sleep. The default value is
200.
Nota: There are certain operations that hold critical locks and should therefore complete
as quickly as possible. Cost-based vacuum delays do not occur during such operations.
Therefore it is possible that the cost accumulates far higher than the specified limit. To
avoid uselessly long delays in such cases, the actual delay is calculated as
vacuum_cost_delay * accumulated_balance / vacuum_cost_limit with a maximum of
vacuum_cost_delay * 4.
17.4.5. Background Writer
Beginning in PostgreSQL 8.0, there is a separate server process called the background writer,
whose sole function is to issue writes of "dirty" shared buffers. The intent is that server processes
handling user queries should seldom or never have to wait for a write to occur, because the
background writer will do it. This arrangement also reduces the performance penalty associated
with checkpoints. The background writer will continuously trickle out dirty pages to disk, so that
only a few pages will need to be forced out when checkpoint time arrives, instead of the storm of
dirty-buffer writes that formerly occurred at each checkpoint. However there is a net overall
increase in I/O load, because where a repeatedly-dirtied page might before have been written only
once per checkpoint interval, the background writer might write it several times in the same
interval. In most situations a continuous low load is preferable to periodic spikes, but the
parameters discussed in this subsection can be used to tune the behavior for local needs.
bgwriter_delay (integer)
Specifies the delay between activity rounds for the background writer. In each round the
writer issues writes for some number of dirty buffers (controllable by the following
parameters). It then sleeps for bgwriter_delay milliseconds, and repeats. The default value is
200. Note that on many systems, the effective resolution of sleep delays is 10 milliseconds;
setting bgwriter_delay to a value that is not a multiple of 10 may have the same results as
setting it to the next higher multiple of 10. This parameter can only be set in the
postgresql.conf file or on the server command line.
bgwriter_lru_percent (floating point)
To reduce the probability that server processes will need to issue their own writes, the
background writer tries to write buffers that are likely to be recycled soon. In each round, it
examines up to bgwriter_lru_percent of the buffers that are nearest to being recycled, and
writes any that are dirty. The default value is 1.0 (this is a percentage of the total number of
shared buffers). This parameter can only be set in the postgresql.conf file or on the server
command line.
bgwriter_lru_maxpages (integer)
In each round, no more than this many buffers will be written as a result of scanning soon-to-
be-recycled buffers. The default value is 5. This parameter can only be set in the
bgwriter_all_percent (floating point)
To reduce the amount of work that will be needed at checkpoint time, the background writer
also does a circular scan through the entire buffer pool, writing buffers that are found to be
dirty. In each round, it examines up to bgwriter_all_percent of the buffers for this purpose.
The default value is 0.333 (this is a percentage of the total number of shared buffers). With
the default bgwriter_delay setting, this will allow the entire shared buffer pool to be scanned
about once per minute. This parameter can only be set in the postgresql.conf file or on the
server command line.
bgwriter_all_maxpages (integer)
In each round, no more than this many buffers will be written as a result of the scan of the
entire buffer pool. (If this limit is reached, the scan stops, and resumes at the next buffer
during the next round.) The default value is 5. This parameter can only be set in the
Smaller values of bgwriter_all_percent and bgwriter_all_maxpages reduce the extra I/O load
caused by the background writer, but leave more work to be done at checkpoint time. To reduce
load spikes at checkpoints, increase these two values. Similarly, smaller values of
bgwriter_lru_percent and bgwriter_lru_maxpages reduce the extra I/O load caused by the
background writer, but make it more likely that server processes will have to issue writes for
themselves, delaying interactive queries. To disable background writing entirely, set both maxpages
values and/or both percent values to zero.

Connections and Authentication Acima Write Ahead Log
Write Ahead Log


See also Seção 27.3 for details on WAL tuning.
17.5.1. Settings
fsync (boolean)
If this parameter is on, the PostgreSQL server will try to make sure that updates are
physically written to disk, by issuing fsync() system calls or various equivalent methods (see
wal_sync_method). This ensures that the database cluster can recover to a consistent state
after an operating system or hardware crash.
However, using fsync results in a performance penalty: when a transaction is committed,

PostgreSQL must wait for the operating system to flush the write-ahead log to disk. When
fsync is disabled, the operating system is allowed to do its best in buffering, ordering, and
delaying writes. This can result in significantly improved performance. However, if the system
crashes, the results of the last few committed transactions may be lost in part or whole. In
the worst case, unrecoverable data corruption may occur. (Crashes of the database software
itself are not a risk factor here. Only an operating-system-level crash creates a risk of
corruption.)
Due to the risks involved, there is no universally correct setting for fsync. Some
administrators always disable fsync, while others only turn it off during initial bulk data loads,
where there is a clear restart point if something goes wrong. Others always leave fsync
enabled. The default is to enable fsync, for maximum reliability. If you trust your operating
system, your hardware, and your utility company (or your battery backup), you can consider
disabling fsync.
This parameter can only be set in the postgresql.conf file or on the server command line. If
you turn this parameter off, also consider turning off full_page_writes.
wal_sync_method (string)
Method used for forcing WAL updates out to disk. If fsync is off then this setting is irrelevant,
since updates will not be forced out at all. Possible values are:
open_datasync (write WAL files with open() option O_DSYNC)
fdatasync (call fdatasync() at each commit)
fsync_writethrough (call fsync() at each commit, forcing write-through of any disk write
cache)
fsync (call fsync() at each commit)
open_sync (write WAL files with open() option O_SYNC)
Not all of these choices are available on all platforms. The default is the first method in the
above list that is supported by the platform. This parameter can only be set in the
full_page_writes (boolean)
http://pgdocptbr.sourceforge.net/pg82/runtime-config-wal.html[09/02/2018 18:28:33]
Write Ahead Log
When this parameter is on, the PostgreSQL server writes the entire content of each disk page
to WAL during the first modification of that page after a checkpoint. This is needed because a
page write that is in process during an operating system crash might be only partially
completed, leading to an on-disk page that contains a mix of old and new data. The row-level
change data normally stored in WAL will not be enough to completely restore such a page
during post-crash recovery. Storing the full page image guarantees that the page can be
correctly restored, but at a price in increasing the amount of data that must be written to
WAL. (Because WAL replay always starts from a checkpoint, it is sufficient to do this during
the first change of each page after a checkpoint. Therefore, one way to reduce the cost of full-
page writes is to increase the checkpoint interval parameters.)
Turning this parameter off speeds normal operation, but might lead to a corrupt database
after an operating system crash or power failure. The risks are similar to turning off fsync,
though smaller. It may be safe to turn off this parameter if you have hardware (such as a
battery-backed disk controller) or file-system software that reduces the risk of partial page
writes to an acceptably low level (e.g., ReiserFS 4).
Turning off this parameter does not affect use of WAL archiving for point-in-time recovery
(PITR) (see Seção 23.3).
This parameter can only be set in the postgresql.conf file or on the server command line. The
default is on.
wal_buffers (integer)
Number of disk-page buffers allocated in shared memory for WAL data. The default is 8. The
setting need only be large enough to hold the amount of WAL data generated by one typical
transaction, since the data is written out to disk at every transaction commit. This parameter
commit_delay (integer)
Time delay between writing a commit record to the WAL buffer and flushing the buffer out to
disk, in microseconds. A nonzero delay can allow multiple transactions to be committed with
only one fsync() system call, if system load is high enough that additional transactions
become ready to commit within the given interval. But the delay is just wasted if no other
transactions become ready to commit. Therefore, the delay is only performed if at least
commit_siblings other transactions are active at the instant that a server process has written
its commit record. The default is zero (no delay).
commit_siblings (integer)
Minimum number of concurrent open transactions to require before performing the

commit_delay delay. A larger value makes it more probable that at least one other transaction
will become ready to commit during the delay interval. The default is five.
17.5.2. Checkpoints
checkpoint_segments (integer)
Maximum distance between automatic WAL checkpoints, in log file segments (each segment is
normally 16 megabytes). The default is three. This parameter can only be set in the
checkpoint_timeout (integer)
Maximum time between automatic WAL checkpoints, in seconds. The default is 300 seconds.
This parameter can only be set in the postgresql.conf file or on the server command line.
Write Ahead Log
checkpoint_warning (integer)
Write a message to the server log if checkpoints caused by the filling of checkpoint segment
files happen closer together than this many seconds (which suggests that
checkpoint_segments ought to be raised). The default is 30 seconds. Zero disables the
warning. This parameter can only be set in the postgresql.conf file or on the server command
line.
17.5.3. Archiving
archive_command (string)
The shell command to execute to archive a completed segment of the WAL file series. If this is
an empty string (the default), WAL archiving is disabled. Any %p in the string is replaced by
the path name of the file to archive, and any %f is replaced by the file name only. (The path
name is relative to the working directory of the server, i.e., the cluster's data directory.) Use
%% to embed an actual % character in the command. For more information see Seção 23.3.1.
It is important for the command to return a zero exit status if and only if it succeeds.
Examples:
archive_command = 'cp "%p" /mnt/server/archivedir/"%f"'

archive_command = 'copy "%p" /mnt/server/archivedir/"%f"' # Windows
archive_timeout (integer)
The archive_command is only invoked on completed WAL segments. Hence, if your server
generates little WAL traffic (or has slack periods where it does so), there could be a long delay
between the completion of a transaction and its safe recording in archive storage. To put a
limit on how old unarchived data can be, you can set archive_timeout to force the server to
switch to a new WAL segment file periodically. When this parameter is greater than zero, the
server will switch to a new segment file whenever this many seconds have elapsed since the
last segment file switch. Note that archived files that are closed early due to a forced switch
are still the same length as completely full files. Therefore, it is unwise to use a very short
archive_timeout — it will bloat your archive storage. archive_timeout settings of a minute or
so are usually reasonable. This parameter can only be set in the postgresql.conf file or on the
server command line.

Resource Consumption Acima Query Planning
Query Planning


17.6.1. Planner Method Configuration
These configuration parameters provide a crude method of influencing the query plans chosen by
the query optimizer. If the default plan chosen by the optimizer for a particular query is not
optimal, a temporary solution may be found by using one of these configuration parameters to force
the optimizer to choose a different plan. Turning one of these settings off permanently is seldom a
good idea, however. Better ways to improve the quality of the plans chosen by the optimizer
include adjusting the Planner Cost Constants, running ANALYZE more frequently, increasing the value
of the default_statistics_target configuration parameter, and increasing the amount of statistics
collected for specific columns using ALTER TABLE SET STATISTICS.
enable_bitmapscan (boolean)
Enables or disables the query planner's use of bitmap-scan plan types. The default is on.
enable_hashagg (boolean)
Enables or disables the query planner's use of hashed aggregation plan types. The default is
on.
enable_hashjoin (boolean)
Enables or disables the query planner's use of hash-join plan types. The default is on.
enable_indexscan (boolean)
Enables or disables the query planner's use of index-scan plan types. The default is on.
enable_mergejoin (boolean)
Enables or disables the query planner's use of merge-join plan types. The default is on.
enable_nestloop (boolean)
Enables or disables the query planner's use of nested-loop join plans. It's not possible to
suppress nested-loop joins entirely, but turning this variable off discourages the planner from
using one if there are other methods available. The default is on.
enable_seqscan (boolean)
Enables or disables the query planner's use of sequential scan plan types. It's not possible to
suppress sequential scans entirely, but turning this variable off discourages the planner from
using one if there are other methods available. The default is on.
enable_sort (boolean)
Enables or disables the query planner's use of explicit sort steps. It's not possible to suppress
explicit sorts entirely, but turning this variable off discourages the planner from using one if
there are other methods available. The default is on.
enable_tidscan (boolean)
http://pgdocptbr.sourceforge.net/pg82/runtime-config-query.html[09/02/2018 18:28:41]
Query Planning
Enables or disables the query planner's use of TID scan plan types. The default is on.
17.6.2. Planner Cost Constants
The cost variables described in this section are measured on an arbitrary scale. Only their relative
values matter, hence scaling them all up or down by the same factor will result in no change in the
planner's choices. Traditionally, these variables have been referenced to sequential page fetches as
the unit of cost; that is, seq_page_cost is conventionally set to 1.0 and the other cost variables are
set with reference to that. But you can use a different scale if you prefer, such as actual execution
times in milliseconds on a particular machine.
Nota: Unfortunately, there is no well-defined method for determining ideal values for
the cost variables. They are best treated as averages over the entire mix of queries that
a particular installation will get. This means that changing them on the basis of just a
few experiments is very risky.
seq_page_cost (floating point)
Sets the planner's estimate of the cost of a disk page fetch that is part of a series of
sequential fetches. The default is 1.0.
random_page_cost (floating point)
Sets the planner's estimate of the cost of a non-sequentially-fetched disk page. The default is
4.0. Reducing this value relative to seq_page_cost will cause the system to prefer index
scans; raising it will make index scans look relatively more expensive. You can raise or lower
both values together to change the importance of disk I/O costs relative to CPU costs, which
are described by the following parameters.
Dica: Although the system will let you set random_page_cost to less than
seq_page_cost, it is not physically sensible to do so. However, setting them equal
makes sense if the database is entirely cached in RAM, since in that case there is
no penalty for touching pages out of sequence. Also, in a heavily-cached database
you should lower both values relative to the CPU parameters, since the cost of
fetching a page already in RAM is much smaller than it would normally be.
cpu_tuple_cost (floating point)
Sets the planner's estimate of the cost of processing each row during a query. The default is
0.01.
cpu_index_tuple_cost (floating point)
Sets the planner's estimate of the cost of processing each index entry during an index scan.
The default is 0.005.
cpu_operator_cost (floating point)
Sets the planner's estimate of the cost of processing each operator or function executed
during a query. The default is 0.0025.
effective_cache_size (integer)
Sets the planner's assumption about the effective size of the disk cache that is available to a
single query. This is factored into estimates of the cost of using an index; a higher value
makes it more likely index scans will be used, a lower value makes it more likely sequential
scans will be used. When setting this parameter you should consider both PostgreSQL's
shared buffers and the portion of the kernel's disk cache that will be used for PostgreSQL data
files. Also, take into account the expected number of concurrent queries on different tables,
since they will have to share the available space. This parameter has no effect on the size of
shared memory allocated by PostgreSQL, nor does it reserve kernel disk cache; it is used only
for estimation purposes. The value is measured in disk pages, which are normally 8192 bytes
each. The default is 16384 (128 MB).
Query Planning
17.6.3. Genetic Query Optimizer
geqo (boolean)
Enables or disables genetic query optimization, which is an algorithm that attempts to do

query planning without exhaustive searching. This is on by default. The geqo_threshold
variable provides a more granular way to disable GEQO for certain classes of queries.
geqo_threshold (integer)
Use genetic query optimization to plan queries with at least this many FROM items involved.
(Note that a FULL OUTER JOIN construct counts as only one FROM item.) The default is 12.
For simpler queries it is usually best to use the deterministic, exhaustive planner, but for
queries with many tables the deterministic planner takes too long.
geqo_effort (integer)
Controls the trade off between planning time and query plan efficiency in GEQO. This variable
must be an integer in the range from 1 to 10. The default value is 5. Larger values increase
the time spent doing query planning, but also increase the likelihood that an efficient query
plan will be chosen.
geqo_effort doesn't actually do anything directly; it is only used to compute the default values
for the other variables that influence GEQO behavior (described below). If you prefer, you can
set the other parameters by hand instead.
geqo_pool_size (integer)
Controls the pool size used by GEQO. The pool size is the number of individuals in the genetic
population. It must be at least two, and useful values are typically 100 to 1000. If it is set to
zero (the default setting) then a suitable default is chosen based on geqo_effort and the
number of tables in the query.
geqo_generations (integer)
Controls the number of generations used by GEQO. Generations specifies the number of
iterations of the algorithm. It must be at least one, and useful values are in the same range
as the pool size. If it is set to zero (the default setting) then a suitable default is chosen based
on geqo_pool_size.
geqo_selection_bias (floating point)
Controls the selection bias used by GEQO. The selection bias is the selective pressure within
the population. Values can be from 1.50 to 2.00; the latter is the default.
17.6.4. Other Planner Options
default_statistics_target (integer)
Sets the default statistics target for table columns that have not had a column-specific target
set via ALTER TABLE SET STATISTICS. Larger values increase the time needed to do
ANALYZE, but may improve the quality of the planner's estimates. The default is 10. For more
information on the use of statistics by the PostgreSQL query planner, refer to Seção 13.2.
constraint_exclusion (boolean)
Enables or disables the query planner's use of table constraints to optimize queries. The
default is off.
When this parameter is on, the planner compares query conditions with table CHECK
constraints, and omits scanning tables for which the conditions contradict the constraints. For
example:
Query Planning
CREATE TABLE parent(key integer, ...);

CREATE TABLE child1000(check (key between 1000 and 1999)) INHERITS(parent);
CREATE TABLE child2000(check (key between 2000 and 2999)) INHERITS(parent);
...
SELECT * FROM parent WHERE key = 2400;
With constraint exclusion enabled, this SELECT will not scan child1000 at all. This can improve
performance when inheritance is used to build partitioned tables.
Currently, constraint_exclusion is disabled by default because it risks incorrect results if query

plans are cached — if a table constraint is changed or dropped, the previously generated plan
might now be wrong, and there is no built-in mechanism to force re-planning. (This deficiency
will probably be addressed in a future PostgreSQL release.) Another reason for keeping it off is
that the constraint checks are relatively expensive, and in many circumstances will yield no
savings. It is recommended to turn this on only if you are actually using partitioned tables
designed to take advantage of the feature.
Refer to Seção 5.9 for more information on using constraint exclusion and partitioning.
from_collapse_limit (integer)
The planner will merge sub-queries into upper queries if the resulting FROM list would have no
more than this many items. Smaller values reduce planning time but may yield inferior query
plans. The default is 8. It is usually wise to keep this less than geqo_threshold. For more
information see Seção 13.3.
join_collapse_limit (integer)
The planner will rewrite explicit JOIN constructs (except FULL JOINs) into lists of FROM items
whenever a list of no more than this many items would result. Smaller values reduce planning
time but may yield inferior query plans.
By default, this variable is set the same as from_collapse_limit, which is appropriate for most
uses. Setting it to 1 prevents any reordering of explicit JOINs. Thus, the explicit join order
specified in the query will be the actual order in which the relations are joined. The query
planner does not always choose the optimal join order; advanced users may elect to
temporarily set this variable to 1, and then specify the join order they desire explicitly. For
more information see Seção 13.3.

Write Ahead Log Acima Error Reporting and Logging
Error Reporting and Logging


17.7.1. Where To Log
log_destination (string)
PostgreSQL supports several methods for logging server messages, including stderr and
syslog. On Windows, eventlog is also supported. Set this parameter to a list of desired log
destinations separated by commas. The default is to log to stderr only. This parameter can
only be set in the postgresql.conf file or on the server command line.
redirect_stderr (boolean)
This parameter allows messages sent to stderr to be captured and redirected into log files.
This method, in combination with logging to stderr, is often more useful than logging to
syslog, since some types of messages may not appear in syslog output (a common example is
dynamic-linker failure messages). This parameter can only be set at server start.
log_directory (string)
When redirect_stderr is enabled, this parameter determines the directory in which log files will
be created. It may be specified as an absolute path, or relative to the cluster data directory.
log_filename (string)
When redirect_stderr is enabled, this parameter sets the file names of the created log files.
The value is treated as a strftime pattern, so %-escapes can be used to specify time-varying
file names. If no %-escapes are present, PostgreSQL will append the epoch of the new log
file's open time. For example, if log_filename were server_log, then the chosen file name
would be server_log.1093827753 for a log starting at Sun Aug 29 19:02:33 2004 MST. This
log_rotation_age (integer)
When redirect_stderr is enabled, this parameter determines the maximum lifetime of an

individual log file. After this many minutes have elapsed, a new log file will be created. Set to
zero to disable time-based creation of new log files. This parameter can only be set in the
log_rotation_size (integer)
When redirect_stderr is enabled, this parameter determines the maximum size of an

individual log file. After this many kilobytes have been emitted into a log file, a new log file
will be created. Set to zero to disable size-based creation of new log files. This parameter can
log_truncate_on_rotation (boolean)
When redirect_stderr is enabled, this parameter will cause PostgreSQL to truncate

(overwrite), rather than append to, any existing log file of the same name. However,
truncation will occur only when a new file is being opened due to time-based rotation, not
http://pgdocptbr.sourceforge.net/pg82/runtime-config-logging.html[09/02/2018 18:28:50]
during server startup or size-based rotation. When off, pre-existing files will be appended to in
all cases. For example, using this setting in combination with a log_filename like postgresql-
%H.log would result in generating twenty-four hourly log files and then cyclically overwriting
them. This parameter can only be set in the postgresql.conf file or on the server command
line.
Example: To keep 7 days of logs, one log file per day named server_log.Mon, server_log.Tue,
etc, and automatically overwrite last week's log with this week's log, set log_filename to
server_log.%a, log_truncate_on_rotation to on, and log_rotation_age to 1440.
Example: To keep 24 hours of logs, one log file per hour, but also rotate sooner if the log file
size exceeds 1GB, set log_filename to server_log.%H%M, log_truncate_on_rotation to on,
log_rotation_age to 60, and log_rotation_size to 1000000. Including %M in log_filename
allows any size-driven rotations that may occur to select a file name different from the hour's
initial file name.
syslog_facility (string)
When logging to syslog is enabled, this parameter determines the syslog "facility" to be used.
You may choose from LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6,
LOCAL7; the default is LOCAL0. See also the documentation of your system's syslog daemon.
syslog_ident (string)
When logging to syslog is enabled, this parameter determines the program name used to
identify PostgreSQL messages in syslog logs. The default is postgres. This parameter can only
be set in the postgresql.conf file or on the server command line.
17.7.2. When To Log
client_min_messages (string)
Controls which message levels are sent to the client. Valid values are DEBUG5, DEBUG4,
DEBUG3, DEBUG2, DEBUG1, LOG, NOTICE, WARNING, ERROR, FATAL, and PANIC. Each level
includes all the levels that follow it. The later the level, the fewer messages are sent. The
default is NOTICE. Note that LOG has a different rank here than in log_min_messages.
log_min_messages (string)
Controls which message levels are written to the server log. Valid values are DEBUG5,
DEBUG4, DEBUG3, DEBUG2, DEBUG1, INFO, NOTICE, WARNING, ERROR, LOG, FATAL, and
PANIC. Each level includes all the levels that follow it. The later the level, the fewer messages
are sent to the log. The default is NOTICE. Note that LOG has a different rank here than in
client_min_messages. Only superusers can change this setting.
log_error_verbosity (string)
Controls the amount of detail written in the server log for each message that is logged. Valid
values are TERSE, DEFAULT, and VERBOSE, each adding more fields to displayed messages.
Only superusers can change this setting.
log_min_error_statement (string)
Controls whether or not the SQL statement that causes an error condition will be recorded in
the server log. The current SQL statement is included in the log entry for any message of the
specified severity or higher. Valid values are DEBUG5, DEBUG4, DEBUG3, DEBUG2, DEBUG1,
INFO, NOTICE, WARNING, ERROR, FATAL, and PANIC. The default is ERROR, which means
statements causing errors, fatal errors, or panics will be logged. To effectively turn off logging
of failing statements, set this parameter to PANIC. Only superusers can change this setting.
log_min_duration_statement (integer)
Causes the duration of each completed statement to be logged if the statement ran for at
least the specified number of milliseconds. Setting this to zero prints all statement durations.
Minus-one (the default) disables logging statement durations. For example, if you set it to 250
then all SQL statements that run 250ms or longer will be logged. Enabling this parameter can
be helpful in tracking down unoptimized queries in your applications. Only superusers can
change this setting.
For clients using extended query protocol, durations of the Parse, Bind, and Execute steps are
logged independently.
Nota: When using this option together with log_statement, the text of statements
that are logged because of log_statement will not be repeated in the duration log
message. If you are not using syslog, it is recommended that you log the PID or
session ID using log_line_prefix so that you can link the statement message to the
later duration message using the process ID or session ID.
silent_mode (boolean)
Runs the server silently. If this parameter is set, the server will automatically run in
background and any controlling terminals are disassociated. The server's standard output and
standard error are redirected to /dev/null, so any messages sent to them will be lost. Unless
syslog logging is selected or redirect_stderr is enabled, using this parameter is discouraged
because it makes it impossible to see error messages. This parameter can only be set at
server start.
Here is a list of the various message severity levels used in these settings:
DEBUG[1-5]
Provides information for use by developers.
INFO
Provides information implicitly requested by the user, e.g., during VACUUM VERBOSE.
NOTICE
Provides information that may be helpful to users, e.g., truncation of long identifiers and the
creation of indexes as part of primary keys.
WARNING
Provides warnings to the user, e.g., COMMIT outside a transaction block.
ERROR
Reports an error that caused the current command to abort.
LOG
Reports information of interest to administrators, e.g., checkpoint activity.
FATAL
Reports an error that caused the current session to abort.
PANIC
Reports an error that caused all sessions to abort.
17.7.3. What To Log
debug_print_parse (boolean)
debug_print_rewritten (boolean)
debug_print_plan (boolean)
debug_pretty_print (boolean)
These parameters enable various debugging output to be emitted. For each executed query,
they print the resulting parse tree, the query rewriter output, or the execution plan.
debug_pretty_print indents these displays to produce a more readable but much longer output
format. client_min_messages or log_min_messages must be DEBUG1 or lower to actually
send this output to the client or the server log, respectively. These parameters are off by
default.
log_connections (boolean)
This outputs a line to the server log detailing each successful connection. This is off by default,
although it is probably very useful. Some client programs, like psql, attempt to connect twice
while determining if a password is required, so duplicate "connection received" messages do
not necessarily indicate a problem. This parameter can only be set in the postgresql.conf file
or on the server command line.
log_disconnections (boolean)
This outputs a line in the server log similar to log_connections but at session termination, and
includes the duration of the session. This is off by default. This parameter can only be set in
the postgresql.conf file or on the server command line.
log_duration (boolean)
Causes the duration of every completed statement to be logged. The default is off. Only
superusers can change this setting.
For clients using extended query protocol, durations of the Parse, Bind, and Execute steps are
logged independently.
Nota: The difference between setting this option and setting

log_min_duration_statement to zero is that exceeding log_min_duration_statement
forces the text of the query to be logged, but this option doesn't. Thus, if
log_duration is on and log_min_duration_statement has a positive value, all
durations are logged but the query text is included only for statements exceeding
the threshold. This behavior can be useful for gathering statistics in high-load
installations.
log_line_prefix (string)
This is a printf-style string that is output at the beginning of each log line. The default is an
empty string. Each recognized escape is replaced as outlined below - anything else that looks
like an escape is ignored. Other characters are copied straight to the log line. Some escapes
are only recognized by session processes, and do not apply to background processes such as
the main server process. Syslog produces its own time stamp and process ID information, so
you probably do not want to use those escapes if you are using syslog. This parameter can
Session
Escape Effect
only
%u User name yes
%d Database name yes
%r Remote host name or IP address, and remote port yes
%h Remote host name or IP address yes
%p Process ID no
%t Time stamp (no milliseconds) no
%m Time stamp with milliseconds no
%i Command tag: This is the command that generated the log line. yes
%c Session ID: A unique identifier for each session. It is 2 4-byte hexadecimal yes
numbers (without leading zeros) separated by a dot. The numbers are the
session start time and the process ID, so this can also be used as a space
saving way of printing these items.
%l Number of the log line for each process, starting at 1 no
%s Session start time stamp yes
%x Transaction ID yes
%q Does not produce any output, but tells non-session processes to stop at this no
point in the string. Ignored by session processes.
%% Literal % no
log_statement (string)
Controls which SQL statements are logged. Valid values are none, ddl, mod, and all. ddl logs
all data definition statements, such as CREATE, ALTER, and DROP statements. mod logs all ddl
statements, plus data-modifying statements such as INSERT, UPDATE, DELETE, TRUNCATE,
and COPY FROM. PREPARE, EXECUTE, and EXPLAIN ANALYZE statements are also logged if
their contained command is of an appropriate type. For clients using extended query protocol,
logging occurs when an Execute message is received, and values of the Bind parameters are
included (with any embedded single-quote marks doubled).
The default is none. Only superusers can change this setting.
Nota: Statements that contain simple syntax errors are not logged even by the
log_statement = all setting, because the log message is emitted only after basic
parsing has been done to determine the statement type. In the case of extended
query protocol, this setting likewise does not log statements that fail before the
Execute phase (i.e., during parse analysis or planning). Set
log_min_error_statement to ERROR (or lower) to log such statements.
log_hostname (boolean)
By default, connection log messages only show the IP address of the connecting host. Turning
on this parameter causes logging of the host name as well. Note that depending on your host
name resolution setup this might impose a non-negligible performance penalty. This

Query Planning Acima Run-Time Statistics
Run-Time Statistics


17.8.1. Query and Index Statistics Collector
These parameters control a server-wide statistics collection feature. When statistics collection is
enabled, the data that is produced can be accessed via the pg_stat and pg_statio family of system
views. Refer to Capítulo 25 for more information.
Nota: As of PostgreSQL 8.2, stats_command_string controls a separate data collection

mechanism that can be turned on or off independently of whether the statistics-
collection subprocess is running. The subprocess is only needed to support collection of
block-level or row-level statistics.
stats_command_string (boolean)
Enables the collection of information on the currently executing command of each session,
along with the time at which that command began execution. This parameter is on by default.
Note that even when enabled, this information is not visible to all users, only to superusers
and the user owning the session being reported on; so it should not represent a security risk.
Only superusers can change this setting.
update_process_title (boolean)
Enables updating of the process title every time a new SQL command is received by the
server. The process title is typically viewed by the ps command or in Windows using the
Process Explorer. Only superusers can change this setting.
stats_start_collector (boolean)
Controls whether the server should start the statistics-collection subprocess. This is on by
default, but may be turned off if you know you have no interest in collecting statistics or
running autovacuum. This parameter can only be set at server start, because the collection
subprocess cannot be started or stopped on-the-fly. (However, the extent to which statistics
are actually gathered can be changed while the server is running, so long as the subprocess
exists.)
stats_block_level (boolean)
Enables the collection of block-level statistics on database activity. This parameter is off by
default. Only superusers can change this setting.
stats_row_level (boolean)
Enables the collection of row-level statistics on database activity. This parameter is off by
default. Only superusers can change this setting.
stats_reset_on_server_start (boolean)
If on, collected block-level and row-level statistics are zeroed out whenever the server is
restarted. If off, statistics are accumulated across server restarts. This parameter is off by
default. This parameter can only be set at server start.
17.8.2. Statistics Monitoring
http://pgdocptbr.sourceforge.net/pg82/runtime-config-statistics.html[09/02/2018 18:29:13]
Run-Time Statistics
log_statement_stats (boolean)
log_parser_stats (boolean)
log_planner_stats (boolean)
log_executor_stats (boolean)
For each query, write performance statistics of the respective module to the server log. This is
a crude profiling instrument. log_statement_stats reports total statement statistics, while the
others report per-module statistics. log_statement_stats cannot be enabled together with any
of the per-module options. All of these options are disabled by default. Only superusers can
change these settings.

Error Reporting and Logging Acima Automatic Vacuuming
http://pgdocptbr.sourceforge.net/pg82/runtime-config-statistics.html[09/02/2018 18:29:13]
Automatic Vacuuming


These settings control the behavior of the autovacuum feature. Refer to Seção 22.1.4 for more
information.
autovacuum (boolean)
Controls whether the server should run the autovacuum daemon. This is off by default.
stats_start_collector and stats_row_level must also be turned on for autovacuum to work.
autovacuum_naptime (integer)
Specifies the delay between activity rounds for the autovacuum daemon. In each round the
daemon examines one database and issues VACUUM and ANALYZE commands as needed for
tables in that database. The delay is measured in seconds, and the default is 60. This
autovacuum_vacuum_threshold (integer)
Specifies the minimum number of updated or deleted tuples needed to trigger a VACUUM in
any one table. The default is 500. This parameter can only be set in the postgresql.conf file or
on the server command line. This setting can be overridden for individual tables by entries in
pg_autovacuum.
autovacuum_analyze_threshold (integer)
Specifies the minimum number of inserted, updated or deleted tuples needed to trigger an
ANALYZE in any one table. The default is 250. This parameter can only be set in the
postgresql.conf file or on the server command line. This setting can be overridden for
individual tables by entries in pg_autovacuum.
autovacuum_vacuum_scale_factor (floating point)
Specifies a fraction of the table size to add to autovacuum_vacuum_threshold when deciding

whether to trigger a VACUUM. The default is 0.2. This parameter can only be set in the
autovacuum_analyze_scale_factor (floating point)
Specifies a fraction of the table size to add to autovacuum_analyze_threshold when deciding

whether to trigger an ANALYZE. The default is 0.1. This parameter can only be set in the
autovacuum_freeze_max_age (integer)
Specifies the maximum age (in transactions) that a table's pg_class.relfrozenxid field can
attain before a VACUUM operation is forced to prevent transaction ID wraparound within the
table. Note that the system will launch autovacuum processes to prevent wraparound even
when autovacuum is otherwise disabled. The default is 200000000 (200 million). This
parameter can only be set at server start, but the setting can be reduced for individual tables
by entries in pg_autovacuum. For more information see Seção 22.1.3.
http://pgdocptbr.sourceforge.net/pg82/runtime-config-autovacuum.html[09/02/2018 18:29:28]
Automatic Vacuuming
autovacuum_vacuum_cost_delay (integer)
Specifies the cost delay value that will be used in automatic VACUUM operations. If -1 is
specified (which is the default), the regular vacuum_cost_delay value will be used. This
parameter can only be set in the postgresql.conf file or on the server command line. This
setting can be overridden for individual tables by entries in pg_autovacuum.
autovacuum_vacuum_cost_limit (integer)
Specifies the cost limit value that will be used in automatic VACUUM operations. If -1 is
specified (which is the default), the regular vacuum_cost_limit value will be used. This
parameter can only be set in the postgresql.conf file or on the server command line. This
setting can be overridden for individual tables by entries in pg_autovacuum.

Run-Time Statistics Acima Client Connection Defaults
http://pgdocptbr.sourceforge.net/pg82/runtime-config-autovacuum.html[09/02/2018 18:29:28]
Client Connection Defaults


17.10.1. Statement Behavior
search_path (string)
This variable specifies the order in which schemas are searched when an object (table, data
type, function, etc.) is referenced by a simple name with no schema component. When there
are objects of identical names in different schemas, the one found first in the search path is
used. An object that is not in any of the schemas in the search path can only be referenced by
specifying its containing schema with a qualified (dotted) name.
The value for search_path has to be a comma-separated list of schema names. If one of the
list items is the special value $user, then the schema having the name returned by
SESSION_USER is substituted, if there is such a schema. (If not, $user is ignored.)
The system catalog schema, pg_catalog, is always searched, whether it is mentioned in the
path or not. If it is mentioned in the path then it will be searched in the specified order. If
pg_catalog is not in the path then it will be searched before searching any of the path items.
It should also be noted that the temporary-table schema, pg_temp_nnn, is implicitly searched
before any of these.
When objects are created without specifying a particular target schema, they will be placed in
the first schema listed in the search path. An error is reported if the search path is empty.
The default value for this parameter is '"$user", public' (where the second part will be ignored
if there is no schema named public). This supports shared use of a database (where no users
have private schemas, and all share use of public), private per-user schemas, and
combinations of these. Other effects can be obtained by altering the default search path
setting, either globally or per-user.
The current effective value of the search path can be examined via the SQL function
current_schemas(). This is not quite the same as examining the value of search_path, since
current_schemas() shows how the requests appearing in search_path were resolved.
For more information on schema handling, see Seção 5.7.
default_tablespace (string)
This variable specifies the default tablespace in which to create objects (tables and indexes)
when a CREATE command does not explicitly specify a tablespace.
The value is either the name of a tablespace, or an empty string to specify using the default
tablespace of the current database. If the value does not match the name of any existing
tablespace, PostgreSQL will automatically use the default tablespace of the current database.
For more information on tablespaces, see Seção 19.6.
check_function_bodies (boolean)
This parameter is normally on. When set to off, it disables validation of the function body
string during CREATE FUNCTION. Disabling validation is occasionally useful to avoid problems
such as forward references when restoring function definitions from a dump.
http://pgdocptbr.sourceforge.net/pg82/runtime-config-client.html[09/02/2018 18:29:36]
default_transaction_isolation (string)
Each SQL transaction has an isolation level, which can be either "read uncommitted", "read
committed", "repeatable read", or "serializable". This parameter controls the default isolation
level of each new transaction. The default is "read committed".
Consult Capítulo 12 and SET TRANSACTION for more information.
default_transaction_read_only (boolean)
A read-only SQL transaction cannot alter non-temporary tables. This parameter controls the
default read-only status of each new transaction. The default is off (read/write).
Consult SET TRANSACTION for more information.
statement_timeout (integer)
Abort any statement that takes over the specified number of milliseconds, starting from the
time the command arrives at the server from the client. If log_min_error_statement is set to
ERROR or lower, the statement that timed out will also be logged. A value of zero (the
default) turns off the limitation.
vacuum_freeze_min_age (integer)
Specifies the cutoff age (in transactions) that VACUUM should use to decide whether to
replace transaction IDs with FrozenXID while scanning a table. The default is 100000000 (100
million). Although users can set this value anywhere from zero to 1000000000, VACUUM will
silently limit the effective value to half the value of autovacuum_freeze_max_age, so that there
is not an unreasonably short time between forced autovacuums. For more information see
Seção 22.1.3.
17.10.2. Locale and Formatting
DateStyle (string)
Sets the display format for date and time values, as well as the rules for interpreting
ambiguous date input values. For historical reasons, this variable contains two independent
components: the output format specification (ISO, Postgres, SQL, or German) and the
input/output specification for year/month/day ordering (DMY, MDY, or YMD). These can be set
separately or together. The keywords Euro and European are synonyms for DMY; the
keywords US, NonEuro, and NonEuropean are synonyms for MDY. See Seção 8.5 for more
information. The built-in default is ISO, MDY, but initdb will initialize the configuration file with
a setting that corresponds to the behavior of the chosen lc_time locale.
timezone (string)
Sets the time zone for displaying and interpreting time stamps. The default is 'unknown',
which means to use whatever the system environment specifies as the time zone. See Seção
8.5 for more information.
timezone_abbreviations (string)
Sets the collection of time zone abbreviations that will be accepted by the server for datetime
input. The default is 'Default', which is a collection that works in most of the world; there are
also 'Australia' and 'India', and other collections can be defined for a particular installation.
See Apêndice B for more information.
extra_float_digits (integer)
This parameter adjusts the number of digits displayed for floating-point values, including
float4, float8, and geometric data types. The parameter value is added to the standard
number of digits (FLT_DIG or DBL_DIG as appropriate). The value can be set as high as 2, to
include partially-significant digits; this is especially useful for dumping float data that needs to
be restored exactly. Or it can be set negative to suppress unwanted digits.
client_encoding (string)
Sets the client-side encoding (character set). The default is to use the database encoding.
lc_messages (string)
Sets the language in which messages are displayed. Acceptable values are system-dependent;
see Seção 21.1 for more information. If this variable is set to the empty string (which is the
default) then the value is inherited from the execution environment of the server in a system-
dependent way.
On some systems, this locale category does not exist. Setting this variable will still work, but
there will be no effect. Also, there is a chance that no translated messages for the desired
language exist. In that case you will continue to see the English messages.
Only superusers can change this setting, because it affects the messages sent to the server
log as well as to the client.
lc_monetary (string)
Sets the locale to use for formatting monetary amounts, for example with the to_char family
of functions. Acceptable values are system-dependent; see Seção 21.1 for more information. If
this variable is set to the empty string (which is the default) then the value is inherited from
the execution environment of the server in a system-dependent way.
lc_numeric (string)
Sets the locale to use for formatting numbers, for example with the to_char family of
functions. Acceptable values are system-dependent; see Seção 21.1 for more information. If
this variable is set to the empty string (which is the default) then the value is inherited from
the execution environment of the server in a system-dependent way.
lc_time (string)
Sets the locale to use for formatting date and time values. (Currently, this setting does
nothing, but it may in the future.) Acceptable values are system-dependent; see Seção 21.1
for more information. If this variable is set to the empty string (which is the default) then the
value is inherited from the execution environment of the server in a system-dependent way.
17.10.3. Other Defaults
explain_pretty_print (boolean)
Determines whether EXPLAIN VERBOSE uses the indented or non-indented format for
displaying detailed query-tree dumps. The default is on.
dynamic_library_path (string)
If a dynamically loadable module needs to be opened and the file name specified in the
CREATE FUNCTION or LOAD command does not have a directory component (i.e. the name
does not contain a slash), the system will search this path for the required file.
The value for dynamic_library_path has to be a list of absolute directory paths separated by
colons (or semi-colons on Windows). If a list element starts with the special string $libdir, the
compiled-in PostgreSQL package library directory is substituted for $libdir. This is where the
modules provided by the standard PostgreSQL distribution are installed. (Use pg_config --
pkglibdir to find out the name of this directory.) For example:
dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
or, in a Windows environment:
dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
The default value for this parameter is '$libdir'. If the value is set to an empty string, the
automatic path search is turned off.
This parameter can be changed at run time by superusers, but a setting done that way will
only persist until the end of the client connection, so this method should be reserved for
development purposes. The recommended way to set this parameter is in the postgresql.conf
configuration file.
gin_fuzzy_search_limit (integer)
Soft upper limit of the size of the set returned by GIN index. For more information see Seção
51.4.
local_preload_libraries (string)
This variable specifies one or more shared libraries that are to be preloaded at connection
start. If more than one library is to be loaded, separate their names with commas. This
parameter cannot be changed after the start of a particular session.
Because this is not a superuser-only option, the libraries that can be loaded are restricted to
those appearing in the plugins subdirectory of the installation's standard library directory. (It
is the database administrator's responsibility to ensure that only "safe" libraries are installed
there.) Entries in local_preload_libraries can specify this directory explicitly, for example
$libdir/plugins/mylib, or just specify the library name — mylib would have the same effect as
$libdir/plugins/mylib.
There is no performance advantage to loading a library at session start rather than when it is
first used. Rather, the intent of this feature is to allow debugging or performance-
measurement libraries to be loaded into specific sessions without an explicit LOAD command
being given. For example, debugging could be enabled for all sessions under a given user
name by setting this parameter with ALTER USER SET.
If a specified library is not found, the connection attempt will fail.
Every PostgreSQL-supported library has a "magic block" that is checked to guarantee

compatibility. For this reason, non-PostgreSQL libraries cannot be loaded in this way.

Automatic Vacuuming Acima Lock Management
Lock Management


deadlock_timeout (integer)
This is the amount of time, in milliseconds, to wait on a lock before checking to see if there is
a deadlock condition. The check for deadlock is relatively slow, so the server doesn't run it
every time it waits for a lock. We (optimistically?) assume that deadlocks are not common in
production applications and just wait on the lock for a while before starting the check for a
deadlock. Increasing this value reduces the amount of time wasted in needless deadlock
checks, but slows down reporting of real deadlock errors. The default is 1000 (i.e., one
second), which is probably about the smallest value you would want in practice. On a heavily
loaded server you might want to raise it. Ideally the setting should exceed your typical
transaction time, so as to improve the odds that a lock will be released before the waiter
decides to check for deadlock.
max_locks_per_transaction (integer)
The shared lock table is created with room to describe locks on max_locks_per_transaction *
(max_connections + max_prepared_transactions) objects; hence, no more than this many
distinct objects can be locked at any one time. (Thus, this parameter's name may be
confusing: it is not a hard limit on the number of locks taken by any one transaction, but
rather a maximum average value.) The default, 64, has historically proven sufficient, but you
might need to raise this value if you have clients that touch many different tables in a single
transaction. This parameter can only be set at server start.

Client Connection Defaults Acima Version and Platform Compatibility
http://pgdocptbr.sourceforge.net/pg82/runtime-config-locks.html[09/02/2018 18:29:48]
Version and Platform Compatibility


17.12.1. Previous PostgreSQL Versions
add_missing_from (boolean)
When on, tables that are referenced by a query will be automatically added to the FROM
clause if not already present. This behavior does not comply with the SQL standard and many
people dislike it because it can mask mistakes (such as referencing a table where you should
have referenced its alias). The default is off. This variable can be enabled for compatibility
with releases of PostgreSQL prior to 8.1, where this behavior was allowed by default.
Note that even when this variable is enabled, a warning message will be emitted for each
implicit FROM entry referenced by a query. Users are encouraged to update their applications
to not rely on this behavior, by adding all tables referenced by a query to the query's FROM
clause (or its USING clause in the case of DELETE).
array_nulls (boolean)
This controls whether the array input parser recognizes unquoted NULL as specifying a null
array element. By default, this is on, allowing array values containing null values to be
entered. However, PostgreSQL versions before 8.2 did not support null values in arrays, and
therefore would treat NULL as specifying a normal array element with the string value "NULL".
For backwards compatibility with applications that require the old behavior, this variable can
be turned off.
Note that it is possible to create array values containing null values even when this variable is
off.
backslash_quote (string)
This controls whether a quote mark can be represented by \' in a string literal. The preferred,
SQL-standard way to represent a quote mark is by doubling it ('') but PostgreSQL has
historically also accepted \'. However, use of \' creates security risks because in some client
character set encodings, there are multibyte characters in which the last byte is numerically
equivalent to ASCII \. If client-side code does escaping incorrectly then a SQL-injection attack
is possible. This risk can be prevented by making the server reject queries in which a quote
mark appears to be escaped by a backslash. The allowed values of backslash_quote are on
(allow \' always), off (reject always), and safe_encoding (allow only if client encoding does not
allow ASCII \ within a multibyte character). safe_encoding is the default setting.
Note that in a standard-conforming string literal, \ just means \ anyway. This parameter
affects the handling of non-standard-conforming literals, including escape string syntax
(E'...').
default_with_oids (boolean)
This controls whether CREATE TABLE and CREATE TABLE AS include an OID column in newly-
created tables, if neither WITH OIDS nor WITHOUT OIDS is specified. It also determines
whether OIDs will be included in tables created by SELECT INTO. In PostgreSQL 8.1
default_with_oids is disabled by default; in prior versions of PostgreSQL, it was on by default.
The use of OIDs in user tables is considered deprecated, so most installations should leave
http://pgdocptbr.sourceforge.net/pg82/runtime-config-compatible.html[09/02/2018 18:29:57]
this variable disabled. Applications that require OIDs for a particular table should specify WITH
OIDS when creating the table. This variable can be enabled for compatibility with old
applications that do not follow this behavior.
escape_string_warning (boolean)
When on, a warning is issued if a backslash (\) appears in an ordinary string literal ('...'
syntax) and standard_conforming_strings is off. The default is on.
Applications that wish to use backslash as escape should be modified to use escape string
syntax (E'...'), because the default behavior of ordinary strings will change in a future release
for SQL compatibility. This variable can be enabled to help detect applications that will break.
regex_flavor (string)
The regular expression "flavor" can be set to advanced, extended, or basic. The default is
advanced. The extended setting may be useful for exact backwards compatibility with pre-7.4
releases of PostgreSQL. See Seção 9.7.3.1 for details.
sql_inheritance (boolean)
This controls the inheritance semantics. If turned off, subtables are not included by various
commands by default; basically an implied ONLY key word. This was added for compatibility
with releases prior to 7.1. See Seção 5.8 for more information.
standard_conforming_strings (boolean)
This controls whether ordinary string literals ('...') treat backslashes literally, as specified in
the SQL standard. The default is currently off, causing PostgreSQL to have its historical
behavior of treating backslashes as escape characters. The default will change to on in a
future release to improve compatibility with the standard. Applications may check this
parameter to determine how string literals will be processed. The presence of this parameter
can also be taken as an indication that the escape string syntax (E'...') is supported. Escape
string syntax should be used if an application desires backslashes to be treated as escape
characters.
17.12.2. Platform and Client Compatibility
transform_null_equals (boolean)
When on, expressions of the form expressão = NULL (or NULL = expressão) are treated as
expressão IS NULL, that is, they return true if expressão evaluates to the null value, and false
otherwise. The correct SQL-spec-compliant behavior of expressão = NULL is to always return
null (unknown). Therefore this parameter defaults to off.
However, filtered forms in Microsoft Access generate queries that appear to use expressão =
NULL to test for null values, so if you use that interface to access the database you might
want to turn this option on. Since expressions of the form expressão = NULL always return
the null value (using the correct interpretation) they are not very useful and do not appear
often in normal applications, so this option does little harm in practice. But new users are
frequently confused about the semantics of expressions involving null values, so this option is
not on by default.
Note that this option only affects the exact form = NULL, not other comparison operators or
other expressions that are computationally equivalent to some expression involving the equals
operator (such as IN). Thus, this option is not a general fix for bad programming.
Refer to Seção 9.2 for related information.

Lock Management Acima Preset Options
Preset Options


The following "parameters" are read-only, and are determined when PostgreSQL is compiled or
when it is installed. As such, they have been excluded from the sample postgresql.conf file. These
options report various aspects of PostgreSQL behavior that may be of interest to certain
applications, particularly administrative front-ends.
block_size (integer)
Reports the size of a disk block. It is determined by the value of BLCKSZ when building the
server. The default value is 8192 bytes. The meaning of some configuration variables (such as
shared_buffers) is influenced by block_size. See Seção 17.4 for information.
integer_datetimes (boolean)
Reports whether PostgreSQL was built with support for 64-bit-integer dates and times. It is
set by configuring with --enable-integer-datetimes when building PostgreSQL. The default
value is off.
lc_collate (string)
Reports the locale in which sorting of textual data is done. Para obter mais informações
consulte a Seção 21.1. The value is determined when the database cluster is initialized.
lc_ctype (string)
Reports the locale that determines character classifications. Para obter mais informações
consulte a Seção 21.1. The value is determined when the database cluster is initialized.
Ordinarily this will be the same as lc_collate, but for special applications it might be set
differently.
max_function_args (integer)
Reports the maximum number of function arguments. It is determined by the value of

FUNC_MAX_ARGS when building the server. The default value is 100.
max_identifier_length (integer)
Reports the maximum identifier length. It is determined as one less than the value of
NAMEDATALEN when building the server. The default value of NAMEDATALEN is 64; therefore
the default max_identifier_length is 63.
max_index_keys (integer)
Reports the maximum number of index keys. It is determined by the value of

INDEX_MAX_KEYS when building the server. The default value is 32.
server_encoding (string)
Reports the database encoding (character set). It is determined when the database is created.
Ordinarily, clients need only be concerned with the value of client_encoding.
server_version (string)
Reports the version number of the server. It is determined by the value of PG_VERSION when
http://pgdocptbr.sourceforge.net/pg82/runtime-config-preset.html[09/02/2018 18:30:11]
Preset Options
building the server.
server_version_num (integer)
Reports the version number of the server as an integer. It is determined by the value of
PG_VERSION_NUM when building the server.

Version and Platform Compatibility Acima Customized Options
http://pgdocptbr.sourceforge.net/pg82/runtime-config-preset.html[09/02/2018 18:30:11]
Customized Options


This feature was designed to allow parameters not normally known to PostgreSQL to be added by
add-on modules (such as procedural languages). This allows add-on modules to be configured in
the standard ways.
custom_variable_classes (string)
This variable specifies one or several class names to be used for custom variables, in the form
of a comma-separated list. A custom variable is a variable not normally known to PostgreSQL
proper but used by some add-on module. Such variables must have names consisting of a
class name, a dot, and a variable name. custom_variable_classes specifies all the class names
in use in a particular installation. This parameter can only be set in the postgresql.conf file or
on the server command line.
The difficulty with setting custom variables in postgresql.conf is that the file must be read before
add-on modules have been loaded, and so custom variables would ordinarily be rejected as
unknown. When custom_variable_classes is set, the server will accept definitions of arbitrary
variables within each specified class. These variables will be treated as placeholders and will have
no function until the module that defines them is loaded. When a module for a specific class is
loaded, it will add the proper variable definitions for its class name, convert any placeholder values
according to those definitions, and issue warnings for any placeholders of its class that remain
(which presumably would be misspelled configuration variables).
Here is an example of what postgresql.conf might contain when using custom variables:
custom_variable_classes = 'plr,plperl'
plr.path = '/usr/lib/R'
plperl.use_strict = true
plruby.use_strict = true # generates error: unknown class name

Preset Options Acima Developer Options
http://pgdocptbr.sourceforge.net/pg82/runtime-config-custom.html[09/02/2018 18:30:20]
Developer Options


The following parameters are intended for work on the PostgreSQL source, and in some cases to
assist with recovery of severely damaged databases. There should be no reason to use them in a
production database setup. As such, they have been excluded from the sample postgresql.conf file.
Note that many of these parameters require special source compilation flags to work at all.
allow_system_table_mods (boolean)
Allows modification of the structure of system tables. This is used by initdb. This parameter
debug_assertions (boolean)
Turns on various assertion checks. This is a debugging aid. If you are experiencing strange
problems or crashes you might want to turn this on, as it might expose programming
mistakes. To use this parameter, the macro USE_ASSERT_CHECKING must be defined when
PostgreSQL is built (accomplished by the configure option --enable-cassert). Note that
debug_assertions defaults to on if PostgreSQL has been built with assertions enabled.
ignore_system_indexes (boolean)
Ignore system indexes when reading system tables (but still update the indexes when
modifying the tables). This is useful when recovering from damaged system indexes. This
parameter cannot be changed after session start.
post_auth_delay (integer)
If nonzero, a delay of this many seconds occurs when a new server process is started, after it
conducts the authentication procedure. This is intended to give an opportunity to attach to the
server process with a debugger. This parameter cannot be changed after session start.
pre_auth_delay (integer)
If nonzero, a delay of this many seconds occurs just after a new server process is forked,
before it conducts the authentication procedure. This is intended to give an opportunity to
attach to the server process with a debugger to trace down misbehavior in authentication.
trace_notify (boolean)
Generates a great amount of debugging output for the LISTEN and NOTIFY commands.
client_min_messages or log_min_messages must be DEBUG1 or lower to send this output to the
client or server log, respectively.
trace_sort (boolean)
If on, emit information about resource usage during sort operations. This parameter is only
available if the TRACE_SORT macro was defined when PostgreSQL was compiled. (However,
TRACE_SORT is currently defined by default.)
trace_locks (boolean)
trace_lwlocks (boolean)
trace_userlocks (boolean)
http://pgdocptbr.sourceforge.net/pg82/runtime-config-developer.html[09/02/2018 18:30:29]
Developer Options
trace_lock_oidmin (boolean)
trace_lock_table (boolean)
debug_deadlocks (boolean)
log_btree_build_stats (boolean)
Various other code tracing and debugging options.
wal_debug (boolean)
If on, emit WAL-related debugging output. This parameter is only available if the WAL_DEBUG
macro was defined when PostgreSQL was compiled.
zero_damaged_pages (boolean)
Detection of a damaged page header normally causes PostgreSQL to report an error, aborting
the current command. Setting zero_damaged_pages to on causes the system to instead
report a warning, zero out the damaged page, and continue processing. This behavior will
destroy data, namely all the rows on the damaged page. But it allows you to get past the
error and retrieve rows from any undamaged pages that may be present in the table. So it is
useful for recovering data if corruption has occurred due to hardware or software error. You
should generally not set this on until you have given up hope of recovering data from the
damaged page(s) of a table. The default setting is off, and it can only be changed by a
superuser.

Customized Options Acima Short Options
http://pgdocptbr.sourceforge.net/pg82/runtime-config-developer.html[09/02/2018 18:30:29]
Short Options


For convenience there are also single letter command-line option switches available for some
parameters. They are described in Tabela 17-1. Some of these options exist for historical reasons,
and their presence as a single-letter option does not necessarily indicate an endorsement to use the
option heavily.
Tabela 17-1. Short option key
Short
Equivalent
option
-A x debug_assertions = x
-B x shared_buffers = x
-d x log_min_messages = DEBUGx
-e datestyle = euro
-fb, -fh, -fi, - enable_bitmapscan = off, enable_hashjoin = off, enable_indexscan = off,
fm, -fn, -fs, - enable_mergejoin = off, enable_nestloop = off, enable_seqscan = off, enable_tidscan
ft = off
-F fsync = off
-h x listen_addresses = x
-i listen_addresses = '*'
-k x unix_socket_directory = x
-l ssl = on
-N x max_connections = x
-O allow_system_table_mods = on
-p x port = x
-P ignore_system_indexes = on
-s log_statement_stats = on
-S x work_mem = x
-tpa, -tpl, -te log_parser_stats = on, log_planner_stats = on, log_executor_stats = on
-W x post_auth_delay = x

Developer Options Acima Database Roles and Privileges
http://pgdocptbr.sourceforge.net/pg82/runtime-config-short.html[09/02/2018 18:30:38]
Database Roles and Privileges

Capítulo 18. Database Roles and Privileges

Sumário
18.3. Privileges
PostgreSQL manages database access permissions using the concept of roles. A role can be thought
of as either a database user, or a group of database users, depending on how the role is set up.
Roles can own database objects (for example, tables) and can assign privileges on those objects to
other roles to control who has access to which objects. Furthermore, it is possible to grant
membership in a role to another role, thus allowing the member role use of privileges assigned to
the role it is a member of.
The concept of roles subsumes the concepts of "users" and "groups". In PostgreSQL versions before
8.1, users and groups were distinct kinds of entities, but now there are only roles. Any role can act
as a user, a group, or both.
This chapter describes how to create and manage roles and introduces the privilege system. More
information about the various types of database objects and the effects of privileges can be found in
Capítulo 5.

Short Options Acima Database Roles
http://pgdocptbr.sourceforge.net/pg82/user-manag.html[09/02/2018 18:30:52]
Database Roles

Anterior Início Capítulo 18. Database Roles and Privileges Fim Próxima

Database roles are conceptually completely separate from operating system users. In practice it
might be convenient to maintain a correspondence, but this is not required. Database roles are
global across a database cluster installation (and not per individual database). To create a role use
the CREATE ROLE SQL command:
CREATE ROLE nome;
nome follows the rules for SQL identifiers: either unadorned without special characters, or double-
quoted. (In practice, you will usually want to add additional options, such as LOGIN, to the
command. More details appear below.) To remove an existing role, use the analogous DROP ROLE
command:
DROP ROLE nome;
For convenience, the programs createuser and dropuser are provided as wrappers around these SQL
commands that can be called from the shell command line:
createuser nome
dropuser nome
To determine the set of existing roles, examine the pg_roles system catalog, for example
SELECT rolname FROM pg_roles;
The psql program's \du meta-command is also useful for listing the existing roles.
In order to bootstrap the database system, a freshly initialized system always contains one
predefined role. This role is always a "superuser", and by default (unless altered when running
initdb) it will have the same name as the operating system user that initialized the database
cluster. Customarily, this role will be named postgres. In order to create more roles you first have
to connect as this initial role.
Every connection to the database server is made in the name of some particular role, and this role
determines the initial access privileges for commands issued on that connection. The role name to
use for a particular database connection is indicated by the client that is initiating the connection
request in an application-specific fashion. For example, the psql program uses the -U command line
option to indicate the role to connect as. Many applications assume the name of the current
operating system user by default (including createuser and psql). Therefore it is often convenient to
maintain a naming correspondence between roles and operating system users.
The set of database roles a given client connection may connect as is determined by the client
authentication setup, as explained in Capítulo 20. (Thus, a client is not necessarily limited to connect
as the role with the same name as its operating system user, just as a person's login name need
not match her real name.) Since the role identity determines the set of privileges available to a
connected client, it is important to carefully configure this when setting up a multiuser environment.

Database Roles and Privileges Acima Role Attributes
http://pgdocptbr.sourceforge.net/pg82/database-roles.html[09/02/2018 18:31:01]
Role Attributes


A database role may have a number of attributes that define its privileges and interact with the
client authentication system.
login privilege
Only roles that have the LOGIN attribute can be used as the initial role name for a database
connection. A role with the LOGIN attribute can be considered the same thing as a "database
user". To create a role with login privilege, use either
CREATE ROLE nome LOGIN;

CREATE USER nome;
(CREATE USER is equivalent to CREATE ROLE except that CREATE USER assumes LOGIN by
default, while CREATE ROLE does not.)
superuser status
A database superuser bypasses all permission checks. This is a dangerous privilege and
should not be used carelessly; it is best to do most of your work as a role that is not a
superuser. To create a new database superuser, use CREATE ROLE nome SUPERUSER. You
must do this as a role that is already a superuser.
database creation
A role must be explicitly given permission to create databases (except for superusers, since
those bypass all permission checks). To create such a role, use CREATE ROLE nome
CREATEDB.
role creation
A role must be explicitly given permission to create more roles (except for superusers, since
those bypass all permission checks). To create such a role, use CREATE ROLE nome
CREATEROLE. A role with CREATEROLE privilege can alter and drop other roles, too, as well as
grant or revoke membership in them. However, to create, alter, drop, or change membership
of a superuser role, superuser status is required; CREATEROLE is not sufficient for that.
password
A password is only significant if the client authentication method requires the user to supply a
password when connecting to the database. The password, md5, and crypt authentication
methods make use of passwords. Database passwords are separate from operating system
passwords. Specify a password upon role creation with CREATE ROLE nome PASSWORD
'cadeia_de_caracteres'.
A role's attributes can be modified after creation with ALTER ROLE. See the reference pages for the
CREATE ROLE and ALTER ROLE commands for details.
Dica: It is good practice to create a role that has the CREATEDB and CREATEROLE
privileges, but is not a superuser, and then use this role for all routine management of
databases and roles. This approach avoids the dangers of operating as a superuser for
tasks that do not really require it.
http://pgdocptbr.sourceforge.net/pg82/role-attributes.html[09/02/2018 18:31:10]
Role Attributes
A role can also have role-specific defaults for many of the run-time configuration settings described
in Capítulo 17. For example, if for some reason you want to disable index scans (hint: not a good
idea) anytime you connect, you can use
ALTER ROLE myname SET enable_indexscan TO off;
This will save the setting (but not set it immediately). In subsequent connections by this role it will
appear as though SET enable_indexscan TO off; had been executed just before the session started.
You can still alter this setting during the session; it will only be the default. To remove a role-
specific default setting, use ALTER ROLE nome_do_papel RESET nome_da_variável;. Note that role-
specific defaults attached to roles without LOGIN privilege are fairly useless, since they will never be
invoked.

Database Roles Acima Privileges
http://pgdocptbr.sourceforge.net/pg82/role-attributes.html[09/02/2018 18:31:10]
Privileges

18.3. Privileges
When an object is created, it is assigned an owner. The owner is normally the role that executed
the creation statement. For most kinds of objects, the initial state is that only the owner (or a
superuser) can do anything with the object. To allow other roles to use it, privileges must be
granted. There are several different kinds of privilege: SELECT, INSERT, UPDATE, DELETE,
REFERENCES, TRIGGER, CREATE, CONNECT, TEMPORARY, EXECUTE, and USAGE. For more
information on the different types of privileges supported by PostgreSQL, see the GRANT reference
page.
To assign privileges, the GRANT command is used. So, if joe is an existing role, and accounts is an
existing table, the privilege to update the table can be granted with
GRANT UPDATE ON accounts TO joe;
The special name PUBLIC can be used to grant a privilege to every role on the system. Writing ALL
in place of a specific privilege specifies that all privileges that apply to the object will be granted.
To revoke a privilege, use the fittingly named REVOKE command:
REVOKE ALL ON accounts FROM PUBLIC;
The special privileges of an object's owner (i.e., the right to modify or destroy the object) are
always implicit in being the owner, and cannot be granted or revoked. But the owner can choose to
revoke his own ordinary privileges, for example to make a table read-only for himself as well as
others.
An object can be assigned to a new owner with an ALTER command of the appropriate kind for the
object. Superusers can always do this; ordinary roles can only do it if they are both the current
owner of the object (or a member of the owning role) and a member of the new owning role.

Role Attributes Acima Role Membership
http://pgdocptbr.sourceforge.net/pg82/privileges.html[09/02/2018 18:31:24]
Role Membership


It is frequently convenient to group users together to ease management of privileges: that way,
privileges can be granted to, or revoked from, a group as a whole. In PostgreSQL this is done by
creating a role that represents the group, and then granting membership in the group role to
individual user roles.
To set up a group role, first create the role:

CREATE ROLE nome;
Typically a role being used as a group would not have the LOGIN attribute, though you can set it if
you wish.
Once the group role exists, you can add and remove members using the GRANT and REVOKE
commands:
GRANT group_role TO papel1, ... ;
REVOKE group_role FROM papel1, ... ;
You can grant membership to other group roles, too (since there isn't really any distinction between
group roles and non-group roles). The database will not let you set up circular membership loops.
Also, it is not permitted to grant membership in a role to PUBLIC.
The members of a role can use the privileges of the group role in two ways. First, every member of
a group can explicitly do SET ROLE to temporarily "become" the group role. In this state, the
database session has access to the privileges of the group role rather than the original login role,
and any database objects created are considered owned by the group role not the login role.
Second, member roles that have the INHERIT attribute automatically have use of privileges of roles
they are members of. As an example, suppose we have done
CREATE ROLE joe LOGIN INHERIT;

CREATE ROLE admin NOINHERIT;
CREATE ROLE wheel NOINHERIT;
GRANT admin TO joe;
GRANT wheel TO admin;
Immediately after connecting as role joe, a database session will have use of privileges granted
directly to joe plus any privileges granted to admin, because joe "inherits" admin's privileges.
However, privileges granted to wheel are not available, because even though joe is indirectly a
member of wheel, the membership is via admin which has the NOINHERIT attribute. After
SET ROLE admin;
the session would have use of only those privileges granted to admin, and not those granted to joe.
After
SET ROLE wheel;
the session would have use of only those privileges granted to wheel, and not those granted to
either joe or admin. The original privilege state can be restored with any of
SET ROLE joe;
http://pgdocptbr.sourceforge.net/pg82/role-membership.html[09/02/2018 18:31:32]
Role Membership
SET ROLE NONE;

RESET ROLE;
Nota: The SET ROLE command always allows selecting any role that the original login
role is directly or indirectly a member of. Thus, in the above example, it is not necessary
to become admin before becoming wheel.
Nota: In the SQL standard, there is a clear distinction between users and roles, and
users do not automatically inherit privileges while roles do. This behavior can be
obtained in PostgreSQL by giving roles being used as SQL roles the INHERIT attribute,
while giving roles being used as SQL users the NOINHERIT attribute. However,
PostgreSQL defaults to giving all roles the INHERIT attribute, for backwards compatibility
with pre-8.1 releases in which users always had use of permissions granted to groups
they were members of.
The role attributes LOGIN, SUPERUSER, CREATEDB, and CREATEROLE can be thought of as special
privileges, but they are never inherited as ordinary privileges on database objects are. You must
actually SET ROLE to a specific role having one of these attributes in order to make use of the
attribute. Continuing the above example, we might well choose to grant CREATEDB and
CREATEROLE to the admin role. Then a session connecting as role joe would not have these
privileges immediately, only after doing SET ROLE admin.
To destroy a group role, use DROP ROLE:

DROP ROLE nome;
Any memberships in the group role are automatically revoked (but the member roles are not
otherwise affected). Note however that any objects owned by the group role must first be dropped
or reassigned to other owners; and any permissions granted to the group role must be revoked.

Privileges Acima Functions and Triggers
http://pgdocptbr.sourceforge.net/pg82/role-membership.html[09/02/2018 18:31:32]
Functions and Triggers


Functions and triggers allow users to insert code into the backend server that other users may
execute unintentionally. Hence, both mechanisms permit users to "Trojan horse" others with
relative ease. The only real protection is tight control over who can define functions.
Functions run inside the backend server process with the operating system permissions of the
database server daemon. If the programming language used for the function allows unchecked
memory accesses, it is possible to change the server's internal data structures. Hence, among many
other things, such functions can circumvent any system access controls. Function languages that
allow such access are considered "untrusted", and PostgreSQL allows only superusers to create
functions written in those languages.

Role Membership Acima Managing Databases
http://pgdocptbr.sourceforge.net/pg82/perm-functions.html[09/02/2018 18:31:41]
Managing Databases

Capítulo 19. Managing Databases

Sumário
19.1. Visão geral
19.6. Tablespaces
Every instance of a running PostgreSQL server manages one or more databases. Databases are
therefore the topmost hierarchical level for organizing SQL objects ("database objects"). This
chapter describes the properties of databases, and how to create, manage, and destroy them.

Functions and Triggers Acima Visão geral
http://pgdocptbr.sourceforge.net/pg82/managing-databases.html[09/02/2018 18:31:55]
Visão geral

Anterior Início Capítulo 19. Managing Databases Fim Próxima
19.1. Visão geral

A database is a named collection of SQL objects ("database objects"). Generally, every database
object (tables, functions, etc.) belongs to one and only one database. (But there are a few system
catalogs, for example pg_database, that belong to a whole cluster and are accessible from each
database within the cluster.) More accurately, a database is a collection of schemas and the
schemas contain the tables, functions, etc. So the full hierarchy is: server, database, schema, table
(or some other kind of object, such as a function).
When connecting to the database server, a client must specify in its connection request the name of
the database it wants to connect to. It is not possible to access more than one database per
connection. (But an application is not restricted in the number of connections it opens to the same
or other databases.) Databases are physically separated and access control is managed at the
connection level. If one PostgreSQL server instance is to house projects or users that should be
separate and for the most part unaware of each other, it is therefore recommendable to put them
into separate databases. If the projects or users are interrelated and should be able to use each
other's resources they should be put in the same database, but possibly into separate schemas.
Schemas are a purely logical structure and who can access what is managed by the privilege
system. More information about managing schemas is in Seção 5.7.
Databases are created with the CREATE DATABASE command (see Seção 19.2) and destroyed with
the DROP DATABASE command (see Seção 19.5). To determine the set of existing databases,
examine the pg_database system catalog, for example
SELECT datname FROM pg_database;
The psql program's \l meta-command and -l command-line option are also useful for listing the
existing databases.
Nota: The SQL standard calls databases "catalogs", but there is no difference in
practice.

Managing Databases Acima Creating a Database
http://pgdocptbr.sourceforge.net/pg82/manage-ag-overview.html[09/02/2018 18:32:16]
Creating a Database


In order to create a database, the PostgreSQL server must be up and running (see Seção 16.3).
Databases are created with the SQL command CREATE DATABASE:

CREATE DATABASE nome;
where nome follows the usual rules for SQL identifiers. The current role automatically becomes the
owner of the new database. It is the privilege of the owner of a database to remove it later on
(which also removes all the objects in it, even if they have a different owner).
The creation of databases is a restricted operation. See Seção 18.2 for how to grant permission.
Since you need to be connected to the database server in order to execute the CREATE DATABASE
command, the question remains how the first database at any given site can be created. The first
database is always created by the initdb command when the data storage area is initialized. (See
Seção 16.2.) This database is called postgres. So to create the first "ordinary" database you can
connect to postgres.
A second database, template1, is also created by initdb. Whenever a new database is created within
the cluster, template1 is essentially cloned. This means that any changes you make in template1
are propagated to all subsequently created databases. Therefore it is unwise to use template1 for
real work, but when used judiciously this feature can be convenient. More details appear in Seção
19.3.
As a convenience, there is a program that you can execute from the shell to create new databases,
createdb.
createdb nome_do_banco_de_dados
createdb does no magic. It connects to the postgres database and issues the CREATE DATABASE
command, exactly as described above. The createdb reference page contains the invocation details.
Note that createdb without any arguments will create a database with the current user name, which
may or may not be what you want.
Nota: Capítulo 20 contains information about how to restrict who can connect to a given
database.
Sometimes you want to create a database for someone else. That role should become the owner of
the new database, so he can configure and manage it himself. To achieve that, use one of the
following commands:
CREATE DATABASE nome_do_banco_de_dados OWNER nome_do_papel;
from the SQL environment, or
createdb -O nome_do_papel nome_do_banco_de_dados
from the shell. You must be a superuser to be allowed to create a database for someone else (that
is, for a role you are not a member of).
http://pgdocptbr.sourceforge.net/pg82/manage-ag-createdb.html[09/02/2018 18:32:31]
Creating a Database

Visão geral Acima Template Databases
http://pgdocptbr.sourceforge.net/pg82/manage-ag-createdb.html[09/02/2018 18:32:31]
Template Databases


CREATE DATABASE actually works by copying an existing database. By default, it copies the
standard system database named template1. Thus that database is the "template" from which new
databases are made. If you add objects to template1, these objects will be copied into subsequently
created user databases. This behavior allows site-local modifications to the standard set of objects
in databases. For example, if you install the procedural language PL/pgSQL in template1, it will
automatically be available in user databases without any extra action being taken when those
databases are made.
There is a second standard system database named template0. This database contains the same
data as the initial contents of template1, that is, only the standard objects predefined by your
version of PostgreSQL. template0 should never be changed after initdb. By instructing CREATE
DATABASE to copy template0 instead of template1, you can create a "virgin" user database that
contains none of the site-local additions in template1. This is particularly handy when restoring a
pg_dump dump: the dump script should be restored in a virgin database to ensure that one
recreates the correct contents of the dumped database, without any conflicts with additions that
may now be present in template1.
To create a database by copying template0, use
CREATE DATABASE nome_do_banco_de_dados TEMPLATE template0;
from the SQL environment, or
createdb -T template0 nome_do_banco_de_dados
from the shell.
It is possible to create additional template databases, and indeed one may copy any database in a
cluster by specifying its name as the template for CREATE DATABASE. It is important to
understand, however, that this is not (yet) intended as a general-purpose "COPY DATABASE"
facility. The principal limitation is that no other sessions can be connected to the source database
while it is being copied. CREATE DATABASE will fail if any other connection exists when it starts;
otherwise, new connections to the source database are locked out until CREATE DATABASE
completes.
Two useful flags exist in pg_database for each database: the columns datistemplate and
datallowconn. datistemplate may be set to indicate that a database is intended as a template for
CREATE DATABASE. If this flag is set, the database may be cloned by any user with CREATEDB
privileges; if it is not set, only superusers and the owner of the database may clone it. If
datallowconn is false, then no new connections to that database will be allowed (but existing
sessions are not killed simply by setting the flag false). The template0 database is normally marked
datallowconn = false to prevent modification of it. Both template0 and template1 should always be
marked with datistemplate = true.
Nota: template1 and template0 do not have any special status beyond the fact that the
name template1 is the default source database name for CREATE DATABASE. For
example, one could drop template1 and recreate it from template0 without any ill
effects. This course of action might be advisable if one has carelessly added a bunch of
junk in template1.
http://pgdocptbr.sourceforge.net/pg82/manage-ag-templatedbs.html[09/02/2018 18:32:41]
Template Databases
The postgres database is also created when a database cluster is initialized. This
database is meant as a default database for users and applications to connect to. It is
simply a copy of template1 and may be dropped and recreated if required.

Creating a Database Acima Database Configuration
http://pgdocptbr.sourceforge.net/pg82/manage-ag-templatedbs.html[09/02/2018 18:32:41]
Database Configuration


Recall from Capítulo 17 that the PostgreSQL server provides a large number of run-time
configuration variables. You can set database-specific default values for many of these settings.
For example, if for some reason you want to disable the GEQO optimizer for a given database,
you'd ordinarily have to either disable it for all databases or make sure that every connecting client
is careful to issue SET geqo TO off;. To make this setting the default within a particular database,
you can execute the command
ALTER DATABASE mydb SET geqo TO off;
This will save the setting (but not set it immediately). In subsequent connections to this database it
will appear as though SET geqo TO off; had been executed just before the session started. Note
that users can still alter this setting during their sessions; it will only be the default. To undo any
such setting, use ALTER DATABASE nome_do_banco_de_dados RESET nome_da_variável;.

Template Databases Acima Destroying a Database
http://pgdocptbr.sourceforge.net/pg82/manage-ag-config.html[09/02/2018 18:32:49]
Destroying a Database


Databases are destroyed with the command DROP DATABASE:
DROP DATABASE nome;
Only the owner of the database, or a superuser, can drop a database. Dropping a database removes
all objects that were contained within the database. The destruction of a database cannot be
undone.
You cannot execute the DROP DATABASE command while connected to the victim database. You
can, however, be connected to any other database, including the template1 database. template1
would be the only option for dropping the last user database of a given cluster.
For convenience, there is also a shell program to drop databases, dropdb:

dropdb nome_do_banco_de_dados
(Unlike createdb, it is not the default action to drop the database with the current user name.)

Database Configuration Acima Tablespaces
http://pgdocptbr.sourceforge.net/pg82/manage-ag-dropdb.html[09/02/2018 18:33:01]
Tablespaces

19.6. Tablespaces
Tablespaces in PostgreSQL allow database administrators to define locations in the file system
where the files representing database objects can be stored. Once created, a tablespace can be
referred to by name when creating database objects.
By using tablespaces, an administrator can control the disk layout of a PostgreSQL installation. This
is useful in at least two ways. First, if the partition or volume on which the cluster was initialized
runs out of space and cannot be extended, a tablespace can be created on a different partition and
used until the system can be reconfigured.
Second, tablespaces allow an administrator to use knowledge of the usage pattern of database
objects to optimize performance. For example, an index which is very heavily used can be placed on
a very fast, highly available disk, such as an expensive solid state device. At the same time a table
storing archived data which is rarely used or not performance critical could be stored on a less
expensive, slower disk system.
To define a tablespace, use the CREATE TABLESPACE command, for example:
CREATE TABLESPACE fastspace LOCATION '/mnt/sda1/postgresql/data';
The location must be an existing, empty directory that is owned by the PostgreSQL system user. All
objects subsequently created within the tablespace will be stored in files underneath this directory.
Nota: There is usually not much point in making more than one tablespace per logical
file system, since you cannot control the location of individual files within a logical file
system. However, PostgreSQL does not enforce any such limitation, and indeed it is not
directly aware of the file system boundaries on your system. It just stores files in the
directories you tell it to use.
Creation of the tablespace itself must be done as a database superuser, but after that you can allow
ordinary database users to make use of it. To do that, grant them the CREATE privilege on it.
Tables, indexes, and entire databases can be assigned to particular tablespaces. To do so, a user
with the CREATE privilege on a given tablespace must pass the tablespace name as a parameter to
the relevant command. For example, the following creates a table in the tablespace space1:
CREATE TABLE foo(i int) TABLESPACE space1;
Alternatively, use the default_tablespace parameter:
SET default_tablespace = space1;

CREATE TABLE foo(i int);
When default_tablespace is set to anything but an empty string, it supplies an implicit TABLESPACE
clause for CREATE TABLE and CREATE INDEX commands that do not have an explicit one.
The tablespace associated with a database is used to store the system catalogs of that database, as
well as any temporary files created by server processes using that database. Furthermore, it is the
default tablespace selected for tables and indexes created within the database, if no TABLESPACE
clause is given (either explicitly or via default_tablespace) when the objects are created. If a
http://pgdocptbr.sourceforge.net/pg82/manage-ag-tablespaces.html[09/02/2018 18:33:10]
Tablespaces
database is created without specifying a tablespace for it, it uses the same tablespace as the
template database it is copied from.
Two tablespaces are automatically created by initdb. The pg_global tablespace is used for shared
system catalogs. The pg_default tablespace is the default tablespace of the template1 and
template0 databases (and, therefore, will be the default tablespace for other databases as well,
unless overridden by a TABLESPACE clause in CREATE DATABASE).
Once created, a tablespace can be used from any database, provided the requesting user has
sufficient privilege. This means that a tablespace cannot be dropped until all objects in all databases
using the tablespace have been removed.
To remove an empty tablespace, use the DROP TABLESPACE command.
To determine the set of existing tablespaces, examine the pg_tablespace system catalog, for
example
SELECT spcname FROM pg_tablespace;
The psql program's \db meta-command is also useful for listing the existing tablespaces.
PostgreSQL makes extensive use of symbolic links to simplify the implementation of tablespaces.
This means that tablespaces can be used only on systems that support symbolic links.
The directory $PGDATA/pg_tblspc contains symbolic links that point to each of the non-built-in
tablespaces defined in the cluster. Although not recommended, it is possible to adjust the
tablespace layout by hand by redefining these links. Two warnings: do not do so while the server is
running; and after you restart the server, update the pg_tablespace catalog to show the new
locations. (If you do not, pg_dump will continue to show the old tablespace locations.)

Destroying a Database Acima Client Authentication
http://pgdocptbr.sourceforge.net/pg82/manage-ag-tablespaces.html[09/02/2018 18:33:10]
Client Authentication

Capítulo 20. Client Authentication

Sumário
20.2.1. Trust authentication

20.2.2. Password authentication
20.2.3. Kerberos authentication
20.2.4. Ident-based authentication
20.2.5. LDAP authentication
20.2.6. PAM authentication
When a client application connects to the database server, it specifies which PostgreSQL database
user name it wants to connect as, much the same way one logs into a Unix computer as a particular
user. Within the SQL environment the active database user name determines access privileges to
database objects — see Capítulo 18 for more information. Therefore, it is essential to restrict which
database users can connect.
Nota: As explained in Capítulo 18, PostgreSQL actually does privilege management in

terms of "roles". In this chapter, we consistently use database user to mean "role with
the LOGIN privilege".
Authentication is the process by which the database server establishes the identity of the client, and
by extension determines whether the client application (or the user who runs the client application)
is permitted to connect with the database user name that was requested.
PostgreSQL offers a number of different client authentication methods. The method used to
authenticate a particular client connection can be selected on the basis of (client) host address,
database, and user.
PostgreSQL database user names are logically separate from user names of the operating system in
which the server runs. If all the users of a particular server also have accounts on the server's
machine, it makes sense to assign database user names that match their operating system user
names. However, a server that accepts remote connections may have many database users who
have no local operating system account, and in such cases there need be no connection between
database user names and OS user names.

Tablespaces Acima The pg_hba.conf file
http://pgdocptbr.sourceforge.net/pg82/client-authentication.html[09/02/2018 18:33:28]
The pg_hba.conf file

Anterior Início Capítulo 20. Client Authentication Fim Próxima

Client authentication is controlled by a configuration file, which traditionally is named pg_hba.conf
and is stored in the database cluster's data directory. (HBA stands for host-based authentication.) A
default pg_hba.conf file is installed when the data directory is initialized by initdb. It is possible to
place the authentication configuration file elsewhere, however; see the hba_file configuration
parameter.
The general format of the pg_hba.conf file is a set of records, one per line. Blank lines are ignored,
as is any text after the # comment character. A record is made up of a number of fields which are
separated by spaces and/or tabs. Fields can contain white space if the field value is quoted. Records
cannot be continued across lines.
Each record specifies a connection type, a client IP address range (if relevant for the connection
type), a database name, a user name, and the authentication method to be used for connections
matching these parameters. The first record with a matching connection type, client address,
requested database, and user name is used to perform authentication. There is no "fall-through" or
"backup": if one record is chosen and the authentication fails, subsequent records are not
considered. If no record matches, access is denied.
A record may have one of the seven formats

local banco_de_dados usuário método_de_autenticação [opção_de_autenticação]
host banco_de_dados usuário endereço_CIDR método_de_autenticação
[opção_de_autenticação]
hostssl banco_de_dados usuário endereço_CIDR método_de_autenticação
hostnossl banco_de_dados usuário endereço_CIDR método_de_autenticação
host banco_de_dados usuário endereço_IP máscara_IP método_de_autenticação
hostssl banco_de_dados usuário endereço_IP máscara_IP método_de_autenticação
hostnossl banco_de_dados usuário endereço_IP máscara_IP método_de_autenticação
The meaning of the fields is as follows:
local
This record matches connection attempts using Unix-domain sockets. Without a record of this
type, Unix-domain socket connections are disallowed.
host
This record matches connection attempts made using TCP/IP. host records match either SSL
or non-SSL connection attempts.
Nota: Remote TCP/IP connections will not be possible unless the server is started
with an appropriate value for the listen_addresses configuration parameter, since
the default behavior is to listen for TCP/IP connections only on the local loopback
address localhost.
hostssl
This record matches connection attempts made using TCP/IP, but only when the connection is
made with SSL encryption.
To make use of this option the server must be built with SSL support. Furthermore, SSL must
http://pgdocptbr.sourceforge.net/pg82/auth-pg-hba-conf.html[09/02/2018 18:34:08]
be enabled at server start time by setting the ssl configuration parameter (see Seção 16.7 for
more information).
hostnossl
This record type has the opposite logic to hostssl: it only matches connection attempts made
over TCP/IP that do not use SSL.
banco_de_dados
Specifies which database names this record matches. The value all specifies that it matches all
databases. The value sameuser specifies that the record matches if the requested database
has the same name as the requested user. The value samerole specifies that the requested
user must be a member of the role with the same name as the requested database.
(samegroup is an obsolete but still accepted spelling of samerole.) Otherwise, this is the name
of a specific PostgreSQL database. Multiple database names can be supplied by separating
them with commas. A separate file containing database names can be specified by preceding
the file name with @.
usuário
Specifies which database user names this record matches. The value all specifies that it
matches all users. Otherwise, this is either the name of a specific database user, or a group
name preceded by +. (Recall that there is no real distinction between users and groups in
PostgreSQL; a + mark really means "match any of the roles that are directly or indirectly
members of this role", while a name without a + mark matches only that specific role.)
Multiple user names can be supplied by separating them with commas. A separate file
containing user names can be specified by preceding the file name with @.
endereço_CIDR
Specifies the client machine IP address range that this record matches. It contains an IP
address in standard dotted decimal notation and a CIDR mask length. (IP addresses can only
be specified numerically, not as domain or host names.) The mask length indicates the
number of high-order bits of the client IP address that must match. Bits to the right of this
must be zero in the given IP address. There must not be any white space between the IP
address, the /, and the CIDR mask length.
Typical examples of a endereço_CIDR are 172.20.143.89/32 for a single host, or

172.20.143.0/24 for a small network, or 10.6.0.0/16 for a larger one. To specify a single host,
use a CIDR mask of 32 for IPv4 or 128 for IPv6. In a network address, do not omit trailing
zeroes.
An IP address given in IPv4 format will match IPv6 connections that have the corresponding
address, for example 127.0.0.1 will match the IPv6 address ::ffff:127.0.0.1. An entry given in
IPv6 format will match only IPv6 connections, even if the represented address is in the IPv4-
in-IPv6 range. Note that entries in IPv6 format will be rejected if the system's C library does
not have support for IPv6 addresses.
This field only applies to host, hostssl, and hostnossl records.
endereço_IP
máscara_IP
These fields may be used as an alternative to the endereço_CIDR notation. Instead of

specifying the mask length, the actual mask is specified in a separate column. For example,
255.0.0.0 represents an IPv4 CIDR mask length of 8, and 255.255.255.255 represents a CIDR
mask length of 32.
These fields only apply to host, hostssl, and hostnossl records.
método_de_autenticação
Specifies the authentication method to use when connecting via this record. The possible
choices are summarized here; details are in Seção 20.2.
trust
Allow the connection unconditionally. This method allows anyone that can connect to the
PostgreSQL database server to login as any PostgreSQL user they like, without the need
for a password. See Seção 20.2.1 for details.
reject
Reject the connection unconditionally. This is useful for "filtering out" certain hosts from
a group.
md5
Require the client to supply an MD5-encrypted password for authentication. Para obter
mais informações consulte a Seção 20.2.2.
crypt
Nota: This option is recommended only for communicating with pre-7.2

clients.
Require the client to supply a crypt()-encrypted password for authentication. md5 is now
recommended over crypt. Para obter mais informações consulte a Seção 20.2.2.
password
Require the client to supply an unencrypted password for authentication. Since the
password is sent in clear text over the network, this should not be used on untrusted
networks. It also does not usually work with threaded client applications. Para obter
mais informações consulte a Seção 20.2.2.
krb5
Use Kerberos V5 to authenticate the user. This is only available for TCP/IP connections.
See Seção 20.2.3 for details.
ident
Obtain the operating system user name of the client (for TCP/IP connections by
contacting the ident server on the client, for local connections by getting it from the
operating system) and check if the user is allowed to connect as the requested database
user by consulting the map specified after the ident key word. Para obter mais
informações consulte a Seção 20.2.4.
ldap
Authenticate using LDAP to a central server. See Seção 20.2.5 for details.
pam
Authenticate using the Pluggable Authentication Modules (PAM) service provided by the
operating system. See Seção 20.2.6 for details.
opção_de_autenticação
The meaning of this optional field depends on the chosen authentication method. Details
appear below.
Files included by @ constructs are read as lists of names, which can be separated by either
whitespace or commas. Comments are introduced by #, just as in pg_hba.conf, and nested @
constructs are allowed. Unless the file name following @ is an absolute path, it is taken to be
relative to the directory containing the referencing file.
Since the pg_hba.conf records are examined sequentially for each connection attempt, the order of
the records is significant. Typically, earlier records will have tight connection match parameters and
weaker authentication methods, while later records will have looser match parameters and stronger
authentication methods. For example, one might wish to use trust authentication for local TCP/IP
connections but require a password for remote TCP/IP connections. In this case a record specifying
trust authentication for connections from 127.0.0.1 would appear before a record specifying
password authentication for a wider range of allowed client IP addresses.
The pg_hba.conf file is read on start-up and when the main server process receives a SIGHUP
signal. If you edit the file on an active system, you will need to signal the server (using pg_ctl
reload or kill -HUP) to make it re-read the file.
Dica: To connect to a particular database, a user must not only pass the pg_hba.conf
checks, but must have the CONNECT privilege for the database. If you wish to restrict
which users can connect to which databases, it's usually easier to control this by
granting/revoking CONNECT privilege than to put the rules into pg_hba.conf entries.
Some examples of pg_hba.conf entries are shown in Exemplo 20-1. See the next section for details
on the different authentication methods.
Exemplo 20-1. Example pg_hba.conf entries
# Allow any user on the local system to connect to any database under
# any database user name using Unix-domain sockets (the default for local
# connections).
#
# TYPE DATABASE USER CIDR-ADDRESS METHOD
local all all trust
# The same using local loopback TCP/IP connections.
#
host all all 127.0.0.1/32 trust
# The same as the last line but using a separate netmask column
#
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
host all all 127.0.0.1 255.255.255.255 trust
# Allow any user from any host with IP address 192.168.93.x to connect
# to database "postgres" as the same user name that ident reports for
# the connection (typically the Unix user name).
#
host postgres all 192.168.93.0/24 ident sameuser
# Allow a user from host 192.168.12.10 to connect to database
# "postgres" if the user's password is correctly supplied.
#
host postgres all 192.168.12.10/32 md5
# In the absence of preceding "host" lines, these two lines will
# reject all connection from 192.168.54.1 (since that entry will be
# matched first), but allow Kerberos 5 connections from anywhere else
# on the Internet. The zero mask means that no bits of the host IP
# address are considered so it matches any host.
#
host all all 192.168.54.1/32 reject
host all all 0.0.0.0/0 krb5
# Allow users from 192.168.x.x hosts to connect to any database, if
# they pass the ident check. If, for example, ident says the user is
# "bryanh" and he requests to connect as PostgreSQL user "guest1", the
# connection is allowed if there is an entry in pg_ident.conf for map
# "omicron" that says "bryanh" is allowed to connect as "guest1".
#
host all all 192.168.0.0/16 ident omicron
# If these are the only three lines for local connections, they will
# allow local users to connect only to their own databases (databases
# with the same name as their database user name) except for administrators
# and members of role "support", who may connect to all databases. The file
# $PGDATA/admins contains a list of names of administrators. Passwords
# are required in all cases.
#
local sameuser all md5
local all @admins md5
local all +support md5
# The last two lines above can be combined into a single line:
local all @admins,+support md5
# The database column can also use lists and file names:
local db1,db2,@demodbs all md5

Client Authentication Acima Authentication methods
Authentication methods


The following subsections describe the authentication methods in more detail.
20.2.1. Trust authentication
When trust authentication is specified, PostgreSQL assumes that anyone who can connect to the
server is authorized to access the database with whatever database user name they specify
(including superusers). Of course, restrictions made in the database and user columns still apply.
This method should only be used when there is adequate operating-system-level protection on
connections to the server.
trust authentication is appropriate and very convenient for local connections on a single-user
workstation. It is usually not appropriate by itself on a multiuser machine. However, you may be
able to use trust even on a multiuser machine, if you restrict access to the server's Unix-domain
socket file using file-system permissions. To do this, set the unix_socket_permissions (and possibly
unix_socket_group) configuration parameters as described in Seção 17.3. Or you could set the
unix_socket_directory configuration parameter to place the socket file in a suitably restricted
directory.
Setting file-system permissions only helps for Unix-socket connections. Local TCP/IP connections
are not restricted by it; therefore, if you want to use file-system permissions for local security,
remove the host ... 127.0.0.1 ... line from pg_hba.conf, or change it to a non-trust authentication
method.
trust authentication is only suitable for TCP/IP connections if you trust every user on every machine
that is allowed to connect to the server by the pg_hba.conf lines that specify trust. It is seldom
reasonable to use trust for any TCP/IP connections other than those from localhost (127.0.0.1).
20.2.2. Password authentication
The password-based authentication methods are md5, crypt, and password. These methods operate
similarly except for the way that the password is sent across the connection: respectively, MD5-
hashed, crypt-encrypted, and clear-text. A limitation is that the crypt method does not work with
passwords that have been encrypted in pg_authid.
If you are at all concerned about password "sniffing" attacks then md5 is preferred, with crypt to be
used only if you must support pre-7.2 clients. Plain password should be avoided especially for
connections over the open Internet (unless you use SSL, SSH, or another communications security
wrapper around the connection).
PostgreSQL database passwords are separate from operating system user passwords. The password
for each database user is stored in the pg_authid system catalog. Passwords can be managed with
the SQL commands CREATE USER and ALTER USER, e.g., CREATE USER foo WITH PASSWORD 'secret';. By
default, that is, if no password has been set up, the stored password is null and password
authentication will always fail for that user.
20.2.3. Kerberos authentication
Kerberos is an industry-standard secure authentication system suitable for distributed computing
http://pgdocptbr.sourceforge.net/pg82/auth-methods.html[09/02/2018 18:34:16]
over a public network. A description of the Kerberos system is far beyond the scope of this
document; in full generality it can be quite complex (yet powerful). The Kerberos FAQ or MIT
Kerberos page can be good starting points for exploration. Several sources for Kerberos distributions
exist. Kerberos provides secure authentication but does not encrypt queries or data passed over the
network; for that use SSL.
PostgreSQL supports Kerberos version 5. Kerberos support has to be enabled when PostgreSQL is
built; see Capítulo 14 for more information.
PostgreSQL operates like a normal Kerberos service. The name of the service principal is
nome_do_serviço/nome_do_hospedeiro@domínio.
nome_do_serviço can be set on the server side using the krb_srvname configuration parameter, and
on the client side using the krbsrvname connection parameter. (See also Seção 29.1.) The
installation default can be changed from the default postgres at build time using ./configure --with-
krb-srvnam=whatever. In most environments, this parameter never needs to be changed.
However, to support multiple PostgreSQL installations on the same host it is necessary. Some
Kerberos implementations may also require a different service name, such as Microsoft Active
Directory which requires the service name to be in uppercase (POSTGRES).
nome_do_hospedeiro is the fully qualified host name of the server machine. The service principal's
realm is the preferred realm of the server machine.
Client principals must have their PostgreSQL database user name as their first component, for
example pgusername/otherstuff@realm. At present the realm of the client is not checked by
PostgreSQL; so if you have cross-realm authentication enabled, then any principal in any realm that
can communicate with yours will be accepted.
Make sure that your server keytab file is readable (and preferably only readable) by the PostgreSQL
server account. (See also Seção 16.1.) The location of the key file is specified by the
krb_server_keyfile configuration parameter. The default is /usr/local/pgsql/etc/krb5.keytab (or
whichever directory was specified as sysconfdir at build time).
The keytab file is generated by the Kerberos software; see the Kerberos documentation for details.
The following example is for MIT-compatible Kerberos 5 implementations:
kadmin% ank -randkey postgres/server.my.domain.org

kadmin% ktadd -k krb5.keytab postgres/server.my.domain.org
When connecting to the database make sure you have a ticket for a principal matching the
requested database user name. For example, for database user name fred, both principal
fred@EXAMPLE.COM and fred/users.example.com@EXAMPLE.COM could be used to authenticate to
the database server.
If you use mod_auth_kerb and mod_perl on your Apache web server, you can use AuthType
KerberosV5SaveCredentials with a mod_perl script. This gives secure database access over the
web, no extra passwords required.
20.2.4. Ident-based authentication
The ident authentication method works by obtaining the client's operating system user name, then
determining the allowed database user names using a map file that lists the permitted
corresponding pairs of names. The determination of the client's user name is the security-critical
point, and it works differently depending on the connection type.
20.2.4.1. Ident Authentication over TCP/IP
The "Identification Protocol" is described in RFC 1413. Virtually every Unix-like operating system
ships with an ident server that listens on TCP port 113 by default. The basic functionality of an ident
server is to answer questions like "What user initiated the connection that goes out of your port X
and connects to my port Y?". Since PostgreSQL knows both X and Y when a physical connection is
established, it can interrogate the ident server on the host of the connecting client and could
theoretically determine the operating system user for any given connection this way.
The drawback of this procedure is that it depends on the integrity of the client: if the client machine
is untrusted or compromised an attacker could run just about any program on port 113 and return
any user name he chooses. This authentication method is therefore only appropriate for closed
networks where each client machine is under tight control and where the database and system
administrators operate in close contact. In other words, you must trust the machine running the
ident server. Heed the warning:

The Identification Protocol is not intended as an authorization or access control
protocol.
--RFC 1413
Some ident servers have a nonstandard option that causes the returned user name to be
encrypted, using a key that only the originating machine's administrator knows. This option must
not be used when using the ident server with PostgreSQL, since PostgreSQL does not have any way
to decrypt the returned string to determine the actual user name.
20.2.4.2. Ident Authentication over Local Sockets
On systems supporting SO_PEERCRED requests for Unix-domain sockets (currently Linux, FreeBSD,
NetBSD, OpenBSD, and BSD/OS), ident authentication can also be applied to local connections. In
this case, no security risk is added by using ident authentication; indeed it is a preferable choice for
local connections on such systems.
On systems without SO_PEERCRED requests, ident authentication is only available for TCP/IP
connections. As a work-around, it is possible to specify the localhost address 127.0.0.1 and make
connections to this address. This method is trustworthy to the extent that you trust the local ident
server.
20.2.4.3. Ident Maps
When using ident-based authentication, after having determined the name of the operating system
user that initiated the connection, PostgreSQL checks whether that user is allowed to connect as the
database user he is requesting to connect as. This is controlled by the ident map argument that
follows the ident key word in the pg_hba.conf file. There is a predefined ident map sameuser, which
allows any operating system user to connect as the database user of the same name (if the latter
exists). Other maps must be created manually.
Ident maps other than sameuser are defined in the ident map file, which by default is named
pg_ident.conf and is stored in the cluster's data directory. (It is possible to place the map file
elsewhere, however; see the ident_file configuration parameter.) The ident map file contains lines of
the general form:
nome_do_mapa ident-username nome_do_usuário_do_banco_de_dados
Comments and whitespace are handled in the same way as in pg_hba.conf. The nome_do_mapa is
an arbitrary name that will be used to refer to this mapping in pg_hba.conf. The other two fields
specify which operating system user is allowed to connect as which database user. The same
nome_do_mapa can be used repeatedly to specify more user-mappings within a single map. There
is no restriction regarding how many database users a given operating system user may correspond
to, nor vice versa.
The pg_ident.conf file is read on start-up and when the main server process receives a SIGHUP
signal. If you edit the file on an active system, you will need to signal the server (using pg_ctl
reload or kill -HUP) to make it re-read the file.
A pg_ident.conf file that could be used in conjunction with the pg_hba.conf file in Exemplo 20-1 is
shown in Exemplo 20-2. In this example setup, anyone logged in to a machine on the 192.168
network that does not have the Unix user name bryanh, ann, or robert would not be granted
access. Unix user robert would only be allowed access when he tries to connect as PostgreSQL user
bob, not as robert or anyone else. ann would only be allowed to connect as ann. User bryanh would
be allowed to connect as either bryanh himself or as guest1.
Exemplo 20-2. An example pg_ident.conf file
# MAPNAME IDENT-USERNAME PG-USERNAME

omicron bryanh bryanh
omicron ann ann
# bob has user name robert on these machines
omicron robert bob
# bryanh can also connect as guest1
omicron bryanh guest1
20.2.5. LDAP authentication
This authentication method operates similarly to password except that it uses LDAP as the
authentication method. LDAP is used only to validate the user name/password pairs. Therefore the
user must already exist in the database before LDAP can be used for authentication. The server and
parameters used are specified after the ldap key word in the file pg_hba.conf. The format of this
parameter is:
ldap[s]://servername[:porta]/base dn[;prefixo[;sufixo]]
for example:
ldap://ldap.example.net/dc=example,dc=net;EXAMPLE\
If ldaps is specified instead of ldap, TLS encryption will be enabled for the connection. Note that this
will encrypt only the connection between the PostgreSQL server and the LDAP server. The
connection between the client and the PostgreSQL server is not affected by this setting. To make
use of TLS encryption, you may need to configure the LDAP library prior to configuring PostgreSQL.
Note that encrypted LDAP is available only if the platform's LDAP library supports it.
If no port is specified, the default port as configured in the LDAP library will be used.
The server will bind to the distinguished name specified as base dn using the user name supplied by
the client. If prefixo and sufixo is specified, it will be prepended and appended to the user name
before the bind. Typically, the prefix parameter is used to specify cn=, or DOMAIN\ in an Active
Directory environment.
20.2.6. PAM authentication
This authentication method operates similarly to password except that it uses PAM (Pluggable
Authentication Modules) as the authentication mechanism. The default PAM service name is
postgresql. You can optionally supply your own service name after the pam key word in the file
pg_hba.conf. PAM is used only to validate user name/password pairs. Therefore the user must
already exist in the database before PAM can be used for authentication. For more information
about PAM, please read the Linux-PAM Page and the Solaris PAM Page.

The pg_hba.conf file Acima Authentication problems
Authentication problems


Genuine authentication failures and related problems generally manifest themselves through error
messages like the following.
FATAL: no pg_hba.conf entry for host "123.123.123.123", user "andym", database "testdb"
This is what you are most likely to get if you succeed in contacting the server, but it does not want
to talk to you. As the message suggests, the server refused the connection request because it found
no matching entry in its pg_hba.conf configuration file.
FATAL: Password authentication failed for user "andym"
Messages like this indicate that you contacted the server, and it is willing to talk to you, but not
until you pass the authorization method specified in the pg_hba.conf file. Check the password you
are providing, or check your Kerberos or ident software if the complaint mentions one of those
authentication types.
FATAL: user "andym" does not exist
The indicated user name was not found.
FATAL: database "testdb" does not exist
The database you are trying to connect to does not exist. Note that if you do not specify a database
name, it defaults to the database user name, which may or may not be the right thing.
Dica: The server log may contain more information about an authentication failure than
is reported to the client. If you are confused about the reason for a failure, check the
log.

Authentication methods Acima Localization
http://pgdocptbr.sourceforge.net/pg82/client-authentication-problems.html[09/02/2018 18:34:25]
Localization

Capítulo 21. Localization

Sumário
21.1.1. Visão geral

21.1.2. Behavior
21.1.3. Problems
21.2.1. Supported Character Sets

21.2.2. Setting the Character Set
21.2.3. Automatic Character Set Conversion Between Server and Client
21.2.4. Leitura adicional
This chapter describes the available localization features from the point of view of the administrator.
PostgreSQL supports localization with two approaches:
Using the locale features of the operating system to provide locale-specific collation order,
number formatting, translated messages, and other aspects.
Providing a number of different character sets defined in the PostgreSQL server, including
multiple-byte character sets, to support storing text in all kinds of languages, and providing
character set translation between client and server.

Authentication problems Acima Locale Support
http://pgdocptbr.sourceforge.net/pg82/charset.html[09/02/2018 18:34:39]
Locale Support

Anterior Início Capítulo 21. Localization Fim Próxima

Locale support refers to an application respecting cultural preferences regarding alphabets, sorting,
number formatting, etc. PostgreSQL uses the standard ISO C and POSIX locale facilities provided by
the server operating system. For additional information refer to the documentation of your system.
21.1.1. Visão geral
Locale support is automatically initialized when a database cluster is created using initdb. initdb will
initialize the database cluster with the locale setting of its execution environment by default, so if
your system is already set to use the locale that you want in your database cluster then there is
nothing else you need to do. If you want to use a different locale (or you are not sure which locale
your system is set to), you can instruct initdb exactly which locale to use by specifying the --locale
option. For example:
initdb --locale=sv_SE
This example sets the locale to Swedish (sv) as spoken in Sweden (SE). Other possibilities might be
en_US (U.S. English) and fr_CA (French Canadian). If more than one character set can be useful for
a locale then the specifications look like this: cs_CZ.ISO8859-2. What locales are available under
what names on your system depends on what was provided by the operating system vendor and
what was installed. (On most systems, the command locale -a will provide a list of available
locales.)
Occasionally it is useful to mix rules from several locales, e.g., use English collation rules but
Spanish messages. To support that, a set of locale subcategories exist that control only a certain
aspect of the localization rules:
LC_COLLATE String sort order

LC_CTYPE Character classification (What is a letter? Its upper-case equivalent?)
LC_MESSAGES Language of messages
LC_MONETARY Formatting of currency amounts
LC_NUMERIC Formatting of numbers
LC_TIME Formatting of dates and times
The category names translate into names of initdb options to override the locale choice for a
specific category. For instance, to set the locale to French Canadian, but use U.S. rules for
formatting currency, use initdb --locale=fr_CA --lc-monetary=en_US.
If you want the system to behave as if it had no locale support, use the special locale C or POSIX.
The nature of some locale categories is that their value has to be fixed for the lifetime of a database
cluster. That is, once initdb has run, you cannot change them anymore. LC_COLLATE and LC_CTYPE
are those categories. They affect the sort order of indexes, so they must be kept fixed, or indexes
on text columns will become corrupt. PostgreSQL enforces this by recording the values of
LC_COLLATE and LC_CTYPE that are seen by initdb. The server automatically adopts those two
values when it is started.
The other locale categories can be changed as desired whenever the server is running by setting
http://pgdocptbr.sourceforge.net/pg82/locale.html[09/02/2018 18:34:48]
Locale Support
the run-time configuration variables that have the same name as the locale categories (see Seção
17.10.2 for details). The defaults that are chosen by initdb are actually only written into the
configuration file postgresql.conf to serve as defaults when the server is started. If you delete these
assignments from postgresql.conf then the server will inherit the settings from its execution
environment.
Note that the locale behavior of the server is determined by the environment variables seen by the
server, not by the environment of any client. Therefore, be careful to configure the correct locale
settings before starting the server. A consequence of this is that if client and server are set up in
different locales, messages may appear in different languages depending on where they originated.
Nota: When we speak of inheriting the locale from the execution environment, this
means the following on most operating systems: For a given locale category, say the
collation, the following environment variables are consulted in this order until one is
found to be set: LC_ALL, LC_COLLATE (the variable corresponding to the respective
category), LANG. If none of these environment variables are set then the locale defaults
to C.
Some message localization libraries also look at the environment variable LANGUAGE
which overrides all other locale settings for the purpose of setting the language of
messages. If in doubt, please refer to the documentation of your operating system, in
particular the documentation about gettext, for more information.
To enable messages to be translated to the user's preferred language, NLS must have been enabled
at build time. This choice is independent of the other locale support.
21.1.2. Behavior
The locale settings influence the following SQL features:
Sort order in queries using ORDER BY on textual data
The ability to use indexes with LIKE clauses
The upper, lower, and initcap functions
The to_char family of functions
The drawback of using locales other than C or POSIX in PostgreSQL is its performance impact. It
slows character handling and prevents ordinary indexes from being used by LIKE. For this reason
use locales only if you actually need them.
As a workaround to allow PostgreSQL to use indexes with LIKE clauses under a non-C locale,
several custom operator classes exist. These allow the creation of an index that performs a strict
character-by-character comparison, ignoring locale comparison rules. Refer to Seção 11.8 for more
information.
21.1.3. Problems
If locale support doesn't work in spite of the explanation above, check that the locale support in
your operating system is correctly configured. To check what locales are installed on your system,
you may use the command locale -a if your operating system provides it.
Check that PostgreSQL is actually using the locale that you think it is. LC_COLLATE and LC_CTYPE
settings are determined at initdb time and cannot be changed without repeating initdb. Other locale
settings including LC_MESSAGES and LC_MONETARY are initially determined by the environment
the server is started in, but can be changed on-the-fly. You can check the active locale settings
using the SHOW command.
The directory src/test/locale in the source distribution contains a test suite for PostgreSQL's locale
support.
Locale Support
Client applications that handle server-side errors by parsing the text of the error message will
obviously have problems when the server's messages are in a different language. Authors of such
applications are advised to make use of the error code scheme instead.
Maintaining catalogs of message translations requires the on-going efforts of many volunteers that
want to see PostgreSQL speak their preferred language well. If messages in your language are
currently not available or not fully translated, your assistance would be appreciated. If you want to
help, refer to Capítulo 46 or write to the developers' mailing list.

Localization Acima Character Set Support
Character Set Support

Anterior Início Capítulo 21. Localization Fim Próxima

The character set support in PostgreSQL allows you to store text in a variety of character sets,
including single-byte character sets such as the ISO 8859 series and multiple-byte character sets
such as EUC (Extended Unix Code), UTF-8, and Mule internal code. All supported character sets can
be used transparently by clients, but a few are not supported for use within the server (that is, as a
server-side encoding). The default character set is selected while initializing your PostgreSQL
database cluster using initdb. It can be overridden when you create a database, so you can have
multiple databases each with a different character set.
21.2.1. Supported Character Sets
Tabela 21-1 shows the character sets available for use in PostgreSQL.
Tabela 21-1. PostgreSQL Character Sets
Name Description Language Server? Bytes/Char Aliases

BIG5 Big Five Traditional Chinese No 1-2 WIN950,
Windows950
EUC_CN Extended UNIX Simplified Chinese Yes 1-3
Code-CN
EUC_JP Extended UNIX Japanese Yes 1-3
Code-JP
EUC_KR Extended UNIX Korean Yes 1-3
Code-KR
EUC_TW Extended UNIX Traditional Chinese, Yes 1-3
Code-TW Taiwanese
GB18030 National Standard Chinese No 1-2
GBK Extended National Simplified Chinese No 1-2 WIN936,
Standard Windows936
ISO_8859_5 ISO 8859-5, ECMA Latin/Cyrillic Yes 1
113
ISO_8859_6 ISO 8859-6, ECMA Latin/Arabic Yes 1
114
ISO_8859_7 ISO 8859-7, ECMA Latin/Greek Yes 1
118
ISO_8859_8 ISO 8859-8, ECMA Latin/Hebrew Yes 1
121
JOHAB JOHAB Korean (Hangul) Yes 1-3
KOI8 KOI8-R(U) Cyrillic Yes 1 KOI8R
LATIN1 ISO 8859-1, ECMA Western European Yes 1 ISO88591
94
LATIN2 ISO 8859-2, ECMA Central European Yes 1 ISO88592
94
LATIN3 ISO 8859-3, ECMA South European Yes 1 ISO88593
94
LATIN4 ISO 8859-4, ECMA North European Yes 1 ISO88594
http://pgdocptbr.sourceforge.net/pg82/multibyte.html[09/02/2018 18:35:02]
94
LATIN5 ISO 8859-9, ECMA Turkish Yes 1 ISO88599
128
LATIN6 ISO 8859-10, ECMA Nordic Yes 1 ISO885910
144
LATIN7 ISO 8859-13 Baltic Yes 1 ISO885913
LATIN8 ISO 8859-14 Celtic Yes 1 ISO885914
LATIN9 ISO 8859-15 LATIN1 with Euro Yes 1 ISO885915
and accents
LATIN10 ISO 8859-16, ASRO Romanian Yes 1 ISO885916
SR 14111
MULE_INTERNAL Mule internal code Multilingual Emacs Yes 1-4
SJIS Shift JIS Japanese No 1-2 Mskanji, ShiftJIS,
WIN932,
Windows932
SQL_ASCII unspecified (see any Yes 1
text)
UHC Unified Hangul Code Korean No 1-2 WIN949,
Windows949
UTF8 Unicode, 8-bit all Yes 1-4 Unicode
WIN866 Windows CP866 Cyrillic Yes 1 ALT
WIN874 Windows CP874 Thai Yes 1
WIN1250 Windows CP1250 Central European Yes 1
WIN1251 Windows CP1251 Cyrillic Yes 1 WIN
WIN1252 Windows CP1252 Western European Yes 1
WIN1253 Windows CP1253 Greek Yes 1
WIN1254 Windows CP1254 Turkish Yes 1
WIN1255 Windows CP1255 Hebrew Yes 1
WIN1256 Windows CP1256 Arabic Yes 1
WIN1257 Windows CP1257 Baltic Yes 1
WIN1258 Windows CP1258 Vietnamese Yes 1 ABC, TCVN,
TCVN5712, VSCII
Not all APIs support all the listed character sets. For example, the PostgreSQL JDBC driver does not
support MULE_INTERNAL, LATIN6, LATIN8, and LATIN10.
The SQL_ASCII setting behaves considerably differently from the other settings. When the server
character set is SQL_ASCII, the server interprets byte values 0-127 according to the ASCII
standard, while byte values 128-255 are taken as uninterpreted characters. No encoding conversion
will be done when the setting is SQL_ASCII. Thus, this setting is not so much a declaration that a
specific encoding is in use, as a declaration of ignorance about the encoding. In most cases, if you
are working with any non-ASCII data, it is unwise to use the SQL_ASCII setting, because
PostgreSQL will be unable to help you by converting or validating non-ASCII characters.
21.2.2. Setting the Character Set
initdb defines the default character set for a PostgreSQL cluster. For example,
initdb -E EUC_JP
sets the default character set (encoding) to EUC_JP (Extended Unix Code for Japanese). You can
use --encoding instead of -E if you prefer to type longer option strings. If no -E or --encoding option
is given, initdb attempts to determine the appropriate encoding to use based on the specified or
default locale.
You can create a database with a different character set:
createdb -E EUC_KR korean
This will create a database named korean that uses the character set EUC_KR. Another way to
accomplish this is to use this SQL command:
CREATE DATABASE korean WITH ENCODING 'EUC_KR';
The encoding for a database is stored in the system catalog pg_database. You can see that by using
the -l option or the \l command of psql.
$ psql -l
List of databases
Database | Owner | Encoding
---------------+---------+---------------
euc_cn | t-ishii | EUC_CN
euc_jp | t-ishii | EUC_JP
euc_kr | t-ishii | EUC_KR
euc_tw | t-ishii | EUC_TW
mule_internal | t-ishii | MULE_INTERNAL
postgres | t-ishii | EUC_JP
regression | t-ishii | SQL_ASCII
template1 | t-ishii | EUC_JP
test | t-ishii | EUC_JP
utf8 | t-ishii | UTF8
(9 rows)
Importante: Although you can specify any encoding you want for a database, it is
unwise to choose an encoding that is not what is expected by the locale you have
selected. The LC_COLLATE and LC_CTYPE settings imply a particular encoding, and
locale-dependent operations (such as sorting) are likely to misinterpret data that is in an
incompatible encoding.
Since these locale settings are frozen by initdb, the apparent flexibility to use different
encodings in different databases of a cluster is more theoretical than real. It is likely that
these mechanisms will be revisited in future versions of PostgreSQL.
One way to use multiple encodings safely is to set the locale to C or POSIX during initdb,
thus disabling any real locale awareness.
21.2.3. Automatic Character Set Conversion Between Server and Client
PostgreSQL supports automatic character set conversion between server and client for certain
character set combinations. The conversion information is stored in the pg_conversion system
catalog. PostgreSQL comes with some predefined conversions, as shown in Tabela 21-2. You can
create a new conversion using the SQL command CREATE CONVERSION.
Tabela 21-2. Client/Server Character Set Conversions
Server
Available Client Character Sets
Character Set
BIG5 not supported as a server encoding
EUC_CN EUC_CN, MULE_INTERNAL, UTF8
EUC_JP EUC_JP, MULE_INTERNAL, SJIS, UTF8
EUC_KR EUC_KR, MULE_INTERNAL, UTF8
EUC_TW EUC_TW, BIG5, MULE_INTERNAL, UTF8
GB18030 not supported as a server encoding
GBK not supported as a server encoding
ISO_8859_5 ISO_8859_5, KOI8, MULE_INTERNAL, UTF8, WIN866, WIN1251
ISO_8859_6 ISO_8859_6, UTF8
ISO_8859_7 ISO_8859_7, UTF8

ISO_8859_8 ISO_8859_8, UTF8
JOHAB JOHAB, UTF8
KOI8 KOI8, ISO_8859_5, MULE_INTERNAL, UTF8, WIN866, WIN1251
LATIN1 LATIN1, MULE_INTERNAL, UTF8
LATIN2 LATIN2, MULE_INTERNAL, UTF8, WIN1250
LATIN5 LATIN5, UTF8
LATIN6 LATIN6, UTF8
LATIN7 LATIN7, UTF8
LATIN8 LATIN8, UTF8
LATIN9 LATIN9, UTF8
LATIN10 LATIN10, UTF8
MULE_INTERNAL MULE_INTERNAL, BIG5, EUC_CN, EUC_JP, EUC_KR, EUC_TW, ISO_8859_5, KOI8,
LATIN1 to LATIN4, SJIS, WIN866, WIN1250, WIN1251
SJIS not supported as a server encoding
SQL_ASCII any (no conversion will be performed)
UHC not supported as a server encoding
UTF8 all supported encodings
WIN866 WIN866, ISO_8859_5, KOI8, MULE_INTERNAL, UTF8, WIN1251
WIN874 WIN874, UTF8
WIN1250 WIN1250, LATIN2, MULE_INTERNAL, UTF8
WIN1251 WIN1251, ISO_8859_5, KOI8, MULE_INTERNAL, UTF8, WIN866
WIN1252 WIN1252, UTF8
To enable automatic character set conversion, you have to tell PostgreSQL the character set
(encoding) you would like to use in the client. There are several ways to accomplish this:
Using the \encoding command in psql. \encoding allows you to change client encoding on the
fly. For example, to change the encoding to SJIS, type:
\encoding SJIS
Using libpq functions. \encoding actually calls PQsetClientEncoding() for its purpose.
int PQsetClientEncoding(PGconn *conexão, const char *codificação);
where conexão is a connection to the server, and codificação is the encoding you want to use.
If the function successfully sets the encoding, it returns 0, otherwise -1. The current encoding
for this connection can be determined by using:
int PQclientEncoding(const PGconn *conexão);
Note that it returns the encoding ID, not a symbolic string such as EUC_JP. To convert an
encoding ID to an encoding name, you can use:
char *pg_encoding_to_char(int id_codificação);
Using SET client_encoding TO. Setting the client encoding can be done with this SQL
command:
SET CLIENT_ENCODING TO 'valor';
Also you can use the standard SQL syntax SET NAMES for this purpose:
SET NAMES 'valor';
To query the current client encoding:
SHOW client_encoding;
To return to the default encoding:
RESET client_encoding;
Using PGCLIENTENCODING. If the environment variable PGCLIENTENCODING is defined in the

client's environment, that client encoding is automatically selected when a connection to the
server is made. (This can subsequently be overridden using any of the other methods
mentioned above.)
Using the configuration variable client_encoding. If the client_encoding variable is set, that
client encoding is automatically selected when a connection to the server is made. (This can
subsequently be overridden using any of the other methods mentioned above.)
If the conversion of a particular character is not possible — suppose you chose EUC_JP for the
server and LATIN1 for the client, then some Japanese characters do not have a representation in
LATIN1 — then an error is reported.
If the client character set is defined as SQL_ASCII, encoding conversion is disabled, regardless of
the server's character set. Just as for the server, use of SQL_ASCII is unwise unless you are
working with all-ASCII data.
21.2.4. Leitura adicional
These are good sources to start learning about various kinds of encoding systems.
http://www.i18ngurus.com/docs/984813247.html
An extensive collection of documents about character sets, encodings, and code pages.
ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/cjk.inf
Detailed explanations of EUC_JP, EUC_CN, EUC_KR, EUC_TW appear in section 3.2.
http://www.unicode.org/
The web site of the Unicode Consortium
RFC 2044
UTF-8 is defined here.

Locale Support Acima Routine Database Maintenance
Tasks
Routine Database Maintenance Tasks

Capítulo 22. Routine Database Maintenance Tasks

Sumário
22.1.1. Recovering disk space

22.1.2. Updating planner statistics
22.1.3. Preventing transaction ID wraparound failures
22.1.4. The auto-vacuum daemon

PostgreSQL, like any database software, requires that certain tasks be performed regularly to
achieve optimum performance. The tasks discussed here are required, but they are repetitive in
nature and can easily be automated using standard Unix tools such as cron scripts or Windows'
Task Scheduler. But it is the database administrator's responsibility to set up appropriate scripts,
and to check that they execute successfully.
One obvious maintenance task is creation of backup copies of the data on a regular schedule.
Without a recent backup, you have no chance of recovery after a catastrophe (disk failure, fire,
mistakenly dropping a critical table, etc.). The backup and recovery mechanisms available in
PostgreSQL are discussed at length in Capítulo 23.
The other main category of maintenance task is periodic "vacuuming" of the database. This activity
is discussed in Seção 22.1. Closely related to this is updating the statistics that will be used by the
query planner, as discussed in Seção 22.1.2.
Another task that might need periodic attention is log file management. This is discussed in Seção
22.3.
PostgreSQL is low-maintenance compared to some other database management systems.

Nonetheless, appropriate attention to these tasks will go far towards ensuring a pleasant and
productive experience with the system.

Character Set Support Acima Routine Vacuuming
http://pgdocptbr.sourceforge.net/pg82/maintenance.html[09/02/2018 18:35:13]
Routine Vacuuming

Anterior Início Capítulo 22. Routine Database Maintenance Tasks Fim Próxima

PostgreSQL's VACUUM command must be run on a regular basis for several reasons:
1. To recover or reuse disk space occupied by updated or deleted rows.
2. To update data statistics used by the PostgreSQL query planner.
3. To protect against loss of very old data due to transaction ID wraparound.
The frequency and scope of the VACUUM operations performed for each of these reasons will vary
depending on the needs of each site. Therefore, database administrators must understand these
issues and develop an appropriate maintenance strategy. This section concentrates on explaining
the high-level issues; for details about command syntax and so on, see the VACUUM reference page.
The standard form of VACUUM can run in parallel with production database operations. Commands
such as SELECT, INSERT, UPDATE, and DELETE will continue to function as normal, though you will
not be able to modify the definition of a table with commands such as ALTER TABLE ADD COLUMN
while it is being vacuumed. Also, VACUUM requires a substantial amount of I/O traffic, which can
cause poor performance for other active sessions. There are configuration parameters that can be
adjusted to reduce the performance impact of background vacuuming — see Seção 17.4.4.
An automated mechanism for performing the necessary VACUUM operations has been added in
PostgreSQL 8.1. See Seção 22.1.4.
22.1.1. Recovering disk space
In normal PostgreSQL operation, an UPDATE or DELETE of a row does not immediately remove the
old version of the row. This approach is necessary to gain the benefits of multiversion concurrency
control (see Capítulo 12): the row version must not be deleted while it is still potentially visible to
other transactions. But eventually, an outdated or deleted row version is no longer of interest to
any transaction. The space it occupies must be reclaimed for reuse by new rows, to avoid infinite
growth of disk space requirements. This is done by running VACUUM.
Clearly, a table that receives frequent updates or deletes will need to be vacuumed more often than
tables that are seldom updated. It may be useful to set up periodic cron tasks that VACUUM only
selected tables, skipping tables that are known not to change often. This is only likely to be helpful
if you have both large heavily-updated tables and large seldom-updated tables — the extra cost of
vacuuming a small table isn't enough to be worth worrying about.
There are two variants of the VACUUM command. The first form, known as "lazy vacuum" or just
VACUUM, marks expired data in tables and indexes for future reuse; it does not attempt to reclaim
the space used by this expired data unless the space is at the end of the table and an exclusive
table lock can be easily obtained. Unused space at the start or middle of the file does not result in
the file being shortened and space returned to the operating system. This variant of VACUUM can
be run concurrently with normal database operations.
The second form is the VACUUM FULL command. This uses a more aggressive algorithm for
reclaiming the space consumed by expired row versions. Any space that is freed by VACUUM FULL
is immediately returned to the operating system. Unfortunately, this variant of the VACUUM
command acquires an exclusive lock on each table while VACUUM FULL is processing it. Therefore,
frequently using VACUUM FULL can have an extremely negative effect on the performance of
http://pgdocptbr.sourceforge.net/pg82/routine-vacuuming.html[09/02/2018 18:35:21]
Routine Vacuuming
concurrent database queries.
The standard form of VACUUM is best used with the goal of maintaining a fairly level steady-state
usage of disk space. If you need to return disk space to the operating system you can use VACUUM
FULL — but what's the point of releasing disk space that will only have to be allocated again soon?
Moderately frequent standard VACUUM runs are a better approach than infrequent VACUUM FULL
runs for maintaining heavily-updated tables.
Recommended practice for most sites is to schedule a database-wide VACUUM once a day at a low-
usage time of day, supplemented by more frequent vacuuming of heavily-updated tables if
necessary. (Some installations with extremely high update rates vacuum their busiest tables as
often as once every few minutes.) If you have multiple databases in a cluster, don't forget to
VACUUM each one; the program vacuumdb may be helpful.
VACUUM FULL is recommended for cases where you know you have deleted the majority of rows in
a table, so that the steady-state size of the table can be shrunk substantially with VACUUM FULL's
more aggressive approach. Use plain VACUUM, not VACUUM FULL, for routine vacuuming for space
recovery.
If you have a table whose entire contents are deleted on a periodic basis, consider doing it with
TRUNCATE rather than using DELETE followed by VACUUM. TRUNCATE removes the entire content
of the table immediately, without requiring a subsequent VACUUM or VACUUM FULL to reclaim the
now-unused disk space.
22.1.2. Updating planner statistics
The PostgreSQL query planner relies on statistical information about the contents of tables in order
to generate good plans for queries. These statistics are gathered by the ANALYZE command, which
can be invoked by itself or as an optional step in VACUUM. It is important to have reasonably
accurate statistics, otherwise poor choices of plans may degrade database performance.
As with vacuuming for space recovery, frequent updates of statistics are more useful for heavily-
updated tables than for seldom-updated ones. But even for a heavily-updated table, there may be
no need for statistics updates if the statistical distribution of the data is not changing much. A
simple rule of thumb is to think about how much the minimum and maximum values of the columns
in the table change. For example, a timestamp column that contains the time of row update will
have a constantly-increasing maximum value as rows are added and updated; such a column will
probably need more frequent statistics updates than, say, a column containing URLs for pages
accessed on a website. The URL column may receive changes just as often, but the statistical
distribution of its values probably changes relatively slowly.
It is possible to run ANALYZE on specific tables and even just specific columns of a table, so the
flexibility exists to update some statistics more frequently than others if your application requires it.
In practice, however, it is usually best to just analyze the entire database because it is a fast
operation. It uses a statistical random sampling of the rows of a table rather than reading every
single row.
Dica: Although per-column tweaking of ANALYZE frequency may not be very productive,
you may well find it worthwhile to do per-column adjustment of the level of detail of the
statistics collected by ANALYZE. Columns that are heavily used in WHERE clauses and
have highly irregular data distributions may require a finer-grain data histogram than
other columns. See ALTER TABLE SET STATISTICS.
Recommended practice for most sites is to schedule a database-wide ANALYZE once a day at a low-
usage time of day; this can usefully be combined with a nightly VACUUM. However, sites with
relatively slowly changing table statistics may find that this is overkill, and that less-frequent
ANALYZE runs are sufficient.
22.1.3. Preventing transaction ID wraparound failures
Routine Vacuuming
PostgreSQL's MVCC transaction semantics depend on being able to compare transaction ID (XID)
numbers: a row version with an insertion XID greater than the current transaction's XID is "in the
future" and should not be visible to the current transaction. But since transaction IDs have limited
size (32 bits at this writing) a cluster that runs for a long time (more than 4 billion transactions)
would suffer transaction ID wraparound: the XID counter wraps around to zero, and all of a sudden
transactions that were in the past appear to be in the future — which means their outputs become
invisible. In short, catastrophic data loss. (Actually the data is still there, but that's cold comfort if
you can't get at it.) To avoid this, it is necessary to vacuum every table in every database at least
once every two billion transactions.
The reason that periodic vacuuming solves the problem is that PostgreSQL distinguishes a special
XID FrozenXID. This XID is always considered older than every normal XID. Normal XIDs are
compared using modulo-231 arithmetic. This means that for every normal XID, there are two billion
XIDs that are "older" and two billion that are "newer"; another way to say it is that the normal XID
space is circular with no endpoint. Therefore, once a row version has been created with a particular
normal XID, the row version will appear to be "in the past" for the next two billion transactions, no
matter which normal XID we are talking about. If the row version still exists after more than two
billion transactions, it will suddenly appear to be in the future. To prevent data loss, old row
versions must be reassigned the XID FrozenXID sometime before they reach the two-billion-
transactions-old mark. Once they are assigned this special XID, they will appear to be "in the past"
to all normal transactions regardless of wraparound issues, and so such row versions will be good
until deleted, no matter how long that is. This reassignment of old XIDs is handled by VACUUM.
VACUUM's behavior is controlled by the configuration parameter vacuum_freeze_min_age: any XID

older than vacuum_freeze_min_age transactions is replaced by FrozenXID. Larger values of
vacuum_freeze_min_age preserve transactional information longer, while smaller values increase
the number of transactions that can elapse before the table must be vacuumed again.
The maximum time that a table can go unvacuumed is two billion transactions minus the
vacuum_freeze_min_age that was used when it was last vacuumed. If it were to go unvacuumed
for longer than that, data loss could result. To ensure that this does not happen, the autovacuum
facility described in Seção 22.1.4 is invoked on any table that might contain XIDs older than the age
specified by the configuration parameter autovacuum_freeze_max_age. (This will happen even if
autovacuum is otherwise disabled.)
This implies that if a table is not otherwise vacuumed, autovacuum will be invoked on it
approximately once every autovacuum_freeze_max_age minus vacuum_freeze_min_age
transactions. For tables that are regularly vacuumed for space reclamation purposes, this is of little
importance. However, for static tables (including tables that receive inserts, but no updates or
deletes), there is no need for vacuuming for space reclamation, and so it can be useful to try to
maximize the interval between forced autovacuums on very large static tables. Obviously one can
do this either by increasing autovacuum_freeze_max_age or by decreasing
vacuum_freeze_min_age.
The sole disadvantage of increasing autovacuum_freeze_max_age is that the pg_clog subdirectory

of the database cluster will take more space, because it must store the commit status for all
transactions back to the autovacuum_freeze_max_age horizon. The commit status uses two bits
per transaction, so if autovacuum_freeze_max_age has its maximum allowed value of a little less
than two billion, pg_clog can be expected to grow to about half a gigabyte. If this is trivial
compared to your total database size, setting autovacuum_freeze_max_age to its maximum
allowed value is recommended. Otherwise, set it depending on what you are willing to allow for
pg_clog storage. (The default, 200 million transactions, translates to about 50MB of pg_clog
storage.)
One disadvantage of decreasing vacuum_freeze_min_age is that it may cause VACUUM to do

useless work: changing a table row's XID to FrozenXID is a waste of time if the row is modified
soon thereafter (causing it to acquire a new XID). So the setting should be large enough that rows
are not frozen until they are unlikely to change any more. Another disadvantage of decreasing this
setting is that details about exactly which transaction inserted or modified a row will be lost sooner.
This information sometimes comes in handy, particularly when trying to analyze what went wrong
after a database failure. For these two reasons, decreasing this setting is not recommended except
for completely static tables.
Routine Vacuuming
To track the age of the oldest XIDs in a database, VACUUM stores XID statistics in the system
tables pg_class and pg_database. In particular, the relfrozenxid column of a table's pg_class row
contains the freeze cutoff XID that was used by the last VACUUM for that table. All normal XIDs
older than this cutoff XID are guaranteed to have been replaced by FrozenXID within the table.
Similarly, the datfrozenxid column of a database's pg_database row is a lower bound on the normal
XIDs appearing in that database — it is just the minimum of the per-table relfrozenxid values within
the database. A convenient way to examine this information is to execute queries such as
SELECT relname, age(relfrozenxid) FROM pg_class WHERE relkind = 'r';

SELECT datname, age(datfrozenxid) FROM pg_database;
The age column measures the number of transactions from the cutoff XID to the current
transaction's XID. Immediately after a VACUUM, age(relfrozenxid) should be a little more than the
vacuum_freeze_min_age setting that was used (more by the number of transactions started since
the VACUUM started). If age(relfrozenxid) exceeds autovacuum_freeze_max_age, an autovacuum
will soon be forced for the table.
If for some reason autovacuum fails to clear old XIDs from a table, the system will begin to emit
warning messages like this when the database's oldest XIDs reach ten million transactions from the
wraparound point:
WARNING: database "mydb" must be vacuumed within 177009986 transactions

HINT: To avoid a database shutdown, execute a full-database VACUUM in "mydb".
If these warnings are ignored, the system will shut down and refuse to execute any new
transactions once there are fewer than 1 million transactions left until wraparound:
ERROR: database is shut down to avoid wraparound data loss in database "mydb"
HINT: Stop the postmaster and use a standalone backend to VACUUM in "mydb".
The 1-million-transaction safety margin exists to let the administrator recover without data loss, by
manually executing the required VACUUM commands. However, since the system will not execute
commands once it has gone into the safety shutdown mode, the only way to do this is to stop the
server and use a single-user backend to execute VACUUM. The shutdown mode is not enforced by a
single-user backend. See the postgres reference page for details about using a single-user backend.
22.1.4. The auto-vacuum daemon
Beginning in PostgreSQL 8.1, there is a separate optional server process called the autovacuum
daemon, whose purpose is to automate the execution of VACUUM and ANALYZE commands. When
enabled, the autovacuum daemon runs periodically and checks for tables that have had a large
number of inserted, updated or deleted tuples. These checks use the row-level statistics collection
facility; therefore, the autovacuum daemon cannot be used unless stats_start_collector and
stats_row_level are set to true. Also, it's important to allow a slot for the autovacuum process when
choosing the value of superuser_reserved_connections.
The autovacuum daemon, when enabled, runs every autovacuum_naptime seconds. On each run, it
selects one database to process and checks each table within that database. VACUUM or ANALYZE
commands are issued as needed.
Tables whose relfrozenxid value is more than autovacuum_freeze_max_age transactions old are
always vacuumed. Otherwise, two conditions are used to determine which operation(s) to apply. If
the number of obsolete tuples since the last VACUUM exceeds the "vacuum threshold", the table is
vacuumed. The vacuum threshold is defined as:
vacuum threshold = vacuum base threshold + vacuum scale factor * number of tuples
where the vacuum base threshold is autovacuum_vacuum_threshold, the vacuum scale factor is
Routine Vacuuming
autovacuum_vacuum_scale_factor, and the number of tuples is pg_class.reltuples. The number of

obsolete tuples is obtained from the statistics collector; it is a semi-accurate count updated by each
UPDATE and DELETE operation. (It is only semi-accurate because some information may be lost
under heavy load.) For analyze, a similar condition is used: the threshold, defined as
analyze threshold = analyze base threshold + analyze scale factor * number of tuples
is compared to the total number of tuples inserted, updated, or deleted since the last ANALYZE.
The default thresholds and scale factors are taken from postgresql.conf, but it is possible to
override them on a table-by-table basis by making entries in the system catalog pg_autovacuum. If
a pg_autovacuum row exists for a particular table, the settings it specifies are applied; otherwise
the global settings are used. See Seção 17.9 for more details on the global settings.
Besides the base threshold values and scale factors, there are five more parameters that can be set
for each table in pg_autovacuum. The first, pg_autovacuum.enabled, can be set to false to instruct
the autovacuum daemon to skip that particular table entirely. In this case autovacuum will only
touch the table if it must do so to prevent transaction ID wraparound. The next two parameters, the
vacuum cost delay (pg_autovacuum.vac_cost_delay) and the vacuum cost limit
(pg_autovacuum.vac_cost_limit), are used to set table-specific values for the Cost-Based Vacuum
Delay feature. The last two parameters, (pg_autovacuum.freeze_min_age) and
(pg_autovacuum.freeze_max_age), are used to set table-specific values for vacuum_freeze_min_age
and autovacuum_freeze_max_age respectively.
If any of the values in pg_autovacuum are set to a negative number, or if a row is not present at all
in pg_autovacuum for any particular table, the corresponding values from postgresql.conf are used.
There is not currently any support for making pg_autovacuum entries, except by doing manual
INSERTs into the catalog. This feature will be improved in future releases, and it is likely that the
catalog definition will change.
Cuidado
The contents of the pg_autovacuum system catalog are currently not saved in database dumps created by
the tools pg_dump and pg_dumpall. If you want to preserve them across a dump/reload cycle, make sure
you dump the catalog manually.

Routine Database Maintenance Acima Routine Reindexing
Tasks
Routine Reindexing


In some situations it is worthwhile to rebuild indexes periodically with the REINDEX command.
In PostgreSQL releases before 7.4, periodic reindexing was frequently necessary to avoid "index
bloat", due to lack of internal space reclamation in B-tree indexes. Any situation in which the range
of index keys changed over time — for example, an index on timestamps in a table where old
entries are eventually deleted — would result in bloat, because index pages for no-longer-needed
portions of the key range were not reclaimed for re-use. Over time, the index size could become
indefinitely much larger than the amount of useful data in it.
In PostgreSQL 7.4 and later, index pages that have become completely empty are reclaimed for re-
use. There is still a possibility for inefficient use of space: if all but a few index keys on a page have
been deleted, the page remains allocated. So a usage pattern in which all but a few keys in each
range are eventually deleted will see poor use of space. The potential for bloat is not indefinite — at
worst there will be one key per page — but it may still be worthwhile to schedule periodic
reindexing for indexes that have such usage patterns.
The potential for bloat in non-B-tree indexes has not been well characterized. It is a good idea to
keep an eye on the index's physical size when using any non-B-tree index type.
Also, for B-tree indexes a freshly-constructed index is somewhat faster to access than one that has
been updated many times, because logically adjacent pages are usually also physically adjacent in a
newly built index. (This consideration does not currently apply to non-B-tree indexes.) It might be
worthwhile to reindex periodically just to improve access speed.

Routine Vacuuming Acima Log File Maintenance
http://pgdocptbr.sourceforge.net/pg82/routine-reindex.html[09/02/2018 18:35:31]
Log File Maintenance


It is a good idea to save the database server's log output somewhere, rather than just routing it to
/dev/null. The log output is invaluable when it comes time to diagnose problems. However, the log
output tends to be voluminous (especially at higher debug levels) and you won't want to save it
indefinitely. You need to "rotate" the log files so that new log files are started and old ones removed
after a reasonable period of time.
If you simply direct the stderr of postgres into a file, you will have log output, but the only way to
truncate the log file is to stop and restart the server. This may be OK if you are using PostgreSQL in
a development environment, but few production servers would find this behavior acceptable.
A better approach is to send the server's stderr output to some type of log rotation program. There
is a built-in log rotation program, which you can use by setting the configuration parameter
redirect_stderr to true in postgresql.conf. The control parameters for this program are described in
Seção 17.7.1.
Alternatively, you might prefer to use an external log rotation program, if you have one that you
are already using with other server software. For example, the rotatelogs tool included in the
Apache distribution can be used with PostgreSQL. To do this, just pipe the server's stderr output to
the desired program. If you start the server with pg_ctl, then stderr is already redirected to stdout,
so you just need a pipe command, for example:
pg_ctl start | rotatelogs /var/log/pgsql_log 86400
Another production-grade approach to managing log output is to send it all to syslog and let syslog
deal with file rotation. To do this, set the configuration parameter log_destination to syslog (to log
to syslog only) in postgresql.conf. Then you can send a SIGHUP signal to the syslog daemon
whenever you want to force it to start writing a new log file. If you want to automate log rotation,
the logrotate program can be configured to work with log files from syslog.
On many systems, however, syslog is not very reliable, particularly with large log messages; it may
truncate or drop messages just when you need them the most. Also, on Linux, syslog will sync each
message to disk, yielding poor performance. (You can use a - at the start of the file name in the
syslog configuration file to disable this behavior.)
Note that all the solutions described above take care of starting new log files at configurable
intervals, but they do not handle deletion of old, no-longer-interesting log files. You will probably
want to set up a batch job to periodically delete old log files. Another possibility is to configure the
rotation program so that old log files are overwritten cyclically.

Routine Reindexing Acima Backup and Restore
http://pgdocptbr.sourceforge.net/pg82/logfile-maintenance.html[09/02/2018 18:35:43]
Backup and Restore

Capítulo 23. Backup and Restore

Sumário
23.1. SQL Dump
23.1.1. Restoring the dump

23.1.2. Using pg_dumpall
23.1.3. Handling large databases

23.3. Continuous Archiving and Point-In-Time Recovery (PITR)
23.3.1. Setting up WAL archiving

23.3.2. Making a Base Backup
23.3.3. Recovering using a Continuous Archive Backup
23.3.4. Timelines
23.3.5. Caveats
23.4.1. Planning
23.4.2. Implementação
23.4.3. Failover
23.4.4. Record-based Log Shipping
23.4.5. Incrementally Updated Backups
As with everything that contains valuable data, PostgreSQL databases should be backed up
regularly. While the procedure is essentially simple, it is important to have a basic understanding of
the underlying techniques and assumptions.
There are three fundamentally different approaches to backing up PostgreSQL data:
SQL dump
File system level backup
Continuous archiving
Each has its own strengths and weaknesses.

Log File Maintenance Acima SQL Dump
http://pgdocptbr.sourceforge.net/pg82/backup.html[09/02/2018 18:36:00]
SQL Dump

Anterior Início Capítulo 23. Backup and Restore Fim Próxima
23.1. SQL Dump

The idea behind this dump method is to generate a text file with SQL commands that, when fed
back to the server, will recreate the database in the same state as it was at the time of the dump.
PostgreSQL provides the utility program pg_dump for this purpose. The basic usage of this
command is:
pg_dump nome_do_banco_de_dados > arquivo_de_saída
As you see, pg_dump writes its results to the standard output. We will see below how this can be
useful.
pg_dump is a regular PostgreSQL client application (albeit a particularly clever one). This means
that you can do this backup procedure from any remote host that has access to the database. But
remember that pg_dump does not operate with special permissions. In particular, it must have read
access to all tables that you want to back up, so in practice you almost always have to run it as a
database superuser.
To specify which database server pg_dump should contact, use the command line options -h
hospedeiro and -p porta. The default host is the local host or whatever your PGHOST environment
variable specifies. Similarly, the default port is indicated by the PGPORT environment variable or,
failing that, by the compiled-in default. (Conveniently, the server will normally have the same
compiled-in default.)
As any other PostgreSQL client application, pg_dump will by default connect with the database user
name that is equal to the current operating system user name. To override this, either specify the -
U option or set the environment variable PGUSER. Remember that pg_dump connections are
subject to the normal client authentication mechanisms (which are described in Capítulo 20).
Dumps created by pg_dump are internally consistent, that is, updates to the database while
pg_dump is running will not be in the dump. pg_dump does not block other operations on the
database while it is working. (Exceptions are those operations that need to operate with an
exclusive lock, such as VACUUM FULL.)
Importante: If your database schema relies on OIDs (for instance as foreign keys) you
must instruct pg_dump to dump the OIDs as well. To do this, use the -o command line
option.
23.1.1. Restoring the dump
The text files created by pg_dump are intended to be read in by the psql program. The general
command form to restore a dump is
psql nome_do_banco_de_dados < arquivo_de_entrada
where arquivo_de_entrada is what you used as arquivo_de_saída for the pg_dump command. The
database dbname will not be created by this command, so you must create it yourself from
template0 before executing psql (e.g., with createdb -T template0 dbname). psql supports similar
options to pg_dump for specifying the database server to connect to and the user name to use. See
the psql reference page for more information.
Before restoring a SQL dump, all the users who own objects or were granted permissions on objects
in the dumped database must already exist. If they do not, then the restore will fail to recreate the
objects with the original ownership and/or permissions. (Sometimes this is what you want, but
http://pgdocptbr.sourceforge.net/pg82/backup-dump.html[09/02/2018 18:36:22]
SQL Dump
usually it is not.)
By default, the psql script will continue to execute after an SQL error is encountered. You may wish
to use the following command at the top of the script to alter that behaviour and have psql exit with
an exit status of 3 if an SQL error occurs:
\set ON_ERROR_STOP
Either way, you will only have a partially restored dump. Alternatively, you can specify that the
whole dump should be restored as a single transaction, so the restore is either fully completed or
fully rolled back. This mode can be specified by passing the -1 or --single-transaction command-line
options to psql. When using this mode, be aware that even the smallest of errors can rollback a
restore that has already run for many hours. However, that may still be preferable to manually
cleaning up a complex database after a partially restored dump.
The ability of pg_dump and psql to write to or read from pipes makes it possible to dump a
database directly from one server to another; for example:
pg_dump -h host1 nome_do_banco_de_dados | psql -h host2 nome_do_banco_de_dados
Importante: The dumps produced by pg_dump are relative to template0. This means
that any languages, procedures, etc. added to template1 will also be dumped by
pg_dump. As a result, when restoring, if you are using a customized template1, you
must create the empty database from template0, as in the example above.
After restoring a backup, it is wise to run ANALYZE on each database so the query optimizer has
useful statistics. An easy way to do this is to run vacuumdb -a -z; this is equivalent to running
VACUUM ANALYZE on each database manually. For more advice on how to load large amounts of
data into PostgreSQL efficiently, refer to Seção 13.4.
23.1.2. Using pg_dumpall
pg_dump dumps only a single database at a time, and it does not dump information about roles or
tablespaces (because those are cluster-wide rather than per-database). To support convenient
dumping of the entire contents of a database cluster, the pg_dumpall program is provided.
pg_dumpall backs up each database in a given cluster, and also preserves cluster-wide data such as
role and tablespace definitions. The basic usage of this command is:
pg_dumpall > arquivo_de_saída
The resulting dump can be restored with psql:

psql -f arquivo_de_entrada postgres
(Actually, you can specify any existing database name to start from, but if you are reloading in an
empty cluster then postgres should generally be used.) It is always necessary to have database
superuser access when restoring a pg_dumpall dump, as that is required to restore the role and
tablespace information. If you use tablespaces, be careful that the tablespace paths in the dump
are appropriate for the new installation.
23.1.3. Handling large databases
Since PostgreSQL allows tables larger than the maximum file size on your system, it can be
problematic to dump such a table to a file, since the resulting file will likely be larger than the
maximum size allowed by your system. Since pg_dump can write to the standard output, you can
use standard Unix tools to work around this possible problem.
Use compressed dumps. You can use your favorite compression program, for example gzip.
pg_dump nome_do_banco_de_dados | gzip > nome_do_arquivo.gz
SQL Dump
Reload with
gunzip -c nome_do_arquivo.gz | psql nome_do_banco_de_dados
or
cat nome_do_arquivo.gz | gunzip | psql nome_do_banco_de_dados
Use split. The split command allows you to split the output into pieces that are acceptable in size
to the underlying file system. For example, to make chunks of 1 megabyte:
pg_dump nome_do_banco_de_dados | split -b 1m - nome_do_arquivo
Reload with
cat nome_do_arquivo* | psql nome_do_banco_de_dados
Use the custom dump format. If PostgreSQL was built on a system with the zlib compression
library installed, the custom dump format will compress data as it writes it to the output file. This
will produce dump file sizes similar to using gzip, but it has the added advantage that tables can be
restored selectively. The following command dumps a database using the custom dump format:
pg_dump -Fc nome_do_banco_de_dados > nome_do_arquivo
A custom-format dump is not a script for psql, but instead must be restored with pg_restore. See
the pg_dump and pg_restore reference pages for details.

Backup and Restore Acima File System Level Backup
File System Level Backup


An alternative backup strategy is to directly copy the files that PostgreSQL uses to store the data in
the database. In Seção 16.2 it is explained where these files are located, but you have probably
found them already if you are interested in this method. You can use whatever method you prefer
for doing usual file system backups, for example
tar -cf backup.tar /usr/local/pgsql/data
There are two restrictions, however, which make this method impractical, or at least inferior to the
pg_dump method:
1. The database server must be shut down in order to get a usable backup. Half-way measures
such as disallowing all connections will not work (mainly because tar and similar tools do not
take an atomic snapshot of the state of the file system at a point in time). Information about
stopping the server can be found in Seção 16.5. Needless to say that you also need to shut
down the server before restoring the data.
2. If you have dug into the details of the file system layout of the database, you may be tempted
to try to back up or restore only certain individual tables or databases from their respective
files or directories. This will not work because the information contained in these files contains
only half the truth. The other half is in the commit log files pg_clog/*, which contain the
commit status of all transactions. A table file is only usable with this information. Of course it
is also impossible to restore only a table and the associated pg_clog data because that would
render all other tables in the database cluster useless. So file system backups only work for
complete restoration of an entire database cluster.
An alternative file-system backup approach is to make a "consistent snapshot" of the data

directory, if the file system supports that functionality (and you are willing to trust that it is
implemented correctly). The typical procedure is to make a "frozen snapshot" of the volume
containing the database, then copy the whole data directory (not just parts, see above) from the
snapshot to a backup device, then release the frozen snapshot. This will work even while the
database server is running. However, a backup created in this way saves the database files in a
state where the database server was not properly shut down; therefore, when you start the
database server on the backed-up data, it will think the server had crashed and replay the WAL log.
This is not a problem, just be aware of it (and be sure to include the WAL files in your backup).
If your database is spread across multiple file systems, there may not be any way to obtain exactly-
simultaneous frozen snapshots of all the volumes. For example, if your data files and WAL log are
on different disks, or if tablespaces are on different file systems, it might not be possible to use
snapshot backup because the snapshots must be simultaneous. Read your file system
documentation very carefully before trusting to the consistent-snapshot technique in such
situations. The safest approach is to shut down the database server for long enough to establish all
the frozen snapshots.
Another option is to use rsync to perform a file system backup. This is done by first running rsync
while the database server is running, then shutting down the database server just long enough to
do a second rsync. The second rsync will be much quicker than the first, because it has relatively
little data to transfer, and the end result will be consistent because the server was down. This
method allows a file system backup to be performed with minimal downtime.
Note that a file system backup will not necessarily be smaller than an SQL dump. On the contrary, it
http://pgdocptbr.sourceforge.net/pg82/backup-file.html[09/02/2018 18:36:33]
File System Level Backup
will most likely be larger. (pg_dump does not need to dump the contents of indexes for example,
just the commands to recreate them.)

SQL Dump Acima Continuous Archiving and Point-In-
Time Recovery (PITR)
http://pgdocptbr.sourceforge.net/pg82/backup-file.html[09/02/2018 18:36:33]
Continuous Archiving and Point-In-Time Recovery (PITR)

23.3. Continuous Archiving and Point-In-Time Recovery

(PITR)
At all times, PostgreSQL maintains a write ahead log (WAL) in the pg_xlog/ subdirectory of the
cluster's data directory. The log describes every change made to the database's data files. This log
exists primarily for crash-safety purposes: if the system crashes, the database can be restored to
consistency by "replaying" the log entries made since the last checkpoint. However, the existence of
the log makes it possible to use a third strategy for backing up databases: we can combine a file-
system-level backup with backup of the WAL files. If recovery is needed, we restore the backup and
then replay from the backed-up WAL files to bring the backup up to current time. This approach is
more complex to administer than either of the previous approaches, but it has some significant
benefits:
We do not need a perfectly consistent backup as the starting point. Any internal inconsistency
in the backup will be corrected by log replay (this is not significantly different from what
happens during crash recovery). So we don't need file system snapshot capability, just tar or
a similar archiving tool.
Since we can string together an indefinitely long sequence of WAL files for replay, continuous
backup can be achieved simply by continuing to archive the WAL files. This is particularly
valuable for large databases, where it may not be convenient to take a full backup frequently.
There is nothing that says we have to replay the WAL entries all the way to the end. We could
stop the replay at any point and have a consistent snapshot of the database as it was at that
time. Thus, this technique supports point-in-time recovery: it is possible to restore the
database to its state at any time since your base backup was taken.
If we continuously feed the series of WAL files to another machine that has been loaded with
the same base backup file, we have a warm standby system: at any point we can bring up the
second machine and it will have a nearly-current copy of the database.
As with the plain file-system-backup technique, this method can only support restoration of an
entire database cluster, not a subset. Also, it requires a lot of archival storage: the base backup
may be bulky, and a busy system will generate many megabytes of WAL traffic that have to be
archived. Still, it is the preferred backup technique in many situations where high reliability is
needed.
To recover successfully using continuous archiving (also called "online backup" by many database
vendors), you need a continuous sequence of archived WAL files that extends back at least as far as
the start time of your backup. So to get started, you should setup and test your procedure for
archiving WAL files before you take your first base backup. Accordingly, we first discuss the
mechanics of archiving WAL files.
23.3.1. Setting up WAL archiving
In an abstract sense, a running PostgreSQL system produces an indefinitely long sequence of WAL
records. The system physically divides this sequence into WAL segment files, which are normally
16MB apiece (although the size can be altered when building PostgreSQL). The segment files are
given numeric names that reflect their position in the abstract WAL sequence. When not using WAL
archiving, the system normally creates just a few segment files and then "recycles" them by
renaming no-longer-needed segment files to higher segment numbers. It's assumed that a segment
file whose contents precede the checkpoint-before-last is no longer of interest and can be recycled.
http://pgdocptbr.sourceforge.net/pg82/continuous-archiving.html[09/02/2018 18:36:43]
When archiving WAL data, we want to capture the contents of each segment file once it is filled,
and save that data somewhere before the segment file is recycled for reuse. Depending on the
application and the available hardware, there could be many different ways of "saving the data
somewhere": we could copy the segment files to an NFS-mounted directory on another machine,
write them onto a tape drive (ensuring that you have a way of identifying the original name of each
file), or batch them together and burn them onto CDs, or something else entirely. To provide the
database administrator with as much flexibility as possible, PostgreSQL tries not to make any
assumptions about how the archiving will be done. Instead, PostgreSQL lets the administrator
specify a shell command to be executed to copy a completed segment file to wherever it needs to
go. The command could be as simple as a cp, or it could invoke a complex shell script — it's all up
to you.
The shell command to use is specified by the archive_command configuration parameter, which in
practice will always be placed in the postgresql.conf file. In this string, any %p is replaced by the
path name of the file to archive, while any %f is replaced by the file name only. (The path name is
relative to the working directory of the server, i.e., the cluster's data directory.) Write %% if you
need to embed an actual % character in the command. The simplest useful command is something
like
archive_command = 'cp -i %p /mnt/server/archivedir/%f </dev/null'
which will copy archivable WAL segments to the directory /mnt/server/archivedir. (This is an
example, not a recommendation, and may not work on all platforms.)
The archive command will be executed under the ownership of the same user that the PostgreSQL
server is running as. Since the series of WAL files being archived contains effectively everything in
your database, you will want to be sure that the archived data is protected from prying eyes; for
example, archive into a directory that does not have group or world read access.
It is important that the archive command return zero exit status if and only if it succeeded. Upon
getting a zero result, PostgreSQL will assume that the WAL segment file has been successfully
archived, and will remove or recycle it. However, a nonzero status tells PostgreSQL that the file was
not archived; it will try again periodically until it succeeds.
The archive command should generally be designed to refuse to overwrite any pre-existing archive
file. This is an important safety feature to preserve the integrity of your archive in case of
administrator error (such as sending the output of two different servers to the same archive
directory). It is advisable to test your proposed archive command to ensure that it indeed does not
overwrite an existing file, and that it returns nonzero status in this case. We have found that cp -i
does this correctly on some platforms but not others. If the chosen command does not itself handle
this case correctly, you should add a command to test for pre-existence of the archive file. For
example, something like
archive_command = 'test ! -f .../%f && cp %p .../%f'
works correctly on most Unix variants.
While designing your archiving setup, consider what will happen if the archive command fails
repeatedly because some aspect requires operator intervention or the archive runs out of space. For
example, this could occur if you write to tape without an autochanger; when the tape fills, nothing
further can be archived until the tape is swapped. You should ensure that any error condition or
request to a human operator is reported appropriately so that the situation can be resolved
relatively quickly. The pg_xlog/ directory will continue to fill with WAL segment files until the
situation is resolved.
The speed of the archiving command is not important, so long as it can keep up with the average
rate at which your server generates WAL data. Normal operation continues even if the archiving
process falls a little behind. If archiving falls significantly behind, this will increase the amount of
data that would be lost in the event of a disaster. It will also mean that the pg_xlog/ directory will
contain large numbers of not-yet-archived segment files, which could eventually exceed available
disk space. You are advised to monitor the archiving process to ensure that it is working as you
intend.
In writing your archive command, you should assume that the file names to be archived may be up
to 64 characters long and may contain any combination of ASCII letters, digits, and dots. It is not
necessary to remember the original relative path (%p) but it is necessary to remember the file
name (%f).
Note that although WAL archiving will allow you to restore any modifications made to the data in
your PostgreSQL database, it will not restore changes made to configuration files (that is,
postgresql.conf, pg_hba.conf and pg_ident.conf), since those are edited manually rather than
through SQL operations. You may wish to keep the configuration files in a location that will be
backed up by your regular file system backup procedures. See Seção 17.2 for how to relocate the
configuration files.
The archive command is only invoked on completed WAL segments. Hence, if your server generates
only little WAL traffic (or has slack periods where it does so), there could be a long delay between
the completion of a transaction and its safe recording in archive storage. To put a limit on how old
unarchived data can be, you can set archive_timeout to force the server to switch to a new WAL
segment file at least that often. Note that archived files that are ended early due to a forced switch
are still the same length as completely full files. It is therefore unwise to set a very short
archive_timeout — it will bloat your archive storage. archive_timeout settings of a minute or so are
usually reasonable.
Also, you can force a segment switch manually with pg_switch_xlog, if you want to ensure that a
just-finished transaction is archived immediately. Other utility functions related to WAL
management are listed in Tabela 9-47.
23.3.2. Making a Base Backup
The procedure for making a base backup is relatively simple:
1. Ensure that WAL archiving is enabled and working.
2. Connect to the database as a superuser, and issue the command
SELECT pg_start_backup('label');
where label is any string you want to use to uniquely identify this backup operation. (One
good practice is to use the full path where you intend to put the backup dump file.)
pg_start_backup creates a backup label file, called backup_label, in the cluster directory with
information about your backup.
It does not matter which database within the cluster you connect to to issue this command.
You can ignore the result returned by the function; but if it reports an error, deal with that
before proceeding.
3. Perform the backup, using any convenient file-system-backup tool such as tar or cpio. It is
neither necessary nor desirable to stop normal operation of the database while you do this.
4. Again connect to the database as a superuser, and issue the command
SELECT pg_stop_backup();
This terminates the backup mode and performs an automatic switch to the next WAL
segment. The reason for the switch is to arrange that the last WAL segment file written during
the backup interval is immediately ready to archive.
5. Once the WAL segment files used during the backup are archived, you are done. The file
identified by pg_stop_backup's result is the last segment that needs to be archived to
complete the backup. Archival of these files will happen automatically, since you have already
configured archive_command. In many cases, this happens fairly quickly, but you are advised
to monitor your archival system to ensure this has taken place so that you can be certain you
have a complete backup.
Some backup tools that you might wish to use emit warnings or errors if the files they are trying to
copy change while the copy proceeds. This situation is normal, and not an error, when taking a
base backup of an active database; so you need to ensure that you can distinguish complaints of
this sort from real errors. For example, some versions of rsync return a separate exit code for
"vanished source files", and you can write a driver script to accept this exit code as a non-error
case. Also, some versions of GNU tar consider it an error if a file is changed while tar is copying it.
There does not seem to be any very convenient way to distinguish this error from other types of
errors, other than manual inspection of tar's messages. GNU tar is therefore not the best tool for
making base backups.
It is not necessary to be very concerned about the amount of time elapsed between
pg_start_backup and the start of the actual backup, nor between the end of the backup and
pg_stop_backup; a few minutes' delay won't hurt anything. (However, if you normally run the
server with full_page_writes disabled, you may notice a drop in performance between
pg_start_backup and pg_stop_backup, since full_page_writes is effectively forced on during backup
mode.) You must ensure that these steps are carried out in sequence without any possible overlap,
or you will invalidate the backup.
Be certain that your backup dump includes all of the files underneath the database cluster directory
(e.g., /usr/local/pgsql/data). If you are using tablespaces that do not reside underneath this
directory, be careful to include them as well (and be sure that your backup dump archives symbolic
links as links, otherwise the restore will mess up your tablespaces).
You may, however, omit from the backup dump the files within the pg_xlog/ subdirectory of the
cluster directory. This slight complication is worthwhile because it reduces the risk of mistakes when
restoring. This is easy to arrange if pg_xlog/ is a symbolic link pointing to someplace outside the
cluster directory, which is a common setup anyway for performance reasons.
To make use of the backup, you will need to keep around all the WAL segment files generated
during and after the file system backup. To aid you in doing this, the pg_stop_backup function
creates a backup history file that is immediately stored into the WAL archive area. This file is named
after the first WAL segment file that you need to have to make use of the backup. For example, if
the starting WAL file is 0000000100001234000055CD the backup history file will be named
something like 0000000100001234000055CD.007C9330.backup. (The second number in the file
name stands for an exact position within the WAL file, and can ordinarily be ignored.) Once you
have safely archived the file system backup and the WAL segment files used during the backup (as
specified in the backup history file), all archived WAL segments with names numerically less are no
longer needed to recover the file system backup and may be deleted. However, you should consider
keeping several backup sets to be absolutely certain that you can recover your data.
The backup history file is just a small text file. It contains the label string you gave to
pg_start_backup, as well as the starting and ending times and WAL segments of the backup. If you
used the label to identify where the associated dump file is kept, then the archived history file is
enough to tell you which dump file to restore, should you need to do so.
Since you have to keep around all the archived WAL files back to your last base backup, the interval
between base backups should usually be chosen based on how much storage you want to expend
on archived WAL files. You should also consider how long you are prepared to spend recovering, if
recovery should be necessary — the system will have to replay all those WAL segments, and that
could take awhile if it has been a long time since the last base backup.
It's also worth noting that the pg_start_backup function makes a file named backup_label in the
database cluster directory, which is then removed again by pg_stop_backup. This file will of course
be archived as a part of your backup dump file. The backup label file includes the label string you
gave to pg_start_backup, as well as the time at which pg_start_backup was run, and the name of
the starting WAL file. In case of confusion it will therefore be possible to look inside a backup dump
file and determine exactly which backup session the dump file came from.
It is also possible to make a backup dump while the server is stopped. In this case, you obviously
cannot use pg_start_backup or pg_stop_backup, and you will therefore be left to your own devices
to keep track of which backup dump is which and how far back the associated WAL files go. It is
generally better to follow the continuous archiving procedure above.
23.3.3. Recovering using a Continuous Archive Backup
Okay, the worst has happened and you need to recover from your backup. Here is the procedure:
1. Stop the server, if it's running.
2. If you have the space to do so, copy the whole cluster data directory and any tablespaces to a
temporary location in case you need them later. Note that this precaution will require that you
have enough free space on your system to hold two copies of your existing database. If you
do not have enough space, you need at the least to copy the contents of the pg_xlog
subdirectory of the cluster data directory, as it may contain logs which were not archived
before the system went down.
3. Clean out all existing files and subdirectories under the cluster data directory and under the
root directories of any tablespaces you are using.
4. Restore the database files from your backup dump. Be careful that they are restored with the
right ownership (the database system user, not root!) and with the right permissions. If you
are using tablespaces, you should verify that the symbolic links in pg_tblspc/ were correctly
restored.
5. Remove any files present in pg_xlog/; these came from the backup dump and are therefore
probably obsolete rather than current. If you didn't archive pg_xlog/ at all, then recreate it,
and be sure to recreate the subdirectory pg_xlog/archive_status/ as well.
6. If you had unarchived WAL segment files that you saved in step 2, copy them into pg_xlog/.
(It is best to copy them, not move them, so that you still have the unmodified files if a
problem occurs and you have to start over.)
7. Create a recovery command file recovery.conf in the cluster data directory (see Recovery
Settings). You may also want to temporarily modify pg_hba.conf to prevent ordinary users
from connecting until you are sure the recovery has worked.
8. Start the server. The server will go into recovery mode and proceed to read through the
archived WAL files it needs. Should the recovery be terminated because of an external error,
the server can simply be restarted and it will continue recovery. Upon completion of the
recovery process, the server will rename recovery.conf to recovery.done (to prevent
accidentally re-entering recovery mode in case of a crash later) and then commence normal
database operations.
9. Inspect the contents of the database to ensure you have recovered to where you want to be.
If not, return to step 1. If all is well, let in your users by restoring pg_hba.conf to normal.
The key part of all this is to setup a recovery command file that describes how you want to recover
and how far the recovery should run. You can use recovery.conf.sample (normally installed in the
installation share/ directory) as a prototype. The one thing that you absolutely must specify in
recovery.conf is the restore_command, which tells PostgreSQL how to get back archived WAL file
segments. Like the archive_command, this is a shell command string. It may contain %f, which is
replaced by the name of the desired log file, and %p, which is replaced by the path name to copy
the log file to. (The path name is relative to the working directory of the server, i.e., the cluster's
data directory.) Write %% if you need to embed an actual % character in the command. The
simplest useful command is something like
restore_command = 'cp /mnt/server/archivedir/%f %p'
which will copy previously archived WAL segments from the directory /mnt/server/archivedir. You
could of course use something much more complicated, perhaps even a shell script that requests
the operator to mount an appropriate tape.
It is important that the command return nonzero exit status on failure. The command will be asked
for log files that are not present in the archive; it must return nonzero when so asked. This is not
an error condition. Be aware also that the base name of the %p path will be different from %f; do
not expect them to be interchangeable.
WAL segments that cannot be found in the archive will be sought in pg_xlog/; this allows use of
recent un-archived segments. However segments that are available from the archive will be used in
preference to files in pg_xlog/. The system will not overwrite the existing contents of pg_xlog/ when
retrieving archived files.
Normally, recovery will proceed through all available WAL segments, thereby restoring the database
to the current point in time (or as close as we can get given the available WAL segments). But if
you want to recover to some previous point in time (say, right before the junior DBA dropped your
main transaction table), just specify the required stopping point in recovery.conf. You can specify
the stop point, known as the "recovery target", either by date/time or by completion of a specific
transaction ID. As of this writing only the date/time option is very usable, since there are no tools
to help you identify with any accuracy which transaction ID to use.
Nota: The stop point must be after the ending time of the base backup (the time of
pg_stop_backup). You cannot use a base backup to recover to a time when that backup
was still going on. (To recover to such a time, you must go back to your previous base
backup and roll forward from there.)
If recovery finds a corruption in the WAL data then recovery will complete at that point and the
server will not start. In such a case the recovery process could be re-run from the beginning,
specifying a "recovery target" before the point of corruption so that recovery can complete
normally. If recovery fails for an external reason, such as a system crash or if the WAL archive has
become inaccessible, then the recovery can simply be restarted and it will restart almost from
where it failed. Recovery restart works much like checkpointing in normal operation: the server
periodically forces all its state to disk, and then updates the pg_control file to indicate that the
already-processed WAL data need not be scanned again.
23.3.3.1. Recovery Settings
These settings can only be made in the recovery.conf file, and apply only for the duration of the
recovery. They must be reset for any subsequent recovery you wish to perform. They cannot be
changed once recovery has begun.
restore_command (string)
The shell command to execute to retrieve an archived segment of the WAL file series. This
parameter is required. Any %f in the string is replaced by the name of the file to retrieve from
the archive, and any %p is replaced by the path name to copy it to on the server. (The path
name is relative to the working directory of the server, i.e., the cluster's data directory.) Write
%% to embed an actual % character in the command.
It is important for the command to return a zero exit status if and only if it succeeds. The
command will be asked for file names that are not present in the archive; it must return
nonzero when so asked. Examples:
restore_command = 'cp /mnt/server/archivedir/%f "%p"'

restore_command = 'copy /mnt/server/archivedir/%f "%p"' # Windows
recovery_target_time (timestamp)
This parameter specifies the time stamp up to which recovery will proceed. At most one of
recovery_target_time and recovery_target_xid can be specified. The default is to recover to the
end of the WAL log. The precise stopping point is also influenced by recovery_target_inclusive.
recovery_target_xid (string)
This parameter specifies the transaction ID up to which recovery will proceed. Keep in mind
that while transaction IDs are assigned sequentially at transaction start, transactions can
complete in a different numeric order. The transactions that will be recovered are those that
committed before (and optionally including) the specified one. At most one of
recovery_target_xid and recovery_target_time can be specified. The default is to recover to the
end of the WAL log. The precise stopping point is also influenced by recovery_target_inclusive.
recovery_target_inclusive (boolean)
Specifies whether we stop just after the specified recovery target (true), or just before the
recovery target (false). Applies to both recovery_target_time and recovery_target_xid,
whichever one is specified for this recovery. This indicates whether transactions having
exactly the target commit time or ID, respectively, will be included in the recovery. Default is
true.
recovery_target_timeline (string)
Specifies recovering into a particular timeline. The default is to recover along the same
timeline that was current when the base backup was taken. You would only need to set this
parameter in complex re-recovery situations, where you need to return to a state that itself
was reached after a point-in-time recovery. See Seção 23.3.4 for discussion.
23.3.4. Timelines
The ability to restore the database to a previous point in time creates some complexities that are
akin to science-fiction stories about time travel and parallel universes. In the original history of the
database, perhaps you dropped a critical table at 5:15PM on Tuesday evening. Unfazed, you get out
your backup, restore to the point-in-time 5:14PM Tuesday evening, and are up and running. In this
history of the database universe, you never dropped the table at all. But suppose you later realize
this wasn't such a great idea after all, and would like to return to some later point in the original
history. You won't be able to if, while your database was up-and-running, it overwrote some of the
sequence of WAL segment files that led up to the time you now wish you could get back to. So you
really want to distinguish the series of WAL records generated after you've done a point-in-time
recovery from those that were generated in the original database history.
To deal with these problems, PostgreSQL has a notion of timelines. Each time you recover to a
point-in-time earlier than the end of the WAL sequence, a new timeline is created to identify the
series of WAL records generated after that recovery. (If recovery proceeds all the way to the end of
WAL, however, we do not start a new timeline: we just extend the existing one.) The timeline ID
number is part of WAL segment file names, and so a new timeline does not overwrite the WAL data
generated by previous timelines. It is in fact possible to archive many different timelines. While that
might seem like a useless feature, it's often a lifesaver. Consider the situation where you aren't
quite sure what point-in-time to recover to, and so have to do several point-in-time recoveries by
trial and error until you find the best place to branch off from the old history. Without timelines this
process would soon generate an unmanageable mess. With timelines, you can recover to any prior
state, including states in timeline branches that you later abandoned.
Each time a new timeline is created, PostgreSQL creates a "timeline history" file that shows which
timeline it branched off from and when. These history files are necessary to allow the system to
pick the right WAL segment files when recovering from an archive that contains multiple timelines.
Therefore, they are archived into the WAL archive area just like WAL segment files. The history files
are just small text files, so it's cheap and appropriate to keep them around indefinitely (unlike the
segment files which are large). You can, if you like, add comments to a history file to make your
own notes about how and why this particular timeline came to be. Such comments will be especially
valuable when you have a thicket of different timelines as a result of experimentation.
The default behavior of recovery is to recover along the same timeline that was current when the
base backup was taken. If you want to recover into some child timeline (that is, you want to return
to some state that was itself generated after a recovery attempt), you need to specify the target
timeline ID in recovery.conf. You cannot recover into timelines that branched off earlier than the
base backup.
23.3.5. Caveats
At this writing, there are several limitations of the continuous archiving technique. These will
probably be fixed in future releases:
Operations on hash indexes are not presently WAL-logged, so replay will not update these
indexes. The recommended workaround is to manually REINDEX each such index after
completing a recovery operation.
If a CREATE DATABASE command is executed while a base backup is being taken, and then the
template database that the CREATE DATABASE copied is modified while the base backup is
still in progress, it is possible that recovery will cause those modifications to be propagated
into the created database as well. This is of course undesirable. To avoid this risk, it is best
not to modify any template databases while taking a base backup.
CREATE TABLESPACE commands are WAL-logged with the literal absolute path, and will
therefore be replayed as tablespace creations with the same absolute path. This might be
undesirable if the log is being replayed on a different machine. It can be dangerous even if the
log is being replayed on the same machine, but into a new data directory: the replay will still
overwrite the contents of the original tablespace. To avoid potential gotchas of this sort, the
best practice is to take a new base backup after creating or dropping tablespaces.
It should also be noted that the default WAL format is fairly bulky since it includes many disk page
snapshots. These page snapshots are designed to support crash recovery, since we may need to fix
partially-written disk pages. Depending on your system hardware and software, the risk of partial
writes may be small enough to ignore, in which case you can significantly reduce the total volume
of archived logs by turning off page snapshots using the full_page_writes parameter. (Read the
notes and warnings in Capítulo 27 before you do so.) Turning off page snapshots does not prevent
use of the logs for PITR operations. An area for future development is to compress archived WAL
data by removing unnecessary page copies even when full_page_writes is on. In the meantime,
administrators may wish to reduce the number of page snapshots included in WAL by increasing the
checkpoint interval parameters as much as feasible.

File System Level Backup Acima Warm Standby Servers for High
Availability
Warm Standby Servers for High Availability


Continuous archiving can be used to create a high availability (HA) cluster configuration with one or
more standby servers ready to take over operations if the primary server fails. This capability is
widely referred to as warm standby or log shipping.
The primary and standby server work together to provide this capability, though the servers are
only loosely coupled. The primary server operates in continuous archiving mode, while each standby
server operates in continuous recovery mode, reading the WAL files from the primary. No changes
to the database tables are required to enable this capability, so it offers low administration
overhead in comparison with some other replication approaches. This configuration also has
relatively low performance impact on the primary server.
Directly moving WAL or "log" records from one database server to another is typically described as
log shipping. PostgreSQL implements file-based log shipping, which means that WAL records are
transferred one file (WAL segment) at a time. WAL files can be shipped easily and cheaply over any
distance, whether it be to an adjacent system, another system on the same site or another system
on the far side of the globe. The bandwidth required for this technique varies according to the
transaction rate of the primary server. Record-based log shipping is also possible with custom-
developed procedures, as discussed in Seção 23.4.4.
It should be noted that the log shipping is asynchronous, i.e. the WAL records are shipped after
transaction commit. As a result there is a window for data loss should the primary server suffer a
catastrophic failure: transactions not yet shipped will be lost. The length of the window of data loss
can be limited by use of the archive_timeout parameter, which can be set as low as a few seconds if
required. However such low settings will substantially increase the bandwidth requirements for file
shipping. If you need a window of less than a minute or so, it's probably better to look into record-
based log shipping.
The standby server is not available for access, since it is continually performing recovery
processing. Recovery performance is sufficiently good that the standby will typically be only
moments away from full availability once it has been activated. As a result, we refer to this
capability as a warm standby configuration that offers high availability. Restoring a server from an
archived base backup and rollforward will take considerably longer, so that technique only really
offers a solution for disaster recovery, not HA.
23.4.1. Planning
It is usually wise to create the primary and standby servers so that they are as similar as possible,
at least from the perspective of the database server. In particular, the path names associated with
tablespaces will be passed across as-is, so both primary and standby servers must have the same
mount paths for tablespaces if that feature is used. Keep in mind that if CREATE TABLESPACE is
executed on the primary, any new mount point needed for it must be created on both the primary
and all standby servers before the command is executed. Hardware need not be exactly the same,
but experience shows that maintaining two identical systems is easier than maintaining two
dissimilar ones over the lifetime of the application and system. In any case the hardware
architecture must be the same — shipping from, say, a 32-bit to a 64-bit system will not work.
In general, log shipping between servers running different major release levels will not be possible.
It is the policy of the PostgreSQL Global Development Group not to make changes to disk formats
during minor release upgrades, so it is likely that running different minor release levels on primary
and standby servers will work successfully. However, no formal support for that is offered and you
http://pgdocptbr.sourceforge.net/pg82/warm-standby.html[09/02/2018 18:41:23]
are advised to keep primary and standby servers at the same release level as much as possible.
When updating to a new minor release, the safest policy is to update the standby servers first — a
new minor release is more likely to be able to read WAL files from a previous minor release than
vice versa.
There is no special mode required to enable a standby server. The operations that occur on both
primary and standby servers are entirely normal continuous archiving and recovery tasks. The only
point of contact between the two database servers is the archive of WAL files that both share:
primary writing to the archive, standby reading from the archive. Care must be taken to ensure that
WAL archives for separate primary servers do not become mixed together or confused.
The magic that makes the two loosely coupled servers work together is simply a restore_command
used on the standby that waits for the next WAL file to become available from the primary. The
restore_command is specified in the recovery.conf file on the standby server. Normal recovery
processing would request a file from the WAL archive, reporting failure if the file was unavailable.
For standby processing it is normal for the next file to be unavailable, so we must be patient and
wait for it to appear. A waiting restore_command can be written as a custom script that loops after
polling for the existence of the next WAL file. There must also be some way to trigger failover,
which should interrupt the restore_command, break the loop and return a file-not-found error to
the standby server. This ends recovery and the standby will then come up as a normal server.
Pseudocode for a suitable restore_command is:
triggered = false;
while (!NextWALFileReady() && !triggered)
{
sleep(100000L); /* wait for ~0.1 sec */
if (CheckForExternalTrigger())
triggered = true;
}
if (!triggered)
CopyWALFileForRecovery();
PostgreSQL does not provide the system software required to identify a failure on the primary and
notify the standby system and then the standby database server. Many such tools exist and are well
integrated with other aspects required for successful failover, such as IP address migration.
The means for triggering failover is an important part of planning and design. The
restore_command is executed in full once for each WAL file. The process running the
restore_command is therefore created and dies for each file, so there is no daemon or server
process and so we cannot use signals and a signal handler. A more permanent notification is
required to trigger the failover. It is possible to use a simple timeout facility, especially if used in
conjunction with a known archive_timeout setting on the primary. This is somewhat error prone
since a network problem or busy primary server might be sufficient to initiate failover. A notification
mechanism such as the explicit creation of a trigger file is less error prone, if this can be arranged.
23.4.2. Implementação
The short procedure for configuring a standby server is as follows. For full details of each step, refer
to previous sections as noted.
1. Set up primary and standby systems as near identically as possible, including two identical
copies of PostgreSQL at the same release level.
2. Set up continuous archiving from the primary to a WAL archive located in a directory on the
standby server. Ensure that archive_command and archive_timeout are set appropriately on the
primary (see Seção 23.3.1).
3. Make a base backup of the primary server (see Seção 23.3.2), and load this data onto the
standby.
4. Begin recovery on the standby server from the local WAL archive, using a recovery.conf that
specifies a restore_command that waits as described previously (see Seção 23.3.3).
Recovery treats the WAL archive as read-only, so once a WAL file has been copied to the standby
system it can be copied to tape at the same time as it is being read by the standby database
server. Thus, running a standby server for high availability can be performed at the same time as
files are stored for longer term disaster recovery purposes.
For testing purposes, it is possible to run both primary and standby servers on the same system.
This does not provide any worthwhile improvement in server robustness, nor would it be described
as HA.
23.4.3. Failover
If the primary server fails then the standby server should begin failover procedures.
If the standby server fails then no failover need take place. If the standby server can be restarted,
even some time later, then the recovery process can also be immediately restarted, taking
advantage of restartable recovery. If the standby server cannot be restarted, then a full new
standby server should be created.
If the primary server fails and then immediately restarts, you must have a mechanism for informing
it that it is no longer the primary. This is sometimes known as STONITH (Shoot the Other Node In
The Head), which is necessary to avoid situations where both systems think they are the primary,
which can lead to confusion and ultimately data loss.
Many failover systems use just two systems, the primary and the standby, connected by some kind
of heartbeat mechanism to continually verify the connectivity between the two and the viability of
the primary. It is also possible to use a third system (called a witness server) to avoid some
problems of inappropriate failover, but the additional complexity may not be worthwhile unless it is
set-up with sufficient care and rigorous testing.
Once failover to the standby occurs, we have only a single server in operation. This is known as a
degenerate state. The former standby is now the primary, but the former primary is down and may
stay down. To return to normal operation we must fully recreate a standby server, either on the
former primary system when it comes up, or on a third, possibly new, system. Once complete the
primary and standby can be considered to have switched roles. Some people choose to use a third
server to provide backup to the new primary until the new standby server is recreated, though
clearly this complicates the system configuration and operational processes.
So, switching from primary to standby server can be fast but requires some time to re-prepare the
failover cluster. Regular switching from primary to standby is encouraged, since it allows regular
downtime on each system for maintenance. This also acts as a test of the failover mechanism to
ensure that it will really work when you need it. Written administration procedures are advised.
23.4.4. Record-based Log Shipping
PostgreSQL directly supports file-based log shipping as described above. It is also possible to
implement record-based log shipping, though this requires custom development.
An external program can call the pg_xlogfile_name_offset() function (see Seção 9.20) to find out the
file name and the exact byte offset within it of the current end of WAL. It can then access the WAL
file directly and copy the data from the last known end of WAL through the current end over to the
standby server (s). With this approach, the window for data loss is the polling cycle time of the
copying program, which can be very small, but there is no wasted bandwidth from forcing partially-
used segment files to be archived. Note that the standby servers' restore_command scripts still deal
in whole WAL files, so the incrementally copied data is not ordinarily made available to the standby
servers. It is of use only when the primary dies — then the last partial WAL file is fed to the standby
before allowing it to come up. So correct implementation of this process requires cooperation of the
restore_command script with the data copying program.
23.4.5. Incrementally Updated Backups
In a warm standby configuration, it is possible to offload the expense of taking periodic base
backups from the primary server; instead base backups can be made by backing up a standby
server's files. This concept is generally known as incrementally updated backups, log change
accumulation or more simply, change accumulation.
If we take a backup of the standby server's files while it is following logs shipped from the primary,
we will be able to reload that data and restart the standby's recovery process from the last restart
point. We no longer need to keep WAL files from before the restart point. If we need to recover, it
will be faster to recover from the incrementally updated backup than from the original base backup.
Since the standby server is not "live", it is not possible to use pg_start_backup() and
pg_stop_backup() to manage the backup process; it will be up to you to determine how far back
you need to keep WAL segment files to have a recoverable backup. You can do this by running
pg_controldata on the standby server to inspect the control file and determine the current
checkpoint WAL location.

Continuous Archiving and Point-In- Acima Migration Between Releases
Time Recovery (PITR)
Migration Between Releases


This section discusses how to migrate your database data from one PostgreSQL release to a newer
one. The software installation procedure per se is not the subject of this section; those details are in
Capítulo 14.
As a general rule, the internal data storage format is subject to change between major releases of
PostgreSQL (where the number after the first dot changes). This does not apply to different minor
releases under the same major release (where the number after the second dot changes); these
always have compatible storage formats. For example, releases 7.2.1, 7.3.2, and 7.4 are not
compatible, whereas 7.2.1 and 7.2.2 are. When you update between compatible versions, you can
simply replace the executables and reuse the data directory on disk. Otherwise you need to back up
your data and restore it on the new server. This has to be done using pg_dump; file system level
backup methods obviously won't work. There are checks in place that prevent you from using a
data directory with an incompatible version of PostgreSQL, so no great harm can be done by trying
to start the wrong server version on a data directory.
It is recommended that you use the pg_dump and pg_dumpall programs from the newer version of
PostgreSQL, to take advantage of any enhancements that may have been made in these programs.
Current releases of the dump programs can read data from any server version back to 7.0.
The least downtime can be achieved by installing the new server in a different directory and running
both the old and the new servers in parallel, on different ports. Then you can use something like
pg_dumpall -p 5432 | psql -d postgres -p 6543
to transfer your data. Or use an intermediate file if you want. Then you can shut down the old
server and start the new server at the port the old one was running at. You should make sure that
the old database is not updated after you run pg_dumpall, otherwise you will obviously lose that
data. See Capítulo 20 for information on how to prohibit access.
In practice you probably want to test your client applications on the new setup before switching
over completely. This is another reason for setting up concurrent installations of old and new
versions.
If you cannot or do not want to run two servers in parallel you can do the backup step before
installing the new version, bring down the server, move the old version out of the way, install the
new version, start the new server, restore the data. For example:
pg_dumpall > backup

pg_ctl stop
mv /usr/local/pgsql /usr/local/pgsql.old
cd ~/postgresql-8.2.0
gmake install
initdb -D /usr/local/pgsql/data
postgres -D /usr/local/pgsql/data
psql -f backup postgres
See Capítulo 16 about ways to start and stop the server and other details. The installation
instructions will advise you of strategic places to perform these steps.
Nota: When you "move the old installation out of the way" it may no longer be perfectly
usable. Some of the executable programs contain absolute paths to various installed
programs and data files. This is usually not a big problem but if you plan on using two
http://pgdocptbr.sourceforge.net/pg82/migration.html[09/02/2018 18:41:52]
Migration Between Releases
installations in parallel for a while you should assign them different installation
directories at build time. (This problem is rectified in PostgreSQL 8.0 and later, but you
need to be wary of moving older installations.)

Warm Standby Servers for High Acima High Availability and Load
Availability Balancing
http://pgdocptbr.sourceforge.net/pg82/migration.html[09/02/2018 18:41:52]
High Availability and Load Balancing

Capítulo 24. High Availability and Load Balancing

Database servers can work together to allow a second server to take over quickly if the primary
server fails (high availability), or to allow several computers to serve the same data (load
balancing). Ideally, database servers could work together seamlessly. Web servers serving static
web pages can be combined quite easily by merely load-balancing web requests to multiple
machines. In fact, read-only database servers can be combined relatively easily too. Unfortunately,
most database servers have a read/write mix of requests, and read/write servers are much harder
to combine. This is because though read-only data needs to be placed on each server only once, a
write to any server has to be propagated to all servers so that future read requests to those servers
return consistent results.
This synchronization problem is the fundamental difficulty for servers working together. Because
there is no single solution that eliminates the impact of the sync problem for all use cases, there are
multiple solutions. Each solution addresses this problem in a different way, and minimizes its impact
for a specific workload.
Some solutions deal with synchronization by allowing only one server to modify the data. Servers
that can modify data are called read/write or "master" servers. Servers that can reply to read-only
queries are called "slave" servers. Servers that cannot be accessed until they are changed to
master servers are called "standby" servers.
Some failover and load balancing solutions are synchronous, meaning that a data-modifying
transaction is not considered committed until all servers have committed the transaction. This
guarantees that a failover will not lose any data and that all load-balanced servers will return
consistent results no matter which server is queried. In contrast, asynchronous solutions allow
some delay between the time of a commit and its propagation to the other servers, opening the
possibility that some transactions might be lost in the switch to a backup server, and that load
balanced servers might return slightly stale results. Asynchronous communication is used when
synchronous would be too slow.
Solutions can also be categorized by their granularity. Some solutions can deal only with an entire
database server, while others allow control at the per-table or per-database level.
Performance must be considered in any failover or load balancing choice. There is usually a tradeoff
between functionality and performance. For example, a full synchronous solution over a slow
network might cut performance by more than half, while an asynchronous one might have a
minimal performance impact.
The remainder of this section outlines various failover, replication, and load balancing solutions.
Shared Disk Failover
Shared disk failover avoids synchronization overhead by having only one copy of the
database. It uses a single disk array that is shared by multiple servers. If the main database
server fails, the standby server is able to mount and start the database as though it was
recovering from a database crash. This allows rapid failover with no data loss.
Shared hardware functionality is common in network storage devices. Using a network file
system is also possible, though care must be taken that the file system has full POSIX
behavior. One significant limitation of this method is that if the shared disk array fails or
becomes corrupt, the primary and standby servers are both nonfunctional. Another issue is
that the standby server should never access the shared storage while the primary server is
http://pgdocptbr.sourceforge.net/pg82/high-availability.html[09/02/2018 18:42:05]
running. It is also possible to use some type of file system mirroring to keep the standby
server current, but the mirroring must be done in a way that ensures the standby server has a
consistent copy of the file system.
Warm Standby Using Point-In-Time Recovery
A warm standby server (see Seção 23.4) can be kept current by reading a stream of write-
ahead log (WAL) records. If the main server fails, the warm standby contains almost all of the
data of the main server, and can be quickly made the new master database server. This is
asynchronous and can only be done for the entire database server.
Master-Slave Replication
A master-slave replication setup sends all data modification queries to the master server. The
master server asynchronously sends data changes to the slave server. The slave can answer
read-only queries while the master server is running. The slave server is ideal for data
warehouse queries.
Slony-I is an example of this type of replication, with per-table granularity, and support for
multiple slaves. Because it updates the slave server asynchronously (in batches), there is
possible data loss during fail over.
Statement-Based Replication Middleware
With statement-based replication middleware, a program intercepts every SQL query and
sends it to one or all servers. Each server operates independently. Read-write queries are sent
to all servers, while read-only queries can be sent to just one server, allowing the read
workload to be distributed.
If queries are simply broadcast unmodified, functions like random(), CURRENT_TIMESTAMP,

and sequences would have different values on different servers. This is because each server
operates independently, and because SQL queries are broadcast (and not actual modified
rows). If this is unacceptable, either the middleware or the application must query such values
from a single server and then use those values in write queries. Also, care must be taken that
all transactions either commit or abort on all servers, perhaps using two-phase commit
(PREPARE TRANSACTION and COMMIT PREPARED. Pgpool and Sequoia are an example of this
type of replication.
Synchronous Multi-Master Replication
In synchronous multi-master replication, each server can accept write requests, and modified
data is transmitted from the original server to every other server before each transaction
commits. Heavy write activity can cause excessive locking, leading to poor performance. In
fact, write performance is often worse than that of a single server. Read requests can be sent
to any server. Some implementations use shared disk to reduce the communication overhead.
Synchronous multi-master replication is best for mostly read workloads, though its big
advantage is that any server can accept write requests — there is no need to partition
workloads between master and slave servers, and because the data changes are sent from
one server to another, there is no problem with non-deterministic functions like random().
PostgreSQL does not offer this type of replication, though PostgreSQL two-phase commit
(PREPARE TRANSACTION and COMMIT PREPARED) can be used to implement this in application
code or middleware.
Asynchronous Multi-Master Replication
For servers that are not regularly connected, like laptops or remote servers, keeping data
consistent among servers is a challenge. Using asynchronous multi-master replication, each
server works independently, and periodically communicates with the other servers to identify
conflicting transactions. The conflicts can be resolved by users or conflict resolution rules.
Data Partitioning
Data partitioning splits tables into data sets. Each set can be modified by only one server. For
example, data can be partitioned by offices, e.g. London and Paris, with a server in each
office. If queries combining London and Paris data are necessary, an application can query
both servers, or master/slave replication can be used to keep a read-only copy of the other
office's data on each server.
Multi-Server Parallel Query Execution
Many of the above solutions allow multiple servers to handle multiple queries, but none allow
a single query to use multiple servers to complete faster. This solution allows multiple servers
to work concurrently on a single query. This is usually accomplished by splitting the data
among servers and having each server execute its part of the query and return results to a
central server where they are combined and returned to the user. Pgpool-II has this
capability.
Commercial Solutions
Because PostgreSQL is open source and easily extended, a number of companies have taken
PostgreSQL and created commercial closed-source solutions with unique failover, replication,
and load balancing capabilities.

Migration Between Releases Acima Monitoring Database Activity
Monitoring Database Activity

Capítulo 25. Monitoring Database Activity

Sumário
25.2.1. Statistics Collection Configuration

25.2.2. Viewing Collected Statistics
25.3. Viewing Locks

25.4.1. Compiling for Dynamic Trace

25.4.2. Built-in Trace Points
25.4.3. Using Trace Points
25.4.4. Defining Trace Points
A database administrator frequently wonders, "What is the system doing right now?" This chapter
discusses how to find that out.
Several tools are available for monitoring database activity and analyzing performance. Most of this
chapter is devoted to describing PostgreSQL's statistics collector, but one should not neglect regular
Unix monitoring programs such as ps, top, iostat, and vmstat. Also, once one has identified a
poorly-performing query, further investigation may be needed using PostgreSQL's EXPLAIN
command. Seção 13.1 discusses EXPLAIN and other methods for understanding the behavior of an
individual query.

High Availability and Load Acima Standard Unix Tools
Balancing
http://pgdocptbr.sourceforge.net/pg82/monitoring.html[09/02/2018 18:42:17]
Standard Unix Tools

Anterior Início Capítulo 25. Monitoring Database Activity Fim Próxima

On most platforms, PostgreSQL modifies its command title as reported by ps, so that individual
server processes can readily be identified. A sample display is
$ ps auxww | grep ^postgres

postgres 960 0.0 1.1 6104 1480 pts/1 SN 13:17 0:00 postgres -i
postgres 963 0.0 1.1 7084 1472 pts/1 SN 13:17 0:00 postgres: writer process
postgres 965 0.0 1.1 6152 1512 pts/1 SN 13:17 0:00 postgres: stats collector
process
postgres 998 0.0 2.3 6532 2992 pts/1 SN 13:18 0:00 postgres: tgl runbug
127.0.0.1 idle
postgres 1003 0.0 2.4 6532 3128 pts/1 SN 13:19 0:00 postgres: tgl regression
[local] SELECT waiting
postgres 1016 0.1 2.4 6532 3080 pts/1 SN 13:19 0:00 postgres: tgl regression
[local] idle in transaction
(The appropriate invocation of ps varies across different platforms, as do the details of what is
shown. This example is from a recent Linux system.) The first process listed here is the master
server process. The command arguments shown for it are the same ones given when it was
launched. The next two processes are background worker processes automatically launched by the
master process. (The "stats collector" process will not be present if you have set the system not to
start the statistics collector.) Each of the remaining processes is a server process handling one
client connection. Each such process sets its command line display in the form
postgres: usuário banco_de_dados hospedeiro atividade
The user, database, and connection source host items remain the same for the life of the client
connection, but the activity indicator changes. The activity may be idle (i.e., waiting for a client
command), idle in transaction (waiting for client inside a BEGIN block), or a command type name
such as SELECT. Also, waiting is attached if the server process is presently waiting on a lock held by
another server process. In the above example we can infer that process 1003 is waiting for process
1016 to complete its transaction and thereby release some lock or other.
If you have turned off update_process_title then the activity indicator is not updated; the process
title is set only once when a new process is launched. On some platforms this saves a useful
amount of per-command overhead, on others it's insignificant.
Dica: Solaris requires special handling. You must use /usr/ucb/ps, rather than /bin/ps.
You also must use two w flags, not just one. In addition, your original invocation of the
postgres command must have a shorter ps status display than that provided by each
server process. If you fail to do all three things, the ps output for each server process
will be the original postgres command line.

Monitoring Database Activity Acima The Statistics Collector
http://pgdocptbr.sourceforge.net/pg82/monitoring-ps.html[09/02/2018 18:42:28]
The Statistics Collector


PostgreSQL's statistics collector is a subsystem that supports collection and reporting of information
about server activity. Presently, the collector can count accesses to tables and indexes in both disk-
block and individual-row terms.
PostgreSQL also supports determining the exact command currently being executed by other server
processes. This is an independent facility that can be enabled or disabled whether or not block-level
and row-level statistics are being collected.
25.2.1. Statistics Collection Configuration
Since collection of statistics adds some overhead to query execution, the system can be configured
to collect or not collect information. This is controlled by configuration parameters that are normally
set in postgresql.conf. (See Capítulo 17 for details about setting configuration parameters.)
The parameter stats_start_collector must be set to true for the statistics collector to be launched at
all. This is the default and recommended setting, but it may be turned off if you have no interest in
statistics and want to squeeze out every last drop of overhead. (The savings is likely to be small,
however.) Note that this option cannot be changed while the server is running.
The parameters stats_block_level and stats_row_level control how much information is actually sent
to the collector and thus determine how much run-time overhead occurs. These respectively
determine whether a server process tracks disk-block-level access statistics and row-level access
statistics and sends these to the collector. Additionally, per-database transaction commit and abort
statistics are collected if either of these parameters are set.
The parameter stats_command_string enables monitoring of the current command being executed by
any server process. The statistics collector subprocess need not be running to enable this feature.
Normally these parameters are set in postgresql.conf so that they apply to all server processes, but
it is possible to turn them on or off in individual sessions using the SET command. (To prevent
ordinary users from hiding their activity from the administrator, only superusers are allowed to
change these parameters with SET.)
Nota: Since the parameters stats_block_level, and stats_row_level default to false, very
few statistics are collected in the default configuration. Enabling either of these
configuration variables will significantly increase the amount of useful data produced by
the statistics facilities, at the expense of additional run-time overhead.
25.2.2. Viewing Collected Statistics
Several predefined views, listed in Tabela 25-1, are available to show the results of statistics
collection. Alternatively, one can build custom views using the underlying statistics functions.
When using the statistics to monitor current activity, it is important to realize that the information
does not update instantaneously. Each individual server process transmits new block and row
access counts to the collector just before going idle; so a query or transaction still in progress does
not affect the displayed totals. Also, the collector itself emits a new report at most once per
PGSTAT_STAT_INTERVAL milliseconds (500 unless altered while building the server). So the
displayed information lags behind actual activity. However, current-query information collected by
stats_command_string is always up-to-date.
http://pgdocptbr.sourceforge.net/pg82/monitoring-stats.html[09/02/2018 18:42:40]
Another important point is that when a server process is asked to display any of these statistics, it
first fetches the most recent report emitted by the collector process and then continues to use this
snapshot for all statistical views and functions until the end of its current transaction. So the
statistics will appear not to change as long as you continue the current transaction. Similarly,
information about the current queries of all processes is collected when any such information is first
requested within a transaction, and the same information will be displayed throughout the
transaction. This is a feature, not a bug, because it allows you to perform several queries on the
statistics and correlate the results without worrying that the numbers are changing underneath you.
But if you want to see new results with each query, be sure to do the queries outside any
transaction block.
Tabela 25-1. Standard Statistics Views
View Name Description

pg_stat_activity One row per server process, showing database OID, database name,
process ID, user OID, user name, current query, query's waiting status,
time at which the current query began execution, time at which the
process was started, and client's address and port number. The columns
that report data on the current query are available unless the parameter
stats_command_string has been turned off. Furthermore, these columns
are only visible if the user examining the view is a superuser or the same
as the user owning the process being reported on.
pg_stat_database One row per database, showing database OID, database name, number of
active server processes connected to that database, number of
transactions committed and rolled back in that database, total disk blocks
read, and total buffer hits (i.e., block read requests avoided by finding the
block already in buffer cache).
pg_stat_all_tables For each table in the current database (including TOAST tables), the table
OID, schema and table name, number of sequential scans initiated,
number of live rows fetched by sequential scans, number of index scans
initiated (over all indexes belonging to the table), number of live rows
fetched by index scans, numbers of row insertions, updates, and deletions,
the last time the table was vacuumed manually, the last time it was
vacuumed by the autovacuum daemon, the last time it was analyzed
manually, and the last time it was analyzed by the autovacuum daemon.
pg_stat_sys_tables Same as pg_stat_all_tables, except that only system tables are shown.
pg_stat_user_tables Same as pg_stat_all_tables, except that only user tables are shown.
pg_stat_all_indexes For each index in the current database, the table and index OID, schema,
table and index name, number of index scans initiated on that index,
number of index entries returned by index scans, and number of live table
rows fetched by simple index scans using that index.
pg_stat_sys_indexes Same as pg_stat_all_indexes, except that only indexes on system tables
are shown.
pg_stat_user_indexes Same as pg_stat_all_indexes, except that only indexes on user tables are
shown.
pg_statio_all_tables For each table in the current database (including TOAST tables), the table
OID, schema and table name, number of disk blocks read from that table,
number of buffer hits, numbers of disk blocks read and buffer hits in all
indexes of that table, numbers of disk blocks read and buffer hits from that
table's auxiliary TOAST table (if any), and numbers of disk blocks read and
buffer hits for the TOAST table's index.
pg_statio_sys_tables Same as pg_statio_all_tables, except that only system tables are shown.
pg_statio_user_tables Same as pg_statio_all_tables, except that only user tables are shown.
pg_statio_all_indexes For each index in the current database, the table and index OID, schema,
table and index name, numbers of disk blocks read and buffer hits in that
index.
pg_statio_sys_indexes Same as pg_statio_all_indexes, except that only indexes on system tables
are shown.
pg_statio_user_indexes Same as pg_statio_all_indexes, except that only indexes on user tables are
shown.
pg_statio_all_sequences For each sequence object in the current database, the sequence OID,
schema and sequence name, numbers of disk blocks read and buffer hits in
that sequence.
pg_statio_sys_sequences Same as pg_statio_all_sequences, except that only system sequences are
shown. (Presently, no system sequences are defined, so this view is always
empty.)
pg_statio_user_sequences Same as pg_statio_all_sequences, except that only user sequences are
shown.
The per-index statistics are particularly useful to determine which indexes are being used and how
effective they are.
Beginning in PostgreSQL 8.1, indexes can be used either directly or via "bitmap scans". In a bitmap
scan the output of several indexes can be combined via AND or OR rules; so it is difficult to
associate individual heap row fetches with specific indexes when a bitmap scan is used. Therefore, a
bitmap scan increments the pg_stat_all_indexes.idx_tup_read count(s) for the index(es) it uses,
and it increments the pg_stat_all_tables.idx_tup_fetch count for the table, but it does not affect
pg_stat_all_indexes.idx_tup_fetch.
Nota: Before PostgreSQL 8.1, the idx_tup_read and idx_tup_fetch counts were
essentially always equal. Now they can be different even without considering bitmap
scans, because idx_tup_read counts index entries retrieved from the index while
idx_tup_fetch counts live rows fetched from the table; the latter will be less if any dead
or not-yet-committed rows are fetched using the index.
The pg_statio_ views are primarily useful to determine the effectiveness of the buffer cache. When
the number of actual disk reads is much smaller than the number of buffer hits, then the cache is
satisfying most read requests without invoking a kernel call. However, these statistics do not give
the entire story: due to the way in which PostgreSQL handles disk I/O, data that is not in the
PostgreSQL buffer cache may still reside in the kernel's I/O cache, and may therefore still be
fetched without requiring a physical read. Users interested in obtaining more detailed information
on PostgreSQL I/O behavior are advised to use the PostgreSQL statistics collector in combination
with operating system utilities that allow insight into the kernel's handling of I/O.
Other ways of looking at the statistics can be set up by writing queries that use the same
underlying statistics access functions as these standard views do. These functions are listed in
Tabela 25-2. The per-database access functions take a database OID as argument to identify which
database to report on. The per-table and per-index functions take a table or index OID. (Note that
only tables and indexes in the current database can be seen with these functions.) The per-server-
process access functions take a server process number, which ranges from one to the number of
currently active server processes.
Tabela 25-2. Statistics Access Functions
Return
Type
pg_stat_get_db_numbackends(oid) integer Number of active server processes for
database
pg_stat_get_db_xact_commit(oid) bigint Transactions committed in database
pg_stat_get_db_xact_rollback(oid) bigint Transactions rolled back in database
pg_stat_get_db_blocks_fetched(oid) bigint Number of disk block fetch requests for
database
pg_stat_get_db_blocks_hit(oid) bigint Number of disk block fetch requests found
in cache for database
pg_stat_get_numscans(oid) bigint Number of sequential scans done when
argument is a table, or number of index
scans done when argument is an index
pg_stat_get_tuples_returned(oid) bigint Number of rows read by sequential scans

when argument is a table, or number of
index entries returned when argument is an
index
pg_stat_get_tuples_fetched(oid) bigint Number of table rows fetched by bitmap
scans when argument is a table, or table
rows fetched by simple index scans using
the index when argument is an index
pg_stat_get_tuples_inserted(oid) bigint Number of rows inserted into table
pg_stat_get_tuples_updated(oid) bigint Number of rows updated in table
pg_stat_get_tuples_deleted(oid) bigint Number of rows deleted from table
pg_stat_get_blocks_fetched(oid) bigint Number of disk block fetch requests for
table or index
pg_stat_get_blocks_hit(oid) bigint Number of disk block requests found in
cache for table or index
pg_stat_get_last_vacuum_time(oid) timestamptz Time of the last vacuum initiated by the
user on this table
pg_stat_get_last_autovacuum_time(oid) timestamptz Time of the last vacuum initiated by the
autovacuum daemon on this table
pg_stat_get_last_analyze_time(oid) timestamptz Time of the last analyze initiated by the
user on this table
pg_stat_get_last_autoanalyze_time(oid) timestamptz Time of the last analyze initiated by the
autovacuum daemon on this table
pg_stat_get_backend_idset() setof Set of currently active server process
integer numbers (from 1 to the number of active
server processes). See usage example in
the text
pg_backend_pid() integer Process ID of the server process attached
to the current session
pg_stat_get_backend_pid(integer) integer Process ID of the given server process
pg_stat_get_backend_dbid(integer) oid Database ID of the given server process
pg_stat_get_backend_userid(integer) oid User ID of the given server process
pg_stat_get_backend_activity(integer) text Active command of the given server
process, but only if the current user is a
superuser or the same user as that of the
session being queried (and
stats_command_string is on)
pg_stat_get_backend_waiting(integer) boolean True if the given server process is waiting
for a lock, but only if the current user is a
superuser or the same user as that of the
session being queried (and
stats_command_string is on)
pg_stat_get_backend_activity_start(integer) timestamp The time at which the given server process'
with time currently executing query was started, but
zone only if the current user is a superuser or
the same user as that of the session being
queried (and stats_command_string is on)
pg_stat_get_backend_start(integer) timestamp The time at which the given server process
with time was started, or null if the current user is
zone not a superuser nor the same user as that
of the session being queried
pg_stat_get_backend_client_addr(integer) inet The IP address of the client connected to
the given server process. Null if the
connection is over a Unix domain socket.
Also null if the current user is not a
superuser nor the same user as that of the
session being queried
pg_stat_get_backend_client_port(integer) integer The IP port number of the client connected
to the given server process. -1 if the

connection is over a Unix domain socket.
Null if the current user is not a superuser
nor the same user as that of the session
being queried
pg_stat_reset() boolean Reset all block-level and row-level statistics
to zero
Nota: blocks_fetched minus blocks_hit gives the number of kernel read() calls issued for
the table, index, or database; but the actual number of physical reads is usually lower
due to kernel-level buffering.
The function pg_stat_get_backend_idset provides a convenient way to generate one row for each
active server process. For example, to show the PIDs and current queries of all server processes:
SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,

pg_stat_get_backend_activity(s.backendid) AS current_query
FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS s;

Standard Unix Tools Acima Viewing Locks
Viewing Locks

25.3. Viewing Locks

Another useful tool for monitoring database activity is the pg_locks system table. It allows the
database administrator to view information about the outstanding locks in the lock manager. For
example, this capability can be used to:
View all the locks currently outstanding, all the locks on relations in a particular database, all
the locks on a particular relation, or all the locks held by a particular PostgreSQL session.
Determine the relation in the current database with the most ungranted locks (which might be
a source of contention among database clients).
Determine the effect of lock contention on overall database performance, as well as the extent
to which contention varies with overall database traffic.
Details of the pg_locks view appear in Seção 43.39. For more information on locking and managing
concurrency with PostgreSQL, refer to Capítulo 12.

The Statistics Collector Acima Dynamic Tracing
http://pgdocptbr.sourceforge.net/pg82/monitoring-locks.html[09/02/2018 18:42:51]
Dynamic Tracing


PostgreSQL provides facilities to support dynamic tracing of the database server. This allows an
external utility to be called at specific points in the code and thereby trace execution. Currently, this
facility is primarily intended for use by database developers, as it requires substantial familiarity
with the code.
A number of trace points, often called probes, are already inserted into the source code. By default
these probes are disabled, and the user needs to explicitly tell the configure script to make the
probes available in PostgreSQL.
Currently, only the DTrace utility is supported, which is only available on Solaris Express and Solaris
10+. It is expected that DTrace will be available in the future on FreeBSD and Mac OS X.
Supporting other dynamic tracing utilities is theoretically possible by changing the definitions for the
PG_TRACE macros in src/include/pg_trace.h.
25.4.1. Compiling for Dynamic Trace
By default, trace points are disabled, so you will need to explicitly tell the configure script to make
the probes available in PostgreSQL. To include DTrace support in a 32-bit binary, specify --enable-
dtrace to configure. For example:
$ ./configure --enable-dtrace ...
To include DTrace support in a 64-bit binary, specify --enable-dtrace and DTRACEFLAGS="-64" to

configure. For example, using the gcc compiler:
$ ./configure CC='gcc -m64' --enable-dtrace DTRACEFLAGS='-64' ...
Using Sun's compiler:
$ ./configure CC='/path_to_sun_compiler/cc -xtarget=native64' --enable-dtrace

DTRACEFLAGS='-64' ...
25.4.2. Built-in Trace Points
A few standard trace points are provided in the source code (of course, more can be added as
needed for a particular problem). These are:
Tabela 25-3. Built-in Trace Points
Name Parameters Overview

transaction__start (int The start of a new transaction.
transactionId)
transaction__commit (int The successful completion of a transaction.
transactionId)
transaction__abort (int The unsuccessful completion of a transaction.
http://pgdocptbr.sourceforge.net/pg82/dynamic-trace.html[09/02/2018 18:43:09]
Dynamic Tracing
transactionId)
lwlock__acquire (int lockid, int An LWLock has been acquired.
mode)
lwlock__release (int lockid, int An LWLock has been released.
mode)
lwlock__startwait (int lockid, int An LWLock was not immediately available and a backend
mode) has begun to wait for the lock to become available.
lwlock__endwait (int lockid, int A backend has been released from its wait for an
mode) LWLock.
lwlock__condacquire (int lockid, int An LWLock was successfully acquired when the caller
mode) specified no waiting.
lwlock__condacquire__fail (int lockid, int An LWLock was not successfully acquired when the caller
mode) specified no waiting.
lock__startwait (int A request for a heavyweight lock (lmgr lock) has begun
locktag_field2, to wait because the lock is not available.
int lockmode)
lock__endwait (int A request for a heavyweight lock (lmgr lock) has finished
locktag_field2, waiting (i.e., has acquired the lock).
int lockmode)
25.4.3. Using Trace Points
The example below shows a DTrace script for analyzing transaction counts on the system, as an
alternative to snapshotting pg_stat_database before and after a performance test.
#!/usr/sbin/dtrace -qs
postgresql$1:::transaction-start
{
@start["Start"] = count();
self->ts = timestamp;
}
postgresql$1:::transaction-abort
{
@abort["Abort"] = count();
}
postgresql$1:::transaction-commit
/self->ts/
{
@commit["Commit"] = count();
@time["Total time (ns)"] = sum(timestamp - self->ts);
self->ts=0;
}
Note how the double underline in trace point names needs to be replaced by a hyphen when using
D script. When executed, the example D script gives output such as:
# ./txn_count.d `pgrep -n postgres`

^C
Start 71
Commit 70
Abort 1
Total time (ns) 2312105013
You should remember that trace programs need to be carefully written and debugged prior to their
use, otherwise the trace information collected may be meaningless. In most cases where problems
are found it is the instrumentation that is at fault, not the underlying system. When discussing
information found using dynamic tracing, be sure to enclose the script used to allow that too to be
checked and discussed.
25.4.4. Defining Trace Points
New trace points can be defined within the code wherever the developer desires, though this will
require a re-compile.
Dynamic Tracing
A trace point can be inserted by using one of the trace macros. These are chosen according to how
many variables will be made available for inspection at that trace point. Tracing the occurrence of
an event can be achieved with a single line, using just the trace point name, e.g.
PG_TRACE (my__new__trace__point);
More complex trace points can be provided with one or more variables for inspection by the
dynamic tracing utility by using the PG_TRACEn macro that corresponds to the number of
parameters after the trace point name:
PG_TRACE3 (my__complex__event, varX, varY, varZ);
The definition of the transaction__start trace point is shown below:
static void
StartTransaction(void)
{
...
/*
* generate a new transaction id
*/
s->transactionId = GetNewTransactionId(false);
XactLockTableInsert(s->transactionId);
PG_TRACE1(transaction__start, s->transactionId);
...
}
Note how the transaction ID is made available to the dynamic tracing utility.
The dynamic tracing utility may require you to further define these trace points. For example,
DTrace requires you to add new probes to the file src/backend/utils/probes.d as shown here:
provider postgresql {
...
probe transaction__start(int);
...
};
You should take care that the datatypes specified for the probe arguments match the datatypes of
the variables used in the PG_TRACE macro. This is not checked at compile time. You can check that
your newly added trace point is available by recompiling, then running the new binary, and as root,
executing a DTrace command such as:
dtrace -l -n transaction-start

Viewing Locks Acima Monitoring Disk Usage
Monitoring Disk Usage

Capítulo 26. Monitoring Disk Usage

Sumário
This chapter discusses how to monitor the disk usage of a PostgreSQL database system.

Dynamic Tracing Acima Determining Disk Usage
http://pgdocptbr.sourceforge.net/pg82/diskusage.html[09/02/2018 18:43:37]
Determining Disk Usage

Anterior Início Capítulo 26. Monitoring Disk Usage Fim Próxima

Each table has a primary heap disk file where most of the data is stored. If the table has any
columns with potentially-wide values, there is also a TOAST file associated with the table, which is
used to store values too wide to fit comfortably in the main table (see Seção 52.2). There will be one
index on the TOAST table, if present. There may also be indexes associated with the base table.
Each table and index is stored in a separate disk file — possibly more than one file, if the file would
exceed one gigabyte. Naming conventions for these files are described in Seção 52.1.
You can monitor disk space from three ways: using SQL functions listed in Tabela 9-48, using
VACUUM information, and from the command line using the tools in contrib/oid2name. The SQL
functions are the easiest to use and report information about tables, tables with indexes and long
value storage (TOAST), databases, and tablespaces.
Using psql on a recently vacuumed or analyzed database, you can issue queries to see the disk
usage of any table:
SELECT relfilenode, relpages FROM pg_class WHERE relname = 'customer';

relfilenode | relpages
-------------+----------
16806 | 60
(1 row)
Each page is typically 8 kilobytes. (Remember, relpages is only updated by VACUUM, ANALYZE, and
a few DDL commands such as CREATE INDEX.) The relfilenode value is of interest if you want to
examine the table's disk file directly.
To show the space used by TOAST tables, use a query like the following:
SELECT relname, relpages

FROM pg_class,
(SELECT reltoastrelid FROM pg_class
WHERE relname = 'customer') ss
WHERE oid = ss.reltoastrelid
OR oid = (SELECT reltoastidxid FROM pg_class
WHERE oid = ss.reltoastrelid)
ORDER BY relname;
relname | relpages
----------------------+----------
pg_toast_16806 | 0
pg_toast_16806_index | 1
You can easily display index sizes, too:
SELECT c2.relname, c2.relpages

FROM pg_class c, pg_class c2, pg_index i
WHERE c.relname = 'customer'
AND c.oid = i.indrelid
AND c2.oid = i.indexrelid
ORDER BY c2.relname;
relname | relpages
----------------------+----------
customer_id_indexdex | 26
It is easy to find your largest tables and indexes using this information:
SELECT relname, relpages FROM pg_class ORDER BY relpages DESC;
http://pgdocptbr.sourceforge.net/pg82/disk-usage.html[09/02/2018 18:43:50]
Determining Disk Usage
relname | relpages
----------------------+----------
bigtable | 3290
customer | 3144
You can also use contrib/oid2name to show disk usage. See README.oid2name in that directory for
examples. It includes a script that shows disk usage for each database.

Monitoring Disk Usage Acima Disk Full Failure
http://pgdocptbr.sourceforge.net/pg82/disk-usage.html[09/02/2018 18:43:50]
Disk Full Failure

Anterior Início Capítulo 26. Monitoring Disk Usage Fim Próxima

The most important disk monitoring task of a database administrator is to make sure the disk
doesn't grow full. A filled data disk will not result in data corruption, but it may well prevent useful
activity from occurring. If the disk holding the WAL files grows full, database server panic and
consequent shutdown may occur.
If you cannot free up additional space on the disk by deleting other things, you can move some of
the database files to other file systems by making use of tablespaces. See Seção 19.6 for more
information about that.
Dica: Some file systems perform badly when they are almost full, so do not wait until
the disk is completely full to take action.
If your system supports per-user disk quotas, then the database will naturally be subject to
whatever quota is placed on the user the server runs as. Exceeding the quota will have the same
bad effects as running out of space entirely.

Determining Disk Usage Acima Reliability and the Write-Ahead Log
http://pgdocptbr.sourceforge.net/pg82/disk-full.html[09/02/2018 18:43:58]
Reliability and the Write-Ahead Log

Capítulo 27. Reliability and the Write-Ahead Log

Sumário
27.1. Reliability
27.4. WAL Internals
This chapter explain how the Write-Ahead Log is used to obtain efficient, reliable operation.

Disk Full Failure Acima Reliability
http://pgdocptbr.sourceforge.net/pg82/wal.html[09/02/2018 18:44:22]
Reliability

Anterior Início Capítulo 27. Reliability and the Write-Ahead Log Fim Próxima
27.1. Reliability
Reliability is an important property of any serious database system, and PostgreSQL does
everything possible to guarantee reliable operation. One aspect of reliable operation is that all data
recorded by a committed transaction should be stored in a nonvolatile area that is safe from power
loss, operating system failure, and hardware failure (except failure of the nonvolatile area itself, of
course). Successfully writing the data to the computer's permanent storage (disk drive or
equivalent) ordinarily meets this requirement. In fact, even if a computer is fatally damaged, if the
disk drives survive they can be moved to another computer with similar hardware and all
committed transactions will remain intact.
While forcing data periodically to the disk platters might seem like a simple operation, it is not.
Because disk drives are dramatically slower than main memory and CPUs, several layers of caching
exist between the computer's main memory and the disk platters. First, there is the operating
system's buffer cache, which caches frequently requested disk blocks and combines disk writes.
Fortunately, all operating systems give applications a way to force writes from the buffer cache to
disk, and PostgreSQL uses those features. (See the wal_sync_method parameter to adjust how this
is done.)
Next, there may be a cache in the disk drive controller; this is particularly common on RAID
controller cards. Some of these caches are write-through, meaning writes are passed along to the
drive as soon as they arrive. Others are write-back, meaning data is passed on to the drive at some
later time. Such caches can be a reliability hazard because the memory in the disk controller cache
is volatile, and will lose its contents in a power failure. Better controller cards have battery-backed
caches, meaning the card has a battery that maintains power to the cache in case of system power
loss. After power is restored the data will be written to the disk drives.
And finally, most disk drives have caches. Some are write-through while some are write-back, and
the same concerns about data loss exist for write-back drive caches as exist for disk controller
caches. Consumer-grade IDE drives are particularly likely to contain write-back caches that will not
survive a power failure.
When the operating system sends a write request to the disk hardware, there is little it can do to
make sure the data has arrived at a truly non-volatile storage area. Rather, it is the administrator's
responsibility to be sure that all storage components ensure data integrity. Avoid disk controllers
that have non-battery-backed write caches. At the drive level, disable write-back caching if the
drive cannot guarantee the data will be written before shutdown.
Another risk of data loss is posed by the disk platter write operations themselves. Disk platters are
divided into sectors, commonly 512 bytes each. Every physical read or write operation processes a
whole sector. When a write request arrives at the drive, it might be for 512 bytes, 1024 bytes, or
8192 bytes, and the process of writing could fail due to power loss at any time, meaning some of
the 512-byte sectors were written, and others were not. To guard against such failures, PostgreSQL
periodically writes full page images to permanent storage before modifying the actual page on disk.
By doing this, during crash recovery PostgreSQL can restore partially-written pages. If you have a
battery-backed disk controller or file-system software that prevents partial page writes (e.g.,
ReiserFS 4), you can turn off this page imaging by using the full_page_writes parameter.

Reliability and the Write-Ahead Log Acima Write-Ahead Logging (WAL)
http://pgdocptbr.sourceforge.net/pg82/wal-reliability.html[09/02/2018 18:44:36]
Write-Ahead Logging (WAL)


Write-Ahead Logging (WAL) is a standard approach to transaction logging. Its detailed description
may be found in most (if not all) books about transaction processing. Briefly, WAL's central concept
is that changes to data files (where tables and indexes reside) must be written only after those
changes have been logged, that is, when log records describing the changes have been flushed to
permanent storage. If we follow this procedure, we do not need to flush data pages to disk on every
transaction commit, because we know that in the event of a crash we will be able to recover the
database using the log: any changes that have not been applied to the data pages can be redone
from the log records. (This is roll-forward recovery, also known as REDO.)
A major benefit of using WAL is a significantly reduced number of disk writes, because only the log
file needs to be flushed to disk at the time of transaction commit, rather than every data file
changed by the transaction. In multiuser environments, commits of many transactions may be
accomplished with a single fsync of the log file. Furthermore, the log file is written sequentially, and
so the cost of syncing the log is much less than the cost of flushing the data pages. This is
especially true for servers handling many small transactions touching different parts of the data
store.
WAL also makes it possible to support on-line backup and point-in-time recovery, as described in
Seção 23.3. By archiving the WAL data we can support reverting to any time instant covered by the
available WAL data: we simply install a prior physical backup of the database, and replay the WAL
log just as far as the desired time. What's more, the physical backup doesn't have to be an
instantaneous snapshot of the database state — if it is made over some period of time, then
replaying the WAL log for that period will fix any internal inconsistencies.

Reliability Acima WAL Configuration
http://pgdocptbr.sourceforge.net/pg82/wal-intro.html[09/02/2018 18:44:46]
WAL Configuration


There are several WAL-related configuration parameters that affect database performance. This
section explains their use. Consult Capítulo 17 for general information about setting server
configuration parameters.
Checkpoints are points in the sequence of transactions at which it is guaranteed that the data files
have been updated with all information written before the checkpoint. At checkpoint time, all dirty
data pages are flushed to disk and a special checkpoint record is written to the log file. In the event
of a crash, the crash recovery procedure looks at the latest checkpoint record to determine the
point in the log (known as the redo record) from which it should start the REDO operation. Any
changes made to data files before that point are known to be already on disk. Hence, after a
checkpoint has been made, any log segments preceding the one containing the redo record are no
longer needed and can be recycled or removed. (When WAL archiving is being done, the log
segments must be archived before being recycled or removed.)
The server's background writer process will automatically perform a checkpoint every so often. A
checkpoint is created every checkpoint_segments log segments, or every checkpoint_timeout seconds,
whichever comes first. The default settings are 3 segments and 300 seconds respectively. It is also
possible to force a checkpoint by using the SQL command CHECKPOINT.
Reducing checkpoint_segments and/or checkpoint_timeout causes checkpoints to be done more

often. This allows faster after-crash recovery (since less work will need to be redone). However, one
must balance this against the increased cost of flushing dirty data pages more often. If
full_page_writes is set (as is the default), there is another factor to consider. To ensure data page
consistency, the first modification of a data page after each checkpoint results in logging the entire
page content. In that case, a smaller checkpoint interval increases the volume of output to the WAL
log, partially negating the goal of using a smaller interval, and in any case causing more disk I/O.
Checkpoints are fairly expensive, first because they require writing out all currently dirty buffers,
and second because they result in extra subsequent WAL traffic as discussed above. It is therefore
wise to set the checkpointing parameters high enough that checkpoints don't happen too often. As a
simple sanity check on your checkpointing parameters, you can set the checkpoint_warning
parameter. If checkpoints happen closer together than checkpoint_warning seconds, a message will
be output to the server log recommending increasing checkpoint_segments. Occasional appearance
of such a message is not cause for alarm, but if it appears often then the checkpoint control
parameters should be increased. Bulk operations such as large COPY transfers may cause a number
of such warnings to appear if you have not set checkpoint_segments high enough.
There will be at least one WAL segment file, and will normally not be more than 2 *
checkpoint_segments + 1 files. Each segment file is normally 16 MB (though this size can be
altered when building the server). You can use this to estimate space requirements for WAL.
Ordinarily, when old log segment files are no longer needed, they are recycled (renamed to become
the next segments in the numbered sequence). If, due to a short-term peak of log output rate,
there are more than 2 * checkpoint_segments + 1 segment files, the unneeded segment files will
be deleted instead of recycled until the system gets back under this limit.
There are two commonly used internal WAL functions: LogInsert and LogFlush. LogInsert is used to
place a new record into the WAL buffers in shared memory. If there is no space for the new record,
LogInsert will have to write (move to kernel cache) a few filled WAL buffers. This is undesirable
because LogInsert is used on every database low level modification (for example, row insertion) at
a time when an exclusive lock is held on affected data pages, so the operation needs to be as fast
http://pgdocptbr.sourceforge.net/pg82/wal-configuration.html[09/02/2018 18:44:56]
WAL Configuration
as possible. What is worse, writing WAL buffers may also force the creation of a new log segment,
which takes even more time. Normally, WAL buffers should be written and flushed by a LogFlush
request, which is made, for the most part, at transaction commit time to ensure that transaction
records are flushed to permanent storage. On systems with high log output, LogFlush requests may
not occur often enough to prevent LogInsert from having to do writes. On such systems one should
increase the number of WAL buffers by modifying the configuration parameter wal_buffers. The
default number of WAL buffers is 8. Increasing this value will correspondingly increase shared
memory usage. When full_page_writes is set and the system is very busy, setting this value higher
will help smooth response times during the period immediately following each checkpoint.
The commit_delay parameter defines for how many microseconds the server process will sleep after
writing a commit record to the log with LogInsert but before performing a LogFlush. This delay
allows other server processes to add their commit records to the log so as to have all of them
flushed with a single log sync. No sleep will occur if fsync is not enabled, nor if fewer than
commit_siblings other sessions are currently in active transactions; this avoids sleeping when it's
unlikely that any other session will commit soon. Note that on most platforms, the resolution of a
sleep request is ten milliseconds, so that any nonzero commit_delay setting between 1 and 10000
microseconds would have the same effect. Good values for these parameters are not yet clear;
experimentation is encouraged.
The wal_sync_method parameter determines how PostgreSQL will ask the kernel to force WAL
updates out to disk. All the options should be the same as far as reliability goes, but it's quite
platform-specific which one will be the fastest. Note that this parameter is irrelevant if fsync has
been turned off.
Enabling the wal_debug configuration parameter (provided that PostgreSQL has been compiled with
support for it) will result in each LogInsert and LogFlush WAL call being logged to the server log.
This option may be replaced by a more general mechanism in the future.

Write-Ahead Logging (WAL) Acima WAL Internals
http://pgdocptbr.sourceforge.net/pg82/wal-configuration.html[09/02/2018 18:44:56]
WAL Internals

27.4. WAL Internals

WAL is automatically enabled; no action is required from the administrator except ensuring that the
disk-space requirements for the WAL logs are met, and that any necessary tuning is done (see
Seção 27.3).
WAL logs are stored in the directory pg_xlog under the data directory, as a set of segment files,
normally each 16 MB in size. Each segment is divided into pages, normally 8 kB each. The log
record headers are described in access/xlog.h; the record content is dependent on the type of event
that is being logged. Segment files are given ever-increasing numbers as names, starting at
000000010000000000000000. The numbers do not wrap, at present, but it should take a very very
long time to exhaust the available stock of numbers.
It is of advantage if the log is located on another disk than the main database files. This may be
achieved by moving the directory pg_xlog to another location (while the server is shut down, of
course) and creating a symbolic link from the original location in the main data directory to the new
location.
The aim of WAL, to ensure that the log is written before database records are altered, may be
subverted by disk drives that falsely report a successful write to the kernel, when in fact they have
only cached the data and not yet stored it on the disk. A power failure in such a situation may still
lead to irrecoverable data corruption. Administrators should try to ensure that disks holding
PostgreSQL's WAL log files do not make such false reports.
After a checkpoint has been made and the log flushed, the checkpoint's position is saved in the file
pg_control. Therefore, when recovery is to be done, the server first reads pg_control and then the
checkpoint record; then it performs the REDO operation by scanning forward from the log position
indicated in the checkpoint record. Because the entire content of data pages is saved in the log on
the first page modification after a checkpoint, all pages changed since the checkpoint will be
restored to a consistent state.
To deal with the case where pg_control is corrupted, we should support the possibility of scanning
existing log segments in reverse order — newest to oldest — in order to find the latest checkpoint.
This has not been implemented yet. pg_control is small enough (less than one disk page) that it is
not subject to partial-write problems, and as of this writing there have been no reports of database
failures due solely to inability to read pg_control itself. So while it is theoretically a weak spot,
pg_control does not seem to be a problem in practice.

WAL Configuration Acima Regression Tests
http://pgdocptbr.sourceforge.net/pg82/wal-internals.html[09/02/2018 18:45:06]
Regression Tests

Capítulo 28. Regression Tests

Sumário
28.2.1. Error message differences

28.2.2. Locale differences
28.2.3. Date and time differences
28.2.4. Floating-point differences
28.2.5. Row ordering differences
28.2.6. Insufficient stack depth
28.2.7. The "random" test
The regression tests are a comprehensive set of tests for the SQL implementation in PostgreSQL.
They test standard SQL operations as well as the extended capabilities of PostgreSQL.

WAL Internals Acima Running the Tests
http://pgdocptbr.sourceforge.net/pg82/regress.html[09/02/2018 18:45:24]
Running the Tests

Anterior Início Capítulo 28. Regression Tests Fim Próxima

The regression tests can be run against an already installed and running server, or using a
temporary installation within the build tree. Furthermore, there is a "parallel" and a "sequential"
mode for running the tests. The sequential method runs each test script in turn, whereas the
parallel method starts up multiple server processes to run groups of tests in parallel. Parallel testing
gives confidence that interprocess communication and locking are working correctly. For historical
reasons, the sequential test is usually run against an existing installation and the parallel method
against a temporary installation, but there are no technical reasons for this.
To run the regression tests after building but before installation, type
gmake check
in the top-level directory. (Or you can change to src/test/regress and run the command there.) This
will first build several auxiliary files, such as some sample user-defined trigger functions, and then
run the test driver script. At the end you should see something like
======================
All 100 tests passed.
======================
or otherwise a note about which tests failed. See Seção 28.2 below before assuming that a "failure"
represents a serious problem.
Because this test method runs a temporary server, it will not work when you are the root user
(since the server will not start as root). If you already did the build as root, you do not have to start
all over. Instead, make the regression test directory writable by some other user, log in as that
user, and restart the tests. For example
root# chmod -R a+w src/test/regress

root# chmod -R a+w contrib/spi
root# su - joeuser
joeuser$ cd top-level build directory
joeuser$ gmake check
(The only possible "security risk" here is that other users might be able to alter the regression test
results behind your back. Use common sense when managing user permissions.)
Alternatively, run the tests after installation.
If you have configured PostgreSQL to install into a location where an older PostgreSQL installation
already exists, and you perform gmake check before installing the new version, you may find that
the tests fail because the new programs try to use the already-installed shared libraries. (Typical
symptoms are complaints about undefined symbols.) If you wish to run the tests before overwriting
the old installation, you'll need to build with configure --disable-rpath. It is not recommended that
you use this option for the final installation, however.
The parallel regression test starts quite a few processes under your user ID. Presently, the
maximum concurrency is twenty parallel test scripts, which means forty processes: there's a server
process and a psql process for each test script. So if your system enforces a per-user limit on the
number of processes, make sure this limit is at least fifty or so, else you may get random-seeming
http://pgdocptbr.sourceforge.net/pg82/regress-run.html[09/02/2018 18:45:47]
Running the Tests
failures in the parallel test. If you are not in a position to raise the limit, you can cut down the
degree of parallelism by setting the MAX_CONNECTIONS parameter. For example,
gmake MAX_CONNECTIONS=10 check
runs no more than ten tests concurrently.
To run the tests after installation (see Capítulo 14), initialize a data area and start the server, as
explained in Capítulo 16, then type
gmake installcheck
or for a parallel test
gmake installcheck-parallel
The tests will expect to contact the server at the local host and the default port number, unless
directed otherwise by PGHOST and PGPORT environment variables.
The source distribution also contains regression tests for the optional procedural languages and for
some of the contrib modules. At present, these tests can be used only against an already-installed
server. To run the tests for all procedural languages that have been built and installed, change to
the src/pl directory of the build tree and type
gmake installcheck
You can also do this in any of the subdirectories of src/pl to run tests for just one procedural
language. To run the tests for all contrib modules that have them, change to the contrib directory of
the build tree and type
gmake installcheck
The contrib modules must have been built and installed first. You can also do this in a subdirectory
of contrib to run the tests for just one module.

Regression Tests Acima Test Evaluation
http://pgdocptbr.sourceforge.net/pg82/regress-run.html[09/02/2018 18:45:47]
Test Evaluation


Some properly installed and fully functional PostgreSQL installations can "fail" some of these
regression tests due to platform-specific artifacts such as varying floating-point representation and
message wording. The tests are currently evaluated using a simple diff comparison against the
outputs generated on a reference system, so the results are sensitive to small system differences.
When a test is reported as "failed", always examine the differences between expected and actual
results; you may well find that the differences are not significant. Nonetheless, we still strive to
maintain accurate reference files across all supported platforms, so it can be expected that all tests
pass.
The actual outputs of the regression tests are in files in the src/test/regress/results directory. The
test script uses diff to compare each output file against the reference outputs stored in the
src/test/regress/expected directory. Any differences are saved for your inspection in
src/test/regress/regression.diffs. (Or you can run diff yourself, if you prefer.)
If for some reason a particular platform generates a "failure" for a given test, but inspection of the
output convinces you that the result is valid, you can add a new comparison file to silence the
failure report in future test runs. See Seção 28.3 for details.
28.2.1. Error message differences
Some of the regression tests involve intentional invalid input values. Error messages can come from
either the PostgreSQL code or from the host platform system routines. In the latter case, the
messages may vary between platforms, but should reflect similar information. These differences in
messages will result in a "failed" regression test that can be validated by inspection.
28.2.2. Locale differences
If you run the tests against an already-installed server that was initialized with a collation-order
locale other than C, then there may be differences due to sort order and follow-up failures. The
regression test suite is set up to handle this problem by providing alternative result files that
together are known to handle a large number of locales.
28.2.3. Date and time differences
Most of the date and time results are dependent on the time zone environment. The reference files
are generated for time zone PST8PDT (Berkeley, California), and there will be apparent failures if
the tests are not run with that time zone setting. The regression test driver sets environment
variable PGTZ to PST8PDT, which normally ensures proper results.
28.2.4. Floating-point differences
Some of the tests involve computing 64-bit floating-point numbers (double precision) from table
columns. Differences in results involving mathematical functions of double precision columns have
been observed. The float8 and geometry tests are particularly prone to small differences across
platforms, or even with different compiler optimization options. Human eyeball comparison is
needed to determine the real significance of these differences which are usually 10 places to the
right of the decimal point.
Some systems display minus zero as -0, while others just show 0.
http://pgdocptbr.sourceforge.net/pg82/regress-evaluation.html[09/02/2018 18:46:01]
Test Evaluation
Some systems signal errors from pow() and exp() differently from the mechanism expected by the
current PostgreSQL code.
28.2.5. Row ordering differences
You might see differences in which the same rows are output in a different order than what appears
in the expected file. In most cases this is not, strictly speaking, a bug. Most of the regression test
scripts are not so pedantic as to use an ORDER BY for every single SELECT, and so their result row
orderings are not well-defined according to the letter of the SQL specification. In practice, since we
are looking at the same queries being executed on the same data by the same software, we usually
get the same result ordering on all platforms, and so the lack of ORDER BY isn't a problem. Some
queries do exhibit cross-platform ordering differences, however. When testing against an already-
installed server, ordering differences can also be caused by non-C locale settings or non-default
parameter settings, such as custom values of work_mem or the planner cost parameters.
Therefore, if you see an ordering difference, it's not something to worry about, unless the query
does have an ORDER BY that your result is violating. But please report it anyway, so that we can
add an ORDER BY to that particular query and thereby eliminate the bogus "failure" in future
releases.
You might wonder why we don't order all the regression test queries explicitly to get rid of this issue
once and for all. The reason is that that would make the regression tests less useful, not more,
since they'd tend to exercise query plan types that produce ordered results to the exclusion of those
that don't.
28.2.6. Insufficient stack depth
If the errors test results in a server crash at the select infinite_recurse() command, it means that
the platform's limit on process stack size is smaller than the max_stack_depth parameter indicates.
This can be fixed by running the server under a higher stack size limit (4MB is recommended with
the default value of max_stack_depth). If you are unable to do that, an alternative is to reduce the
value of max_stack_depth.
28.2.7. The "random" test
The random test script is intended to produce random results. In rare cases, this causes the random
regression test to fail. Typing
diff results/random.out expected/random.out
should produce only one or a few lines of differences. You need not worry unless the random test
fails repeatedly.

Running the Tests Acima Variant Comparison Files
http://pgdocptbr.sourceforge.net/pg82/regress-evaluation.html[09/02/2018 18:46:01]
Variant Comparison Files


Since some of the tests inherently produce environment-dependent results, we have provided ways
to specify alternative "expected" result files. Each regression test can have several comparison files
showing possible results on different platforms. There are two independent mechanisms for
determining which comparison file is used for each test.
The first mechanism allows comparison files to be selected for specific platforms. There is a
mapping file, src/test/regress/resultmap, that defines which comparison file to use for each
platform. To eliminate bogus test "failures" for a particular platform, you first choose or make a
variant result file, and then add a line to the resultmap file.
Each line in the mapping file is of the form

testname/platformpattern=comparisonfilename
The test name is just the name of the particular regression test module. The platform pattern is a
pattern in the style of the Unix tool expr (that is, a regular expression with an implicit ^ anchor at
the start). It is matched against the platform name as printed by config.guess. The comparison file
name is the base name of the substitute result comparison file.
For example: some systems interpret very small floating-point values as zero, rather than reporting
an underflow error. This causes a few differences in the float8 regression test. Therefore, we
provide a variant comparison file, float8-small-is-zero.out, which includes the results to be expected
on these systems. To silence the bogus "failure" message on OpenBSD platforms, resultmap
includes
float8/i.86-.*-openbsd=float8-small-is-zero
which will trigger on any machine for which the output of config.guess matches i.86-.*-openbsd.
Other lines in resultmap select the variant comparison file for other platforms where it's
appropriate.
The second selection mechanism for variant comparison files is much more automatic: it simply
uses the "best match" among several supplied comparison files. The regression test driver script
considers both the standard comparison file for a test, nome_do_teste.out, and variant files named
nome_do_teste_dígito.out (where the dígito is any single digit 0-9). If any such file is an exact
match, the test is considered to pass; otherwise, the one that generates the shortest diff is used to
create the failure report. (If resultmap includes an entry for the particular test, then the base
nome_do_teste is the substitute name given in resultmap.)
For example, for the char test, the comparison file char.out contains results that are expected in the
C and POSIX locales, while the file char_1.out contains results sorted as they appear in many other
locales.
The best-match mechanism was devised to cope with locale-dependent results, but it can be used
in any situation where the test results cannot be predicted easily from the platform name alone. A
limitation of this mechanism is that the test driver cannot tell which variant is actually "correct" for
the current environment; it will just pick the variant that seems to work best. Therefore it is safest
to use this mechanism only for variant results that you are willing to consider equally valid in all
contexts.
http://pgdocptbr.sourceforge.net/pg82/regress-variant.html[09/02/2018 18:46:12]
Variant Comparison Files

Test Evaluation Acima Interfaces cliente
http://pgdocptbr.sourceforge.net/pg82/regress-variant.html[09/02/2018 18:46:12]

Como Convencer Alguem em 90 Seg - Nicholas Boothman

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Como Convencer Alguem em 90 Seg - Nicholas Boothman

Caricato da

Copyright:

Formati disponibili

Documentação do PostgreSQL 8.2.

Documentação do PostgreSQL 8.2.0

The PostgreSQL Global Development Group

Copyright © 1996-2006 The PostgreSQL Global Development Group

II. A linguagem SQL

III. Administração do servidor

14. Installation Instructions

26. Monitoring Disk Usage

IV. Interfaces cliente

29. libpq - C Library

33. Extending SQL

42. Overview of PostgreSQL Internals

A. PostgreSQL Error Codes

9-35. array Operators

32-33. sql_packages Columns

43-40. pg_prepared_statements Columns

37-8. Porting a Procedure from PL/SQL to PL/pgSQL

Documentação do PostgreSQL 8.2.0

Parte I é uma introdução informal para os novos usuários.

Parte II documenta o ambiente da linguagem de comandos SQL, incluindo tipos de dado e

Parte III descreve a instalação e a administração do servidor. Todas as pessoas responsáveis

Parte IV descreve as interfaces de programação para os programas cliente do PostgreSQL.

Parte V contém informações para os usuários avançados sobre a capacidade de extensão do

Parte VI contém informações de referência sobre os comandos SQL, programas cliente e

Parte VII contém diversas informações úteis para os desenvolvedores do PostgreSQL.

Anterior Principal Próxima

Documentação do PostgreSQL 8.2.0

Anterior Principal Próxima

Documentação do PostgreSQL 8.2.0

Uma breve história do PostgreSQL

O projeto POSTGRES de Berkeley

O tamanho da comunidade de usuários externos praticamente dobrou durante o ano de 1993.

Em 1994, Andrew Yu e Jolly Chen adicionaram um interpretador da linguagem SQL ao POSTGRES.

A linguagem de comandos PostQUEL foi substituída pela linguagem SQL (implementada no

Um breve tutorial introduzindo as funcionalidades regulares da linguagem SQL, assim como as

A ênfase durante o desenvolvimento do Postgres95 era identificar e compreender os problemas

Anterior Principal Próxima

Documentação do PostgreSQL 8.2.0

Anterior Principal Próxima

Documentação do PostgreSQL 8.2.0

README files are available for most contributed packages.

Anterior Principal Próxima

Documentação do PostgreSQL 8.2.0

Bug Reporting Guidelines

A program produces the wrong output for any given input.

A program refuses to accept valid input (as defined in the documentation).

PostgreSQL fails to compile, build, or install according to the instructions on supported

The following items should be contained in every bug report:

Anything you did at all differently from the installation instructions.

Where to report bugs

If your bug is a portability problem on a non-supported platform, send mail to <pgsql-

Anterior Principal Próxima

Documentação do PostgreSQL 8.2.0

Anterior Principal Próxima

Documentação do PostgreSQL 8.2.0

Anterior Principal Próxima

Documentação do PostgreSQL 8.2.0

Anterior Principal Próxima

Documentação do PostgreSQL 8.2.0

1.2. Fundamentos da arquitetura

No jargão de banco de dados, o PostgreSQL utiliza o modelo cliente-servidor. Uma sessão do

Como é típico na arquitetura cliente-servidor, o cliente e o servidor podem estar em hospedeiros

Anterior Principal Próxima