1. PostgreSQL 8.4.0 Documentation
The PostgreSQL Global Development Group

2. PostgreSQL 8.4.0 Documentation
by The PostgreSQL Global Development Group
Copyright © 1996-2009 The PostgreSQL Global Development Group
Legal Notice
PostgreSQL is Copyright © 1996-2009 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, INCI-
DENTAL, 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 IM-
PLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HERE-
UNDER 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...........................................................................................................................l
2.3. PostgreSQL.........................................................................................................................l
3. Conventions................................................................................................................................... li
4. Further Information....................................................................................................................... li
5. Bug Reporting Guidelines............................................................................................................ lii
5.1. Identifying Bugs .............................................................................................................. lii
5.2. What to report................................................................................................................. liii
5.3. Where to report bugs ........................................................................................................lv
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 ........................................................................................................................6
2.1. Introduction .......................................................................................................................6
2.2. Concepts ............................................................................................................................6
2.3. Creating a New Table ........................................................................................................6
2.4. Populating a Table With Rows ..........................................................................................7
2.5. Querying a Table ...............................................................................................................8
2.6. Joins Between Tables.......................................................................................................10
2.7. Aggregate Functions........................................................................................................12
2.8. Updates ............................................................................................................................14
2.9. Deletions..........................................................................................................................14
3. Advanced Features .......................................................................................................................16
3.1. Introduction .....................................................................................................................16
3.2. Views ...............................................................................................................................16
3.3. Foreign Keys....................................................................................................................16
3.4. Transactions.....................................................................................................................17
3.5. Window Functions...........................................................................................................19
3.6. Inheritance .......................................................................................................................22
3.7. Conclusion.......................................................................................................................24
II. The SQL Language.............................................................................................................................25
4. SQL Syntax ..................................................................................................................................27
4.1. Lexical Structure..............................................................................................................27
4.1.1. Identifiers and Key Words...................................................................................27
4.1.2. Constants.............................................................................................................29
4.1.2.1. String Constants .....................................................................................29
4.1.2.2. String Constants with C-Style Escapes ..................................................29
4.1.2.3. String Constants with Unicode Escapes.................................................30
4.1.2.4. Dollar-Quoted String Constants .............................................................31
iii

4. 4.1.2.5. Bit-String Constants ...............................................................................32
4.1.2.6. Numeric Constants .................................................................................32
4.1.2.7. Constants of Other Types .......................................................................33
4.1.3. Operators.............................................................................................................34
4.1.4. Special Characters...............................................................................................34
4.1.5. Comments ...........................................................................................................35
4.1.6. Lexical Precedence .............................................................................................35
4.2. Value Expressions............................................................................................................37
4.2.1. Column References.............................................................................................37
4.2.2. Positional Parameters..........................................................................................38
4.2.3. Subscripts............................................................................................................38
4.2.4. Field Selection ....................................................................................................39
4.2.5. Operator Invocations...........................................................................................39
4.2.6. Function Calls .....................................................................................................39
4.2.7. Aggregate Expressions........................................................................................40
4.2.8. Window Function Calls.......................................................................................40
4.2.9. Type Casts ...........................................................................................................42
4.2.10. Scalar Subqueries..............................................................................................42
4.2.11. Array Constructors............................................................................................43
4.2.12. Row Constructors..............................................................................................44
4.2.13. Expression Evaluation Rules ............................................................................46
5. Data Definition .............................................................................................................................48
5.1. Table Basics.....................................................................................................................48
5.2. Default Values .................................................................................................................49
5.3. Constraints.......................................................................................................................50
5.3.1. Check Constraints ...............................................................................................50
5.3.2. Not-Null Constraints...........................................................................................52
5.3.3. Unique Constraints..............................................................................................53
5.3.4. Primary Keys.......................................................................................................54
5.3.5. Foreign Keys .......................................................................................................55
5.4. System Columns..............................................................................................................57
5.5. Modifying Tables.............................................................................................................59
5.5.1. Adding a Column................................................................................................59
5.5.2. Removing a Column ...........................................................................................60
5.5.3. Adding a Constraint ............................................................................................60
5.5.4. Removing a Constraint .......................................................................................60
5.5.5. Changing a Column’s Default Value...................................................................61
5.5.6. Changing a Column’s Data Type ........................................................................61
5.5.7. Renaming a Column ...........................................................................................61
5.5.8. Renaming a Table ...............................................................................................61
5.6. Privileges .........................................................................................................................62
5.7. Schemas...........................................................................................................................62
5.7.1. Creating a Schema ..............................................................................................63
5.7.2. The Public Schema .............................................................................................64
5.7.3. The Schema Search Path.....................................................................................64
5.7.4. Schemas and Privileges.......................................................................................66
5.7.5. The System Catalog Schema ..............................................................................66
5.7.6. Usage Patterns.....................................................................................................66
iv

