PostgreSQL 9.0.4 Documentation

The PostgreSQL Global Development Group

PostgreSQL 9.0.4 Documentationby The PostgreSQL Global Development GroupCopyright © 1996-2010 The PostgreSQL Global Development Group

Legal Notice

PostgreSQL is Copyright © 1996-2010 by the PostgreSQL Global Development Group and is distributed under the terms of the license of theUniversity 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 agreementis 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 ITSDOCUMENTATION, 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.

Table of ContentsPreface ......................................................................................................................................................liv

1. What is PostgreSQL? ...................................................................................................................liv2. A Brief History of PostgreSQL.....................................................................................................lv

2.1. The Berkeley POSTGRES Project ...................................................................................lv2.2. Postgres95....................................................................................................................... lvi2.3. PostgreSQL..................................................................................................................... lvi

3. Conventions................................................................................................................................ lvii4. Further Information.................................................................................................................... lvii5. Bug Reporting Guidelines......................................................................................................... lviii

5.1. Identifying Bugs ........................................................................................................... lviii5.2. What to report................................................................................................................. lix5.3. Where to report bugs ...................................................................................................... lxi

I. Tutorial ....................................................................................................................................................11. Getting Started ...............................................................................................................................1

1.1. Installation .........................................................................................................................11.2. Architectural Fundamentals...............................................................................................11.3. Creating a Database...........................................................................................................21.4. Accessing a Database ........................................................................................................3

2. The SQL Language ........................................................................................................................62.1. Introduction .......................................................................................................................62.2. Concepts ............................................................................................................................62.3. Creating a New Table ........................................................................................................62.4. Populating a Table With Rows ..........................................................................................72.5. Querying a Table ...............................................................................................................82.6. Joins Between Tables.......................................................................................................102.7. Aggregate Functions........................................................................................................122.8. Updates ............................................................................................................................142.9. Deletions..........................................................................................................................14

3. Advanced Features .......................................................................................................................163.1. Introduction .....................................................................................................................163.2. Views ...............................................................................................................................163.3. Foreign Keys....................................................................................................................163.4. Transactions.....................................................................................................................173.5. Window Functions...........................................................................................................193.6. Inheritance .......................................................................................................................223.7. Conclusion.......................................................................................................................24

II. The SQL Language.............................................................................................................................254. SQL Syntax ..................................................................................................................................27

4.1. Lexical Structure..............................................................................................................274.1.1. Identifiers and Key Words...................................................................................274.1.2. Constants.............................................................................................................29

4.1.2.1. String Constants .....................................................................................294.1.2.2. String Constants with C-Style Escapes ..................................................294.1.2.3. String Constants with Unicode Escapes.................................................314.1.2.4. Dollar-Quoted String Constants .............................................................32

iii

4.1.2.5. Bit-String Constants ...............................................................................334.1.2.6. Numeric Constants .................................................................................334.1.2.7. Constants of Other Types .......................................................................33

4.1.3. Operators.............................................................................................................344.1.4. Special Characters...............................................................................................354.1.5. Comments ...........................................................................................................354.1.6. Lexical Precedence .............................................................................................36

4.2. Value Expressions............................................................................................................374.2.1. Column References.............................................................................................384.2.2. Positional Parameters..........................................................................................384.2.3. Subscripts............................................................................................................384.2.4. Field Selection ....................................................................................................394.2.5. Operator Invocations...........................................................................................394.2.6. Function Calls .....................................................................................................404.2.7. Aggregate Expressions........................................................................................404.2.8. Window Function Calls.......................................................................................414.2.9. Type Casts ...........................................................................................................434.2.10. Scalar Subqueries..............................................................................................444.2.11. Array Constructors............................................................................................444.2.12. Row Constructors..............................................................................................464.2.13. Expression Evaluation Rules ............................................................................47

4.3. Calling Functions.............................................................................................................484.3.1. Using positional notation ....................................................................................484.3.2. Using named notation .........................................................................................494.3.3. Using mixed notation..........................................................................................49

5. Data Definition .............................................................................................................................515.1. Table Basics.....................................................................................................................515.2. Default Values .................................................................................................................525.3. Constraints .......................................................................................................................53

5.3.1. Check Constraints ...............................................................................................535.3.2. Not-Null Constraints...........................................................................................555.3.3. Unique Constraints..............................................................................................565.3.4. Primary Keys.......................................................................................................575.3.5. Foreign Keys .......................................................................................................585.3.6. Exclusion Constraints .........................................................................................60

5.4. System Columns..............................................................................................................615.5. Modifying Tables.............................................................................................................62

