From 817ec1bc8227eb0d7f3bbb5725ea1de0ec73c1ea Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 10 May 2012 23:01:28 -0400 Subject: [PATCH] Improve discussion of setting server parameters. Rewrite description of "include_if_exists" for clarity. Add subsection headings to make the structure of the page a little clearer. A couple other minor improvements too. Josh Kupershmidt and Tom Lane --- doc/src/sgml/config.sgml | 304 +++++++++++++++++++++------------------ 1 file changed, 163 insertions(+), 141 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 804b1e5ca7..074afee494 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -18,45 +18,52 @@ Setting Parameters - - All parameter names are case-insensitive. Every parameter takes a - value of one of five types: Boolean, integer, floating point, - string or enum. Boolean values can be written as on, - off, true, - false, yes, - no, 1, 0 - (all case-insensitive) or any unambiguous prefix of these. - + + Parameter Names and Values - - Some settings specify a memory or time value. Each of these has an - implicit unit, which is either kilobytes, blocks (typically eight - kilobytes), milliseconds, seconds, or minutes. Default units can be - found by referencing pg_settings.unit. - For convenience, - a different unit can also be specified explicitly. Valid memory units - are kB (kilobytes), MB - (megabytes), and GB (gigabytes); valid time units - are ms (milliseconds), s - (seconds), min (minutes), h - (hours), and d (days). Note that the multiplier - for memory units is 1024, not 1000. - + + All parameter names are case-insensitive. Every parameter takes a + value of one of five types: Boolean, integer, floating point, + string or enum. Boolean values can be written as on, + off, true, + false, yes, + no, 1, 0 + (all case-insensitive) or any unambiguous prefix of these. + - - Parameters of type enum are specified in the same way as string - parameters, but are restricted to a limited set of values. The allowed - values can be found - from pg_settings.enumvals. - Enum parameter values are case-insensitive. - + + Some settings specify a memory or time value. Each of these has an + implicit unit, which is either kilobytes, blocks (typically eight + kilobytes), milliseconds, seconds, or minutes. Default units can be + found by referencing pg_settings.unit. + For convenience, + a different unit can also be specified explicitly. Valid memory units + are kB (kilobytes), MB + (megabytes), and GB (gigabytes); valid time units + are ms (milliseconds), s + (seconds), min (minutes), h + (hours), and d (days). Note that the multiplier + for memory units is 1024, not 1000. + - - One way to set these parameters is to edit the file - postgresql.confpostgresql.conf, - which is normally kept in the data directory. (A default copy is - installed there when the database cluster directory is - initialized.) An example of what this file might look like is: + + Parameters of type enum are specified in the same way as string + parameters, but are restricted to a limited set of values. The allowed + values can be found + from pg_settings.enumvals. + Enum parameter values are case-insensitive. + + + + + Setting Parameters via the Configuration File + + + One way to set these parameters is to edit the file + postgresql.confpostgresql.conf, + which is normally kept in the data directory. (A default copy is + installed there when the database cluster directory is + initialized.) An example of what this file might look like is: # This is a comment log_connections = yes @@ -64,132 +71,147 @@ log_destination = 'syslog' search_path = '"$user", public' shared_buffers = 128MB - One parameter is specified per line. The equal sign between name and - value is optional. Whitespace is insignificant and blank lines are - ignored. Hash marks (#) designate the rest of the - line as a comment. Parameter values that are not simple identifiers or - numbers must be single-quoted. To embed a single quote in a parameter - value, write either two quotes (preferred) or backslash-quote. - + One parameter is specified per line. The equal sign between name and + value is optional. Whitespace is insignificant and blank lines are + ignored. Hash marks (#) designate the remainder of the + line as a comment. Parameter values that are not simple identifiers or + numbers must be single-quoted. To embed a single quote in a parameter + value, write either two quotes (preferred) or backslash-quote. + - - - include - in configuration file - - In addition to parameter settings, the postgresql.conf - file can contain include directives, which specify - another file to read and process as if it were inserted into the - configuration file at this point. Include directives simply look like: + + + include + in configuration file + + In addition to parameter settings, the postgresql.conf + file can contain include directives, which specify + another file to read and process as if it were inserted into the + configuration file at this point. This feature allows a configuration + file to be divided into physically separate parts. + Include directives simply look like: include 'filename' - If the file name is not an absolute path, it is taken as relative to - the directory containing the referencing configuration file. - Inclusions can be nested. - + If the file name is not an absolute path, it is taken as relative to + the directory containing the referencing configuration file. + Inclusions can be nested. + - - - include_if_exists - in configuration file - - Use the same approach as the include directive, continuing - normally if the file does not exist. A regular include - will stop with an error if the referenced file is missing, while - include_if_exists does not. A warning about the missing - file will be logged. - + + + include_if_exists + in configuration file + + There is also an include_if_exists directive, which acts + the same as the include directive, except for the behavior + when the referenced file does not exist or cannot be read. A regular + include will consider this an error condition, but + include_if_exists merely logs a message and continues + processing the referencing configuration file. + - - - SIGHUP - - The configuration file is reread whenever the main server process receives a - SIGHUP signal (which is most easily sent by means - of pg_ctl reload). The main server process - 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. Some parameters can only be set at server start; - any changes to their entries in the configuration file will be ignored - until the server is restarted. Invalid parameter settings in the - configuration file are likewise ignored (but logged) during - SIGHUP processing. - + + + SIGHUP + + The configuration file is reread whenever the main server process + receives a + SIGHUP signal (which is most easily sent by means + of pg_ctl reload). The main server process + 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. Some parameters can only be set at server start; + any changes to their entries in the configuration file will be ignored + until the server is restarted. Invalid parameter settings in the + configuration file are likewise ignored (but logged) during + SIGHUP processing. + + - - A second way to set these configuration parameters is to give them - as a command-line option to the postgres command, such as: + + Other Ways to Set Parameters + + + A second way to set these configuration parameters is to give them + as a command-line option to the postgres command, + such as: postgres -c log_connections=yes -c log_destination='syslog' - Command-line options override any conflicting settings in - postgresql.conf. Note that this means you won't - be able to change the value on-the-fly by editing - postgresql.conf, so while the command-line - method might be convenient, it can cost you flexibility later. - + Command-line options override any conflicting settings in + postgresql.conf. Note that this means you won't + be able to change the value on-the-fly by editing + postgresql.conf, so while the command-line + method might be convenient, it can cost you flexibility later. + - - Occasionally it is useful to give a command line option to - one particular session only. The environment variable - PGOPTIONS can be used for this purpose on the - client side: + + Occasionally it is useful to give a command line option to + one particular session only. The environment variable + PGOPTIONS can be used for this purpose on the + client side: env PGOPTIONS='-c geqo=off' psql - (This works for any libpq-based client application, not - just psql.) Note that this won't work for - parameters that are fixed when the server is started or that must be - specified in postgresql.conf. - + (This works for any libpq-based client application, not + just psql.) Note that this won't work for + parameters that are fixed when the server is started or that must be + specified in postgresql.conf. + - - Furthermore, it is possible to assign a set of parameter 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 - and , - respectively, are used to configure these settings. Per-database - settings override anything received from the - postgres command-line or the configuration - file, and in turn are overridden by per-user settings; both are - overridden by per-session settings. - + + Furthermore, it is possible to assign a set of parameter 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 + and , + respectively, are used to configure these settings. Per-database + settings override anything received from the + postgres command-line or the configuration + file, and in turn are overridden by per-user settings; both are + overridden by per-session settings. + - - Some parameters can be changed in individual SQL - sessions with the - command, for example: + + Some parameters can be changed in individual SQL + sessions with the + command, for example: SET ENABLE_SEQSCAN TO OFF; - If SET is allowed, it overrides all other sources of - values for the parameter. Some parameters cannot be changed via - SET: for example, if they control behavior that - cannot be changed without restarting the entire - PostgreSQL server. Also, - some SET or ALTER parameter modifications - require superuser permission. - + If SET is allowed, it overrides all other sources of + values for the parameter. Some parameters cannot be changed via + SET: for example, if they control behavior that + cannot be changed without restarting the entire + PostgreSQL server. Also, some parameters + require superuser permission to change via SET or + ALTER. + + - - The - command allows inspection of the current values of all parameters. - + + Examining Parameter Settings - - The virtual table pg_settings also allows - displaying and updating session run-time parameters; see for details and a description of the - different variable types and when they can be changed. - pg_settings is equivalent to SHOW - and SET, but can be more convenient - to use because it can be joined with other tables, or selected from using - any desired selection condition. It also contains more information about - what values are allowed for the parameters. - + + The + command allows inspection of the current values of all parameters. + + + + The virtual table pg_settings also allows + displaying and updating session run-time parameters; see for details and a description of the + different variable types and when they can be changed. + pg_settings is equivalent to SHOW + and SET, but can be more convenient + to use because it can be joined with other tables, or selected from using + any desired selection condition. It also contains more information about + each parameter than is available from SHOW. + + + -- 2.40.0