5. 5.7.7. Portability............................................................................................................67
5.8. Inheritance .......................................................................................................................67
5.8.1. Caveats ................................................................................................................70
5.9. Partitioning ......................................................................................................................71
5.9.1. Overview.............................................................................................................71
5.9.2. Implementing Partitioning ..................................................................................71
5.9.3. Managing Partitions ............................................................................................74
5.9.4. Partitioning and Constraint Exclusion ................................................................75
5.9.5. Alternative Partitioning Methods........................................................................77
5.9.6. Caveats ................................................................................................................77
5.10. Other Database Objects .................................................................................................78
5.11. Dependency Tracking....................................................................................................78
6. Data Manipulation........................................................................................................................80
6.1. Inserting Data ..................................................................................................................80
6.2. Updating Data..................................................................................................................81
6.3. Deleting Data...................................................................................................................82
7. Queries .........................................................................................................................................83
7.1. Overview .........................................................................................................................83
7.2. Table Expressions ............................................................................................................83
7.2.1. The FROM Clause.................................................................................................84
7.2.1.1. Joined Tables ..........................................................................................84
7.2.1.2. Table and Column Aliases......................................................................87
7.2.1.3. Subqueries ..............................................................................................89
7.2.1.4. Table Functions ......................................................................................89
7.2.2. The WHERE Clause...............................................................................................90
7.2.3. The GROUP BY and HAVING Clauses..................................................................91
7.2.4. Window Function Processing .............................................................................93
7.3. Select Lists.......................................................................................................................94
7.3.1. Select-List Items .................................................................................................94
7.3.2. Column Labels ....................................................................................................95
7.3.3. DISTINCT ...........................................................................................................95
7.4. Combining Queries..........................................................................................................96
7.5. Sorting Rows ...................................................................................................................96
7.6. LIMIT and OFFSET..........................................................................................................97
7.7. VALUES Lists ...................................................................................................................98
7.8. WITH Queries ...................................................................................................................99
8. Data Types..................................................................................................................................103
8.1. Numeric Types...............................................................................................................104
8.1.1. Integer Types.....................................................................................................105
8.1.2. Arbitrary Precision Numbers ............................................................................105
8.1.3. Floating-Point Types .........................................................................................106
8.1.4. Serial Types.......................................................................................................108
8.2. Monetary Types .............................................................................................................108
8.3. Character Types .............................................................................................................109
8.4. Binary Data Types .........................................................................................................111
8.5. Date/Time Types............................................................................................................113
8.5.1. Date/Time Input ................................................................................................114
8.5.1.1. Dates.....................................................................................................115
v

6. 8.5.1.2. Times ....................................................................................................115
8.5.1.3. Time Stamps.........................................................................................116
8.5.1.4. Special Values ......................................................................................117
8.5.2. Date/Time Output .............................................................................................118
8.5.3. Time Zones .......................................................................................................119
8.5.4. Interval Input.....................................................................................................120
8.5.5. Interval Output ..................................................................................................122
8.5.6. Internals.............................................................................................................123
8.6. Boolean Type.................................................................................................................123
8.7. Enumerated Types .........................................................................................................124
8.7.1. Declaration of Enumerated Types.....................................................................124
8.7.2. Ordering ............................................................................................................125
8.7.3. Type Safety .......................................................................................................125
8.7.4. Implementation Details.....................................................................................126
8.8. Geometric Types............................................................................................................126
8.8.1. Points ................................................................................................................127
8.8.2. Line Segments...................................................................................................127
8.8.3. Boxes.................................................................................................................127
8.8.4. Paths..................................................................................................................128
8.8.5. Polygons............................................................................................................128
8.8.6. Circles ...............................................................................................................128
8.9. Network Address Types.................................................................................................129
8.9.1. inet ..................................................................................................................129
8.9.2. cidr ..................................................................................................................129
8.9.3. inet vs. cidr ...................................................................................................130
8.9.4. macaddr ...........................................................................................................130
8.10. Bit String Types ...........................................................................................................131
8.11. Text Search Types........................................................................................................131
8.11.1. tsvector .......................................................................................................132
8.11.2. tsquery .........................................................................................................133
8.12. UUID Type ..................................................................................................................134
8.13. XML Type ...................................................................................................................135
8.13.1. Creating XML Values .....................................................................................135
8.13.2. Encoding Handling .........................................................................................136
8.13.3. Accessing XML Values...................................................................................136
8.14. Arrays ..........................................................................................................................137
8.14.1. Declaration of Array Types.............................................................................137
8.14.2. Array Value Input............................................................................................138
8.14.3. Accessing Arrays ............................................................................................139
8.14.4. Modifying Arrays............................................................................................141
8.14.5. Searching in Arrays.........................................................................................144
8.14.6. Array Input and Output Syntax.......................................................................144
8.15. Composite Types .........................................................................................................146
8.15.1. Declaration of Composite Types.....................................................................146
8.15.2. Composite Value Input....................................................................................147
8.15.3. Accessing Composite Types ...........................................................................148
8.15.4. Modifying Composite Types...........................................................................148
8.15.5. Composite Type Input and Output Syntax......................................................149
vi