5.5.1. Adding a Column................................................................................................635.5.2. Removing a Column ...........................................................................................635.5.3. Adding a Constraint ............................................................................................635.5.4. Removing a Constraint .......................................................................................645.5.5. Changing a Column’s Default Value...................................................................645.5.6. Changing a Column’s Data Type ........................................................................655.5.7. Renaming a Column ...........................................................................................655.5.8. Renaming a Table ...............................................................................................65

5.6. Privileges .........................................................................................................................655.7. Schemas...........................................................................................................................66

5.7.1. Creating a Schema ..............................................................................................67

iv

5.7.2. The Public Schema .............................................................................................685.7.3. The Schema Search Path.....................................................................................685.7.4. Schemas and Privileges.......................................................................................695.7.5. The System Catalog Schema ..............................................................................695.7.6. Usage Patterns.....................................................................................................705.7.7. Portability............................................................................................................70

5.8. Inheritance .......................................................................................................................715.8.1. Caveats ................................................................................................................73

5.9. Partitioning ......................................................................................................................745.9.1. Overview.............................................................................................................745.9.2. Implementing Partitioning ..................................................................................755.9.3. Managing Partitions ............................................................................................785.9.4. Partitioning and Constraint Exclusion ................................................................795.9.5. Alternative Partitioning Methods........................................................................805.9.6. Caveats ................................................................................................................81

5.10. Other Database Objects .................................................................................................825.11. Dependency Tracking....................................................................................................82

6. Data Manipulation........................................................................................................................846.1. Inserting Data ..................................................................................................................846.2. Updating Data..................................................................................................................856.3. Deleting Data...................................................................................................................86

7. Queries .........................................................................................................................................877.1. Overview .........................................................................................................................877.2. Table Expressions ............................................................................................................87

7.2.1. The FROM Clause.................................................................................................887.2.1.1. Joined Tables ..........................................................................................887.2.1.2. Table and Column Aliases......................................................................917.2.1.3. Subqueries ..............................................................................................937.2.1.4. Table Functions ......................................................................................93

7.2.2. The WHERE Clause...............................................................................................947.2.3. The GROUP BY and HAVING Clauses..................................................................957.2.4. Window Function Processing .............................................................................97

7.3. Select Lists.......................................................................................................................987.3.1. Select-List Items .................................................................................................987.3.2. Column Labels ....................................................................................................987.3.3. DISTINCT ...........................................................................................................99

7.4. Combining Queries........................................................................................................1007.5. Sorting Rows .................................................................................................................1007.6. LIMIT and OFFSET........................................................................................................1017.7. VALUES Lists .................................................................................................................1027.8. WITH Queries (Common Table Expressions) ................................................................103

8. Data Types..................................................................................................................................1078.1. Numeric Types...............................................................................................................108

8.1.1. Integer Types.....................................................................................................1098.1.2. Arbitrary Precision Numbers ............................................................................1098.1.3. Floating-Point Types .........................................................................................1108.1.4. Serial Types.......................................................................................................112

8.2. Monetary Types .............................................................................................................112

v

8.3. Character Types .............................................................................................................1138.4. Binary Data Types .........................................................................................................115

8.4.1. bytea hex format .............................................................................................1168.4.2. bytea escape format ........................................................................................116

8.5. Date/Time Types............................................................................................................1178.5.1. Date/Time Input ................................................................................................119

8.5.1.1. Dates.....................................................................................................1198.5.1.2. Times ....................................................................................................1208.5.1.3. Time Stamps.........................................................................................1218.5.1.4. Special Values ......................................................................................122

8.5.2. Date/Time Output .............................................................................................1238.5.3. Time Zones .......................................................................................................1238.5.4. Interval Input.....................................................................................................1258.5.5. Interval Output ..................................................................................................1278.5.6. Internals.............................................................................................................128

8.6. Boolean Type.................................................................................................................1288.7. Enumerated Types .........................................................................................................129

8.7.1. Declaration of Enumerated Types.....................................................................1298.7.2. Ordering ............................................................................................................1308.7.3. Type Safety .......................................................................................................1308.7.4. Implementation Details.....................................................................................131

8.8. Geometric Types............................................................................................................1318.8.1. Points ................................................................................................................1328.8.2. Line Segments...................................................................................................1328.8.3. Boxes.................................................................................................................1328.8.4. Paths..................................................................................................................1338.8.5. Polygons............................................................................................................1338.8.6. Circles ...............................................................................................................133

8.9. Network Address Types.................................................................................................1348.9.1. inet ..................................................................................................................1348.9.2. cidr ..................................................................................................................1348.9.3. inet vs. cidr...................................................................................................1358.9.4. macaddr ...........................................................................................................135

8.10. Bit String Types ...........................................................................................................1368.11. Text Search Types........................................................................................................136

8.11.1. tsvector .......................................................................................................1378.11.2. tsquery .........................................................................................................138

