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. Identifiers 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 Definition......................................................................................................................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 Column’s Default Value............................................................56
5.5.6. Changing a Column’s 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 Identifier 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. Configurations..........................................................................................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 Configuration .............................................................296
12.6.4.2. Thesaurus Example .....................................................................297
12.6.5. Ispell Dictionary.......................................................................................298
12.6.6. Snowball Dictionary ................................................................................299
12.7. Configuration Example.........................................................................................299
12.8. Testing and Debugging Text Search.....................................................................301
12.8.1. Configuration 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-Specific 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. configure 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 files .........................................................................................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 Spoofing..................................................................................376
17.7. Encryption Options...............................................................................................377
17.8. Secure TCP/IP Connections with SSL .................................................................378
17.8.1. Using client certificates............................................................................378
17.8.2. SSL Server File Usage.............................................................................379
17.8.3. Creating a Self-Signed Certificate ...........................................................379
17.9. Secure TCP/IP Connections with SSH Tunnels...................................................380
18. Server Configuration.........................................................................................................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 Configuration.................................................................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 file.........................................................................................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. Certificate 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 Configuration ........................................................................................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 Configuration ..........................................................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. Defining 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 Configuration ..............................................................................................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. Insufficient 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 Notification...................................................................................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. Certificate verification............................................................................576
30.17.2. Client certificates ...................................................................................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 files.........................................................................................638
32.12.2. The #define 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-Defined 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-Defined Aggregates ...................................................................................736
34.11. User-Defined Types ............................................................................................739
34.12. User-Defined 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
36.2.2. View Rules in Non-SELECT Statements ..................................................773
36.2.3. The Power of Views in PostgreSQL ........................................................774
36.2.4. Updating a View.......................................................................................774
36.3. Rules on INSERT, UPDATE, and DELETE .............................................................774
36.3.1. How Update Rules Work .........................................................................775
36.3.1.1. A First Rule Step by Step............................................................776
36.3.2. Cooperation with Views...........................................................................779
36.4. Rules and Privileges .............................................................................................785
36.5. Rules and Command Status..................................................................................786
36.6. Rules versus Triggers ...........................................................................................786
37. Procedural Languages.......................................................................................................790
xvii

18. 37.1. Installing Procedural Languages ..........................................................................790
38. PL/pgSQL - SQL Procedural Language ...........................................................................792
38.1. Overview ..............................................................................................................792
38.1.1. Advantages of Using PL/pgSQL .............................................................792
38.1.2. Supported Argument and Result Data Types...........................................792
38.2. Structure of PL/pgSQL.........................................................................................793
38.3. Declarations..........................................................................................................794
38.3.1. Aliases for Function Parameters ..............................................................795
38.3.2. Copying Types .........................................................................................797
38.3.3. Row Types................................................................................................798
38.3.4. Record Types ...........................................................................................798
38.3.5. RENAME.....................................................................................................799
38.4. Expressions...........................................................................................................799
38.5. Basic Statements...................................................................................................800
38.5.1. Assignment ..............................................................................................800
38.5.2. Executing a Command With No Result...................................................800
38.5.3. Executing a Query with a Single-Row Result .........................................801
38.5.4. Executing Dynamic Commands ..............................................................803
38.5.5. Obtaining the Result Status......................................................................805
38.5.6. Doing Nothing At All ..............................................................................806
38.6. Control Structures.................................................................................................806
38.6.1. Returning From a Function......................................................................807
38.6.1.1. RETURN........................................................................................807
38.6.1.2. RETURN NEXT and RETURN QUERY ...........................................807
38.6.2. Conditionals.............................................................................................808
38.6.2.1. IF-THEN......................................................................................809
38.6.2.2. IF-THEN-ELSE...........................................................................809
38.6.2.3. IF-THEN-ELSIF.........................................................................809
38.6.2.4. Simple CASE................................................................................810
38.6.2.5. Searched CASE.............................................................................811
38.6.3. Simple Loops ...........................................................................................812
38.6.3.1. LOOP ............................................................................................812
38.6.3.2. EXIT ............................................................................................812
38.6.3.3. CONTINUE....................................................................................813
38.6.3.4. WHILE ..........................................................................................813
38.6.3.5. FOR (integer variant)....................................................................813
38.6.4. Looping Through Query Results .............................................................814
38.6.5. Trapping Errors........................................................................................815
38.7. Cursors..................................................................................................................817
38.7.1. Declaring Cursor Variables......................................................................817
38.7.2. Opening Cursors ......................................................................................818
38.7.2.1. OPEN FOR query........................................................................818
38.7.2.2. OPEN FOR EXECUTE ..................................................................818
38.7.2.3. Opening a Bound Cursor.............................................................819
38.7.3. Using Cursors...........................................................................................819
38.7.3.1. FETCH ..........................................................................................819
38.7.3.2. MOVE ............................................................................................820
38.7.3.3. UPDATE/DELETE WHERE CURRENT OF ....................................820
38.7.3.4. CLOSE ..........................................................................................821
38.7.3.5. Returning Cursors .......................................................................821
38.7.4. Looping Through a Cursor’s Result.........................................................822
38.8. Errors and Messages.............................................................................................823
xviii