7. 8.16. Object Identifier Types ................................................................................................150
8.17. Pseudo-Types...............................................................................................................151
9. Functions and Operators ............................................................................................................153
9.1. Logical Operators ..........................................................................................................153
9.2. Comparison Operators...................................................................................................153
9.3. Mathematical Functions and Operators.........................................................................155
9.4. String Functions and Operators .....................................................................................159
9.5. Binary String Functions and Operators .........................................................................172
9.6. Bit String Functions and Operators ...............................................................................174
9.7. Pattern Matching ...........................................................................................................175
9.7.1. LIKE ..................................................................................................................175
9.7.2. SIMILAR TO Regular Expressions ...................................................................176
9.7.3. POSIX Regular Expressions .............................................................................177
9.7.3.1. Regular Expression Details ..................................................................180
9.7.3.2. Bracket Expressions .............................................................................182
9.7.3.3. Regular Expression Escapes.................................................................183
9.7.3.4. Regular Expression Metasyntax...........................................................186
9.7.3.5. Regular Expression Matching Rules ....................................................187
9.7.3.6. Limits and Compatibility .....................................................................189
9.7.3.7. Basic Regular Expressions ...................................................................189
9.8. Data Type Formatting Functions ...................................................................................190
9.9. Date/Time Functions and Operators..............................................................................196
9.9.1. EXTRACT, date_part ......................................................................................200
9.9.2. date_trunc .....................................................................................................204
9.9.3. AT TIME ZONE.................................................................................................205
9.9.4. Current Date/Time ............................................................................................206
9.9.5. Delaying Execution...........................................................................................207
9.10. Enum Support Functions .............................................................................................208
9.11. Geometric Functions and Operators............................................................................209
9.12. Network Address Functions and Operators.................................................................213
9.13. Text Search Functions and Operators..........................................................................215
9.14. XML Functions ...........................................................................................................219
9.14.1. Producing XML Content.................................................................................219
9.14.1.1. xmlcomment ......................................................................................219
9.14.1.2. xmlconcat ........................................................................................220
9.14.1.3. xmlelement ......................................................................................220
9.14.1.4. xmlforest ........................................................................................222
9.14.1.5. xmlpi .................................................................................................222
9.14.1.6. xmlroot .............................................................................................223
9.14.1.7. xmlagg ...............................................................................................223
9.14.1.8. XML Predicates..................................................................................224
9.14.2. Processing XML .............................................................................................224
9.14.3. Mapping Tables to XML.................................................................................224
9.15. Sequence Manipulation Functions ..............................................................................228
9.16. Conditional Expressions..............................................................................................230
9.16.1. CASE ................................................................................................................230
9.16.2. COALESCE .......................................................................................................232
9.16.3. NULLIF............................................................................................................232
vii

8. 9.16.4. GREATEST and LEAST .....................................................................................233
9.17. Array Functions and Operators ...................................................................................233
9.18. Aggregate Functions....................................................................................................235
9.19. Window Functions.......................................................................................................239
9.20. Subquery Expressions .................................................................................................241
9.20.1. EXISTS............................................................................................................241
9.20.2. IN ....................................................................................................................241
9.20.3. NOT IN............................................................................................................242
9.20.4. ANY/SOME ........................................................................................................243
9.20.5. ALL ..................................................................................................................243
9.20.6. Row-wise Comparison....................................................................................244
9.21. Row and Array Comparisons ......................................................................................244
9.21.1. IN ....................................................................................................................244
9.21.2. NOT IN............................................................................................................244
9.21.3. ANY/SOME (array) ............................................................................................245
9.21.4. ALL (array) ......................................................................................................245
9.21.5. Row-wise Comparison....................................................................................246
9.22. Set Returning Functions ..............................................................................................247
9.23. System Information Functions ....................................................................................249
9.24. System Administration Functions ...............................................................................259
9.25. Trigger Functions ........................................................................................................265
10. Type Conversion.......................................................................................................................266
10.1. Overview .....................................................................................................................266
10.2. Operators .....................................................................................................................267
10.3. Functions .....................................................................................................................270
10.4. Value Storage...............................................................................................................273
10.5. UNION, CASE, and Related Constructs.........................................................................274
11. Indexes .....................................................................................................................................276
11.1. Introduction .................................................................................................................276
11.2. Index Types..................................................................................................................277
11.3. Multicolumn Indexes...................................................................................................278
11.4. Indexes and ORDER BY ................................................................................................279
11.5. Combining Multiple Indexes .......................................................................................280
11.6. Unique Indexes ............................................................................................................281
11.7. Indexes on Expressions ...............................................................................................281
11.8. Partial Indexes .............................................................................................................282
11.9. Operator Classes and Operator Families .....................................................................285
11.10. Examining Index Usage.............................................................................................286
12. Full Text Search .......................................................................................................................288
12.1. Introduction .................................................................................................................288
12.1.1. What Is a Document?......................................................................................289
12.1.2. Basic Text Matching .......................................................................................290
12.1.3. Configurations.................................................................................................291
12.2. Tables and Indexes.......................................................................................................291
12.2.1. Searching a Table ............................................................................................291
12.2.2. Creating Indexes .............................................................................................292
12.3. Controlling Text Search...............................................................................................293
12.3.1. Parsing Documents .........................................................................................294
viii