8.12. UUID Type ..................................................................................................................1398.13. XML Type ...................................................................................................................140

8.13.1. Creating XML Values .....................................................................................1408.13.2. Encoding Handling .........................................................................................1418.13.3. Accessing XML Values...................................................................................141

8.14. Arrays ..........................................................................................................................1428.14.1. Declaration of Array Types.............................................................................1428.14.2. Array Value Input............................................................................................1438.14.3. Accessing Arrays ............................................................................................1448.14.4. Modifying Arrays............................................................................................1468.14.5. Searching in Arrays.........................................................................................149

vi

8.14.6. Array Input and Output Syntax.......................................................................1498.15. Composite Types .........................................................................................................151

8.15.1. Declaration of Composite Types.....................................................................1518.15.2. Composite Value Input....................................................................................1528.15.3. Accessing Composite Types ...........................................................................1538.15.4. Modifying Composite Types...........................................................................1538.15.5. Composite Type Input and Output Syntax......................................................154

8.16. Object Identifier Types ................................................................................................1558.17. Pseudo-Types...............................................................................................................156

9. Functions and Operators ............................................................................................................1589.1. Logical Operators ..........................................................................................................1589.2. Comparison Operators...................................................................................................1589.3. Mathematical Functions and Operators.........................................................................1609.4. String Functions and Operators .....................................................................................1649.5. Binary String Functions and Operators .........................................................................1779.6. Bit String Functions and Operators ...............................................................................1799.7. Pattern Matching ...........................................................................................................180

9.7.1. LIKE ..................................................................................................................1809.7.2. SIMILAR TO Regular Expressions ...................................................................1819.7.3. POSIX Regular Expressions .............................................................................182

9.7.3.1. Regular Expression Details ..................................................................1859.7.3.2. Bracket Expressions .............................................................................1889.7.3.3. Regular Expression Escapes.................................................................1899.7.3.4. Regular Expression Metasyntax...........................................................1919.7.3.5. Regular Expression Matching Rules ....................................................1939.7.3.6. Limits and Compatibility .....................................................................1949.7.3.7. Basic Regular Expressions ...................................................................195

9.8. Data Type Formatting Functions ...................................................................................1959.9. Date/Time Functions and Operators..............................................................................202

9.9.1. EXTRACT, date_part ......................................................................................2069.9.2. date_trunc .....................................................................................................2109.9.3. AT TIME ZONE.................................................................................................2119.9.4. Current Date/Time ............................................................................................2119.9.5. Delaying Execution...........................................................................................213

9.10. Enum Support Functions .............................................................................................2149.11. Geometric Functions and Operators ............................................................................2159.12. Network Address Functions and Operators.................................................................2199.13. Text Search Functions and Operators ..........................................................................2219.14. XML Functions ...........................................................................................................225

9.14.1. Producing XML Content.................................................................................2259.14.1.1. xmlcomment ......................................................................................2259.14.1.2. xmlconcat ........................................................................................2259.14.1.3. xmlelement ......................................................................................2269.14.1.4. xmlforest ........................................................................................2279.14.1.5. xmlpi .................................................................................................2289.14.1.6. xmlroot.............................................................................................2289.14.1.7. xmlagg ...............................................................................................2299.14.1.8. XML Predicates..................................................................................230

vii

9.14.2. Processing XML .............................................................................................2309.14.3. Mapping Tables to XML.................................................................................231

9.15. Sequence Manipulation Functions ..............................................................................2349.16. Conditional Expressions..............................................................................................236

9.16.1. CASE ................................................................................................................2369.16.2. COALESCE .......................................................................................................2389.16.3. NULLIF............................................................................................................2389.16.4. GREATEST and LEAST.....................................................................................239

9.17. Array Functions and Operators ...................................................................................2399.18. Aggregate Functions....................................................................................................2419.19. Window Functions.......................................................................................................2459.20. Subquery Expressions .................................................................................................247

9.20.1. EXISTS............................................................................................................2479.20.2. IN ....................................................................................................................2479.20.3. NOT IN............................................................................................................2489.20.4. ANY/SOME ........................................................................................................2499.20.5. ALL ..................................................................................................................2499.20.6. Row-wise Comparison....................................................................................250

9.21. Row and Array Comparisons ......................................................................................2509.21.1. IN ....................................................................................................................2509.21.2. NOT IN............................................................................................................2519.21.3. ANY/SOME (array) ............................................................................................2519.21.4. ALL (array) ......................................................................................................2519.21.5. Row-wise Comparison....................................................................................252

9.22. Set Returning Functions ..............................................................................................2539.23. System Information Functions ....................................................................................2559.24. System Administration Functions ...............................................................................2659.25. Trigger Functions ........................................................................................................273

