1. PostgreSQL 8.4.22 Documentation The PostgreSQL Global
Development Group
2. PostgreSQL 8.4.22 Documentation by The PostgreSQL Global
Development Group Copyright 1996-2014 The PostgreSQL Global
Development Group Legal Notice PostgreSQL is Copyright 1996-2014 by
the PostgreSQL Global Development Group and is distributed under
the terms of the license of the University of California below.
Postgres95 is Copyright 1994-5 by the Regents of the University of
California. Permission to use, copy, modify, and distribute this
software and its documentation for any purpose, without fee, and
without a written agreement is hereby granted, provided that the
above copyright notice and this paragraph and the following two
paragraphs appear in all copies. IN NO EVENT SHALL THE UNIVERSITY
OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL,
INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,
ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS
ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
THE SOFTWARE PRO- VIDED HEREUNDER IS ON AN AS-IS BASIS, AND THE
UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
3. Table of Contents Preface
...........................................................................................................................................xlviii
1. What is
PostgreSQL?........................................................................................................xlviii
2. A Brief History of
PostgreSQL...........................................................................................xlix
2.1. The Berkeley POSTGRES Project
.........................................................................xlix
2.2.
Postgres95...............................................................................................................xlix
2.3.
PostgreSQL..................................................................................................................l
3.
Conventions..............................................................................................................................l
4. Further
Information.................................................................................................................li
5. Bug Reporting
Guidelines.......................................................................................................li
5.1. Identifying
Bugs........................................................................................................lii
5.2. What to
report............................................................................................................lii
5.3. Where to report bugs
................................................................................................liv
I.
Tutorial.............................................................................................................................................1
1. Getting Started
........................................................................................................................1
1.1.
Installation..................................................................................................................1
1.2. Architectural
Fundamentals........................................................................................1
1.3. Creating a
Database....................................................................................................2
1.4. Accessing a Database
.................................................................................................3
2. The SQL Language
.................................................................................................................5
2.1. Introduction
................................................................................................................5
2.2. Concepts
.....................................................................................................................5
2.3. Creating a New Table
.................................................................................................5
2.4. Populating a Table With Rows
...................................................................................6
2.5. Querying a Table
........................................................................................................7
2.6. Joins Between
Tables..................................................................................................9
2.7. Aggregate
Functions.................................................................................................11
2.8.
Updates.....................................................................................................................12
2.9.
Deletions...................................................................................................................13
3. Advanced
Features................................................................................................................14
3.1. Introduction
..............................................................................................................14
3.2. Views
........................................................................................................................14
3.3. Foreign
Keys.............................................................................................................14
3.4.
Transactions..............................................................................................................15
3.5. Window
Functions....................................................................................................17
3.6. Inheritance
................................................................................................................20
3.7.
Conclusion................................................................................................................21
II. The SQL
Language......................................................................................................................22
4. SQL
Syntax...........................................................................................................................24
4.1. Lexical
Structure.......................................................................................................24
4.1.1. Identiers and Key
Words............................................................................24
4.1.2.
Constants......................................................................................................26
4.1.2.1. String Constants
..............................................................................26
4.1.2.2. String Constants with C-Style Escapes
...........................................26 4.1.2.3. String
Constants with Unicode
Escapes..........................................27 4.1.2.4.
Dollar-Quoted String
Constants......................................................28
4.1.2.5. Bit-String Constants
........................................................................29
4.1.2.6. Numeric Constants
..........................................................................29
4.1.2.7. Constants of Other Types
................................................................30
iii
4. 4.1.3.
Operators......................................................................................................30
4.1.4. Special
Characters........................................................................................31
4.1.5. Comments
....................................................................................................31
4.1.6. Lexical Precedence
......................................................................................32
4.2. Value
Expressions.....................................................................................................33
4.2.1. Column
References......................................................................................34
4.2.2. Positional
Parameters...................................................................................34
4.2.3.
Subscripts.....................................................................................................34
4.2.4. Field Selection
.............................................................................................35
4.2.5. Operator
Invocations....................................................................................35
4.2.6. Function
Calls..............................................................................................36
4.2.7. Aggregate
Expressions.................................................................................36
4.2.8. Window Function
Calls................................................................................37
4.2.9. Type
Casts....................................................................................................38
4.2.10. Scalar
Subqueries.......................................................................................39
4.2.11. Array
Constructors.....................................................................................39
4.2.12. Row
Constructors.......................................................................................41
4.2.13. Expression Evaluation Rules
.....................................................................42
5. Data
Denition......................................................................................................................44
5.1. Table
Basics..............................................................................................................44
5.2. Default Values
..........................................................................................................45
5.3.
Constraints................................................................................................................46
5.3.1. Check
Constraints........................................................................................46
5.3.2. Not-Null
Constraints....................................................................................48
5.3.3. Unique
Constraints.......................................................................................49
5.3.4. Primary
Keys................................................................................................49
5.3.5. Foreign
Keys................................................................................................50
5.4. System
Columns.......................................................................................................53
5.5. Modifying
Tables......................................................................................................54
5.5.1. Adding a
Column.........................................................................................54
5.5.2. Removing a Column
....................................................................................55
5.5.3. Adding a
Constraint.....................................................................................55
5.5.4. Removing a Constraint
................................................................................56
5.5.5. Changing a Columns Default
Value............................................................56
5.5.6. Changing a Columns Data Type
.................................................................56
5.5.7. Renaming a Column
....................................................................................57
5.5.8. Renaming a Table
........................................................................................57
5.6. Privileges
..................................................................................................................57
5.7.
Schemas....................................................................................................................58
5.7.1. Creating a Schema
.......................................................................................58
5.7.2. The Public Schema
......................................................................................59
5.7.3. The Schema Search
Path..............................................................................59
5.7.4. Schemas and
Privileges................................................................................61
5.7.5. The System Catalog Schema
.......................................................................61
5.7.6. Usage
Patterns..............................................................................................61
5.7.7.
Portability.....................................................................................................62
5.8. Inheritance
................................................................................................................62
5.8.1.
Caveats.........................................................................................................65
5.9. Partitioning
...............................................................................................................65
5.9.1.
Overview......................................................................................................65
5.9.2. Implementing Partitioning
...........................................................................66
5.9.3. Managing
Partitions.....................................................................................69
iv
5. 5.9.4. Partitioning and Constraint Exclusion
.........................................................70 5.9.5.
Alternative Partitioning
Methods.................................................................71
5.9.6.
Caveats.........................................................................................................72
5.10. Other Database Objects
..........................................................................................73
5.11. Dependency
Tracking.............................................................................................73
6. Data
Manipulation.................................................................................................................75
6.1. Inserting Data
...........................................................................................................75
6.2. Updating
Data...........................................................................................................76
6.3. Deleting
Data............................................................................................................77
7. Queries
..................................................................................................................................78
7.1. Overview
..................................................................................................................78
7.2. Table
Expressions.....................................................................................................78
7.2.1. The FROM
Clause..........................................................................................79
7.2.1.1. Joined Tables
...................................................................................79
7.2.1.2. Table and Column
Aliases...............................................................82
7.2.1.3. Subqueries
.......................................................................................83
7.2.1.4. Table Functions
...............................................................................84
7.2.2. The WHERE
Clause........................................................................................85
7.2.3. The GROUP BY and HAVING
Clauses...........................................................86
7.2.4. Window Function Processing
......................................................................88
7.3. Select
Lists................................................................................................................88
7.3.1. Select-List Items
..........................................................................................88
7.3.2. Column
Labels.............................................................................................89
7.3.3. DISTINCT
....................................................................................................89
7.4. Combining
Queries...................................................................................................90
7.5. Sorting Rows
............................................................................................................91
7.6. LIMIT and
OFFSET...................................................................................................92
7.7. VALUES Lists
............................................................................................................92
7.8. WITH Queries (Common Table Expressions)
...........................................................93 8.
Data
Types.............................................................................................................................97
8.1. Numeric
Types..........................................................................................................98
8.1.1. Integer
Types................................................................................................99
8.1.2. Arbitrary Precision
Numbers.......................................................................99
8.1.3. Floating-Point
Types..................................................................................100
8.1.4. Serial
Types................................................................................................102
8.2. Monetary
Types......................................................................................................102
8.3. Character
Types......................................................................................................103
8.4. Binary Data Types
..................................................................................................105
8.5. Date/Time
Types.....................................................................................................107
8.5.1. Date/Time
Input.........................................................................................108
8.5.1.1.
Dates..............................................................................................109
8.5.1.2.
Times.............................................................................................109
8.5.1.3. Time
Stamps..................................................................................110
8.5.1.4. Special Values
...............................................................................111
8.5.2. Date/Time Output
......................................................................................112
8.5.3. Time Zones
................................................................................................112
8.5.4. Interval
Input..............................................................................................114
8.5.5. Interval
Output...........................................................................................116
8.5.6.
Internals......................................................................................................116
8.6. Boolean
Type..........................................................................................................117
8.7. Enumerated Types
..................................................................................................118
8.7.1. Declaration of Enumerated
Types..............................................................118
v
6. 8.7.2.
Ordering.....................................................................................................118
8.7.3. Type Safety
................................................................................................119
8.7.4. Implementation
Details..............................................................................119
8.8. Geometric
Types.....................................................................................................120
8.8.1. Points
.........................................................................................................120
8.8.2. Line
Segments............................................................................................120
8.8.3.
Boxes..........................................................................................................120
8.8.4.
Paths...........................................................................................................121
8.8.5.
Polygons.....................................................................................................121
8.8.6. Circles
........................................................................................................121
8.9. Network Address
Types..........................................................................................122
8.9.1.
inet...........................................................................................................122
8.9.2.
cidr...........................................................................................................122
8.9.3. inet vs.
cidr............................................................................................123
8.9.4. macaddr
....................................................................................................123
8.10. Bit String
Types....................................................................................................124
8.11. Text Search
Types.................................................................................................124
8.11.1. tsvector
................................................................................................125
8.11.2. tsquery
..................................................................................................126
8.12. UUID Type
...........................................................................................................127
8.13. XML Type
............................................................................................................127
8.13.1. Creating XML Values
..............................................................................128
8.13.2. Encoding Handling
..................................................................................128
8.13.3. Accessing XML
Values............................................................................129
8.14. Arrays
...................................................................................................................129
8.14.1. Declaration of Array
Types......................................................................130
8.14.2. Array Value
Input.....................................................................................130
8.14.3. Accessing Arrays
.....................................................................................132
8.14.4. Modifying
Arrays.....................................................................................133
8.14.5. Searching in
Arrays..................................................................................136
8.14.6. Array Input and Output
Syntax................................................................136
8.15. Composite Types
..................................................................................................138
8.15.1. Declaration of Composite
Types..............................................................138
8.15.2. Composite Value
Input.............................................................................139
8.15.3. Accessing Composite Types
....................................................................140
8.15.4. Modifying Composite
Types....................................................................140
8.15.5. Composite Type Input and Output
Syntax...............................................141 8.16.
Object Identier Types
.........................................................................................141
8.17.
Pseudo-Types........................................................................................................143
9. Functions and Operators
.....................................................................................................145
9.1. Logical Operators
...................................................................................................145
9.2. Comparison
Operators............................................................................................145
9.3. Mathematical Functions and
Operators..................................................................147
9.4. String Functions and
Operators..............................................................................150
9.5. Binary String Functions and Operators
..................................................................162
9.6. Bit String Functions and
Operators........................................................................164
9.7. Pattern Matching
....................................................................................................165
9.7.1.
LIKE...........................................................................................................165
9.7.2. SIMILAR TO Regular
Expressions............................................................166
9.7.3. POSIX Regular
Expressions......................................................................167
9.7.3.1. Regular Expression Details
...........................................................170
9.7.3.2. Bracket Expressions
......................................................................172
vi
7. 9.7.3.3. Regular Expression
Escapes..........................................................173
9.7.3.4. Regular Expression
Metasyntax....................................................176
9.7.3.5. Regular Expression Matching
Rules.............................................177 9.7.3.6.
Limits and Compatibility
..............................................................178
9.7.3.7. Basic Regular
Expressions............................................................179
9.8. Data Type Formatting Functions
............................................................................179
9.9. Date/Time Functions and
Operators.......................................................................185
9.9.1. EXTRACT,
date_part...............................................................................189
9.9.2.
date_trunc..............................................................................................193
9.9.3. AT TIME
ZONE..........................................................................................194
9.9.4. Current Date/Time
.....................................................................................194
9.9.5. Delaying
Execution....................................................................................196
9.10. Enum Support
Functions......................................................................................196
9.11. Geometric Functions and
Operators.....................................................................197
9.12. Network Address Functions and
Operators..........................................................201
9.13. Text Search Functions and
Operators...................................................................203
9.14. XML Functions
....................................................................................................208
9.14.1. Producing XML
Content..........................................................................208
9.14.1.1. xmlcomment
...............................................................................208
9.14.1.2. xmlconcat
.................................................................................208
9.14.1.3. xmlelement
...............................................................................209
9.14.1.4. xmlforest
.................................................................................210
9.14.1.5. xmlpi
..........................................................................................211
9.14.1.6.
xmlroot......................................................................................211
9.14.1.7.
xmlagg........................................................................................212
9.14.1.8. XML
Predicates...........................................................................212
9.14.2. Processing XML
......................................................................................212
9.14.3. Mapping Tables to
XML..........................................................................213
9.15. Sequence Manipulation Functions
.......................................................................216
9.16. Conditional
Expressions.......................................................................................218
9.16.1.
CASE.........................................................................................................218
9.16.2. COALESCE
................................................................................................220
9.16.3.
NULLIF.....................................................................................................220
9.16.4. GREATEST and
LEAST..............................................................................221
9.17. Array Functions and Operators
............................................................................221
9.18. Aggregate
Functions.............................................................................................223
9.19. Window
Functions................................................................................................226
9.20. Subquery Expressions
..........................................................................................228
9.20.1.
EXISTS.....................................................................................................228
9.20.2. IN
.............................................................................................................229
9.20.3. NOT
IN.....................................................................................................229
9.20.4. ANY/SOME
.................................................................................................230
9.20.5.
ALL...........................................................................................................230
9.20.6. Row-wise
Comparison.............................................................................231
9.21. Row and Array Comparisons
...............................................................................231
9.21.1. IN
.............................................................................................................231
9.21.2. NOT
IN.....................................................................................................232
9.21.3. ANY/SOME (array)
.....................................................................................232
9.21.4. ALL (array)
...............................................................................................233
9.21.5. Row-wise
Comparison.............................................................................233
9.22. Set Returning Functions
.......................................................................................234
9.23. System Information Functions
.............................................................................236
vii
8. 9.24. System Administration Functions
........................................................................245
9.25. Trigger Functions
.................................................................................................251
10. Type
Conversion................................................................................................................253
10.1. Overview
..............................................................................................................253
10.2. Operators
..............................................................................................................254
10.3. Functions
..............................................................................................................257
10.4. Value
Storage........................................................................................................259
10.5. UNION, CASE, and Related
Constructs..................................................................260
11. Indexes
..............................................................................................................................263
11.1. Introduction
..........................................................................................................263
11.2. Index
Types...........................................................................................................264
11.3. Multicolumn
Indexes............................................................................................265
11.4. Indexes and ORDER
BY.........................................................................................266
11.5. Combining Multiple
Indexes................................................................................267
11.6. Unique
Indexes.....................................................................................................268
11.7. Indexes on Expressions
........................................................................................268
11.8. Partial Indexes
......................................................................................................269
11.9. Operator Classes and Operator Families
..............................................................271
11.10. Examining Index
Usage......................................................................................272
12. Full Text Search
................................................................................................................274
12.1. Introduction
..........................................................................................................274
12.1.1. What Is a
Document?...............................................................................275
12.1.2. Basic Text Matching
................................................................................275
12.1.3.
Congurations..........................................................................................276
12.2. Tables and
Indexes................................................................................................277
12.2.1. Searching a
Table.....................................................................................277
12.2.2. Creating Indexes
......................................................................................278
12.3. Controlling Text
Search........................................................................................279
12.3.1. Parsing Documents
..................................................................................279
12.3.2. Parsing Queries
........................................................................................280
12.3.3. Ranking Search Results
...........................................................................282
12.3.4. Highlighting Results
................................................................................284
12.4. Additional Features
..............................................................................................285
12.4.1. Manipulating
Documents.........................................................................285
12.4.2. Manipulating
Queries...............................................................................286
12.4.2.1. Query
Rewriting..........................................................................287
12.4.3. Triggers for Automatic Updates
..............................................................288
12.4.4. Gathering Document Statistics
................................................................290
12.5.
Parsers...................................................................................................................290
12.6.
Dictionaries...........................................................................................................292
12.6.1. Stop
Words...............................................................................................293
12.6.2. Simple
Dictionary....................................................................................294
12.6.3. Synonym Dictionary
................................................................................295
12.6.4. Thesaurus
Dictionary...............................................................................296
12.6.4.1. Thesaurus Conguration
.............................................................296
12.6.4.2. Thesaurus Example
.....................................................................297
12.6.5. Ispell
Dictionary.......................................................................................298
12.6.6. Snowball Dictionary
................................................................................299
12.7. Conguration
Example.........................................................................................299
12.8. Testing and Debugging Text
Search.....................................................................301
12.8.1. Conguration
Testing...............................................................................301
12.8.2. Parser
Testing...........................................................................................303
viii
9. 12.8.3. Dictionary
Testing....................................................................................304
12.9. GiST and GIN Index
Types..................................................................................305
12.10. psql
Support........................................................................................................306
12.11.
Limitations..........................................................................................................309
12.12. Migration from Pre-8.3 Text
Search...................................................................309
13. Concurrency
Control.........................................................................................................311
13.1. Introduction
..........................................................................................................311
13.2. Transaction Isolation
............................................................................................311
13.2.1. Read Committed Isolation Level
.............................................................312
13.2.2. Serializable Isolation
Level......................................................................313
13.2.2.1. Serializable Isolation versus True
Serializability........................314 13.3. Explicit
Locking...................................................................................................315
13.3.1. Table-Level
Locks....................................................................................315
13.3.2. Row-Level
Locks.....................................................................................317
13.3.3.
Deadlocks.................................................................................................318
13.3.4. Advisory
Locks........................................................................................319
13.4. Data Consistency Checks at the Application
Level..............................................319 13.5.
Locking and
Indexes.............................................................................................320
14. Performance Tips
..............................................................................................................322
14.1. Using EXPLAIN
....................................................................................................322
14.2. Statistics Used by the Planner
..............................................................................326
14.3. Controlling the Planner with Explicit JOIN
Clauses............................................328 14.4.
Populating a Database
..........................................................................................330
14.4.1. Disable
Autocommit................................................................................330
14.4.2. Use
COPY..................................................................................................330
14.4.3. Remove
Indexes.......................................................................................330
14.4.4. Remove Foreign Key Constraints
............................................................331
14.4.5. Increase
maintenance_work_mem........................................................331
14.4.6. Increase checkpoint_segments
..........................................................331
14.4.7. Turn off archive_mode
.........................................................................331
14.4.8. Run ANALYZE
Afterwards........................................................................331
14.4.9. Some Notes About
pg_dump...................................................................332
III. Server Administration
.............................................................................................................333
15. Installation from Source Code
..........................................................................................335
15.1. Short Version
........................................................................................................335
15.2.
Requirements........................................................................................................335
15.3. Getting The
Source...............................................................................................337
15.4.
Upgrading.............................................................................................................337
15.5. Installation
Procedure...........................................................................................338
15.6. Post-Installation
Setup..........................................................................................347
15.6.1. Shared
Libraries.......................................................................................347
15.6.2. Environment
Variables.............................................................................348
15.7. Supported
Platforms.............................................................................................349
15.8. Platform-Specic
Notes........................................................................................349
15.8.1. AIX
..........................................................................................................350
15.8.1.1. GCC issues
..................................................................................350
15.8.1.2. Unix-domain sockets
broken.......................................................350
15.8.1.3. Internet address
issues.................................................................351
15.8.1.4. Memory
management..................................................................351
References and
resources..................................................................352
15.8.2.
Cygwin.....................................................................................................352
ix
10. 15.8.3. HP-UX
.....................................................................................................353
15.8.4. IRIX
.........................................................................................................354
15.8.5. MinGW/Native Windows
........................................................................355
15.8.6. SCO OpenServer and SCO
UnixWare.....................................................355
15.8.6.1.
Skunkware...................................................................................355
15.8.6.2. GNU Make
..................................................................................355
15.8.6.3.
Readline.......................................................................................355
15.8.6.4. Using the UDK on
OpenServer...................................................356
15.8.6.5. Reading the PostgreSQL man pages
...........................................356 15.8.6.6. C99 Issues
with the 7.1.1b Feature Supplement .........................356
15.8.6.7. --enable-thread-safety and UnixWare
.............................356 15.8.7. Solaris
......................................................................................................356
15.8.7.1. Required tools
.............................................................................357
15.8.7.2. Problems with OpenSSL
.............................................................357
15.8.7.3. congure complains about a failed test
program.........................357 15.8.7.4. 64-bit build
sometimes crashes
...................................................357 15.8.7.5.
Compiling for optimal
performance............................................358
15.8.7.6. Using DTrace for tracing PostgreSQL
........................................358 16. Installation from
Source Code on Windows
.....................................................................359
16.1. Building with Visual C++
2005............................................................................359
16.1.1. Requirements
...........................................................................................359
16.1.2. Building
...................................................................................................360
16.1.3. Cleaning and installing
............................................................................361
16.1.4. Running the regression tests
....................................................................361
16.1.5. Building the
documentation.....................................................................362
16.2. Building libpq with Visual C++ or Borland
C++.................................................362 16.2.1.
Generated les
.........................................................................................363
17. Server Setup and Operation
..............................................................................................364
17.1. The PostgreSQL User Account
............................................................................364
17.2. Creating a Database Cluster
.................................................................................364
17.2.1. Network File
Systems..............................................................................365
17.3. Starting the Database
Server.................................................................................365
17.3.1. Server Start-up Failures
...........................................................................367
17.3.2. Client Connection Problems
....................................................................367
17.4. Managing Kernel
Resources.................................................................................368
17.4.1. Shared Memory and Semaphores
............................................................368
17.4.2. Resource Limits
.......................................................................................374
17.4.3. Linux Memory
Overcommit....................................................................375
17.5. Shutting Down the
Server.....................................................................................375
17.6. Preventing Server
Spoong..................................................................................376
17.7. Encryption
Options...............................................................................................377
17.8. Secure TCP/IP Connections with SSL
.................................................................378
17.8.1. Using client
certicates............................................................................378
17.8.2. SSL Server File
Usage.............................................................................379
17.8.3. Creating a Self-Signed Certicate
...........................................................379
17.9. Secure TCP/IP Connections with SSH
Tunnels...................................................380 18.
Server
Conguration.........................................................................................................382
18.1. Setting
Parameters................................................................................................382
18.2. File
Locations.......................................................................................................383
18.3. Connections and
Authentication...........................................................................384
18.3.1. Connection Settings
.................................................................................384
18.3.2. Security and
Authentication.....................................................................386
x
11. 18.4. Resource
Consumption.........................................................................................387
18.4.1.
Memory....................................................................................................387
18.4.2. Kernel Resource
Usage............................................................................389
18.4.3. Cost-Based Vacuum Delay
......................................................................390
18.4.4. Background
Writer...................................................................................391
18.4.5. Asynchronous
Behavior...........................................................................391
18.5. Write Ahead Log
..................................................................................................392
18.5.1.
Settings.....................................................................................................392
18.5.2.
Checkpoints..............................................................................................394
18.5.3. Archiving
.................................................................................................395
18.6. Query
Planning.....................................................................................................395
18.6.1. Planner Method
Conguration.................................................................395
18.6.2. Planner Cost Constants
............................................................................396
18.6.3. Genetic Query
Optimizer.........................................................................397
18.6.4. Other Planner
Options..............................................................................398
18.7. Error Reporting and Logging
...............................................................................399
18.7.1. Where To Log
..........................................................................................400
18.7.2. When To Log
...........................................................................................402
18.7.3. What To Log
............................................................................................403
18.7.4. Using CSV-Format Log Output
...............................................................406
18.8. Run-Time Statistics
..............................................................................................408
18.8.1. Query and Index Statistics Collector
.......................................................408 18.8.2.
Statistics
Monitoring................................................................................409
18.9. Automatic
Vacuuming..........................................................................................409
18.10. Client Connection Defaults
................................................................................410
18.10.1. Statement
Behavior................................................................................411
18.10.2. Locale and Formatting
...........................................................................413
18.10.3. Other
Defaults........................................................................................415
18.11. Lock
Management..............................................................................................416
18.12. Version and Platform
Compatibility...................................................................416
18.12.1. Previous PostgreSQL Versions
..............................................................417
18.12.2. Platform and Client
Compatibility.........................................................418
18.13. Preset
Options.....................................................................................................419
18.14. Customized Options
...........................................................................................420
18.15. Developer
Options..............................................................................................421
18.16. Short
Options......................................................................................................423
19. Client Authentication
........................................................................................................425
19.1. The pg_hba.conf
le.........................................................................................425
19.2. Username maps
....................................................................................................430
19.3. Authentication
methods........................................................................................431
19.3.1. Trust
authentication..................................................................................431
19.3.2. Password
authentication...........................................................................432
19.3.3. GSSAPI
authentication............................................................................432
19.3.4. SSPI
authentication..................................................................................432
19.3.5. Kerberos authentication
...........................................................................433
19.3.6. Ident-based authentication
.......................................................................435
19.3.6.1. Ident Authentication over
TCP/IP...............................................435 19.3.6.2.
Ident Authentication over Local Sockets
....................................435 19.3.7. LDAP
authentication................................................................................435
19.3.8. Certicate authentication
.........................................................................436
19.3.9. PAM
authentication..................................................................................437
19.4. Authentication problems
......................................................................................437
xi
12. 20. Database Roles and Privileges
..........................................................................................439
20.1. Database Roles
.....................................................................................................439
20.2. Role
Attributes......................................................................................................440
20.3. Privileges
..............................................................................................................441
20.4. Role Membership
.................................................................................................441
20.5. Functions and Triggers
.........................................................................................443
21. Managing Databases
.........................................................................................................444
21.1. Overview
..............................................................................................................444
21.2. Creating a
Database..............................................................................................444
21.3. Template
Databases..............................................................................................445
21.4. Database Conguration
........................................................................................446
21.5. Destroying a
Database..........................................................................................447
21.6.
Tablespaces...........................................................................................................447
22.
Localization.......................................................................................................................449
22.1. Locale
Support......................................................................................................449
22.1.1.
Overview..................................................................................................449
22.1.2.
Behavior...................................................................................................450
22.1.3. Problems
..................................................................................................451
22.2. Character Set
Support...........................................................................................451
22.2.1. Supported Character
Sets.........................................................................451
22.2.2. Setting the Character
Set..........................................................................454
22.2.3. Automatic Character Set Conversion Between Server and
Client...........455 22.2.4. Further Reading
.......................................................................................457
23. Routine Database Maintenance
Tasks...............................................................................458
23.1. Routine Vacuuming
..............................................................................................458
23.1.1. Vacuuming
Basics....................................................................................458
23.1.2. Recovering Disk
Space............................................................................459
23.1.3. Updating Planner
Statistics......................................................................460
23.1.4. Preventing Transaction ID Wraparound
Failures.....................................461 23.1.5. The
Autovacuum Daemon
.......................................................................463
23.2. Routine
Reindexing..............................................................................................464
23.3. Log File
Maintenance...........................................................................................465
24. Backup and Restore
..........................................................................................................466
24.1. SQL
Dump............................................................................................................466
24.1.1. Restoring the
dump..................................................................................466
24.1.2. Using
pg_dumpall....................................................................................467
24.1.3. Handling large databases
.........................................................................468
24.2. File System Level
Backup....................................................................................469
24.3. Continuous Archiving and Point-In-Time Recovery (PITR)
...............................470 24.3.1. Setting up WAL
archiving........................................................................471
24.3.2. Making a Base Backup
............................................................................473
24.3.3. Recovering using a Continuous Archive Backup
....................................474 24.3.3.1. Recovery
Settings........................................................................476
24.3.4.
Timelines..................................................................................................477
24.3.5. Tips and
Examples...................................................................................478
24.3.5.1. Standalone hot
backups...............................................................478
24.3.5.2. Compressed Archive Logs
..........................................................479
24.3.5.3. archive_command
scripts.........................................................479
24.3.6.
Caveats.....................................................................................................480
24.4. Warm Standby Servers for High
Availability.......................................................480
24.4.1. Planning
...................................................................................................481
24.4.2. Implementation
........................................................................................482
xii
13. 24.4.3. Failover
....................................................................................................483
24.4.4. Record-based Log
Shipping.....................................................................483
24.5. Migration Between Releases
................................................................................484
25. High Availability, Load Balancing, and
Replication.........................................................486
26. Monitoring Database
Activity...........................................................................................490
26.1. Standard Unix
Tools.............................................................................................490
26.2. The Statistics
Collector.........................................................................................490
26.2.1. Statistics Collection Conguration
..........................................................491
26.2.2. Viewing Collected Statistics
....................................................................491
26.3. Viewing
Locks......................................................................................................499
26.4. Dynamic Tracing
..................................................................................................499
26.4.1. Compiling for Dynamic
Tracing..............................................................500
26.4.2. Built-in Probes
.........................................................................................500
26.4.3. Using
Probes............................................................................................508
26.4.4. Dening New Probes
...............................................................................509
27. Monitoring Disk
Usage.....................................................................................................511
27.1. Determining Disk Usage
......................................................................................511
27.2. Disk Full
Failure...................................................................................................512
28. Reliability and the Write-Ahead
Log................................................................................513
28.1. Reliability
.............................................................................................................513
28.2. Write-Ahead Logging (WAL)
..............................................................................514
28.3. Asynchronous
Commit.........................................................................................514
28.4. WAL Conguration
..............................................................................................516
28.5. WAL Internals
......................................................................................................518
29. Regression
Tests................................................................................................................519
29.1. Running the Tests
.................................................................................................519
29.2. Test Evaluation
.....................................................................................................520
29.2.1. Error message
differences........................................................................520
29.2.2. Locale
differences....................................................................................521
29.2.3. Date and time differences
........................................................................521
29.2.4. Floating-point
differences........................................................................521
29.2.5. Row ordering
differences.........................................................................522
29.2.6. Insufcient stack depth
............................................................................522
29.2.7. The random
test....................................................................................522
29.3. Variant Comparison Files
.....................................................................................522
29.4. Test Coverage
Examination..................................................................................523
IV. Client Interfaces
.......................................................................................................................525
30. libpq - C Library
...............................................................................................................527
30.1. Database Connection Control
Functions..............................................................527
30.2. Connection Status
Functions................................................................................534
30.3. Command Execution Functions
...........................................................................538
30.3.1. Main Functions
........................................................................................538
30.3.2. Retrieving Query Result Information
......................................................544 30.3.3.
Retrieving Result Information for Other Commands
..............................548 30.3.4. Escaping Strings for
Inclusion in SQL Commands.................................549
30.3.5. Escaping Binary Strings for Inclusion in SQL Commands
.....................550 30.4. Asynchronous Command
Processing...................................................................551
30.5. Cancelling Queries in Progress
............................................................................555
30.6. The Fast-Path
Interface.........................................................................................556
30.7. Asynchronous
Notication...................................................................................557
30.8. Functions Associated with the COPY Command
..................................................558 xiii
14. 30.8.1. Functions for Sending COPY
Data............................................................559
30.8.2. Functions for Receiving COPY
Data.........................................................560
30.8.3. Obsolete Functions for COPY
...................................................................560
30.9. Control
Functions.................................................................................................562
30.10. Miscellaneous Functions
....................................................................................563
30.11. Notice Processing
...............................................................................................565
30.12. Event
System......................................................................................................567
30.12.1. Event
Types............................................................................................567
30.12.2. Event Callback
Procedure......................................................................569
30.12.3. Event Support
Functions........................................................................569
30.12.4. Event
Example.......................................................................................570
30.13. Environment Variables
.......................................................................................573
30.14. The Password File
..............................................................................................574
30.15. The Connection Service File
..............................................................................574
30.16. LDAP Lookup of Connection
Parameters..........................................................575
30.17. SSL
Support........................................................................................................576
30.17.1. Certicate
verication............................................................................576
30.17.2. Client certicates
...................................................................................577
30.17.3. Protection provided in different
modes..................................................577 30.17.4.
SSL File Usage
......................................................................................579
30.17.5. SSL library
initialization........................................................................579
30.18. Behavior in Threaded
Programs.........................................................................580
30.19. Building libpq
Programs.....................................................................................580
30.20. Example
Programs..............................................................................................581
31. Large Objects
....................................................................................................................591
31.1. Introduction
..........................................................................................................591
31.2. Implementation Features
......................................................................................591
31.3. Client
Interfaces....................................................................................................591
31.3.1. Creating a Large
Object...........................................................................591
31.3.2. Importing a Large
Object.........................................................................592
31.3.3. Exporting a Large
Object.........................................................................592
31.3.4. Opening an Existing Large
Object...........................................................592
31.3.5. Writing Data to a Large
Object................................................................593
31.3.6. Reading Data from a Large Object
..........................................................593
31.3.7. Seeking in a Large
Object........................................................................593
31.3.8. Obtaining the Seek Position of a Large
Object........................................594 31.3.9.
Truncating a Large Object
.......................................................................594
31.3.10. Closing a Large Object Descriptor
........................................................594
31.3.11. Removing a Large Object
......................................................................594
31.4. Server-Side
Functions...........................................................................................594
31.5. Example Program
.................................................................................................595
32. ECPG - Embedded SQL in
C............................................................................................601
32.1. The
Concept..........................................................................................................601
32.2. Connecting to the Database
Server.......................................................................601
32.3. Closing a Connection
...........................................................................................602
32.4. Running SQL
Commands.....................................................................................603
32.5. Choosing a
Connection.........................................................................................604
32.6. Using Host Variables
............................................................................................604
32.6.1.
Overview..................................................................................................604
32.6.2. Declare
Sections.......................................................................................605
32.6.3. Different types of host variables
..............................................................605
32.6.4. SELECT INTO and FETCH INTO
............................................................606
xiv
15. 32.6.5.
Indicators..................................................................................................607
32.7. Dynamic
SQL.......................................................................................................608
32.8. pgtypes
library......................................................................................................609
32.8.1. The numeric type
.....................................................................................609
32.8.2. The date
type............................................................................................612
32.8.3. The timestamp
type..................................................................................615
32.8.4. The interval type
......................................................................................619
32.8.5. The decimal
type......................................................................................619
32.8.6. errno values of
pgtypeslib........................................................................620
32.8.7. Special constants of
pgtypeslib................................................................620
32.9. Informix compatibility
mode................................................................................621
32.9.1. Additional embedded SQL
statements.....................................................621
32.9.2. Additional
functions.................................................................................621
32.9.3. Additional
constants.................................................................................630
32.10. Using SQL Descriptor
Areas..............................................................................631
32.11. Error
Handling....................................................................................................633
32.11.1. Setting Callbacks
...................................................................................633
32.11.2. sqlca
.......................................................................................................635
32.11.3. SQLSTATE vs
SQLCODE..........................................................................635
32.12. Preprocessor
directives.......................................................................................638
32.12.1. Including
les.........................................................................................638
32.12.2. The #dene and #undef directives
.........................................................638
32.12.3. ifdef, ifndef, else, elif and endif directives
............................................639 32.13. Processing
Embedded SQL
Programs................................................................639
32.14. Library Functions
...............................................................................................640
32.15. Internals
..............................................................................................................641
33. The Information
Schema...................................................................................................644
33.1. The Schema
..........................................................................................................644
33.2. Data
Types............................................................................................................644
33.3. information_schema_catalog_name
...........................................................644
33.4.
administrable_role_authorizations.......................................................645
33.5.
applicable_roles............................................................................................645
33.6.
attributes.........................................................................................................646
33.7. check_constraint_routine_usage
.............................................................648
33.8. check_constraints
.........................................................................................649
33.9. column_domain_usage
.....................................................................................649
33.10. column_privileges
.......................................................................................650
33.11.
column_udt_usage..........................................................................................651
33.12.
columns.............................................................................................................651
33.13. constraint_column_usage
..........................................................................656
33.14.
constraint_table_usage.............................................................................656
33.15.
data_type_privileges.................................................................................657
33.16. domain_constraints
.....................................................................................658
33.17.
domain_udt_usage..........................................................................................658
33.18.
domains.............................................................................................................659
33.19.
element_types................................................................................................661
33.20.
enabled_roles................................................................................................664
33.21.
foreign_data_wrapper_options................................................................664
33.22.
foreign_data_wrappers...............................................................................665
33.23.
foreign_server_options.............................................................................665
33.24.
foreign_servers............................................................................................666
33.25.
key_column_usage..........................................................................................666
xv
16. 33.26.
parameters.......................................................................................................667
33.27. referential_constraints
..........................................................................670
33.28. role_column_grants
.....................................................................................671
33.29. role_routine_grants
...................................................................................671
33.30. role_table_grants
.......................................................................................672
33.31. role_usage_grants
.......................................................................................673
33.32. routine_privileges
.....................................................................................673
33.33.
routines...........................................................................................................674
33.34.
schemata...........................................................................................................680
33.35.
sequences.........................................................................................................680
33.36. sql_features
..................................................................................................681
33.37. sql_implementation_info
..........................................................................682
33.38.
sql_languages................................................................................................682
33.39. sql_packages
..................................................................................................683
33.40.
sql_parts.........................................................................................................684
33.41.
sql_sizing.......................................................................................................684
33.42. sql_sizing_profiles
...................................................................................685
33.43. table_constraints
.......................................................................................685
33.44.
table_privileges..........................................................................................686
33.45. tables
...............................................................................................................687
33.46.
triggers...........................................................................................................687
33.47.
usage_privileges..........................................................................................689
33.48.
user_mapping_options.................................................................................689
33.49.
user_mappings................................................................................................690
33.50. view_column_usage
.......................................................................................690
33.51. view_routine_usage
.....................................................................................691
33.52.
view_table_usage..........................................................................................692
33.53. views
.................................................................................................................692
V. Server Programming
.................................................................................................................694
34. Extending
SQL..................................................................................................................696
34.1. How Extensibility
Works......................................................................................696
34.2. The PostgreSQL Type
System..............................................................................696
34.2.1. Base Types
...............................................................................................696
34.2.2. Composite
Types......................................................................................696
34.2.3.
Domains...................................................................................................697
34.2.4. Pseudo-Types
...........................................................................................697
34.2.5. Polymorphic Types
..................................................................................697
34.3. User-Dened
Functions........................................................................................698
34.4. Query Language (SQL) Functions
.......................................................................698
34.4.1. SQL Functions on Base
Types.................................................................699
34.4.2. SQL Functions on Composite Types
.......................................................701 34.4.3.
SQL Functions with Output Parameters
..................................................703 34.4.4. SQL
Functions with Variable Numbers of
Arguments............................704 34.4.5. SQL Functions with
Default Values for Arguments................................705
34.4.6. SQL Functions as Table Sources
.............................................................706
34.4.7. SQL Functions Returning Sets
................................................................706
34.4.8. SQL Functions Returning TABLE
............................................................708
34.4.9. Polymorphic SQL Functions
...................................................................708
34.5. Function
Overloading...........................................................................................710
34.6. Function Volatility
Categories..............................................................................711
34.7. Procedural Language Functions
...........................................................................712
xvi
17. 34.8. Internal
Functions.................................................................................................712
34.9. C-Language
Functions..........................................................................................713
34.9.1. Dynamic
Loading.....................................................................................713
34.9.2. Base Types in C-Language
Functions......................................................714
34.9.3. Version 0 Calling Conventions
................................................................717
34.9.4. Version 1 Calling Conventions
................................................................719
34.9.5. Writing
Code............................................................................................721
34.9.6. Compiling and Linking Dynamically-Loaded Functions
........................722 34.9.7. Extension Building
Infrastructure............................................................724
34.9.8. Composite-Type Arguments
....................................................................726
34.9.9. Returning Rows (Composite
Types)........................................................728
34.9.10. Returning
Sets........................................................................................730
34.9.11. Polymorphic Arguments and Return
Types...........................................734 34.9.12. Shared
Memory and LWLocks
..............................................................736
34.10. User-Dened Aggregates
...................................................................................736
34.11. User-Dened Types
............................................................................................739
34.12. User-Dened
Operators......................................................................................742
34.13. Operator Optimization
Information....................................................................743
34.13.1.
COMMUTATOR..........................................................................................743
34.13.2. NEGATOR
................................................................................................744
34.13.3. RESTRICT
..............................................................................................744
34.13.4.
JOIN.......................................................................................................745
34.13.5.
HASHES...................................................................................................746
34.13.6.
MERGES...................................................................................................746
34.14. Interfacing Extensions To
Indexes......................................................................747
34.14.1. Index Methods and Operator Classes
....................................................747 34.14.2.
Index Method Strategies
........................................................................748
34.14.3. Index Method Support Routines
............................................................749
34.14.4. An Example
...........................................................................................751
34.14.5. Operator Classes and Operator
Families................................................753
34.14.6. System Dependencies on Operator
Classes...........................................756 34.14.7.
Special Features of Operator
Classes.....................................................756 35.
Triggers
.............................................................................................................................758
35.1. Overview of Trigger
Behavior..............................................................................758
35.2. Visibility of Data
Changes....................................................................................759
35.3. Writing Trigger Functions in C
............................................................................760
35.4. A Complete Example
...........................................................................................762
36. The Rule System
...............................................................................................................766
36.1. The Query
Tree.....................................................................................................766
36.2. Views and the Rule System
..................................................................................768
36.2.1. How SELECT Rules
Work........................................................................768