From af06aa822dbc023f3a103278ec381e1c88d67db1 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 14 Dec 2014 18:09:51 -0500 Subject: [PATCH] Improve documentation around parameter-setting and ALTER SYSTEM. The ALTER SYSTEM ref page hadn't been held to a very high standard, nor was the feature well integrated into section 18.1 (parameter setting). Also, though commit 4c4654afe had improved the structure of 18.1, it also introduced a lot of poor wording, imprecision, and outright falsehoods. Try to clean that up. --- doc/src/sgml/config.sgml | 358 ++++++++++++++++------------- doc/src/sgml/ref/alter_system.sgml | 55 +++-- 2 files changed, 227 insertions(+), 186 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index d607eca892..48ae3e41f9 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -23,15 +23,16 @@ All parameter names are case-insensitive. Every parameter takes a - value of one of five types: boolean, integer, floating point, - string, or enum. + value of one of five types: boolean, string, integer, floating point, + or enumerated (enum). The type determines the syntax for setting the + parameter: - - Boolean: Values can be written as + Boolean: + Values can be written as on, off, true, @@ -40,37 +41,42 @@ no, 1, 0 - (all case-insensitive) or any unambiguous prefix of these. + (all case-insensitive) or any unambiguous prefix of one of these. - String: Enclose the value in - single-quotes. Values are case-insensitive. If multiple values - are allowed, separate them with commas. + String: + In general, enclose the value in single quotes, doubling any single + quotes within the value. Quotes can usually be omitted if the value + is a simple number or identifier, however. - Numeric (integer and floating point): Do - not use single-quotes (unless otherwise required) or thousand - separators. + Numeric (integer and floating point): + A decimal point is permitted only for floating-point parameters. + Do not use thousands separators. Quotes are not required. - 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. + Numeric with Unit: + Some numeric parameters have an implicit unit, because they describe + quantities of memory or time. The unit might be kilobytes, blocks + (typically eight kilobytes), milliseconds, seconds, or minutes. + An unadorned numeric value for one of these settings will use the + setting's default unit, which can be learned from + pg_settings.unit. + For convenience, settings can be given with a unit specified explicitly, + for example '120 ms' for a time value, and they will be + converted to whatever the parameter's actual unit is. Note that the + value must be written as a string (with quotes) to use this feature. + The unit name is case-sensitive, and there can be whitespace between + the numeric value and the unit. @@ -81,7 +87,7 @@ The multiplier for memory units is 1024, not 1000. - + Valid time units are ms (milliseconds), @@ -95,13 +101,11 @@ - 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; - + Enumerated: + Enumerated-type parameters are written in the same way as string + parameters, but are restricted to have one of a limited set of + values. The values allowable for such a parameter can be found from + pg_settings.enumvals. Enum parameter values are case-insensitive. @@ -109,13 +113,13 @@ SELECT name, setting, enumvals FROM pg_settings WHERE enumvals IS NOT NULL; - Parameter Interaction via Configuration File + Parameter Interaction via the Configuration File - The primary way to set these parameters is to edit the file + The most fundamental 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 when the database cluster directory is initialized.) + which is normally kept in the data directory. A default copy is + installed when the database cluster directory is initialized. An example of what this file might look like is: # This is a comment @@ -125,81 +129,96 @@ 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 + value is optional. Whitespace is insignificant (except within a quoted + parameter value) 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) + 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 + The settings seen by active sessions will be these values unless they + are 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 + receives a SIGHUP signal; this signal is most easily + sent 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 - when they complete their transactions. Alternatively, you can + server processes, so that existing sessions also adopt the new values + (this will happen after they complete any currently-executing client + command). 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. + + + In addition to postgresql.conf, + a PostgreSQL data directory contains a file + postgresql.auto.confpostgresql.auto.conf, + which has the same format as postgresql.conf but should + never be edited manually. This file holds settings provided through + the command. This file is automatically + read whenever postgresql.conf is, and its settings take + effect in the same way. Settings in postgresql.auto.conf + override those in postgresql.conf. + 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. + PostgreSQL provides three SQL + commands to establish configuration defaults. + The already-mentioned command + provides a SQL-accessible means of changing global defaults; it is + functionally equivalent to editing postgresql.conf. + In addition, there are two commands that allow setting of defaults + on a per-database or per-role basis: - - - The command provides an - SQL-accessible means of changing global defaults. + + + The command allows global + settings to be overridden on a per-database basis. - 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. + The command allows both global and + per-database settings to be overridden 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. + Values set with ALTER DATABASE and ALTER ROLE + are applied only when starting a fresh database session. They + override values obtained from the configuration files or server + command line, and constitute defaults for the rest of the session. + Note that some settings cannot be changed after server start, and + so cannot be set with these commands (or the ones listed below). + + + + Once a client is connected to the database, PostgreSQL + provides two additional SQL commands (and equivalent functions) to + interact with session-local configuration settings: @@ -214,49 +233,50 @@ shared_buffers = 128MB The command allows modification of the - current value of some parameters. The corresponding function is + current value of those parameters that can be set locally to a + session; it has no effect on other sessions. + The corresponding function is set_config(setting_name, new_value, is_local). - Both SELECT and UPDATE - can be issued against the system view pg_settings to view - and change session-local values. + In addition, the system view pg_settings can be + used 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. + Querying this view is similar to using SHOW ALL but + provides more detail. It is also more flexible, since it's possible + to specify filter conditions or join against other relations. - - - Using on this relation, specifically + + + Using on this view, specifically updating the setting column, is the equivalent - of issuing SQL SET, though all values must be - single-quoted. Note that the equivalent of + of issuing SET commands. For example, the equivalent of SET configuration_parameter TO DEFAULT; - - is: + + is: UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter'; - - - + + + - Parameter Interaction via Shell + Parameter Interaction via the Shell + In addition to setting global defaults or attaching overrides at the database or role level, you can pass settings to @@ -268,41 +288,38 @@ UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter - On the server, command-line options can be - passed to the postgres command directly via the - - On the libpq-client, command-line options can be + When starting a client session via libpq, + parameter settings 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 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. + settings without direct use of SQL commands. @@ -310,25 +327,32 @@ env PGOPTIONS="-c geqo=off -c statement_timeout='5 min'" psql - Configuration File Includes + Managing Configuration File Contents + + + PostgreSQL provides several features for breaking + down complex postgresql.conf files into sub-files. + These features are especially useful when managing multiple servers + with related, but not identical, configurations. + 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: + + In addition to individual 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. @@ -336,12 +360,12 @@ include 'filename' 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. + There is also an include_if_exists directive, which acts + the same as the include directive, except + 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. @@ -349,79 +373,83 @@ include 'filename' include_dir in configuration file - The postgresql.conf file can also contain - include_dir directives, which specify an entire directory - of configuration files to include. It is used similarly: + The postgresql.conf file can also contain + include_dir directives, which specify an entire + directory of configuration files to include. These look like include_dir 'directory' - Non-absolute directory names follow the same rules as single file include - directives: they are relative to the directory containing the referencing - configuration file. Within that directory, only non-directory files whose - names end with the suffix .conf will be included. File - names that start with the . character are also excluded, - to prevent mistakes as they are hidden on some platforms. Multiple files - within an include directory are processed in file name order. The file names - are ordered by C locale rules, i.e. numbers before letters, and uppercase - letters before lowercase ones. + Non-absolute directory names are taken as relative to the directory + containing the referencing configuration file. Within the specified + directory, only non-directory files whose names end with the + suffix .conf will be included. File names that + start with the . character are also ignored, to + prevent mistakes since such files are hidden on some platforms. Multiple + files within an include directory are processed in file name order + (according to C locale rules, i.e. numbers before letters, and + uppercase letters before lowercase ones). - Include files or directories can be used to logically separate portions - of the database configuration, rather than having a single large - postgresql.conf file. Consider a company that has two - database servers, each with a different amount of memory. There are likely - elements of the configuration both will share, for things such as logging. - But memory-related parameters on the server will vary between the two. And - there might be server specific customizations, too. One way to manage this - situation is to break the custom configuration changes for your site into - three files. You could add this to the end of your - postgresql.conf file to include them: + Include files or directories can be used to logically separate portions + of the database configuration, rather than having a single large + postgresql.conf file. Consider a company that has two + database servers, each with a different amount of memory. There are + likely elements of the configuration both will share, for things such + as logging. But memory-related parameters on the server will vary + between the two. And there might be server specific customizations, + too. One way to manage this situation is to break the custom + configuration changes for your site into three files. You could add + this to the end of your postgresql.conf file to include + them: include 'shared.conf' include 'memory.conf' include 'server.conf' - All systems would have the same shared.conf. Each server - with a particular amount of memory could share the same - memory.conf; you might have one for all servers with 8GB of RAM, - another for those having 16GB. And finally server.conf could - have truly server-specific configuration information in it. + All systems would have the same shared.conf. Each + server with a particular amount of memory could share the + same memory.conf; you might have one for all servers + with 8GB of RAM, another for those having 16GB. And + finally server.conf could have truly server-specific + configuration information in it. - Another possibility is to create a configuration file directory and - put this information into files there. For example, a conf.d - directory could be referenced at the end ofpostgresql.conf: + Another possibility is to create a configuration file directory and + put this information into files there. For example, a conf.d + directory could be referenced at the end of postgresql.conf: include_dir 'conf.d' - Then you could name the files in the conf.d directory like this: + Then you could name the files in the conf.d directory + like this: 00shared.conf 01memory.conf 02server.conf - This shows a clear order in which these files will be loaded. This is - important because only the last setting encountered when the server is - reading its configuration will be used. Something set in - conf.d/02server.conf in this example would override a value - set in conf.d/01memory.conf. + This naming convention establishes a clear order in which these + files will be loaded. This is important because only the last + setting encountered for a particular parameter while the server is + reading configuration files will be used. In this example, + something set in conf.d/02server.conf would override a + value set in conf.d/01memory.conf. - You might instead use this configuration directory approach while naming - these files more descriptively: + You might instead use this approach to naming the files + descriptively: 00shared.conf 01memory-8GB.conf 02server-foo.conf - This sort of arrangement gives a unique name for each configuration file - variation. This can help eliminate ambiguity when several servers have - their configurations all stored in one place, such as in a version - control repository. (Storing database configuration files under version - control is another good practice to consider). + This sort of arrangement gives a unique name for each configuration file + variation. This can help eliminate ambiguity when several servers have + their configurations all stored in one place, such as in a version + control repository. (Storing database configuration files under version + control is another good practice to consider.) diff --git a/doc/src/sgml/ref/alter_system.sgml b/doc/src/sgml/ref/alter_system.sgml index a6e32106e8..f6a018f341 100644 --- a/doc/src/sgml/ref/alter_system.sgml +++ b/doc/src/sgml/ref/alter_system.sgml @@ -32,23 +32,30 @@ ALTER SYSTEM RESET ALL Description - ALTER SYSTEM writes the configuration parameter - values to the postgresql.auto.conf file. - Setting the parameter to DEFAULT, or using the - RESET variant, removes the configuration entry from + ALTER SYSTEM is used for changing server configuration + parameters across the entire database cluster. It can be more convenient + than the traditional method of manually editing + the postgresql.conf file. + ALTER SYSTEM writes the given parameter setting to + the postgresql.auto.conf file, which is read in + addition to postgresql.conf. + Setting a parameter to DEFAULT, or using the + RESET variant, removes that configuration entry from the postgresql.auto.conf file. Use RESET - ALL to clear all configuration entries. The values will - be effective after reload of server configuration (SIGHUP) or in next - server start based on the type of configuration parameter modified. + ALL to remove all such configuration entries. - This command is not allowed inside transaction block or function. + Values set with ALTER SYSTEM will be effective after + the next server configuration reload (SIGHUP + or pg_ctl reload), or after the next server restart in the + case of parameters that can only be changed at server start. - See for other ways to set the parameters and - how they become effective. + Only superusers can use ALTER SYSTEM. Also, since + this command acts directly on the file system and cannot be rolled back, + it is not allowed inside a transaction block or function. @@ -60,7 +67,7 @@ ALTER SYSTEM RESET ALL configuration_parameter - Name of a settable run-time parameter. Available parameters are + Name of a settable configuration parameter. Available parameters are documented in . @@ -70,11 +77,11 @@ ALTER SYSTEM RESET ALL value - New value of parameter. Values can be specified as string + New value of the parameter. Values can be specified as string constants, identifiers, numbers, or comma-separated lists of these, as appropriate for the particular parameter. - DEFAULT can be written to specify to remove the - parameter and its value from postgresql.auto.conf + DEFAULT can be written to specify removing the + parameter and its value from postgresql.auto.conf. @@ -85,12 +92,16 @@ ALTER SYSTEM RESET ALL Notes - This command can't be used to set - and any parameters (e.g., preset options) - that are not allowed in postgresql.conf. + This command can't be used to set , + nor parameters that are not allowed in postgresql.conf + (e.g., preset options). + + + + See for other ways to set the parameters. - + Examples @@ -102,10 +113,12 @@ ALTER SYSTEM SET wal_level = hot_standby; - Set the authentication_timeout: + Undo that, restoring whatever setting was effective + in postgresql.conf: -ALTER SYSTEM SET authentication_timeout = 10; - +ALTER SYSTEM RESET wal_level; + +