10. Type Conversion.......................................................................................................................27410.1. Overview .....................................................................................................................27410.2. Operators .....................................................................................................................27510.3. Functions .....................................................................................................................27810.4. Value Storage...............................................................................................................28110.5. UNION, CASE, and Related Constructs.........................................................................282

11. Indexes .....................................................................................................................................28411.1. Introduction .................................................................................................................28411.2. Index Types..................................................................................................................28511.3. Multicolumn Indexes...................................................................................................28611.4. Indexes and ORDER BY................................................................................................28711.5. Combining Multiple Indexes .......................................................................................28811.6. Unique Indexes ............................................................................................................28911.7. Indexes on Expressions ...............................................................................................28911.8. Partial Indexes .............................................................................................................29011.9. Operator Classes and Operator Families .....................................................................29311.10. Examining Index Usage.............................................................................................294

12. Full Text Search .......................................................................................................................29612.1. Introduction .................................................................................................................296

12.1.1. What Is a Document?......................................................................................297

viii

12.1.2. Basic Text Matching .......................................................................................29812.1.3. Configurations.................................................................................................299

12.2. Tables and Indexes.......................................................................................................29912.2.1. Searching a Table ............................................................................................29912.2.2. Creating Indexes .............................................................................................300

12.3. Controlling Text Search...............................................................................................30112.3.1. Parsing Documents .........................................................................................30212.3.2. Parsing Queries ...............................................................................................30312.3.3. Ranking Search Results ..................................................................................30412.3.4. Highlighting Results .......................................................................................306

12.4. Additional Features .....................................................................................................30812.4.1. Manipulating Documents................................................................................30812.4.2. Manipulating Queries......................................................................................309

12.4.2.1. Query Rewriting .................................................................................30912.4.3. Triggers for Automatic Updates .....................................................................31112.4.4. Gathering Document Statistics .......................................................................312

12.5. Parsers..........................................................................................................................31312.6. Dictionaries..................................................................................................................315

12.6.1. Stop Words......................................................................................................31612.6.2. Simple Dictionary ...........................................................................................31712.6.3. Synonym Dictionary .......................................................................................31812.6.4. Thesaurus Dictionary ......................................................................................320

12.6.4.1. Thesaurus Configuration ....................................................................32112.6.4.2. Thesaurus Example ............................................................................321

12.6.5. Ispell Dictionary..............................................................................................32212.6.6. Snowball Dictionary .......................................................................................323

12.7. Configuration Example................................................................................................32412.8. Testing and Debugging Text Search ............................................................................325

12.8.1. Configuration Testing......................................................................................32612.8.2. Parser Testing..................................................................................................32812.8.3. Dictionary Testing...........................................................................................329

12.9. GiST and GIN Index Types .........................................................................................33012.10. psql Support...............................................................................................................33112.11. Limitations.................................................................................................................33412.12. Migration from Pre-8.3 Text Search..........................................................................334

13. Concurrency Control ................................................................................................................33613.1. Introduction .................................................................................................................33613.2. Transaction Isolation ...................................................................................................336

13.2.1. Read Committed Isolation Level ....................................................................33713.2.2. Serializable Isolation Level.............................................................................338

13.2.2.1. Serializable Isolation versus True Serializability ...............................33913.3. Explicit Locking ..........................................................................................................340

13.3.1. Table-Level Locks...........................................................................................34013.3.2. Row-Level Locks ............................................................................................34313.3.3. Deadlocks........................................................................................................34313.3.4. Advisory Locks...............................................................................................344

13.4. Data Consistency Checks at the Application Level.....................................................34513.5. Locking and Indexes....................................................................................................346

ix

14. Performance Tips .....................................................................................................................34814.1. Using EXPLAIN ...........................................................................................................34814.2. Statistics Used by the Planner .....................................................................................35314.3. Controlling the Planner with Explicit JOIN Clauses...................................................35414.4. Populating a Database .................................................................................................356

14.4.1. Disable Autocommit .......................................................................................35614.4.2. Use COPY.........................................................................................................35714.4.3. Remove Indexes ..............................................................................................35714.4.4. Remove Foreign Key Constraints ...................................................................35714.4.5. Increase maintenance_work_mem ...............................................................35814.4.6. Increase checkpoint_segments .................................................................35814.4.7. Disable WAL archival and streaming replication ...........................................35814.4.8. Run ANALYZE Afterwards...............................................................................35814.4.9. Some Notes About pg_dump..........................................................................359

14.5. Non-Durable Settings ..................................................................................................359

III. Server Administration ....................................................................................................................36115. Installation from Source Code .................................................................................................363

15.1. Short Version ...............................................................................................................36315.2. Requirements...............................................................................................................36315.3. Getting The Source......................................................................................................36515.4. Upgrading ....................................................................................................................36515.5. Installation Procedure..................................................................................................36615.6. Post-Installation Setup.................................................................................................376