9. 12.3.2. Parsing Queries ...............................................................................................295
12.3.3. Ranking Search Results ..................................................................................296
12.3.4. Highlighting Results .......................................................................................298
12.4. Additional Features .....................................................................................................300
12.4.1. Manipulating Documents................................................................................300
12.4.2. Manipulating Queries......................................................................................301
12.4.2.1. Query Rewriting .................................................................................302
12.4.3. Triggers for Automatic Updates .....................................................................303
12.4.4. Gathering Document Statistics .......................................................................305
12.5. Parsers..........................................................................................................................305
12.6. Dictionaries..................................................................................................................307
12.6.1. Stop Words......................................................................................................308
12.6.2. Simple Dictionary ...........................................................................................309
12.6.3. Synonym Dictionary .......................................................................................310
12.6.4. Thesaurus Dictionary ......................................................................................311
12.6.4.1. Thesaurus Configuration ....................................................................312
12.6.4.2. Thesaurus Example ............................................................................312
12.6.5. Ispell Dictionary..............................................................................................313
12.6.6. Snowball Dictionary .......................................................................................314
12.7. Configuration Example................................................................................................315
12.8. Testing and Debugging Text Search ............................................................................317
12.8.1. Configuration Testing......................................................................................317
12.8.2. Parser Testing..................................................................................................319
12.8.3. Dictionary Testing...........................................................................................320
12.9. GiST and GIN Index Types .........................................................................................321
12.10. psql Support...............................................................................................................322
12.11. Limitations.................................................................................................................325
12.12. Migration from Pre-8.3 Text Search..........................................................................325
13. Concurrency Control................................................................................................................327
13.1. Introduction .................................................................................................................327
13.2. Transaction Isolation ...................................................................................................327
13.2.1. Read Committed Isolation Level ....................................................................328
13.2.2. Serializable Isolation Level.............................................................................329
13.2.2.1. Serializable Isolation versus True Serializability ...............................330
13.3. Explicit Locking ..........................................................................................................331
13.3.1. Table-Level Locks...........................................................................................331
13.3.2. Row-Level Locks ............................................................................................334
13.3.3. Deadlocks........................................................................................................334
13.3.4. Advisory Locks...............................................................................................335
13.4. Data Consistency Checks at the Application Level.....................................................336
13.5. Locking and Indexes....................................................................................................337
14. Performance Tips .....................................................................................................................339
14.1. Using EXPLAIN ...........................................................................................................339
14.2. Statistics Used by the Planner .....................................................................................344
14.3. Controlling the Planner with Explicit JOIN Clauses...................................................345
14.4. Populating a Database .................................................................................................347
14.4.1. Disable Autocommit .......................................................................................347
14.4.2. Use COPY .........................................................................................................347
ix

10. 14.4.3. Remove Indexes ..............................................................................................348
14.4.4. Remove Foreign Key Constraints ...................................................................348
14.4.5. Increase maintenance_work_mem ...............................................................348
14.4.6. Increase checkpoint_segments .................................................................348
14.4.7. Turn off archive_mode ................................................................................349
14.4.8. Run ANALYZE Afterwards...............................................................................349
14.4.9. Some Notes About pg_dump ..........................................................................349
III. Server Administration ....................................................................................................................351
15. Installation from Source Code .................................................................................................353
15.1. Short Version ...............................................................................................................353
15.2. Requirements...............................................................................................................353
15.3. Getting The Source......................................................................................................355
15.4. Upgrading ....................................................................................................................355
15.5. Installation Procedure..................................................................................................356
15.6. Post-Installation Setup.................................................................................................366
15.6.1. Shared Libraries ..............................................................................................366
15.6.2. Environment Variables....................................................................................367
15.7. Supported Platforms ....................................................................................................367
15.8. Platform-Specific Notes...............................................................................................368
15.8.1. AIX .................................................................................................................368
15.8.1.1. GCC issues .........................................................................................369
15.8.1.2. Unix-domain sockets broken..............................................................369
15.8.1.3. Internet address issues ........................................................................369
15.8.1.4. Memory management.........................................................................370
References and resources.........................................................................371
15.8.2. Cygwin............................................................................................................371
15.8.3. HP-UX ............................................................................................................372
15.8.4. IRIX ................................................................................................................373
15.8.5. MinGW/Native Windows ...............................................................................374
15.8.6. SCO OpenServer and SCO UnixWare............................................................374
15.8.6.1. Skunkware ..........................................................................................374
15.8.6.2. GNU Make .........................................................................................374
15.8.6.3. Readline..............................................................................................375
15.8.6.4. Using the UDK on OpenServer..........................................................375
15.8.6.5. Reading the PostgreSQL man pages ..................................................375
15.8.6.6. C99 Issues with the 7.1.1b Feature Supplement ................................375
15.8.6.7. --enable-thread-safety and UnixWare ....................................376
15.8.7. Solaris .............................................................................................................376
15.8.7.1. Required tools ....................................................................................376
15.8.7.2. Problems with OpenSSL ....................................................................376
15.8.7.3. configure complains about a failed test program................................377
15.8.7.4. 64-bit build sometimes crashes ..........................................................377
15.8.7.5. Compiling for optimal performance...................................................377
15.8.7.6. Using DTrace for tracing PostgreSQL ...............................................377
16. Installation from Source Code on Windows ............................................................................379
16.1. Building with Visual C++ 2005...................................................................................379
16.1.1. Requirements ..................................................................................................379
x

