Post on 25-Jun-2020
PostgreSQL 9.5.14 Documentation
The PostgreSQL Global Development Group
PostgreSQL 9.5.14 Documentationby The PostgreSQL Global Development GroupCopyright © 1996-2018 The PostgreSQL Global Development Group
Legal Notice
PostgreSQL is Copyright © 1996-2018 by the PostgreSQL Global Development Group.
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 ..................................................................................................................................................lxxiv
1. What is PostgreSQL? ...............................................................................................................lxxiv2. A Brief History of PostgreSQL.................................................................................................lxxv
2.1. The Berkeley POSTGRES Project ...............................................................................lxxv2.2. Postgres95................................................................................................................... lxxvi2.3. PostgreSQL................................................................................................................. lxxvi
3. Conventions............................................................................................................................ lxxvii4. Further Information................................................................................................................ lxxvii5. Bug Reporting Guidelines...................................................................................................... lxxvii
5.1. Identifying Bugs ....................................................................................................... lxxviii5.2. What to Report ......................................................................................................... lxxviii5.3. Where to Report Bugs ..................................................................................................lxxx
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. Operator Precedence ...........................................................................................36
4.2. Value Expressions............................................................................................................374.2.1. Column References.............................................................................................384.2.2. Positional Parameters..........................................................................................384.2.3. Subscripts............................................................................................................394.2.4. Field Selection ....................................................................................................394.2.5. Operator Invocations...........................................................................................404.2.6. Function Calls .....................................................................................................404.2.7. Aggregate Expressions........................................................................................404.2.8. Window Function Calls.......................................................................................434.2.9. Type Casts ...........................................................................................................454.2.10. Collation Expressions .......................................................................................454.2.11. Scalar Subqueries..............................................................................................464.2.12. Array Constructors............................................................................................474.2.13. Row Constructors..............................................................................................484.2.14. Expression Evaluation Rules ............................................................................50
4.3. Calling Functions.............................................................................................................514.3.1. Using Positional Notation ...................................................................................524.3.2. Using Named Notation .......................................................................................524.3.3. Using Mixed Notation.........................................................................................53
5. Data Definition .............................................................................................................................555.1. Table Basics.....................................................................................................................555.2. Default Values .................................................................................................................565.3. Constraints .......................................................................................................................57
5.3.1. Check Constraints ...............................................................................................575.3.2. Not-Null Constraints...........................................................................................595.3.3. Unique Constraints..............................................................................................605.3.4. Primary Keys.......................................................................................................615.3.5. Foreign Keys .......................................................................................................625.3.6. Exclusion Constraints .........................................................................................65
5.4. System Columns..............................................................................................................655.5. Modifying Tables.............................................................................................................66
5.5.1. Adding a Column................................................................................................675.5.2. Removing a Column ...........................................................................................675.5.3. Adding a Constraint ............................................................................................685.5.4. Removing a Constraint .......................................................................................685.5.5. Changing a Column’s Default Value...................................................................685.5.6. Changing a Column’s Data Type ........................................................................695.5.7. Renaming a Column ...........................................................................................695.5.8. Renaming a Table ...............................................................................................69
5.6. Privileges .........................................................................................................................695.7. Row Security Policies......................................................................................................70
iv
5.8. Schemas...........................................................................................................................765.8.1. Creating a Schema ..............................................................................................765.8.2. The Public Schema .............................................................................................775.8.3. The Schema Search Path.....................................................................................775.8.4. Schemas and Privileges.......................................................................................795.8.5. The System Catalog Schema ..............................................................................795.8.6. Usage Patterns.....................................................................................................805.8.7. Portability............................................................................................................80
5.9. Inheritance .......................................................................................................................815.9.1. Caveats ................................................................................................................84
5.10. Partitioning ....................................................................................................................855.10.1. Overview...........................................................................................................855.10.2. Implementing Partitioning ................................................................................855.10.3. Managing Partitions ..........................................................................................895.10.4. Partitioning and Constraint Exclusion ..............................................................895.10.5. Alternative Partitioning Methods......................................................................915.10.6. Caveats ..............................................................................................................91
5.11. Foreign Data ..................................................................................................................925.12. Other Database Objects .................................................................................................935.13. Dependency Tracking....................................................................................................93
6. Data Manipulation........................................................................................................................956.1. Inserting Data ..................................................................................................................956.2. Updating Data..................................................................................................................966.3. Deleting Data...................................................................................................................976.4. Returning Data From Modified Rows .............................................................................97
7. Queries .........................................................................................................................................997.1. Overview .........................................................................................................................997.2. Table Expressions ............................................................................................................99
7.2.1. The FROM Clause...............................................................................................1007.2.1.1. Joined Tables ........................................................................................1007.2.1.2. Table and Column Aliases....................................................................1047.2.1.3. Subqueries ............................................................................................1057.2.1.4. Table Functions ....................................................................................1067.2.1.5. LATERAL Subqueries ............................................................................107
7.2.2. The WHERE Clause.............................................................................................1087.2.3. The GROUP BY and HAVING Clauses................................................................1097.2.4. GROUPING SETS, CUBE, and ROLLUP ..............................................................1117.2.5. Window Function Processing ...........................................................................114
7.3. Select Lists.....................................................................................................................1147.3.1. Select-List Items ...............................................................................................1157.3.2. Column Labels ..................................................................................................1157.3.3. DISTINCT .........................................................................................................116
7.4. Combining Queries........................................................................................................1167.5. Sorting Rows .................................................................................................................1177.6. LIMIT and OFFSET........................................................................................................1187.7. VALUES Lists .................................................................................................................1197.8. WITH Queries (Common Table Expressions) ................................................................120
7.8.1. SELECT in WITH................................................................................................120
v
7.8.2. Data-Modifying Statements in WITH ................................................................1238. Data Types..................................................................................................................................126
8.1. Numeric Types...............................................................................................................1278.1.1. Integer Types.....................................................................................................1288.1.2. Arbitrary Precision Numbers ............................................................................1298.1.3. Floating-Point Types .........................................................................................1308.1.4. Serial Types.......................................................................................................131
8.2. Monetary Types .............................................................................................................1328.3. Character Types .............................................................................................................1338.4. Binary Data Types .........................................................................................................135
8.4.1. bytea Hex Format............................................................................................1358.4.2. bytea Escape Format.......................................................................................136
8.5. Date/Time Types............................................................................................................1378.5.1. Date/Time Input ................................................................................................139
8.5.1.1. Dates.....................................................................................................1398.5.1.2. Times ....................................................................................................1408.5.1.3. Time Stamps.........................................................................................1418.5.1.4. Special Values ......................................................................................142
8.5.2. Date/Time Output .............................................................................................1438.5.3. Time Zones .......................................................................................................1448.5.4. Interval Input.....................................................................................................1458.5.5. Interval Output ..................................................................................................147
8.6. Boolean Type.................................................................................................................1488.7. Enumerated Types .........................................................................................................149
8.7.1. Declaration of Enumerated Types.....................................................................1498.7.2. Ordering ............................................................................................................1508.7.3. Type Safety .......................................................................................................1518.7.4. Implementation Details.....................................................................................151
8.8. Geometric Types............................................................................................................1518.8.1. Points ................................................................................................................1528.8.2. Lines..................................................................................................................1528.8.3. Line Segments...................................................................................................1538.8.4. Boxes.................................................................................................................1538.8.5. Paths..................................................................................................................1538.8.6. Polygons............................................................................................................1548.8.7. Circles ...............................................................................................................154
8.9. Network Address Types.................................................................................................1548.9.1. inet ..................................................................................................................1558.9.2. cidr ..................................................................................................................1558.9.3. inet vs. cidr...................................................................................................1568.9.4. macaddr ...........................................................................................................156
8.10. Bit String Types ...........................................................................................................1568.11. Text Search Types........................................................................................................157
8.11.1. tsvector .......................................................................................................1578.11.2. tsquery .........................................................................................................159
8.12. UUID Type ..................................................................................................................1608.13. XML Type ...................................................................................................................160
8.13.1. Creating XML Values .....................................................................................161
vi
8.13.2. Encoding Handling .........................................................................................1628.13.3. Accessing XML Values...................................................................................162
8.14. JSON Types .................................................................................................................1638.14.1. JSON Input and Output Syntax.......................................................................1648.14.2. Designing JSON documents effectively .........................................................1658.14.3. jsonb Containment and Existence.................................................................1668.14.4. jsonb Indexing...............................................................................................167
8.15. Arrays ..........................................................................................................................1708.15.1. Declaration of Array Types.............................................................................1708.15.2. Array Value Input............................................................................................1718.15.3. Accessing Arrays ............................................................................................1728.15.4. Modifying Arrays............................................................................................1748.15.5. Searching in Arrays.........................................................................................1778.15.6. Array Input and Output Syntax.......................................................................178
8.16. Composite Types .........................................................................................................1808.16.1. Declaration of Composite Types.....................................................................1808.16.2. Constructing Composite Values......................................................................1818.16.3. Accessing Composite Types ...........................................................................1828.16.4. Modifying Composite Types...........................................................................1828.16.5. Using Composite Types in Queries.................................................................1838.16.6. Composite Type Input and Output Syntax......................................................185
8.17. Range Types ................................................................................................................1868.17.1. Built-in Range Types ......................................................................................1878.17.2. Examples.........................................................................................................1878.17.3. Inclusive and Exclusive Bounds .....................................................................1878.17.4. Infinite (Unbounded) Ranges..........................................................................1888.17.5. Range Input/Output.........................................................................................1888.17.6. Constructing Ranges .......................................................................................1898.17.7. Discrete Range Types .....................................................................................1908.17.8. Defining New Range Types ............................................................................1908.17.9. Indexing ..........................................................................................................1918.17.10. Constraints on Ranges...................................................................................191
8.18. Object Identifier Types ................................................................................................1938.19. pg_lsn Type..................................................................................................................1948.20. Pseudo-Types...............................................................................................................194
9. Functions and Operators ............................................................................................................1979.1. Logical Operators ..........................................................................................................1979.2. Comparison Operators...................................................................................................1979.3. Mathematical Functions and Operators.........................................................................1999.4. String Functions and Operators .....................................................................................203
9.4.1. format..............................................................................................................2189.5. Binary String Functions and Operators .........................................................................2209.6. Bit String Functions and Operators ...............................................................................2229.7. Pattern Matching ...........................................................................................................223
9.7.1. LIKE ..................................................................................................................2249.7.2. SIMILAR TO Regular Expressions ...................................................................2259.7.3. POSIX Regular Expressions .............................................................................226
9.7.3.1. Regular Expression Details ..................................................................229
vii
9.7.3.2. Bracket Expressions .............................................................................2329.7.3.3. Regular Expression Escapes.................................................................2339.7.3.4. Regular Expression Metasyntax...........................................................2359.7.3.5. Regular Expression Matching Rules ....................................................2379.7.3.6. Limits and Compatibility .....................................................................2389.7.3.7. Basic Regular Expressions ...................................................................239
9.8. Data Type Formatting Functions ...................................................................................2399.9. Date/Time Functions and Operators..............................................................................247
9.9.1. EXTRACT, date_part ......................................................................................2539.9.2. date_trunc .....................................................................................................2569.9.3. AT TIME ZONE.................................................................................................2579.9.4. Current Date/Time ............................................................................................2589.9.5. Delaying Execution...........................................................................................260
9.10. Enum Support Functions .............................................................................................2609.11. Geometric Functions and Operators ............................................................................2619.12. Network Address Functions and Operators.................................................................2659.13. Text Search Functions and Operators ..........................................................................2689.14. XML Functions ...........................................................................................................272
9.14.1. Producing XML Content.................................................................................2729.14.1.1. xmlcomment ......................................................................................2729.14.1.2. xmlconcat ........................................................................................2729.14.1.3. xmlelement ......................................................................................2739.14.1.4. xmlforest ........................................................................................2749.14.1.5. xmlpi .................................................................................................2759.14.1.6. xmlroot.............................................................................................2759.14.1.7. xmlagg ...............................................................................................276
9.14.2. XML Predicates ..............................................................................................2779.14.2.1. IS DOCUMENT ....................................................................................2779.14.2.2. IS NOT DOCUMENT............................................................................2779.14.2.3. XMLEXISTS ........................................................................................2779.14.2.4. xml_is_well_formed .....................................................................277
9.14.3. Processing XML .............................................................................................2789.14.4. Mapping Tables to XML.................................................................................280
9.15. JSON Functions and Operators ...................................................................................2839.16. Sequence Manipulation Functions ..............................................................................2929.17. Conditional Expressions..............................................................................................294
9.17.1. CASE ................................................................................................................2949.17.2. COALESCE .......................................................................................................2969.17.3. NULLIF............................................................................................................2969.17.4. GREATEST and LEAST.....................................................................................297
9.18. Array Functions and Operators ...................................................................................2979.19. Range Functions and Operators...................................................................................3019.20. Aggregate Functions....................................................................................................3039.21. Window Functions.......................................................................................................3109.22. Subquery Expressions .................................................................................................312
9.22.1. EXISTS............................................................................................................3139.22.2. IN ....................................................................................................................3139.22.3. NOT IN............................................................................................................314
viii
9.22.4. ANY/SOME ........................................................................................................3149.22.5. ALL ..................................................................................................................3159.22.6. Single-row Comparison ..................................................................................315
9.23. Row and Array Comparisons ......................................................................................3169.23.1. IN ....................................................................................................................3169.23.2. NOT IN............................................................................................................3169.23.3. ANY/SOME (array) ............................................................................................3179.23.4. ALL (array) ......................................................................................................3179.23.5. Row Constructor Comparison.........................................................................3179.23.6. Composite Type Comparison..........................................................................318
9.24. Set Returning Functions ..............................................................................................3199.25. System Information Functions ....................................................................................3229.26. System Administration Functions ...............................................................................335
9.26.1. Configuration Settings Functions....................................................................3359.26.2. Server Signaling Functions .............................................................................3369.26.3. Backup Control Functions ..............................................................................3379.26.4. Recovery Control Functions ...........................................................................3399.26.5. Snapshot Synchronization Functions..............................................................3419.26.6. Replication Functions .....................................................................................3429.26.7. Database Object Management Functions........................................................3459.26.8. Index Maintenance Functions .........................................................................3489.26.9. Generic File Access Functions........................................................................3489.26.10. Advisory Lock Functions..............................................................................349
9.27. Trigger Functions ........................................................................................................3519.28. Event Trigger Functions ..............................................................................................352
9.28.1. Capturing Changes at Command End.............................................................3529.28.2. Processing Objects Dropped by a DDL Command ........................................3539.28.3. Handling a Table Rewrite Event .....................................................................355
10. Type Conversion.......................................................................................................................35610.1. Overview .....................................................................................................................35610.2. Operators .....................................................................................................................35710.3. Functions .....................................................................................................................36110.4. Value Storage...............................................................................................................36510.5. UNION, CASE, and Related Constructs.........................................................................366
11. Indexes .....................................................................................................................................36911.1. Introduction .................................................................................................................36911.2. Index Types..................................................................................................................37011.3. Multicolumn Indexes...................................................................................................37211.4. Indexes and ORDER BY................................................................................................37311.5. Combining Multiple Indexes .......................................................................................37411.6. Unique Indexes ............................................................................................................37511.7. Indexes on Expressions ...............................................................................................37611.8. Partial Indexes .............................................................................................................37611.9. Operator Classes and Operator Families .....................................................................37911.10. Indexes and Collations...............................................................................................38011.11. Examining Index Usage.............................................................................................381
12. Full Text Search .......................................................................................................................38312.1. Introduction .................................................................................................................383
ix
12.1.1. What Is a Document?......................................................................................38412.1.2. Basic Text Matching .......................................................................................38512.1.3. Configurations.................................................................................................386
12.2. Tables and Indexes.......................................................................................................38612.2.1. Searching a Table ............................................................................................38612.2.2. Creating Indexes .............................................................................................387
12.3. Controlling Text Search...............................................................................................38812.3.1. Parsing Documents .........................................................................................38912.3.2. Parsing Queries ...............................................................................................39012.3.3. Ranking Search Results ..................................................................................39112.3.4. Highlighting Results .......................................................................................393
12.4. Additional Features .....................................................................................................39512.4.1. Manipulating Documents................................................................................39512.4.2. Manipulating Queries......................................................................................396
12.4.2.1. Query Rewriting .................................................................................39612.4.3. Triggers for Automatic Updates .....................................................................39812.4.4. Gathering Document Statistics .......................................................................399
12.5. Parsers..........................................................................................................................40012.6. Dictionaries..................................................................................................................402
12.6.1. Stop Words......................................................................................................40312.6.2. Simple Dictionary ...........................................................................................40412.6.3. Synonym Dictionary .......................................................................................40512.6.4. Thesaurus Dictionary ......................................................................................407
12.6.4.1. Thesaurus Configuration ....................................................................40812.6.4.2. Thesaurus Example ............................................................................408
12.6.5. Ispell Dictionary..............................................................................................40912.6.6. Snowball Dictionary .......................................................................................410
12.7. Configuration Example................................................................................................41112.8. Testing and Debugging Text Search ............................................................................412
12.8.1. Configuration Testing......................................................................................41312.8.2. Parser Testing..................................................................................................41512.8.3. Dictionary Testing...........................................................................................416
12.9. GIN and GiST Index Types .........................................................................................41712.10. psql Support...............................................................................................................41812.11. Limitations.................................................................................................................42012.12. Migration from Pre-8.3 Text Search..........................................................................421
13. Concurrency Control ................................................................................................................42213.1. Introduction .................................................................................................................42213.2. Transaction Isolation ...................................................................................................422
13.2.1. Read Committed Isolation Level ....................................................................42313.2.2. Repeatable Read Isolation Level.....................................................................42513.2.3. Serializable Isolation Level.............................................................................426
13.3. Explicit Locking ..........................................................................................................42813.3.1. Table-level Locks ............................................................................................42913.3.2. Row-level Locks .............................................................................................43113.3.3. Page-level Locks .............................................................................................43213.3.4. Deadlocks........................................................................................................43313.3.5. Advisory Locks...............................................................................................434
x
13.4. Data Consistency Checks at the Application Level.....................................................43413.4.1. Enforcing Consistency With Serializable Transactions ..................................43513.4.2. Enforcing Consistency With Explicit Blocking Locks ...................................435
13.5. Caveats.........................................................................................................................43613.6. Locking and Indexes....................................................................................................437
14. Performance Tips .....................................................................................................................43814.1. Using EXPLAIN ...........................................................................................................438
14.1.1. EXPLAIN Basics ..............................................................................................43814.1.2. EXPLAIN ANALYZE ........................................................................................44414.1.3. Caveats ............................................................................................................448
14.2. Statistics Used by the Planner .....................................................................................44914.3. Controlling the Planner with Explicit JOIN Clauses...................................................45014.4. Populating a Database .................................................................................................452
14.4.1. Disable Autocommit .......................................................................................45314.4.2. Use COPY.........................................................................................................45314.4.3. Remove Indexes ..............................................................................................45314.4.4. Remove Foreign Key Constraints ...................................................................45314.4.5. Increase maintenance_work_mem ...............................................................45414.4.6. Increase max_wal_size ................................................................................45414.4.7. Disable WAL Archival and Streaming Replication ........................................45414.4.8. Run ANALYZE Afterwards...............................................................................45514.4.9. Some Notes About pg_dump..........................................................................455
14.5. Non-Durable Settings ..................................................................................................456
III. Server Administration ....................................................................................................................45715. Installation from Source Code .................................................................................................459
15.1. Short Version ...............................................................................................................45915.2. Requirements...............................................................................................................45915.3. Getting The Source......................................................................................................46115.4. Installation Procedure..................................................................................................46115.5. Post-Installation Setup.................................................................................................472
15.5.1. Shared Libraries ..............................................................................................47215.5.2. Environment Variables ....................................................................................473
15.6. Supported Platforms ....................................................................................................47315.7. Platform-specific Notes ...............................................................................................474
15.7.1. AIX .................................................................................................................47415.7.1.1. GCC Issues.........................................................................................47515.7.1.2. Unix-Domain Sockets Broken............................................................47515.7.1.3. Internet Address Issues.......................................................................47515.7.1.4. Memory Management ........................................................................476
References and Resources .......................................................................47715.7.2. Cygwin............................................................................................................47715.7.3. HP-UX ............................................................................................................47815.7.4. MinGW/Native Windows ...............................................................................479
15.7.4.1. Collecting Crash Dumps on Windows ...............................................47915.7.5. SCO OpenServer and SCO UnixWare............................................................480
15.7.5.1. Skunkware ..........................................................................................48015.7.5.2. GNU Make .........................................................................................480
xi
15.7.5.3. Readline..............................................................................................48015.7.5.4. Using the UDK on OpenServer..........................................................48015.7.5.5. Reading the PostgreSQL Man Pages..................................................48115.7.5.6. C99 Issues with the 7.1.1b Feature Supplement ................................48115.7.5.7. Threading on UnixWare .....................................................................481
15.7.6. Solaris .............................................................................................................48115.7.6.1. Required Tools ...................................................................................48115.7.6.2. Problems with OpenSSL ....................................................................48215.7.6.3. configure Complains About a Failed Test Program ...........................48215.7.6.4. 64-bit Build Sometimes Crashes ........................................................48215.7.6.5. Compiling for Optimal Performance..................................................48315.7.6.6. Using DTrace for Tracing PostgreSQL..............................................483
16. Installation from Source Code on Windows ............................................................................48416.1. Building with Visual C++ or the Microsoft Windows SDK........................................484
16.1.1. Requirements ..................................................................................................48516.1.2. Special Considerations for 64-bit Windows ...................................................48716.1.3. Building ..........................................................................................................48716.1.4. Cleaning and Installing ...................................................................................48716.1.5. Running the Regression Tests .........................................................................48816.1.6. Building the Documentation ...........................................................................489
16.2. Building libpq with Visual C++ or Borland C++........................................................48916.2.1. Generated Files ...............................................................................................490
17. Server Setup and Operation .....................................................................................................49117.1. The PostgreSQL User Account ...................................................................................49117.2. Creating a Database Cluster ........................................................................................491
17.2.1. Use of Secondary File Systems.......................................................................49217.2.2. Use of Network File Systems .........................................................................493
17.3. Starting the Database Server........................................................................................49317.3.1. Server Start-up Failures ..................................................................................49417.3.2. Client Connection Problems ...........................................................................495
17.4. Managing Kernel Resources........................................................................................49617.4.1. Shared Memory and Semaphores ...................................................................49617.4.2. systemd RemoveIPC.......................................................................................50117.4.3. Resource Limits ..............................................................................................50217.4.4. Linux Memory Overcommit ...........................................................................50317.4.5. Linux Huge Pages ...........................................................................................505
17.5. Shutting Down the Server............................................................................................50517.6. Upgrading a PostgreSQL Cluster ................................................................................506
17.6.1. Upgrading Data via pg_dumpall.....................................................................50717.6.2. Upgrading Data via pg_upgrade .....................................................................50917.6.3. Upgrading Data via Replication......................................................................509
17.7. Preventing Server Spoofing .........................................................................................50917.8. Encryption Options......................................................................................................50917.9. Secure TCP/IP Connections with SSL ........................................................................511
17.9.1. Using Client Certificates .................................................................................51217.9.2. SSL Server File Usage ....................................................................................51217.9.3. Creating Certificates........................................................................................513
17.10. Secure TCP/IP Connections with SSH Tunnels ........................................................514
xii
17.11. Registering Event Log on Windows..........................................................................51518. Server Configuration ................................................................................................................516
18.1. Setting Parameters .......................................................................................................51618.1.1. Parameter Names and Values..........................................................................51618.1.2. Parameter Interaction via the Configuration File............................................51618.1.3. Parameter Interaction via SQL........................................................................51718.1.4. Parameter Interaction via the Shell .................................................................51818.1.5. Managing Configuration File Contents...........................................................518
18.2. File Locations ..............................................................................................................52018.3. Connections and Authentication..................................................................................521
18.3.1. Connection Settings ........................................................................................52118.3.2. Security and Authentication............................................................................523
18.4. Resource Consumption................................................................................................52618.4.1. Memory...........................................................................................................52618.4.2. Disk .................................................................................................................52818.4.3. Kernel Resource Usage...................................................................................52818.4.4. Cost-based Vacuum Delay ..............................................................................52918.4.5. Background Writer..........................................................................................53018.4.6. Asynchronous Behavior..................................................................................531
18.5. Write Ahead Log .........................................................................................................53118.5.1. Settings............................................................................................................53118.5.2. Checkpoints.....................................................................................................53518.5.3. Archiving ........................................................................................................536
18.6. Replication...................................................................................................................53718.6.1. Sending Server(s)............................................................................................53718.6.2. Master Server ..................................................................................................53818.6.3. Standby Servers ..............................................................................................539
18.7. Query Planning............................................................................................................54118.7.1. Planner Method Configuration........................................................................54118.7.2. Planner Cost Constants ...................................................................................54218.7.3. Genetic Query Optimizer................................................................................54318.7.4. Other Planner Options.....................................................................................544
18.8. Error Reporting and Logging ......................................................................................54518.8.1. Where To Log .................................................................................................54618.8.2. When To Log ..................................................................................................54818.8.3. What To Log ...................................................................................................55018.8.4. Using CSV-Format Log Output ......................................................................55418.8.5. Process Title....................................................................................................555
18.9. Run-time Statistics.......................................................................................................55518.9.1. Query and Index Statistics Collector ..............................................................55618.9.2. Statistics Monitoring.......................................................................................556
18.10. Automatic Vacuuming ...............................................................................................55718.11. Client Connection Defaults .......................................................................................559
18.11.1. Statement Behavior .......................................................................................55918.11.2. Locale and Formatting ..................................................................................56318.11.3. Shared Library Preloading ............................................................................56418.11.4. Other Defaults ...............................................................................................566
18.12. Lock Management .....................................................................................................567
xiii
18.13. Version and Platform Compatibility..........................................................................56818.13.1. Previous PostgreSQL Versions .....................................................................56818.13.2. Platform and Client Compatibility................................................................570
18.14. Error Handling...........................................................................................................57018.15. Preset Options............................................................................................................57018.16. Customized Options ..................................................................................................57218.17. Developer Options .....................................................................................................57218.18. Short Options.............................................................................................................575
19. Client Authentication ...............................................................................................................57719.1. The pg_hba.conf File ...............................................................................................57719.2. User Name Maps .........................................................................................................58319.3. Authentication Methods ..............................................................................................585
19.3.1. Trust Authentication .......................................................................................58519.3.2. Password Authentication ................................................................................58519.3.3. GSSAPI Authentication ..................................................................................58619.3.4. SSPI Authentication........................................................................................58719.3.5. Ident Authentication........................................................................................58819.3.6. Peer Authentication.........................................................................................58919.3.7. LDAP Authentication .....................................................................................58919.3.8. RADIUS Authentication.................................................................................59119.3.9. Certificate Authentication ...............................................................................59219.3.10. PAM Authentication .....................................................................................592
19.4. Authentication Problems .............................................................................................59320. Database Roles .........................................................................................................................594
20.1. Database Roles ............................................................................................................59420.2. Role Attributes.............................................................................................................59520.3. Role Membership ........................................................................................................59620.4. Dropping Roles............................................................................................................59820.5. Function Security.........................................................................................................599
21. Managing Databases ................................................................................................................60021.1. Overview .....................................................................................................................60021.2. Creating a Database.....................................................................................................60021.3. Template Databases .....................................................................................................60121.4. Database Configuration ...............................................................................................60221.5. Destroying a Database .................................................................................................60321.6. Tablespaces..................................................................................................................603
22. Localization..............................................................................................................................60622.1. Locale Support.............................................................................................................606
22.1.1. Overview.........................................................................................................60622.1.2. Behavior ..........................................................................................................60722.1.3. Problems .........................................................................................................608
22.2. Collation Support.........................................................................................................60822.2.1. Concepts..........................................................................................................60922.2.2. Managing Collations.......................................................................................610
22.3. Character Set Support..................................................................................................61122.3.1. Supported Character Sets................................................................................61222.3.2. Setting the Character Set.................................................................................61422.3.3. Automatic Character Set Conversion Between Server and Client..................615
xiv
22.3.4. Further Reading ..............................................................................................61823. Routine Database Maintenance Tasks......................................................................................619
23.1. Routine Vacuuming .....................................................................................................61923.1.1. Vacuuming Basics...........................................................................................61923.1.2. Recovering Disk Space ...................................................................................62023.1.3. Updating Planner Statistics .............................................................................62123.1.4. Updating The Visibility Map ..........................................................................62223.1.5. Preventing Transaction ID Wraparound Failures............................................622
23.1.5.1. Multixacts and Wraparound ...............................................................62523.1.6. The Autovacuum Daemon ..............................................................................626
23.2. Routine Reindexing .....................................................................................................62723.3. Log File Maintenance..................................................................................................627
24. Backup and Restore .................................................................................................................62924.1. SQL Dump...................................................................................................................629
24.1.1. Restoring the Dump ........................................................................................63024.1.2. Using pg_dumpall...........................................................................................63124.1.3. Handling Large Databases ..............................................................................631
24.2. File System Level Backup...........................................................................................63224.3. Continuous Archiving and Point-in-Time Recovery (PITR).......................................633
24.3.1. Setting Up WAL Archiving.............................................................................63424.3.2. Making a Base Backup ...................................................................................63624.3.3. Making a Base Backup Using the Low Level API .........................................63724.3.4. Recovering Using a Continuous Archive Backup ..........................................63924.3.5. Timelines.........................................................................................................64124.3.6. Tips and Examples ..........................................................................................642
24.3.6.1. Standalone Hot Backups ....................................................................64224.3.6.2. Compressed Archive Logs .................................................................64224.3.6.3. archive_command Scripts ...............................................................643
24.3.7. Caveats ............................................................................................................64325. High Availability, Load Balancing, and Replication................................................................645
25.1. Comparison of Different Solutions..............................................................................64525.2. Log-Shipping Standby Servers....................................................................................649
25.2.1. Planning ..........................................................................................................64925.2.2. Standby Server Operation ...............................................................................65025.2.3. Preparing the Master for Standby Servers ......................................................65025.2.4. Setting Up a Standby Server ...........................................................................65025.2.5. Streaming Replication.....................................................................................651
25.2.5.1. Authentication ....................................................................................65225.2.5.2. Monitoring..........................................................................................653
25.2.6. Replication Slots .............................................................................................65325.2.6.1. Querying and manipulating replication slots .....................................65325.2.6.2. Configuration Example ......................................................................653
25.2.7. Cascading Replication ....................................................................................65425.2.8. Synchronous Replication ................................................................................654
25.2.8.1. Basic Configuration............................................................................65525.2.8.2. Planning for Performance...................................................................65625.2.8.3. Planning for High Availability ...........................................................656
25.2.9. Continuous archiving in standby ....................................................................657
xv
25.3. Failover ........................................................................................................................65725.4. Alternative Method for Log Shipping .........................................................................658
25.4.1. Implementation ...............................................................................................65925.4.2. Record-based Log Shipping............................................................................660
25.5. Hot Standby .................................................................................................................66025.5.1. User’s Overview..............................................................................................66025.5.2. Handling Query Conflicts ...............................................................................66225.5.3. Administrator’s Overview...............................................................................66425.5.4. Hot Standby Parameter Reference ..................................................................66725.5.5. Caveats ............................................................................................................667
26. Recovery Configuration ...........................................................................................................66926.1. Archive Recovery Settings ..........................................................................................66926.2. Recovery Target Settings .............................................................................................67026.3. Standby Server Settings...............................................................................................671
27. Monitoring Database Activity..................................................................................................67327.1. Standard Unix Tools ....................................................................................................67327.2. The Statistics Collector................................................................................................674
27.2.1. Statistics Collection Configuration .................................................................67427.2.2. Viewing Statistics............................................................................................67527.2.3. Statistics Functions .........................................................................................690
27.3. Viewing Locks.............................................................................................................69227.4. Dynamic Tracing .........................................................................................................692
27.4.1. Compiling for Dynamic Tracing.....................................................................69327.4.2. Built-in Probes ................................................................................................69327.4.3. Using Probes ...................................................................................................70227.4.4. Defining New Probes ......................................................................................703
28. Monitoring Disk Usage............................................................................................................70528.1. Determining Disk Usage .............................................................................................70528.2. Disk Full Failure..........................................................................................................706
29. Reliability and the Write-Ahead Log.......................................................................................70729.1. Reliability ....................................................................................................................70729.2. Write-Ahead Logging (WAL) .....................................................................................70929.3. Asynchronous Commit................................................................................................70929.4. WAL Configuration .....................................................................................................71129.5. WAL Internals .............................................................................................................714
30. Regression Tests.......................................................................................................................71630.1. Running the Tests ........................................................................................................716
30.1.1. Running the Tests Against a Temporary Installation ......................................71630.1.2. Running the Tests Against an Existing Installation ........................................71730.1.3. Additional Test Suites .....................................................................................71730.1.4. Locale and Encoding.......................................................................................71830.1.5. Extra Tests.......................................................................................................71830.1.6. Testing Hot Standby........................................................................................718
30.2. Test Evaluation ............................................................................................................71930.2.1. Error Message Differences..............................................................................71930.2.2. Locale Differences ..........................................................................................72030.2.3. Date and Time Differences .............................................................................72030.2.4. Floating-Point Differences..............................................................................720
xvi
30.2.5. Row Ordering Differences ..............................................................................72130.2.6. Insufficient Stack Depth..................................................................................72130.2.7. The “random” Test ..........................................................................................72130.2.8. Configuration Parameters................................................................................722
30.3. Variant Comparison Files ............................................................................................72230.4. TAP Tests.....................................................................................................................72330.5. Test Coverage Examination.........................................................................................723
IV. Client Interfaces ..............................................................................................................................72431. libpq - C Library ......................................................................................................................726
31.1. Database Connection Control Functions .....................................................................72631.1.1. Connection Strings..........................................................................................732
31.1.1.1. Keyword/Value Connection Strings ...................................................73331.1.1.2. Connection URIs ................................................................................733
31.1.2. Parameter Key Words .....................................................................................73431.2. Connection Status Functions .......................................................................................73831.3. Command Execution Functions ..................................................................................743
31.3.1. Main Functions ...............................................................................................74331.3.2. Retrieving Query Result Information .............................................................75031.3.3. Retrieving Other Result Information ..............................................................75431.3.4. Escaping Strings for Inclusion in SQL Commands ........................................755
31.4. Asynchronous Command Processing ..........................................................................75831.5. Retrieving Query Results Row-By-Row .....................................................................76231.6. Canceling Queries in Progress.....................................................................................76331.7. The Fast-Path Interface................................................................................................76431.8. Asynchronous Notification..........................................................................................76531.9. Functions Associated with the COPY Command .........................................................766
31.9.1. Functions for Sending COPY Data...................................................................76731.9.2. Functions for Receiving COPY Data................................................................76731.9.3. Obsolete Functions for COPY ..........................................................................768
31.10. Control Functions ......................................................................................................77031.11. Miscellaneous Functions ...........................................................................................77131.12. Notice Processing ......................................................................................................77431.13. Event System .............................................................................................................775
31.13.1. Event Types...................................................................................................77531.13.2. Event Callback Procedure.............................................................................77731.13.3. Event Support Functions...............................................................................77831.13.4. Event Example ..............................................................................................779
31.14. Environment Variables ..............................................................................................78231.15. The Password File .....................................................................................................78331.16. The Connection Service File .....................................................................................78331.17. LDAP Lookup of Connection Parameters .................................................................78431.18. SSL Support...............................................................................................................785
31.18.1. Client Verification of Server Certificates ......................................................78531.18.2. Client Certificates..........................................................................................78631.18.3. Protection Provided in Different Modes .......................................................78631.18.4. SSL Client File Usage...................................................................................78831.18.5. SSL Library Initialization .............................................................................789
xvii
31.19. Behavior in Threaded Programs ................................................................................78931.20. Building libpq Programs.............................................