15.6.1. Shared Libraries ..............................................................................................37715.6.2. Environment Variables ....................................................................................377

15.7. Supported Platforms ....................................................................................................37815.8. Platform-Specific Notes...............................................................................................379

15.8.1. AIX .................................................................................................................37915.8.1.1. GCC issues .........................................................................................37915.8.1.2. Unix-domain sockets broken..............................................................38015.8.1.3. Internet address issues ........................................................................38015.8.1.4. Memory management.........................................................................381

References and resources.........................................................................38215.8.2. Cygwin............................................................................................................38215.8.3. HP-UX ............................................................................................................38315.8.4. IRIX ................................................................................................................38415.8.5. MinGW/Native Windows ...............................................................................38415.8.6. SCO OpenServer and SCO UnixWare............................................................385

15.8.6.1. Skunkware ..........................................................................................38515.8.6.2. GNU Make .........................................................................................38515.8.6.3. Readline..............................................................................................38515.8.6.4. Using the UDK on OpenServer..........................................................38615.8.6.5. Reading the PostgreSQL man pages ..................................................38615.8.6.6. C99 Issues with the 7.1.1b Feature Supplement ................................38615.8.6.7. Threading on UnixWare .....................................................................386

15.8.7. Solaris .............................................................................................................38615.8.7.1. Required tools ....................................................................................387

x

15.8.7.2. Problems with OpenSSL ....................................................................38715.8.7.3. configure complains about a failed test program................................38715.8.7.4. 64-bit build sometimes crashes ..........................................................38715.8.7.5. Compiling for optimal performance...................................................38815.8.7.6. Using DTrace for tracing PostgreSQL ...............................................388

16. Installation from Source Code on Windows ............................................................................38916.1. Building with Visual C++ or the Platform SDK .........................................................389

16.1.1. Requirements ..................................................................................................39016.1.2. Special considerations for 64-bit Windows ....................................................39116.1.3. Building ..........................................................................................................39116.1.4. Cleaning and installing ...................................................................................39216.1.5. Running the regression tests ...........................................................................39216.1.6. Building the documentation............................................................................392

16.2. Building libpq with Visual C++ or Borland C++........................................................39316.2.1. Generated files ................................................................................................394

17. Server Setup and Operation .....................................................................................................39517.1. The PostgreSQL User Account ...................................................................................39517.2. Creating a Database Cluster ........................................................................................395

17.2.1. Network File Systems .....................................................................................39617.3. Starting the Database Server........................................................................................397

17.3.1. Server Start-up Failures ..................................................................................39817.3.2. Client Connection Problems ...........................................................................399

17.4. Managing Kernel Resources........................................................................................39917.4.1. Shared Memory and Semaphores ...................................................................40017.4.2. Resource Limits ..............................................................................................40517.4.3. Linux Memory Overcommit ...........................................................................406

17.5. Shutting Down the Server............................................................................................40717.6. Preventing Server Spoofing .........................................................................................40817.7. Encryption Options......................................................................................................40917.8. Secure TCP/IP Connections with SSL ........................................................................410

17.8.1. Using client certificates...................................................................................41117.8.2. SSL Server File Usage ....................................................................................41117.8.3. Creating a Self-Signed Certificate ..................................................................412

17.9. Secure TCP/IP Connections with SSH Tunnels ..........................................................41218. Server Configuration ................................................................................................................414

18.1. Setting Parameters .......................................................................................................41418.2. File Locations ..............................................................................................................41518.3. Connections and Authentication..................................................................................416

18.3.1. Connection Settings ........................................................................................41618.3.2. Security and Authentication............................................................................419

18.4. Resource Consumption................................................................................................42018.4.1. Memory...........................................................................................................42018.4.2. Kernel Resource Usage...................................................................................42218.4.3. Cost-Based Vacuum Delay .............................................................................42318.4.4. Background Writer..........................................................................................42418.4.5. Asynchronous Behavior..................................................................................425

18.5. Write Ahead Log .........................................................................................................42518.5.1. Settings............................................................................................................425

xi

18.5.2. Checkpoints.....................................................................................................42818.5.3. Archiving ........................................................................................................42918.5.4. Streaming Replication.....................................................................................42918.5.5. Standby Servers ..............................................................................................430

18.6. Query Planning............................................................................................................43118.6.1. Planner Method Configuration........................................................................43118.6.2. Planner Cost Constants ...................................................................................43218.6.3. Genetic Query Optimizer................................................................................43318.6.4. Other Planner Options.....................................................................................434

18.7. Error Reporting and Logging ......................................................................................43618.7.1. Where To Log .................................................................................................43618.7.2. When To Log ..................................................................................................43818.7.3. What To Log ...................................................................................................44018.7.4. Using CSV-Format Log Output ......................................................................443