11. 16.1.2. Building ..........................................................................................................380
16.1.3. Cleaning and installing ...................................................................................381
16.1.4. Running the regression tests ...........................................................................382
16.1.5. Building the documentation............................................................................382
16.2. Building libpq with Visual C++ or Borland C++ ........................................................383
16.2.1. Generated files ................................................................................................383
17. Server Setup and Operation .....................................................................................................385
17.1. The PostgreSQL User Account ...................................................................................385
17.2. Creating a Database Cluster ........................................................................................385
17.2.1. Network File Systems .....................................................................................386
17.3. Starting the Database Server........................................................................................386
17.3.1. Server Start-up Failures ..................................................................................388
17.3.2. Client Connection Problems ...........................................................................389
17.4. Managing Kernel Resources........................................................................................389
17.4.1. Shared Memory and Semaphores ...................................................................389
17.4.2. Resource Limits ..............................................................................................395
17.4.3. Linux Memory Overcommit ...........................................................................396
17.5. Shutting Down the Server............................................................................................397
17.6. Preventing Server Spoofing .........................................................................................398
17.7. Encryption Options......................................................................................................398
17.8. Secure TCP/IP Connections with SSL ........................................................................400
17.8.1. Using client certificates...................................................................................400
17.8.2. SSL Server File Usage ....................................................................................401
17.8.3. Creating a Self-Signed Certificate ..................................................................401
17.9. Secure TCP/IP Connections with SSH Tunnels ..........................................................402
18. Server Configuration ................................................................................................................404
18.1. Setting Parameters .......................................................................................................404
18.2. File Locations ..............................................................................................................405
18.3. Connections and Authentication..................................................................................406
18.3.1. Connection Settings ........................................................................................406
18.3.2. Security and Authentication............................................................................408
18.4. Resource Consumption................................................................................................409
18.4.1. Memory...........................................................................................................409
18.4.2. Kernel Resource Usage...................................................................................411
18.4.3. Cost-Based Vacuum Delay .............................................................................412
18.4.4. Background Writer..........................................................................................413
18.4.5. Asynchronous Behavior..................................................................................413
18.5. Write Ahead Log .........................................................................................................414
18.5.1. Settings............................................................................................................414
18.5.2. Checkpoints.....................................................................................................416
18.5.3. Archiving ........................................................................................................417
18.6. Query Planning............................................................................................................418
18.6.1. Planner Method Configuration........................................................................418
18.6.2. Planner Cost Constants ...................................................................................419
18.6.3. Genetic Query Optimizer................................................................................420
18.6.4. Other Planner Options.....................................................................................421
18.7. Error Reporting and Logging ......................................................................................422
18.7.1. Where To Log .................................................................................................422
xi

