From 64a7b58aa0b202d308e0456acf62e1c5927aba8c Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Thu, 11 Sep 2003 17:27:38 +0000 Subject: [PATCH] This patch makes a number of improvements to the runtime config documentation. Neil Conway --- doc/src/sgml/runtime.sgml | 284 +++++++++++++++++++++----------------- 1 file changed, 156 insertions(+), 128 deletions(-) diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 425036d81d..57310c221f 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,5 +1,5 @@ @@ -448,14 +448,15 @@ psql: could not connect to server: Connection refused - There are a lot of configuration parameters that affect the behavior - of the database system. Here we describe how to set them and the - following subsections will discuss each in detail. + There are a lot of configuration parameters that affect the + behavior of the database system. In this subsection, we describe + how to set configuration parameters; the following subsections + discuss each parameter in detail. All parameter names are case-insensitive. Every parameter takes a - value of one of the four types: Boolean, integer, floating point, + value of one of the four types: boolean, integer, floating point, and string. Boolean values are ON, OFF, TRUE, FALSE, YES, @@ -465,18 +466,18 @@ psql: could not connect to server: Connection refused One way to set these options is to edit the file - postgresql.confpostgresql.conf in the data directory. (A - default file is installed there.) An example of what this file might - look like is: + postgresql.confpostgresql.conf + in the data directory. (A default file is installed there.) An + example of what this file might look like is: # This is a comment log_connections = yes syslog = 2 search_path = '$user, public' - As you see, options are one per line. The equal sign between name - and value is optional. Whitespace is insignificant and blank lines - are ignored. Hash marks (#) introduce comments + One option is specified per line. The equal sign between name and + value is optional. Whitespace is insignificant and blank lines are + ignored. Hash marks (#) introduce comments anywhere. Parameter values that are not simple identifiers or numbers should be single-quoted. @@ -485,12 +486,14 @@ search_path = '$user, public' SIGHUP - The configuration file is reread whenever the postmaster process receives a - SIGHUP signal (which is most easily sent by means of - pg_ctl reload). The postmaster also propagates this - signal to all currently running server processes so that existing - sessions also get the new value. Alternatively, you can send the - signal to a single server process directly. + The configuration file is reread whenever the + postmaster process receives a + SIGHUP signal (which is most easily sent by means + of pg_ctl reload). The postmaster + also propagates this signal to all currently running server + processes so that existing sessions also get the new + value. Alternatively, you can send the signal to a single server + process directly. @@ -518,20 +521,21 @@ env PGOPTIONS='-c geqo=off' psql - Some options can be changed in individual SQL sessions with the - SET command, for example: + Some options can be changed in individual SQL + sessions with the SET command, for example: SET ENABLE_SEQSCAN TO OFF; - See the SQL command language reference for details on the syntax. + See the SQL command language reference for + details on the syntax. Furthermore, it is possible to assign a set of option settings to a user or a database. Whenever a session is started, the default settings for the user and database involved are loaded. The - commands ALTER DATABASE and ALTER - USER, respectively, are used to configure these + commands ALTER DATABASE and ALTER + USER, respectively, are used to configure these settings. Such per-database settings override anything received from the postmaster command-line or the configuration file, and in turn are overridden by per-user @@ -643,9 +647,9 @@ SET ENABLE_SEQSCAN TO OFF; Determines the maximum number of concurrent connections to the database server. The default is typically 100, but may be less - if your kernel settings will not support it (as determined - during initdb). - This parameter can only be set at server start. + if your kernel settings will not support it (as determined + during initdb). This parameter can only be + set at server start. @@ -665,16 +669,16 @@ SET ENABLE_SEQSCAN TO OFF; Determines the number of connection slots that are reserved for connections by PostgreSQL - superusers. At most max_connections connections can + superusers. At most MAX_CONNECTIONS connections can ever be active simultaneously. Whenever the number of active - concurrent connections is at least max_connections minus - superuser_reserved_connections, new connections + concurrent connections is at least MAX_CONNECTIONS minus + SUPERUSER_RESERVED_CONNECTIONS, new connections will be accepted only for superusers. The default value is 2. The value must be less than the value of - max_connections. This parameter can only be + MAX_CONNECTIONS. This parameter can only be set at server start. @@ -874,7 +878,7 @@ SET ENABLE_SEQSCAN TO OFF; - Resource Usage (Except WAL) + Resource Consumption Memory @@ -885,16 +889,16 @@ SET ENABLE_SEQSCAN TO OFF; Sets the number of shared memory buffers used by the database - server. The default is typically 1000, but may be less - if your kernel settings will not support it (as determined - during initdb). Each buffer is 8192 - bytes, unless a different value of BLCKSZ was chosen - when building the server. This setting must be at least 16, - as well as at least twice the value of - MAX_CONNECTIONS; however, settings significantly - higher than the minimum are usually needed for good performance. - Values of a few thousand are recommended for production installations. - This option can only be set at server start. + server. The default is typically 1000, but may be less if your + kernel settings will not support it (as determined during + initdb). Each buffer is 8192 bytes, unless a + different value of BLCKSZ was chosen when building + the server. This setting must be at least 16, as well as at + least twice the value of MAX_CONNECTIONS; + however, settings significantly higher than the minimum are + usually needed for good performance. Values of a few thousand + are recommended for production installations. This option can + only be set at server start. @@ -924,7 +928,7 @@ SET ENABLE_SEQSCAN TO OFF; Hash tables are used in hash joins, hash-based aggregation, and hash-based processing of IN subqueries. Because CREATE INDEX is used when restoring a database, it might - be good to temporary increase this value during a restore. + be good to temporarily increase this value during a restore. @@ -955,7 +959,7 @@ SET ENABLE_SEQSCAN TO OFF; Sets the maximum number of disk pages for which free space will be tracked in the shared free-space map. Six bytes of shared memory are consumed for each page slot. This setting must be more than - 16 * max_fsm_relations. The default is 20000. + 16 * MAX_FSM_RELATIONS. The default is 20000. This option can only be set at server start. @@ -1008,14 +1012,14 @@ SET ENABLE_SEQSCAN TO OFF; This variable specifies one or more shared libraries that are - to be preloaded at server start. A parameterless initialization - function can optionally be called for each library. To specify - that, add a colon and the name of the initialization function after - the library name. For example + to be preloaded at server start. A parameterless + initialization function can optionally be called for each + library. To specify that, add a colon and the name of the + initialization function after the library name. For example '$libdir/mylib:mylib_init' would cause mylib to be preloaded and mylib_init - to be executed. If more than one library is to be loaded, separate - their names with commas. + to be executed. If more than one library is to be loaded, + separate their names with commas. @@ -1024,11 +1028,11 @@ SET ENABLE_SEQSCAN TO OFF; - PostgreSQL procedural language libraries may be preloaded in this way, - typically by using the syntax - '$libdir/plXXX:plXXX_init' - where XXX is pgsql, - perl, tcl, or python. + PostgreSQL procedural language libraries may be preloaded in + this way, typically by using the syntax + '$libdir/plXXX:plXXX_init' where + XXX is pgsql, perl, + tcl, or python. @@ -1075,27 +1079,29 @@ SET ENABLE_SEQSCAN TO OFF; - However, this operation does slow down - PostgreSQL because at transaction commit it has - wait for the operating system to flush the write-ahead log. - Without fsync, the operating system is allowed to - do its best in buffering, sorting, and delaying writes, which - can considerably increase performance. However, if the system - crashes, the results of the last few committed transactions may - be lost in part or whole. In the worst case, unrecoverable data - corruption may occur. + However, using fsync() results in a + performance penalty: when a transaction is committed, + PostgreSQL must wait for the + operating system to flush the write-ahead log to disk. When + FSYNC is disabled, the operating system is + allowed to do its best in buffering, ordering, and delaying + writes. This can result in significantly improved performance. + However, if the system crashes, the results of the last few + committed transactions may be lost in part or whole. In the + worst case, unrecoverable data corruption may occur. - For the above reasons, everyone can decide for himself what to - do with the fsync option. Some administrators - always leave it off, some turn it off only for bulk loads, - where there is a clear restart point if something goes wrong, - and some leave it on just to be on the safe side. The default - is on so that you are on the safe side. If you trust your - operating system, your hardware, and your utility company (or - better your battery backup), you can consider disabling - fsync. + Due to the risks involved, there is no universally correct + setting for FSYNC. Some administrators + always disable FSYNC, while others only + turn it off for bulk loads, where there is a clear restart + point if something goes wrong, whereas some administrators + always leave FSYNC enabled. The default is + to enable FSYNC, for maximum reliability. + If you trust your operating system, your hardware, and your + utility company (or your battery backup), you can consider + disabling FSYNC. @@ -1143,10 +1149,10 @@ SET ENABLE_SEQSCAN TO OFF; CHECKPOINT_SEGMENTS (integer) - Maximum distance between automatic WAL checkpoints, in log file - segments (each segment is normally 16 megabytes). - This option can only be set at server start or in the - postgresql.conf file. + Maximum distance between automatic WAL checkpoints, in log + file segments (each segment is normally 16 megabytes). The + default is three. This option can only be set at server start + or in the postgresql.conf file. @@ -1155,9 +1161,10 @@ SET ENABLE_SEQSCAN TO OFF; CHECKPOINT_TIMEOUT (integer) - Maximum time between automatic WAL checkpoints, in seconds. - This option can only be set at server start or in the - postgresql.conf file. + Maximum time between automatic WAL checkpoints, in + seconds. The default is 300 seconds. This option can only be + set at server start or in the postgresql.conf + file. @@ -1166,9 +1173,10 @@ SET ENABLE_SEQSCAN TO OFF; CHECKPOINT_WARNING (integer) - Send a message to the server logs if checkpoints caused by the - filling of checkpoint segment files happens more frequently than - this number of seconds. Zero turns off the warning. + Write a message to the server logs if checkpoints caused by + the filling of checkpoint segment files happens more + frequently than this number of seconds. The default is 30 + seconds. Zero turns off the warning. @@ -1178,16 +1186,17 @@ SET ENABLE_SEQSCAN TO OFF; COMMIT_DELAY (integer) - Time delay between writing a commit record to the WAL buffer and - flushing the buffer out to disk, in microseconds. A nonzero - delay allows multiple transactions to be committed with only one - fsync system call, if system load is high - enough additional transactions may become ready to commit within - the given interval. But the delay is just wasted if no other - transactions become ready to commit. Therefore, the delay is - only performed if at least COMMIT_SIBLINGS other transactions - are active at the instant that a server process has written its commit - record. + Time delay between writing a commit record to the WAL buffer + and flushing the buffer out to disk, in microseconds. A + nonzero delay allows multiple transactions to be committed + with only one fsync() system call, if + system load is high enough additional transactions may become + ready to commit within the given interval. But the delay is + just wasted if no other transactions become ready to + commit. Therefore, the delay is only performed if at least + COMMIT_SIBLINGS other transactions are + active at the instant that a server process has written its + commit record. The default is zero (no delay). @@ -1196,10 +1205,11 @@ SET ENABLE_SEQSCAN TO OFF; COMMIT_SIBLINGS (integer) - Minimum number of concurrent open transactions to require before - performing the COMMIT_DELAY delay. A larger value - makes it more probable that at least one other transaction will - become ready to commit during the delay interval. + Minimum number of concurrent open transactions to require + before performing the COMMIT_DELAY delay. A larger + value makes it more probable that at least one other + transaction will become ready to commit during the delay + interval. The default is five. @@ -1209,20 +1219,36 @@ SET ENABLE_SEQSCAN TO OFF; - Query Tuning + Query Planning - Planner Method Enabling + Planner Method Configuration + + + + These configuration parameters provide a crude method for + influencing the query plans chosen by the query optimizer. If + the default plan chosen by the optimizer is not optimal, a + temporary solution may be found by using one of these + configuration parameters to force the optimizer to choose a + better plan. Other ways to improve the quality of the plans + chosen by the optimizer include configuring the , running + ANALYZE more frequently, and increasing the + amount of statistics collected for a particular column using + ALTER TABLE SET STATISTICS. + + + - - ENABLE_HASHAGG (boolean) - Enables or disables the query planner's use of hashed aggregation - plan types. The default is on. This is used for debugging the query - planner. + Enables or disables the query planner's use of hashed + aggregation plan types. The default is on. This is used for + debugging the query planner. @@ -1232,8 +1258,8 @@ SET ENABLE_SEQSCAN TO OFF; Enables or disables the query planner's use of hash-join plan - types. The default is on. This is used for debugging the - query planner. + types. The default is on. This is used for debugging the query + planner. @@ -1247,8 +1273,8 @@ SET ENABLE_SEQSCAN TO OFF; Enables or disables the query planner's use of index-scan plan - types. The default is on. This is used to debugging the - query planner. + types. The default is on. This is used for debugging the query + planner. @@ -1258,8 +1284,8 @@ SET ENABLE_SEQSCAN TO OFF; Enables or disables the query planner's use of merge-join plan - types. The default is on. This is used for debugging the - query planner. + types. The default is on. This is used for debugging the query + planner. @@ -1311,9 +1337,9 @@ SET ENABLE_SEQSCAN TO OFF; ENABLE_TIDSCAN (boolean) - Enables or disables the query planner's use of TID scan plan - types. The default is on. This is used for debugging the - query planner. + Enables or disables the query planner's use of TID + scan plan types. The default is on. This is used for debugging + the query planner. @@ -1321,7 +1347,9 @@ SET ENABLE_SEQSCAN TO OFF; - Planner Cost Constants + + Planner Cost Constants + @@ -1339,10 +1367,10 @@ SET ENABLE_SEQSCAN TO OFF; Sets the planner's assumption about the effective size of the - disk cache (that is, the portion of the kernel's disk cache that - will be used for PostgreSQL data - files). This is measured in disk pages, which are normally 8 kB - each. + disk cache (that is, the portion of the kernel's disk cache + that will be used for PostgreSQL + data files). This is measured in disk pages, which are + normally 8192 bytes each. @@ -2002,7 +2030,7 @@ SET ENABLE_SEQSCAN TO OFF; - The value for search_path has to be a comma-separated + The value for SEARCH_PATH has to be a comma-separated list of schema names. If one of the list items is the special value $user, then the schema having the name returned by SESSION_USER is substituted, if there @@ -2040,11 +2068,11 @@ SET ENABLE_SEQSCAN TO OFF; The current effective value of the search path can be examined - via the SQL function current_schemas(). This is not - quite the same as examining the value of - search_path, since current_schemas() - shows how the requests appearing in search_path - were resolved. + via the SQL function + current_schemas(). This is not quite the same as + examining the value of SEARCH_PATH, since + current_schemas() shows how the requests + appearing in SEARCH_PATH were resolved. @@ -2381,8 +2409,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' The shared lock table is sized on the assumption that at most - max_locks_per_transaction * - max_connections distinct objects will need to + MAX_LOCKS_PER_TRANSACTION * + MAX_CONNECTIONS distinct objects will need to be locked at any one time. The default, 64, has historically proven sufficient, but you might need to raise this value if you have clients that touch many different tables in a single @@ -2590,7 +2618,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' Detection of a damaged page header normally causes PostgreSQL to report an error, aborting the current - transaction. Setting zero_damaged_pages to true causes + transaction. Setting ZERO_DAMAGED_PAGES to true causes the system to instead report a warning, zero out the damaged page, and continue processing. This behavior will destroy data, namely all the rows on the damaged page. But it allows you to get @@ -2786,7 +2814,7 @@ $ postmaster -o '-S 1024 -s' SHMMAX Maximum size of shared memory segment (bytes) - 250 kB + 8.2 kB * shared_buffers + 14.2 kB * max_connections up to infinity + 250 kB + 8.2 kB * SHARED_BUFFERS + 14.2 kB * MAX_CONNECTIONS up to infinity @@ -3331,7 +3359,7 @@ default:\ processes do so then the system-wide limit can easily be exceeded. If you find this happening, and you do not want to alter the system-wide limit, you can set PostgreSQL's - max_files_per_process configuration parameter to + MAX_FILES_PER_PROCESS configuration parameter to limit the consumption of open files. @@ -3440,7 +3468,7 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`SSL support compiled in, the PostgreSQL server can be started with SSL enabled by setting the parameter - ssl to on in postgresql.conf. When + SSL to on in postgresql.conf. When starting in SSL mode, the server will look for the files server.key and server.crt in the data directory, which should contain the server private key