18.8. Run-Time Statistics .....................................................................................................44518.8.1. Query and Index Statistics Collector ..............................................................44518.8.2. Statistics Monitoring.......................................................................................446

18.9. Automatic Vacuuming .................................................................................................44618.10. Client Connection Defaults .......................................................................................448

18.10.1. Statement Behavior .......................................................................................44818.10.2. Locale and Formatting ..................................................................................45018.10.3. Other Defaults ...............................................................................................452

18.11. Lock Management .....................................................................................................45318.12. Version and Platform Compatibility..........................................................................454

18.12.1. Previous PostgreSQL Versions .....................................................................45418.12.2. Platform and Client Compatibility................................................................455

18.13. Preset Options............................................................................................................45618.14. Customized Options ..................................................................................................45718.15. Developer Options .....................................................................................................45818.16. Short Options.............................................................................................................461

19. Client Authentication ...............................................................................................................46219.1. The pg_hba.conf file ................................................................................................46219.2. User name maps ..........................................................................................................46719.3. Authentication methods...............................................................................................468

19.3.1. Trust authentication.........................................................................................46919.3.2. Password authentication..................................................................................46919.3.3. GSSAPI authentication ...................................................................................46919.3.4. SSPI authentication.........................................................................................47019.3.5. Kerberos authentication ..................................................................................47119.3.6. Ident-based authentication ..............................................................................472

19.3.6.1. Ident Authentication over TCP/IP......................................................47319.3.6.2. Ident Authentication over Local Sockets ...........................................473

19.3.7. LDAP authentication.......................................................................................47319.3.8. RADIUS authentication ..................................................................................47519.3.9. Certificate authentication ................................................................................47519.3.10. PAM authentication.......................................................................................476

19.4. Authentication problems .............................................................................................47620. Database Roles and Privileges .................................................................................................478

xii

20.1. Database Roles ............................................................................................................47820.2. Role Attributes.............................................................................................................47920.3. Privileges .....................................................................................................................48020.4. Role Membership ........................................................................................................48120.5. Function and Trigger Security .....................................................................................482

21. Managing Databases ................................................................................................................48421.1. Overview .....................................................................................................................48421.2. Creating a Database.....................................................................................................48421.3. Template Databases .....................................................................................................48521.4. Database Configuration ...............................................................................................48621.5. Destroying a Database .................................................................................................48721.6. Tablespaces..................................................................................................................487

22. Localization..............................................................................................................................49022.1. Locale Support.............................................................................................................490

22.1.1. Overview.........................................................................................................49022.1.2. Behavior ..........................................................................................................49122.1.3. Problems .........................................................................................................492

22.2. Character Set Support..................................................................................................49222.2.1. Supported Character Sets................................................................................49322.2.2. Setting the Character Set.................................................................................49522.2.3. Automatic Character Set Conversion Between Server and Client..................49622.2.4. Further Reading ..............................................................................................499

23. Routine Database Maintenance Tasks......................................................................................50023.1. Routine Vacuuming .....................................................................................................500

23.1.1. Vacuuming Basics...........................................................................................50023.1.2. Recovering Disk Space ...................................................................................50123.1.3. Updating Planner Statistics .............................................................................50223.1.4. Preventing Transaction ID Wraparound Failures............................................50323.1.5. The Autovacuum Daemon ..............................................................................505

23.2. Routine Reindexing .....................................................................................................50623.3. Log File Maintenance..................................................................................................507

24. Backup and Restore .................................................................................................................50924.1. SQL Dump...................................................................................................................509

24.1.1. Restoring the dump.........................................................................................51024.1.2. Using pg_dumpall...........................................................................................51024.1.3. Handling large databases ................................................................................511

24.2. File System Level Backup...........................................................................................51224.3. Continuous Archiving and Point-In-Time Recovery (PITR) ......................................513

24.3.1. Setting up WAL archiving...............................................................................51424.3.2. Making a Base Backup ...................................................................................51624.3.3. Recovering using a Continuous Archive Backup ...........................................51824.3.4. Timelines.........................................................................................................52024.3.5. Tips and Examples ..........................................................................................521

24.3.5.1. Standalone hot backups......................................................................52124.3.5.2. archive_command scripts ................................................................522

24.3.6. Caveats ............................................................................................................52224.4. Migration Between Releases .......................................................................................523

24.4.1. Migrating data via pg_dump...........................................................................524

xiii

24.4.2. Other data migration methods.........................................................................52525. High Availability, Load Balancing, and Replication................................................................526

25.1. Comparison of different solutions ...............................................................................52625.2. Log-Shipping Standby Servers....................................................................................530