12. 18.7.2. When To Log ..................................................................................................424
18.7.3. What To Log ...................................................................................................426
18.7.4. Using CSV-Format Log Output ......................................................................429
18.8. Run-Time Statistics .....................................................................................................431
18.8.1. Query and Index Statistics Collector ..............................................................431
18.8.2. Statistics Monitoring.......................................................................................432
18.9. Automatic Vacuuming .................................................................................................432
18.10. Client Connection Defaults .......................................................................................434
18.10.1. Statement Behavior .......................................................................................434
18.10.2. Locale and Formatting ..................................................................................436
18.10.3. Other Defaults...............................................................................................438
18.11. Lock Management .....................................................................................................439
18.12. Version and Platform Compatibility..........................................................................440
18.12.1. Previous PostgreSQL Versions .....................................................................440
18.12.2. Platform and Client Compatibility................................................................441
18.13. Preset Options............................................................................................................442
18.14. Customized Options ..................................................................................................443
18.15. Developer Options .....................................................................................................444
18.16. Short Options.............................................................................................................446
19. Client Authentication ...............................................................................................................448
19.1. The pg_hba.conf file ................................................................................................448
19.2. Username maps ...........................................................................................................453
19.3. Authentication methods...............................................................................................454
19.3.1. Trust authentication.........................................................................................454
19.3.2. Password authentication..................................................................................455
19.3.3. GSSAPI authentication ...................................................................................455
19.3.4. SSPI authentication.........................................................................................456
19.3.5. Kerberos authentication ..................................................................................456
19.3.6. Ident-based authentication ..............................................................................458
19.3.6.1. Ident Authentication over TCP/IP ......................................................458
19.3.6.2. Ident Authentication over Local Sockets ...........................................459
19.3.7. LDAP authentication.......................................................................................459
19.3.8. Certificate authentication ................................................................................460
19.3.9. PAM authentication.........................................................................................460
19.4. Authentication problems .............................................................................................461
20. Database Roles and Privileges .................................................................................................462
20.1. Database Roles ............................................................................................................462
20.2. Role Attributes.............................................................................................................463
20.3. Privileges .....................................................................................................................464
20.4. Role Membership ........................................................................................................465
20.5. Functions and Triggers ................................................................................................466
21. Managing Databases ................................................................................................................468
21.1. Overview .....................................................................................................................468
21.2. Creating a Database.....................................................................................................468
21.3. Template Databases .....................................................................................................469
21.4. Database Configuration ...............................................................................................470
21.5. Destroying a Database .................................................................................................471
21.6. Tablespaces..................................................................................................................471
xii

13. 22. Localization..............................................................................................................................474
22.1. Locale Support.............................................................................................................474
22.1.1. Overview.........................................................................................................474
22.1.2. Behavior ..........................................................................................................475
22.1.3. Problems .........................................................................................................476
22.2. Character Set Support..................................................................................................476
22.2.1. Supported Character Sets................................................................................477
22.2.2. Setting the Character Set.................................................................................479
22.2.3. Automatic Character Set Conversion Between Server and Client..................480
22.2.4. Further Reading ..............................................................................................483
23. Routine Database Maintenance Tasks......................................................................................484
23.1. Routine Vacuuming .....................................................................................................484
23.1.1. Vacuuming Basics...........................................................................................484
23.1.2. Recovering Disk Space ...................................................................................485
23.1.3. Updating Planner Statistics .............................................................................486
23.1.4. Preventing Transaction ID Wraparound Failures............................................487
23.1.5. The Autovacuum Daemon ..............................................................................489
23.2. Routine Reindexing .....................................................................................................490
23.3. Log File Maintenance..................................................................................................491
24. Backup and Restore .................................................................................................................493
24.1. SQL Dump...................................................................................................................493
24.1.1. Restoring the dump .........................................................................................493
24.1.2. Using pg_dumpall...........................................................................................494
24.1.3. Handling large databases ................................................................................495
24.2. File System Level Backup ...........................................................................................496
24.3. Continuous Archiving and Point-In-Time Recovery (PITR) ......................................497
24.3.1. Setting up WAL archiving...............................................................................498
24.3.2. Making a Base Backup ...................................................................................500
24.3.3. Recovering using a Continuous Archive Backup ...........................................502
24.3.3.1. Recovery Settings...............................................................................504
24.3.4. Timelines.........................................................................................................505
24.3.5. Tips and Examples ..........................................................................................506
24.3.5.1. Standalone hot backups ......................................................................506
24.3.5.2. archive_command scripts ................................................................507
24.3.6. Caveats ............................................................................................................507
24.4. Warm Standby Servers for High Availability ..............................................................508
24.4.1. Planning ..........................................................................................................509
24.4.2. Implementation ...............................................................................................510
24.4.3. Failover ...........................................................................................................510
24.4.4. Record-based Log Shipping............................................................................511
24.4.5. Incrementally Updated Backups .....................................................................511
24.5. Migration Between Releases .......................................................................................512
25. High Availability, Load Balancing, and Replication................................................................514
26. Monitoring Database Activity..................................................................................................518
26.1. Standard Unix Tools ....................................................................................................518
26.2. The Statistics Collector................................................................................................519
26.2.1. Statistics Collection Configuration .................................................................519
26.2.2. Viewing Collected Statistics ...........................................................................519
xiii

