rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Tom Lane 2014-12-14 18:09:51 -05:00
parent 0923b01e3e
commit af06aa822d
2 changed files with 227 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

358
doc/src/sgml/config.sgml
View File

@ -23,15 +23,16 @@
<para> <para>
All parameter names are case-insensitive. Every parameter takes a All parameter names are case-insensitive. Every parameter takes a
value of one of five types: boolean, integer, floating point, value of one of five types: boolean, string, integer, floating point,
string, or enum. or enumerated (enum). The type determines the syntax for setting the
parameter:
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<emphasis>Boolean:</emphasis> Values can be written as <emphasis>Boolean:</emphasis>
Values can be written as
<literal>on</literal>, <literal>on</literal>,
<literal>off</literal>, <literal>off</literal>,
<literal>true</literal>, <literal>true</literal>,
@ -40,37 +41,42 @@
<literal>no</literal>, <literal>no</literal>,
<literal>1</literal>, <literal>1</literal>,
<literal>0</literal> <literal>0</literal>
(all case-insensitive) or any unambiguous prefix of these. (all case-insensitive) or any unambiguous prefix of one of these.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<emphasis>String:</emphasis> Enclose the value in <emphasis>String:</emphasis>
single-quotes. Values are case-insensitive. If multiple values In general, enclose the value in single quotes, doubling any single
are allowed, separate them with commas. quotes within the value. Quotes can usually be omitted if the value
is a simple number or identifier, however.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<emphasis>Numeric (integer and floating point):</emphasis> Do <emphasis>Numeric (integer and floating point):</emphasis>
not use single-quotes (unless otherwise required) or thousand A decimal point is permitted only for floating-point parameters.
separators. Do not use thousands separators. Quotes are not required.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<emphasis>Numeric or String with Unit (Memory &amp; <emphasis>Numeric with Unit:</emphasis>
Time):</emphasis> These have an implicit unit, which is Some numeric parameters have an implicit unit, because they describe
either kilobytes, blocks (typically eight kilobytes), quantities of memory or time. The unit might be kilobytes, blocks
milliseconds, seconds, or minutes. A unadorned numeric (typically eight kilobytes), milliseconds, seconds, or minutes.
value will use the default, which can be found by referencing An unadorned numeric value for one of these settings will use the
<structname>pg_settings</>.<structfield>unit</>. For convenience, setting's default unit, which can be learned from
a different unit can also be specified explicitly via a string <structname>pg_settings</>.<structfield>unit</>.
value. It is case-sensitive and may include whitespace between For convenience, settings can be given with a unit specified explicitly,
the value and the unit. for example <literal>'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.
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -81,7 +87,7 @@
The multiplier for memory units is 1024, not 1000. The multiplier for memory units is 1024, not 1000.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Valid time units are <literal>ms</literal> (milliseconds), Valid time units are <literal>ms</literal> (milliseconds),
@ -95,13 +101,11 @@
<listitem> <listitem>
<para> <para>
<emphasis><quote>enum</>:</emphasis> These are specified <emphasis>Enumerated:</emphasis>
in the same way as string parameters, but are restricted Enumerated-type parameters are written in the same way as string
to a limited set of values that can be queried from parameters, but are restricted to have one of a limited set of
<structname>pg_settings</>.<structfield>enumvals</>: values. The values allowable for such a parameter can be found from
<programlisting> <structname>pg_settings</>.<structfield>enumvals</>.
SELECT name, setting, enumvals FROM pg_settings WHERE enumvals IS NOT NULL;
</programlisting>
Enum parameter values are case-insensitive. Enum parameter values are case-insensitive.
</para> </para>
</listitem> </listitem>
@ -109,13 +113,13 @@ SELECT name, setting, enumvals FROM pg_settings WHERE enumvals IS NOT NULL;
</sect2> </sect2>
<sect2 id="config-setting-configuration-file"> <sect2 id="config-setting-configuration-file">
<title>Parameter Interaction via Configuration File</title> <title>Parameter Interaction via the Configuration File</title>
<para> <para>
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
<filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>, <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
which is normally kept in the data directory. (A default copy is which is normally kept in the data directory. A default copy is
installed when the database cluster directory is initialized.) installed when the database cluster directory is initialized.
An example of what this file might look like is: An example of what this file might look like is:
<programlisting> <programlisting>
# This is a comment # This is a comment
@ -125,81 +129,96 @@ search_path = '"$user", public'
shared_buffers = 128MB shared_buffers = 128MB
</programlisting> </programlisting>
One parameter is specified per line. The equal sign between name and 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 (<literal>#</literal>) designate the remainder ignored. Hash marks (<literal>#</literal>) designate the remainder
of the line as a comment. Parameter values that are not simple of the line as a comment. Parameter values that are not simple
identifiers or numbers must be single-quoted. To embed a single 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. or backslash-quote.
</para> </para>
<para> <para>
Parameters set in this way provide default values for the cluster. Parameters set in this way provide default values for the cluster.
The setting seen by active sessions will be this value unless The settings seen by active sessions will be these values unless they
it is overridden. The following sections describe ways in which the are overridden. The following sections describe ways in which the
administrator or user can override these defaults. administrator or user can override these defaults.
</para> </para>
<para> <para>
<indexterm> <indexterm>
<primary>SIGHUP</primary> <primary>SIGHUP</primary>
</indexterm> </indexterm>
The configuration file is reread whenever the main server process The configuration file is reread whenever the main server process
receives a <systemitem>SIGHUP</> signal; this is most easily done by receives a <systemitem>SIGHUP</> signal; this signal is most easily
running <literal>pg_ctl reload</> from the command-line or by calling sent by running <literal>pg_ctl reload</> from the command line or by
the SQL function <function>pg_reload_conf()</function>. The main calling the SQL function <function>pg_reload_conf()</function>. The main
server process also propagates this signal to all currently running server process also propagates this signal to all currently running
server processes so that existing sessions also get the new value server processes, so that existing sessions also adopt the new values
when they complete their transactions. Alternatively, you can (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 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 can only be set at server start; any changes to their entries in the
configuration file will be ignored until the server is restarted. configuration file will be ignored until the server is restarted.
Invalid parameter settings in the configuration file are likewise Invalid parameter settings in the configuration file are likewise
ignored (but logged) during <systemitem>SIGHUP</> processing. ignored (but logged) during <systemitem>SIGHUP</> processing.
</para> </para>
<para>
In addition to <filename>postgresql.conf</>,
a <productname>PostgreSQL</productname> data directory contains a file
<filename>postgresql.auto.conf</><indexterm><primary>postgresql.auto.conf</></>,
which has the same format as <filename>postgresql.conf</> but should
never be edited manually. This file holds settings provided through
the <xref linkend="SQL-ALTERSYSTEM"> command. This file is automatically
read whenever <filename>postgresql.conf</> is, and its settings take
effect in the same way. Settings in <filename>postgresql.auto.conf</>
override those in <filename>postgresql.conf</>.
</para>
</sect2> </sect2>
<sect2 id="config-setting-sql-command-interaction"> <sect2 id="config-setting-sql-command-interaction">
<title>Parameter Interaction via SQL</title> <title>Parameter Interaction via SQL</title>
<para> <para>
<productname>PostgreSQL</productname> provides three SQL <productname>PostgreSQL</productname> provides three SQL
commands to establish configuration defaults that override those commands to establish configuration defaults.
configured globally. The evaluation of these defaults occurs The already-mentioned <xref linkend="SQL-ALTERSYSTEM"> command
at the beginning of a new session, upon the user issuing <xref provides a SQL-accessible means of changing global defaults; it is
linkend="SQL-DISCARD">, or if the server forces the session to functionally equivalent to editing <filename>postgresql.conf</>.
reload its configuration after a <systemitem>SIGHUP</systemitem> In addition, there are two commands that allow setting of defaults
signal. on a per-database or per-role basis:
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
The <xref linkend="SQL-ALTERSYSTEM"> command provides an The <xref linkend="sql-alterdatabase"> command allows global
SQL-accessible means of changing global defaults. settings to be overridden on a per-database basis.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The <xref linkend="sql-alterdatabase"> command allows database The <xref linkend="sql-alterrole"> command allows both global and
administrators to override global settings on a per-database basis. per-database settings to be overridden with user-specific values.
</para>
</listitem>
<listitem>
<para>
The <xref linkend="sql-alterrole"> command allows database
administrators to override both global and per-database settings
with user-specific values.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para> <para>
Once a client connects to the database PostgreSQL provides Values set with <command>ALTER DATABASE</> and <command>ALTER ROLE</>
two additional SQL commands to interact with session-local are applied only when starting a fresh database session. They
configuration settings. Both of these commands have equivalent override values obtained from the configuration files or server
system administration functions. 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).
</para>
<para>
Once a client is connected to the database, <productname>PostgreSQL</>
provides two additional SQL commands (and equivalent functions) to
interact with session-local configuration settings:
</para> </para>
<itemizedlist> <itemizedlist>
@ -214,49 +233,50 @@ shared_buffers = 128MB
<listitem> <listitem>
<para> <para>
The <xref linkend="SQL-SET"> command allows modification of the The <xref linkend="SQL-SET"> 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
<function>set_config(setting_name, new_value, is_local)</function>. <function>set_config(setting_name, new_value, is_local)</function>.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para> <para>
Both <command>SELECT</> and <command>UPDATE</> In addition, the system view <link
can be issued against the system view <link linkend="view-pg-settings"><structname>pg_settings</></> can be
linkend="view-pg-settings"><structname>pg_settings</></> to view used to view and change session-local values:
and change session-local values.
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Querying this view is the same as <command>SHOW</> but provides Querying this view is similar to using <command>SHOW ALL</> but
more detail, as well as allowing for joins against other relations provides more detail. It is also more flexible, since it's possible
and the specification of filter criteria. to specify filter conditions or join against other relations.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Using <xref linkend="SQL-UPDATE"> on this relation, specifically Using <xref linkend="SQL-UPDATE"> on this view, specifically
updating the <structname>setting</> column, is the equivalent updating the <structname>setting</> column, is the equivalent
of issuing SQL <command>SET</>, though all values must be of issuing <command>SET</> commands. For example, the equivalent of
single-quoted. Note that the equivalent of
<programlisting> <programlisting>
SET configuration_parameter TO DEFAULT; SET configuration_parameter TO DEFAULT;
</> </programlisting>
is: is:
<programlisting> <programlisting>
UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter'; UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
</programlisting> </programlisting>
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</sect2> </sect2>
<sect2> <sect2>
<title>Parameter Interaction via Shell</title> <title>Parameter Interaction via the Shell</title>
<para> <para>
In addition to setting global defaults or attaching In addition to setting global defaults or attaching
overrides at the database or role level, you can pass settings to 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
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
On the <emphasis>server</emphasis>, command-line options can be During server startup, parameter settings can be
passed to the <command>postgres</command> command directly via the passed to the <command>postgres</command> command via the
<option>-c</> parameter. <option>-c</> command-line parameter. For example,
<programlisting> <programlisting>
postgres -c log_connections=yes -c log_destination='syslog' postgres -c log_connections=yes -c log_destination='syslog'
</programlisting> </programlisting>
Settings provided this way override those resolved globally (via Settings provided in this way override those set via
<filename>postgresql.conf</> or <command>ALTER SYSTEM</>) but <filename>postgresql.conf</> or <command>ALTER SYSTEM</>,
are otherwise treated as being global for the purpose of database so they cannot be changed globally without restarting the server.
and role overrides.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
On the <emphasis>libpq-client</emphasis>, command-line options can be When starting a client session via <application>libpq</>,
parameter settings can be
specified using the <envar>PGOPTIONS</envar> environment variable. specified using the <envar>PGOPTIONS</envar> environment variable.
When connecting to the server, the contents of this variable are Settings established in this way constitute defaults for the life
sent to the server as if they were being executed via SQL <xref of the session, but do not affect other sessions.
linkend="SQL-SET"> at the beginning of the session. For historical reasons, the format of <envar>PGOPTIONS</envar> is
</para> similar to that used when launching the <command>postgres</command>
command; specifically, the <option>-c</> flag must be specified.
<para> For example,
However, the format of <envar>PGOPTIONS</envar> is similar to that
used when launching the <command>postgres</command> command.
Specifically, the <option>-c</> flag must be specified.
<programlisting> <programlisting>
env PGOPTIONS="-c geqo=off -c statement_timeout='5 min'" psql env PGOPTIONS="-c geqo=off -c statement_timeout=5min" psql
</programlisting> </programlisting>
</para> </para>
<para> <para>
Other clients and libraries might provide their own mechanisms, Other clients and libraries might provide their own mechanisms,
via the shell or otherwise, that allow the user to alter session 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.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -310,25 +327,32 @@ env PGOPTIONS="-c geqo=off -c statement_timeout='5 min'" psql
</sect2> </sect2>
<sect2 id="config-includes"> <sect2 id="config-includes">
<title>Configuration File Includes</title> <title>Managing Configuration File Contents</title>
<para>
<productname>PostgreSQL</> provides several features for breaking
down complex <filename>postgresql.conf</> files into sub-files.
These features are especially useful when managing multiple servers
with related, but not identical, configurations.
</para>
<para> <para>
<indexterm> <indexterm>
<primary><literal>include</></primary> <primary><literal>include</></primary>
<secondary>in configuration file</secondary> <secondary>in configuration file</secondary>
</indexterm> </indexterm>
In addition to parameter settings, the <filename>postgresql.conf</> In addition to individual parameter settings,
file can contain <firstterm>include directives</>, which specify the <filename>postgresql.conf</> file can contain <firstterm>include
another file to read and process as if it were inserted into the directives</>, which specify another file to read and process as if
configuration file at this point. This feature allows a configuration it were inserted into the configuration file at this point. This
file to be divided into physically separate parts. feature allows a configuration file to be divided into physically
Include directives simply look like: separate parts. Include directives simply look like:
<programlisting> <programlisting>
include 'filename' include 'filename'
</programlisting> </programlisting>
If the file name is not an absolute path, it is taken as relative to If the file name is not an absolute path, it is taken as relative to
the directory containing the referencing configuration file. the directory containing the referencing configuration file.
Inclusions can be nested. Inclusions can be nested.
</para> </para>
<para> <para>
@ -336,12 +360,12 @@ include 'filename'
<primary><literal>include_if_exists</></primary> <primary><literal>include_if_exists</></primary>
<secondary>in configuration file</secondary> <secondary>in configuration file</secondary>
</indexterm> </indexterm>
There is also an <literal>include_if_exists</> directive, which acts There is also an <literal>include_if_exists</> directive, which acts
the same as the <literal>include</> directive, except for the behavior the same as the <literal>include</> directive, except
when the referenced file does not exist or cannot be read. A regular when the referenced file does not exist or cannot be read. A regular
<literal>include</> will consider this an error condition, but <literal>include</> will consider this an error condition, but
<literal>include_if_exists</> merely logs a message and continues <literal>include_if_exists</> merely logs a message and continues
processing the referencing configuration file. processing the referencing configuration file.
</para> </para>
<para> <para>
@ -349,79 +373,83 @@ include 'filename'
<primary><literal>include_dir</></primary> <primary><literal>include_dir</></primary>
<secondary>in configuration file</secondary> <secondary>in configuration file</secondary>
</indexterm> </indexterm>
The <filename>postgresql.conf</> file can also contain The <filename>postgresql.conf</> file can also contain
<literal>include_dir</literal> directives, which specify an entire directory <literal>include_dir</literal> directives, which specify an entire
of configuration files to include. It is used similarly: directory of configuration files to include. These look like
<programlisting> <programlisting>
include_dir 'directory' include_dir 'directory'
</programlisting> </programlisting>
Non-absolute directory names follow the same rules as single file include Non-absolute directory names are taken as relative to the directory
directives: they are relative to the directory containing the referencing containing the referencing configuration file. Within the specified
configuration file. Within that directory, only non-directory files whose directory, only non-directory files whose names end with the
names end with the suffix <literal>.conf</literal> will be included. File suffix <literal>.conf</literal> will be included. File names that
names that start with the <literal>.</literal> character are also excluded, start with the <literal>.</literal> character are also ignored, to
to prevent mistakes as they are hidden on some platforms. Multiple files prevent mistakes since such files are hidden on some platforms. Multiple
within an include directory are processed in file name order. The file names files within an include directory are processed in file name order
are ordered by C locale rules, i.e. numbers before letters, and uppercase (according to C locale rules, i.e. numbers before letters, and
letters before lowercase ones. uppercase letters before lowercase ones).
</para> </para>
<para> <para>
Include files or directories can be used to logically separate portions Include files or directories can be used to logically separate portions
of the database configuration, rather than having a single large of the database configuration, rather than having a single large
<filename>postgresql.conf</> file. Consider a company that has two <filename>postgresql.conf</> file. Consider a company that has two
database servers, each with a different amount of memory. There are likely database servers, each with a different amount of memory. There are
elements of the configuration both will share, for things such as logging. likely elements of the configuration both will share, for things such
But memory-related parameters on the server will vary between the two. And as logging. But memory-related parameters on the server will vary
there might be server specific customizations, too. One way to manage this between the two. And there might be server specific customizations,
situation is to break the custom configuration changes for your site into too. One way to manage this situation is to break the custom
three files. You could add this to the end of your configuration changes for your site into three files. You could add
<filename>postgresql.conf</> file to include them: this to the end of your <filename>postgresql.conf</> file to include
them:
<programlisting> <programlisting>
include 'shared.conf' include 'shared.conf'
include 'memory.conf' include 'memory.conf'
include 'server.conf' include 'server.conf'
</programlisting> </programlisting>
All systems would have the same <filename>shared.conf</>. Each server All systems would have the same <filename>shared.conf</>. Each
with a particular amount of memory could share the same server with a particular amount of memory could share the
<filename>memory.conf</>; you might have one for all servers with 8GB of RAM, same <filename>memory.conf</>; you might have one for all servers
another for those having 16GB. And finally <filename>server.conf</> could with 8GB of RAM, another for those having 16GB. And
have truly server-specific configuration information in it. finally <filename>server.conf</> could have truly server-specific
configuration information in it.
</para> </para>
<para> <para>
Another possibility is to create a configuration file directory and Another possibility is to create a configuration file directory and
put this information into files there. For example, a <filename>conf.d</> put this information into files there. For example, a <filename>conf.d</>
directory could be referenced at the end of<filename>postgresql.conf</>: directory could be referenced at the end of <filename>postgresql.conf</>:
<programlisting> <programlisting>
include_dir 'conf.d' include_dir 'conf.d'
</programlisting> </programlisting>
Then you could name the files in the <filename>conf.d</> directory like this: Then you could name the files in the <filename>conf.d</> directory
like this:
<programlisting> <programlisting>
00shared.conf 00shared.conf
01memory.conf 01memory.conf
02server.conf 02server.conf
</programlisting> </programlisting>
This shows a clear order in which these files will be loaded. This is This naming convention establishes a clear order in which these
important because only the last setting encountered when the server is files will be loaded. This is important because only the last
reading its configuration will be used. Something set in setting encountered for a particular parameter while the server is
<filename>conf.d/02server.conf</> in this example would override a value reading configuration files will be used. In this example,
set in <filename>conf.d/01memory.conf</>. something set in <filename>conf.d/02server.conf</> would override a
value set in <filename>conf.d/01memory.conf</>.
</para> </para>
<para> <para>
You might instead use this configuration directory approach while naming You might instead use this approach to naming the files
these files more descriptively: descriptively:
<programlisting> <programlisting>
00shared.conf 00shared.conf
01memory-8GB.conf 01memory-8GB.conf
02server-foo.conf 02server-foo.conf
</programlisting> </programlisting>
This sort of arrangement gives a unique name for each configuration file This sort of arrangement gives a unique name for each configuration file
variation. This can help eliminate ambiguity when several servers have variation. This can help eliminate ambiguity when several servers have
their configurations all stored in one place, such as in a version their configurations all stored in one place, such as in a version
control repository. (Storing database configuration files under version control repository. (Storing database configuration files under version
control is another good practice to consider). control is another good practice to consider.)
</para> </para>
</sect2> </sect2>
</sect1> </sect1>

55
doc/src/sgml/ref/alter_system.sgml
View File

@ -32,23 +32,30 @@ ALTER SYSTEM RESET ALL
<title>Description</title> <title>Description</title>
<para> <para>
<command>ALTER SYSTEM</command> writes the configuration parameter <command>ALTER SYSTEM</command> is used for changing server configuration
values to the <filename>postgresql.auto.conf</filename> file. parameters across the entire database cluster. It can be more convenient
Setting the parameter to <literal>DEFAULT</literal>, or using the than the traditional method of manually editing
<command>RESET</command> variant, removes the configuration entry from the <filename>postgresql.conf</filename> file.
<command>ALTER SYSTEM</command> writes the given parameter setting to
the <filename>postgresql.auto.conf</filename> file, which is read in
addition to <filename>postgresql.conf</filename>.
Setting a parameter to <literal>DEFAULT</literal>, or using the
<command>RESET</command> variant, removes that configuration entry from the
<filename>postgresql.auto.conf</filename> file. Use <literal>RESET <filename>postgresql.auto.conf</filename> file. Use <literal>RESET
ALL</literal> to clear all configuration entries. The values will ALL</literal> to remove all such configuration entries.
be effective after reload of server configuration (SIGHUP) or in next
server start based on the type of configuration parameter modified.
</para> </para>
<para> <para>
This command is not allowed inside transaction block or function. Values set with <command>ALTER SYSTEM</command> will be effective after
the next server configuration reload (<systemitem>SIGHUP</>
or <literal>pg_ctl reload</>), or after the next server restart in the
case of parameters that can only be changed at server start.
</para> </para>
<para> <para>
See <xref linkend="config-setting"> for other ways to set the parameters and Only superusers can use <command>ALTER SYSTEM</command>. Also, since
how they become effective. this command acts directly on the file system and cannot be rolled back,
it is not allowed inside a transaction block or function.
</para> </para>
</refsect1> </refsect1>
@ -60,7 +67,7 @@ ALTER SYSTEM RESET ALL
<term><replaceable class="parameter">configuration_parameter</replaceable></term> <term><replaceable class="parameter">configuration_parameter</replaceable></term>
<listitem> <listitem>
<para> <para>
Name of a settable run-time parameter. Available parameters are Name of a settable configuration parameter. Available parameters are
documented in <xref linkend="runtime-config">. documented in <xref linkend="runtime-config">.
</para> </para>
</listitem> </listitem>
@ -70,11 +77,11 @@ ALTER SYSTEM RESET ALL
<term><replaceable class="parameter">value</replaceable></term> <term><replaceable class="parameter">value</replaceable></term>
<listitem> <listitem>
<para> <para>
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 constants, identifiers, numbers, or comma-separated lists of
these, as appropriate for the particular parameter. these, as appropriate for the particular parameter.
<literal>DEFAULT</literal> can be written to specify to remove the <literal>DEFAULT</literal> can be written to specify removing the
parameter and its value from <filename>postgresql.auto.conf</filename> parameter and its value from <filename>postgresql.auto.conf</filename>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -85,12 +92,16 @@ ALTER SYSTEM RESET ALL
<title>Notes</title> <title>Notes</title>
<para> <para>
This command can't be used to set <xref linkend="guc-data-directory"> This command can't be used to set <xref linkend="guc-data-directory">,
and any parameters (e.g., <link linkend="runtime-config-preset">preset options</>) nor parameters that are not allowed in <filename>postgresql.conf</>
that are not allowed in <filename>postgresql.conf</>. (e.g., <link linkend="runtime-config-preset">preset options</>).
</para>
<para>
See <xref linkend="config-setting"> for other ways to set the parameters.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Examples</title> <title>Examples</title>
@ -102,10 +113,12 @@ ALTER SYSTEM SET wal_level = hot_standby;
</para> </para>
<para> <para>
Set the <literal>authentication_timeout</>: Undo that, restoring whatever setting was effective
in <filename>postgresql.conf</>:
<programlisting> <programlisting>
ALTER SYSTEM SET authentication_timeout = 10; ALTER SYSTEM RESET wal_level;
</programlisting></para> </programlisting>
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>