25.2.1. Planning ..........................................................................................................53025.2.2. Standby Server Operation ...............................................................................53125.2.3. Preparing the Master for Standby Servers ......................................................53125.2.4. Setting Up a Standby Server ...........................................................................53125.2.5. Streaming Replication.....................................................................................532

25.2.5.1. Authentication ....................................................................................53325.2.5.2. Monitoring..........................................................................................534

25.3. Failover ........................................................................................................................53425.4. Alternative method for log shipping............................................................................535

25.4.1. Implementation ...............................................................................................53625.4.2. Record-based Log Shipping............................................................................536

25.5. Hot Standby .................................................................................................................53725.5.1. User’s Overview..............................................................................................53725.5.2. Handling query conflicts .................................................................................53925.5.3. Administrator’s Overview...............................................................................54125.5.4. Hot Standby Parameter Reference ..................................................................54325.5.5. Caveats ............................................................................................................543

26. Recovery Configuration ...........................................................................................................54526.1. Archive recovery settings ............................................................................................54526.2. Recovery target settings...............................................................................................54626.3. Standby server settings ................................................................................................546

27. Monitoring Database Activity..................................................................................................54827.1. Standard Unix Tools ....................................................................................................54827.2. The Statistics Collector................................................................................................549

27.2.1. Statistics Collection Configuration .................................................................54927.2.2. Viewing Collected Statistics ...........................................................................549

27.3. Viewing Locks.............................................................................................................55827.4. Dynamic Tracing .........................................................................................................558

27.4.1. Compiling for Dynamic Tracing.....................................................................55827.4.2. Built-in Probes ................................................................................................55927.4.3. Using Probes ...................................................................................................56727.4.4. Defining New Probes ......................................................................................567

28. Monitoring Disk Usage............................................................................................................57028.1. Determining Disk Usage .............................................................................................57028.2. Disk Full Failure..........................................................................................................571

29. Reliability and the Write-Ahead Log.......................................................................................57229.1. Reliability ....................................................................................................................57229.2. Write-Ahead Logging (WAL) .....................................................................................57329.3. Asynchronous Commit................................................................................................57429.4. WAL Configuration .....................................................................................................57529.5. WAL Internals .............................................................................................................578

30. Regression Tests.......................................................................................................................57930.1. Running the Tests ........................................................................................................57930.2. Test Evaluation ............................................................................................................581

xiv

30.2.1. Error message differences...............................................................................58130.2.2. Locale differences ...........................................................................................58130.2.3. Date and time differences ...............................................................................58230.2.4. Floating-point differences ...............................................................................58230.2.5. Row ordering differences................................................................................58230.2.6. Insufficient stack depth ...................................................................................58330.2.7. The “random” test ...........................................................................................583

30.3. Variant Comparison Files ............................................................................................58330.4. Test Coverage Examination.........................................................................................584

IV. Client Interfaces ..............................................................................................................................58631. libpq - C Library ......................................................................................................................588

31.1. Database Connection Control Functions .....................................................................58831.2. Connection Status Functions .......................................................................................59731.3. Command Execution Functions ..................................................................................600

31.3.1. Main Functions ...............................................................................................60031.3.2. Retrieving Query Result Information .............................................................60731.3.3. Retrieving Other Result Information ..............................................................61131.3.4. Escaping Strings for Inclusion in SQL Commands ........................................612

31.4. Asynchronous Command Processing ..........................................................................61531.5. Cancelling Queries in Progress ...................................................................................61831.6. The Fast-Path Interface................................................................................................61931.7. Asynchronous Notification..........................................................................................62031.8. Functions Associated with the COPY Command .........................................................621

31.8.1. Functions for Sending COPY Data...................................................................62231.8.2. Functions for Receiving COPY Data................................................................62331.8.3. Obsolete Functions for COPY ..........................................................................624

31.9. Control Functions ........................................................................................................62631.10. Miscellaneous Functions ...........................................................................................62731.11. Notice Processing ......................................................................................................62931.12. Event System .............................................................................................................630

31.12.1. Event Types...................................................................................................63031.12.2. Event Callback Procedure.............................................................................63231.12.3. Event Support Functions...............................................................................63331.12.4. Event Example ..............................................................................................634

31.13. Environment Variables ..............................................................................................63731.14. The Password File .....................................................................................................63831.15. The Connection Service File .....................................................................................63931.16. LDAP Lookup of Connection Parameters .................................................................63931.17. SSL Support...............................................................................................................640

31.17.1. Certificate verification...................................................................................64031.17.2. Client certificates ..........................................................................................64131.17.3. Protection provided in different modes.........................................................64131.17.4. SSL File Usage .............................................................................................64331.17.5. SSL library initialization...............................................................................644

31.18. Behavior in Threaded Programs ................................................................................64531.19. Building libpq Programs............................................................................................64531.20. Example Programs.....................................................................................................646