14. 26.3. Viewing Locks.............................................................................................................527
26.4. Dynamic Tracing .........................................................................................................528
26.4.1. Compiling for Dynamic Tracing.....................................................................528
26.4.2. Built-in Probes ................................................................................................528
26.4.3. Using Probes ...................................................................................................536
26.4.4. Defining New Probes ......................................................................................537
27. Monitoring Disk Usage ............................................................................................................539
27.1. Determining Disk Usage .............................................................................................539
27.2. Disk Full Failure..........................................................................................................540
28. Reliability and the Write-Ahead Log.......................................................................................541
28.1. Reliability ....................................................................................................................541
28.2. Write-Ahead Logging (WAL) .....................................................................................542
28.3. Asynchronous Commit................................................................................................542
28.4. WAL Configuration .....................................................................................................544
28.5. WAL Internals .............................................................................................................546
29. Regression Tests.......................................................................................................................547
29.1. Running the Tests ........................................................................................................547
29.2. Test Evaluation ............................................................................................................548
29.2.1. Error message differences...............................................................................549
29.2.2. Locale differences ...........................................................................................549
29.2.3. Date and time differences ...............................................................................549
29.2.4. Floating-point differences ...............................................................................549
29.2.5. Row ordering differences................................................................................550
29.2.6. Insufficient stack depth ...................................................................................550
29.2.7. The “random” test ...........................................................................................550
29.3. Variant Comparison Files ............................................................................................551
29.4. Test Coverage Examination.........................................................................................552
IV. Client Interfaces ..............................................................................................................................553
30. libpq - C Library ......................................................................................................................555
30.1. Database Connection Control Functions .....................................................................555
30.2. Connection Status Functions .......................................................................................562
30.3. Command Execution Functions ..................................................................................566
30.3.1. Main Functions ...............................................................................................566
30.3.2. Retrieving Query Result Information .............................................................573
30.3.3. Retrieving Result Information for Other Commands .....................................577
30.3.4. Escaping Strings for Inclusion in SQL Commands ........................................578
30.3.5. Escaping Binary Strings for Inclusion in SQL Commands ............................579
30.4. Asynchronous Command Processing ..........................................................................581
30.5. Cancelling Queries in Progress ...................................................................................585
30.6. The Fast-Path Interface................................................................................................586
30.7. Asynchronous Notification..........................................................................................587
30.8. Functions Associated with the COPY Command .........................................................588
30.8.1. Functions for Sending COPY Data...................................................................588
30.8.2. Functions for Receiving COPY Data................................................................589
30.8.3. Obsolete Functions for COPY ..........................................................................590
30.9. Control Functions ........................................................................................................592
30.10. Miscellaneous Functions ...........................................................................................593
xiv

15. 30.11. Notice Processing ......................................................................................................595
30.12. Event System .............................................................................................................597
30.12.1. Event Types...................................................................................................597
30.12.2. Event Callback Procedure.............................................................................599
30.12.3. Event Support Functions...............................................................................600
30.12.4. Event Example ..............................................................................................601
30.13. Environment Variables ..............................................................................................603
30.14. The Password File .....................................................................................................605
30.15. The Connection Service File .....................................................................................605
30.16. LDAP Lookup of Connection Parameters.................................................................606
30.17. SSL Support...............................................................................................................607
30.17.1. Certificate verification...................................................................................607
30.17.2. Client certificates ..........................................................................................607
30.17.3. Protection provided in different modes.........................................................608
30.17.4. SSL File Usage .............................................................................................610
30.17.5. SSL library initialization...............................................................................610
30.18. Behavior in Threaded Programs ................................................................................611
30.19. Building libpq Programs............................................................................................611
30.20. Example Programs.....................................................................................................613
31. Large Objects ...........................................................................................................................623
31.1. Introduction .................................................................................................................623
31.2. Implementation Features .............................................................................................623
31.3. Client Interfaces...........................................................................................................623
31.3.1. Creating a Large Object ..................................................................................623
31.3.2. Importing a Large Object................................................................................624
31.3.3. Exporting a Large Object................................................................................624
31.3.4. Opening an Existing Large Object..................................................................625
31.3.5. Writing Data to a Large Object.......................................................................625
31.3.6. Reading Data from a Large Object .................................................................625
31.3.7. Seeking in a Large Object...............................................................................626
31.3.8. Obtaining the Seek Position of a Large Object...............................................626
31.3.9. Truncating a Large Object ..............................................................................626
31.3.10. Closing a Large Object Descriptor ...............................................................626
31.3.11. Removing a Large Object .............................................................................627
31.4. Server-Side Functions..................................................................................................627
31.5. Example Program ........................................................................................................628
32. ECPG - Embedded SQL in C...................................................................................................633
32.1. The Concept.................................................................................................................633
32.2. Connecting to the Database Server..............................................................................633
32.3. Closing a Connection ..................................................................................................634
32.4. Running SQL Commands............................................................................................635
32.5. Choosing a Connection................................................................................................636
32.6. Using Host Variables ...................................................................................................636
32.6.1. Overview.........................................................................................................637
32.6.2. Declare Sections..............................................................................................637
32.6.3. Different types of host variables .....................................................................638
32.6.4. SELECT INTO and FETCH INTO ...................................................................639
32.6.5. Indicators.........................................................................................................639
xv

