From 4c4654afeb5208c80720b8c373a31c499237989b Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Wed, 10 Sep 2014 20:50:15 -0400 Subject: [PATCH] doc: improve configuration management section Patch by David Johnston Backpatch through 9.4 --- doc/src/sgml/config.sgml | 376 +++++++++++++++++++++++++-------------- 1 file changed, 245 insertions(+), 131 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 49547ee980..1e5c328d80 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -10,8 +10,8 @@ There are many configuration parameters that affect the behavior of - the database system. In the first section of this chapter, we - describe how to set configuration parameters. The subsequent sections + the database system. In the first section of this chapter we + describe how to interact with configuration parameters. The subsequent sections discuss each parameter in detail. @@ -23,47 +23,100 @@ 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. + value of one of five types: boolean, integer, floating point, + string, or enum. - - 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), GB (gigabytes), and TB (terabytes); 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. - + - - 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. - + + + Boolean: Values can be written as + on, + off, + true, + false, + yes, + no, + 1, + 0 + (all case-insensitive) or any unambiguous prefix of these. + + + + + + String: Enclose the value in + single-quotes. Values are case-insensitive. If multiple values + are allowed, separate them with commas. + + + + + + Numeric (integer and floating point): Do + not use single-quotes (unless otherwise required) or thousand + separators. + + + + + + Numeric or String with Unit (Memory & + Time): These have an implicit unit, which is + either kilobytes, blocks (typically eight kilobytes), + milliseconds, seconds, or minutes. A unadorned numeric + value will use the default, which can be found by referencing + pg_settings.unit. For convenience, + a different unit can also be specified explicitly via a string + value. It is case-sensitive and may include whitespace between + the value and the unit. + + + + + Valid memory units are kB (kilobytes), + MB (megabytes), GB + (gigabytes), and TB (terabytes). + The multiplier for memory units is 1024, not 1000. + + + + + + Valid time units are ms (milliseconds), + s (seconds), min (minutes), + h (hours), and d (days). + + + + + + + + + enum: These are specified + in the same way as string parameters, but are restricted + to a limited set of values that can be queried from + pg_settings.enumvals: + +SELECT name, setting, enumvals FROM pg_settings WHERE enumvals IS NOT NULL; + + Enum parameter values are case-insensitive. + + + - Setting Parameters via the Configuration File + Parameter Interaction via Configuration File - One way to set these parameters is to edit the file + The primary 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: + installed when the database cluster directory is initialized.) + An example of what this file might look like is: # This is a comment log_connections = yes @@ -73,125 +126,186 @@ 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 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. + 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. + + + + Parameters set in this way provide default values for the cluster. + The setting seen by active sessions will be this value unless + it is overridden. The following sections describe ways in which the + administrator or user can override these defaults. - SIGHUP + SIGHUP The configuration file is reread whenever the main server process receives a SIGHUP signal; this is most easily done by running pg_ctl reload from the command-line or by calling the SQL function pg_reload_conf(). 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. + server process also propagates this signal to all currently running + server processes so that existing sessions also get the new value + when they complete their transactions. 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. - - Other Ways to Set Parameters + + Parameter Interaction via SQL + + PostgreSQL provides three SQL + commands to establish configuration defaults that override those + configured globally. The evaluation of these defaults occurs + at the beginning of a new session, upon the user issuing , or if the server forces the session to + reload its configuration after a SIGHUP + signal. + + + + + + The command provides an + SQL-accessible means of changing global defaults. + + + + + + The command allows database + administrators to override global settings on a per-database basis. + + + + + + The command allows database + administrators to override both global and per-database settings + with user-specific values. + + + + + + Once a client connects to the database PostgreSQL provides + two additional SQL commands to interact with session-local + configuration settings. Both of these commands have equivalent + system administration functions. + + + + + + The command allows inspection of the + current value of all parameters. The corresponding function is + current_setting(setting_name text). + + + + + + The command allows modification of the + current value of some parameters. The corresponding function is + set_config(setting_name, new_value, is_local). + + + - A second way to set these configuration parameters is to give them - as a command-line option to the postgres command, - such as: + Both SELECT and UPDATE + can be issued against the system view pg_settings to view + and change session-local values. + + + + + + Querying this view is the same as SHOW but provides + more detail, as well as allowing for joins against other relations + and the specification of filter criteria. + + + + + + Using on this relation, specifically + updating the setting column, is the equivalent + of issuing SQL SET, though all values must be + single-quoted. Note that the equivalent of + +SET configuration_parameter TO DEFAULT; + + is: + +UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter'; + + + + + + + + + Parameter Interaction via Shell + + In addition to setting global defaults or attaching + overrides at the database or role level, you can pass settings to + PostgreSQL via shell facilities. + Both the server and libpq client library + accept parameter values via the shell. + + + + + + On the server, command-line options can be + passed to the postgres command directly via the + + Settings provided this way override those resolved globally (via + postgresql.conf or ALTER SYSTEM) but + are otherwise treated as being global for the purpose of database + and role overrides. + + - - 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: + + + On the libpq-client, command-line options can be + specified using the PGOPTIONS environment variable. + When connecting to the server, the contents of this variable are + sent to the server as if they were being executed via SQL at the beginning of the session. + + + + However, the format of PGOPTIONS is similar to that + used when launching the postgres command. + Specifically, the + - - 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: - -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 parameters - require superuser permission to change via SET or - ALTER. - - - - Another way to change configuration parameters persistently is by - use of - command, for example: - -ALTER SYSTEM SET checkpoint_timeout TO 600; - - This command will allow users to change values persistently - through SQL command. The values will be effective after reload of server configuration - (SIGHUP) or server startup. The effect of this command is similar to when - user manually changes values in postgresql.conf. - - - - - Examining Parameter Settings - - - 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. - + + Other clients and libraries might provide their own mechanisms, + via the shell or otherwise, that allow the user to alter session + settings without requiring the user to issue SQL commands. + + +