xv

32. Large Objects ...........................................................................................................................65632.1. Introduction .................................................................................................................65632.2. Implementation Features .............................................................................................65632.3. Client Interfaces...........................................................................................................656

32.3.1. Creating a Large Object ..................................................................................65632.3.2. Importing a Large Object................................................................................65732.3.3. Exporting a Large Object................................................................................65832.3.4. Opening an Existing Large Object..................................................................65832.3.5. Writing Data to a Large Object.......................................................................65832.3.6. Reading Data from a Large Object .................................................................65932.3.7. Seeking in a Large Object...............................................................................65932.3.8. Obtaining the Seek Position of a Large Object...............................................65932.3.9. Truncating a Large Object ..............................................................................65932.3.10. Closing a Large Object Descriptor ...............................................................66032.3.11. Removing a Large Object .............................................................................660

32.4. Server-Side Functions..................................................................................................66032.5. Example Program ........................................................................................................661

33. ECPG - Embedded SQL in C...................................................................................................66733.1. The Concept.................................................................................................................66733.2. Connecting to the Database Server..............................................................................66733.3. Closing a Connection ..................................................................................................66833.4. Running SQL Commands............................................................................................66933.5. Choosing a Connection................................................................................................67033.6. Using Host Variables ...................................................................................................670

33.6.1. Overview.........................................................................................................67133.6.2. Declare Sections..............................................................................................67133.6.3. Different types of host variables .....................................................................67233.6.4. SELECT INTO and FETCH INTO ...................................................................67333.6.5. Indicators.........................................................................................................673

33.7. Dynamic SQL..............................................................................................................67433.8. pgtypes library .............................................................................................................675

33.8.1. The numeric type ............................................................................................67533.8.2. The date type...................................................................................................67833.8.3. The timestamp type.........................................................................................68233.8.4. The interval type .............................................................................................68633.8.5. The decimal type.............................................................................................68633.8.6. errno values of pgtypeslib ...............................................................................68733.8.7. Special constants of pgtypeslib.......................................................................687

33.9. Using Descriptor Areas ...............................................................................................68833.9.1. Named SQL Descriptor Areas ........................................................................68833.9.2. SQLDA Descriptor Areas ...............................................................................690

33.10. Informix compatibility mode.....................................................................................69333.10.1. Additional types ............................................................................................69333.10.2. Additional/missing embedded SQL statements ............................................69433.10.3. Informix-compatible SQLDA Descriptor Areas...........................................69433.10.4. Additional functions......................................................................................69733.10.5. Additional constants......................................................................................706

33.11. Error Handling...........................................................................................................707

xvi

33.11.1. Setting Callbacks ..........................................................................................70733.11.2. sqlca ..............................................................................................................70933.11.3. SQLSTATE vs SQLCODE.................................................................................710

33.12. Preprocessor directives ..............................................................................................71333.12.1. Including files................................................................................................71333.12.2. The #define and #undef directives ................................................................71333.12.3. ifdef, ifndef, else, elif, and endif directives ..................................................714

33.13. Processing Embedded SQL Programs.......................................................................71533.14. Library Functions ......................................................................................................71633.15. Internals .....................................................................................................................716

34. The Information Schema..........................................................................................................71934.1. The Schema .................................................................................................................71934.2. Data Types ...................................................................................................................71934.3. information_schema_catalog_name ..................................................................72034.4. administrable_role_authorizations ..............................................................72034.5. applicable_roles...................................................................................................72034.6. attributes................................................................................................................72134.7. check_constraint_routine_usage ....................................................................72434.8. check_constraints ................................................................................................72434.9. column_domain_usage ............................................................................................72534.10. column_privileges ..............................................................................................72534.11. column_udt_usage.................................................................................................72634.12. columns ....................................................................................................................72734.13. constraint_column_usage .................................................................................73134.14. constraint_table_usage....................................................................................73234.15. data_type_privileges ........................................................................................73334.16. domain_constraints ............................................................................................73434.17. domain_udt_usage.................................................................................................73434.18. domains ....................................................................................................................73534.19. element_types .......................................................................................................73834.20. enabled_roles .......................................................................................................74134.21. foreign_data_wrapper_options.......................................................................74134.22. foreign_data_wrappers......................................................................................74134.23. foreign_server_options....................................................................................74234.24. foreign_servers...................................................................................................74234.25. key_column_usage.................................................................................................74334.26. parameters..............................................................................................................74434.27. referential_constraints .................................................................................74734.28. role_column_grants ............................................................................................74834.29. role_routine_grants ..........................................................................................74834.30. role_table_grants ..............................................................................................74934.31. role_usage_grants ..............................................................................................75034.32. routine_privileges ............................................................................................75134.33. routines .................................................