16. 32.7. Dynamic SQL..............................................................................................................640
32.8. pgtypes library .............................................................................................................641
32.8.1. The numeric type ............................................................................................641
32.8.2. The date type...................................................................................................644
32.8.3. The timestamp type.........................................................................................648
32.8.4. The interval type .............................................................................................652
32.8.5. The decimal type.............................................................................................652
32.8.6. errno values of pgtypeslib ...............................................................................653
32.8.7. Special constants of pgtypeslib.......................................................................653
32.9. Informix compatibility mode.......................................................................................654
32.9.1. Additional embedded SQL statements............................................................654
32.9.2. Additional functions........................................................................................655
32.9.3. Additional constants........................................................................................663
32.10. Using SQL Descriptor Areas.....................................................................................665
32.11. Error Handling...........................................................................................................666
32.11.1. Setting Callbacks ..........................................................................................667
32.11.2. sqlca ..............................................................................................................668
32.11.3. SQLSTATE vs SQLCODE.................................................................................669
32.12. Preprocessor directives ..............................................................................................672
32.12.1. Including files................................................................................................672
32.12.2. The #define and #undef directives ................................................................672
32.12.3. ifdef, ifndef, else, elif and endif directives ...................................................673
32.13. Processing Embedded SQL Programs.......................................................................674
32.14. Library Functions ......................................................................................................675
32.15. Internals .....................................................................................................................675
33. The Information Schema..........................................................................................................678
33.1. The Schema .................................................................................................................678
33.2. Data Types ...................................................................................................................678
33.3. information_schema_catalog_name ..................................................................679
33.4. administrable_role_authorizations ..............................................................679
33.5. applicable_roles...................................................................................................679
33.6. attributes................................................................................................................680
33.7. check_constraint_routine_usage ....................................................................683
33.8. check_constraints ................................................................................................683
33.9. column_domain_usage ............................................................................................684
33.10. column_privileges ..............................................................................................684
33.11. column_udt_usage.................................................................................................685
33.12. columns ....................................................................................................................686
33.13. constraint_column_usage .................................................................................690
33.14. constraint_table_usage....................................................................................691
33.15. data_type_privileges ........................................................................................692
33.16. domain_constraints ............................................................................................693
33.17. domain_udt_usage.................................................................................................693
33.18. domains ....................................................................................................................694
33.19. element_types .......................................................................................................697
33.20. enabled_roles .......................................................................................................699
33.21. foreign_data_wrapper_options.......................................................................700
33.22. foreign_data_wrappers ......................................................................................700
xvi

17. 33.23. foreign_server_options....................................................................................701
33.24. foreign_servers ...................................................................................................701
33.25. key_column_usage.................................................................................................702
33.26. parameters..............................................................................................................703
33.27. referential_constraints .................................................................................705
33.28. role_column_grants ............................................................................................706
33.29. role_routine_grants ..........................................................................................707
33.30. role_table_grants ..............................................................................................708
33.31. role_usage_grants ..............................................................................................708
33.32. routine_privileges ............................................................................................709
33.33. routines ..................................................................................................................710
33.34. schemata ..................................................................................................................716
33.35. sequences ................................................................................................................716
33.36. sql_features .........................................................................................................717
33.37. sql_implementation_info .................................................................................718
33.38. sql_languages .......................................................................................................719
33.39. sql_packages .........................................................................................................719
33.40. sql_parts ................................................................................................................720
33.41. sql_sizing..............................................................................................................720
33.42. sql_sizing_profiles ..........................................................................................721
33.43. table_constraints ..............................................................................................721
33.44. table_privileges.................................................................................................722
33.45. tables ......................................................................................................................723
33.46. triggers ..................................................................................................................724
33.47. usage_privileges.................................................................................................725
33.48. user_mapping_options ........................................................................................726
33.49. user_mappings .......................................................................................................727
33.50. view_column_usage ..............................................................................................727
33.51. view_routine_usage ............................................................................................728
33.52. view_table_usage.................................................................................................729
33.53. views ........................................................................................................................729
V. Server Programming ........................................................................................................................731
34. Extending SQL.........................................................................................................................733
34.1. How Extensibility Works.............................................................................................733
34.2. The PostgreSQL Type System.....................................................................................733
34.2.1. Base Types ......................................................................................................733
34.2.2. Composite Types.............................................................................................734
34.2.3. Domains ..........................................................................................................734
34.2.4. Pseudo-Types ..................................................................................................734
34.2.5. Polymorphic Types .........................................................................................734
34.3. User-Defined Functions...............................................................................................735
34.4. Query Language (SQL) Functions ..............................................................................735
34.4.1. SQL Functions on Base Types ........................................................................736
34.4.2. SQL Functions on Composite Types ..............................................................738
34.4.3. SQL Functions with Output Parameters .........................................................741
34.4.4. SQL Functions with Variable Numbers of Arguments ...................................742
34.4.5. SQL Functions with Default Values for Arguments .......................................743
xvii