database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-09 22:41:56 +03:00
Code Activity

Improve discussion of setting server parameters.

Browse Source 
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
This commit is contained in:
Tom Lane
2012-05-10 23:01:28 -04:00
parent ee24de4001
commit 817ec1bc82
1 changed files with 163 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -18,45 +18,52 @@
<sect1 id="config-setting"> <sect1 id="config-setting">
<title>Setting Parameters</title> <title>Setting Parameters</title>
<para> <sect2 id="config-setting-names-values">
All parameter names are case-insensitive. Every parameter takes a <title>Parameter Names and Values</title>
value of one of five types: Boolean, integer, floating point,
string or enum. Boolean values can be written as <literal>on</literal>,
<literal>off</literal>, <literal>true</literal>,
<literal>false</literal>, <literal>yes</literal>,
<literal>no</literal>, <literal>1</literal>, <literal>0</literal>
(all case-insensitive) or any unambiguous prefix of these.
</para>
<para> <para>
Some settings specify a memory or time value. Each of these has an All parameter names are case-insensitive. Every parameter takes a
implicit unit, which is either kilobytes, blocks (typically eight value of one of five types: Boolean, integer, floating point,
kilobytes), milliseconds, seconds, or minutes. Default units can be string or enum. Boolean values can be written as <literal>on</literal>,
found by referencing <structname>pg_settings</>.<structfield>unit</>. <literal>off</literal>, <literal>true</literal>,
For convenience, <literal>false</literal>, <literal>yes</literal>,
a different unit can also be specified explicitly. Valid memory units <literal>no</literal>, <literal>1</literal>, <literal>0</literal>
are <literal>kB</literal> (kilobytes), <literal>MB</literal> (all case-insensitive) or any unambiguous prefix of these.
(megabytes), and <literal>GB</literal> (gigabytes); valid time units </para>
are <literal>ms</literal> (milliseconds), <literal>s</literal>
(seconds), <literal>min</literal> (minutes), <literal>h</literal>
(hours), and <literal>d</literal> (days). Note that the multiplier
for memory units is 1024, not 1000.
</para>
<para> <para>
Parameters of type <quote>enum</> are specified in the same way as string Some settings specify a memory or time value. Each of these has an
parameters, but are restricted to a limited set of values. The allowed implicit unit, which is either kilobytes, blocks (typically eight
values can be found kilobytes), milliseconds, seconds, or minutes. Default units can be
from <structname>pg_settings</>.<structfield>enumvals</>. found by referencing <structname>pg_settings</>.<structfield>unit</>.
Enum parameter values are case-insensitive. For convenience,
</para> a different unit can also be specified explicitly. Valid memory units
are <literal>kB</literal> (kilobytes), <literal>MB</literal>
(megabytes), and <literal>GB</literal> (gigabytes); valid time units
are <literal>ms</literal> (milliseconds), <literal>s</literal>
(seconds), <literal>min</literal> (minutes), <literal>h</literal>
(hours), and <literal>d</literal> (days). Note that the multiplier
for memory units is 1024, not 1000.
</para>
<para> <para>
One way to set these parameters is to edit the file Parameters of type <quote>enum</> are specified in the same way as string
<filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>, parameters, but are restricted to a limited set of values. The allowed
which is normally kept in the data directory. (A default copy is values can be found
installed there when the database cluster directory is from <structname>pg_settings</>.<structfield>enumvals</>.
initialized.) An example of what this file might look like is: Enum parameter values are case-insensitive.
</para>
</sect2>
<sect2 id="config-setting-configuration-file">
<title>Setting Parameters via the Configuration File</title>
<para>
One way to set these parameters is to edit the file
<filename>postgresql.conf</><indexterm><primary>postgresql.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:
<programlisting> <programlisting>
# This is a comment # This is a comment
log_connections = yes log_connections = yes
@ -64,132 +71,147 @@ log_destination = 'syslog'
search_path = '"$user", public' 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 and blank lines are
ignored. Hash marks (<literal>#</literal>) designate the rest of the ignored. Hash marks (<literal>#</literal>) designate the remainder of the
line as a comment. Parameter values that are not simple identifiers or 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 numbers must be single-quoted. To embed a single quote in a parameter
value, write either two quotes (preferred) or backslash-quote. value, write either two quotes (preferred) or backslash-quote.
</para> </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 parameter settings, the <filename>postgresql.conf</>
file can contain <firstterm>include directives</>, which specify file can contain <firstterm>include directives</>, which specify
another file to read and process as if it were inserted into the another file to read and process as if it were inserted into the
configuration file at this point. Include directives simply look like: configuration file at this point. This feature allows a configuration
file to be divided into physically 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>
<indexterm> <indexterm>
<primary><literal>include_if_exists</></primary> <primary><literal>include_if_exists</></primary>
<secondary>in configuration file</secondary> <secondary>in configuration file</secondary>
</indexterm> </indexterm>
Use the same approach as the <literal>include</> directive, continuing There is also an <literal>include_if_exists</> directive, which acts
normally if the file does not exist. A regular <literal>include</> the same as the <literal>include</> directive, except for the behavior
will stop with an error if the referenced file is missing, while when the referenced file does not exist or cannot be read. A regular
<literal>include_if_exists</> does not. A warning about the missing <literal>include</> will consider this an error condition, but
file will be logged. <literal>include_if_exists</> merely logs a message and continues
</para> processing the referencing configuration file.
</para>
<para> <para>
<indexterm> <indexterm>
<primary>SIGHUP</primary> <primary>SIGHUP</primary>
</indexterm> </indexterm>
The configuration file is reread whenever the main server process receives a The configuration file is reread whenever the main server process
<systemitem>SIGHUP</> signal (which is most easily sent by means receives a
of <literal>pg_ctl reload</>). The main server process <systemitem>SIGHUP</> signal (which is most easily sent by means
also propagates this signal to all currently running server of <literal>pg_ctl reload</>). The main server process
processes so that existing sessions also get the new also propagates this signal to all currently running server
value. Alternatively, you can send the signal to a single server processes so that existing sessions also get the new
process directly. Some parameters can only be set at server start; value. Alternatively, you can send the signal to a single server
any changes to their entries in the configuration file will be ignored process directly. Some parameters can only be set at server start;
until the server is restarted. Invalid parameter settings in the any changes to their entries in the configuration file will be ignored
configuration file are likewise ignored (but logged) during until the server is restarted. Invalid parameter settings in the
<systemitem>SIGHUP</> processing. configuration file are likewise ignored (but logged) during
</para> <systemitem>SIGHUP</> processing.
</para>
</sect2>
<para> <sect2 id="config-setting-other-methods">
A second way to set these configuration parameters is to give them <title>Other Ways to Set Parameters</title>
as a command-line option to the <command>postgres</command> command, such as:
<para>
A second way to set these configuration parameters is to give them
as a command-line option to the <command>postgres</command> command,
such as:
<programlisting> <programlisting>
postgres -c log_connections=yes -c log_destination='syslog' postgres -c log_connections=yes -c log_destination='syslog'
</programlisting> </programlisting>
Command-line options override any conflicting settings in Command-line options override any conflicting settings in
<filename>postgresql.conf</filename>. Note that this means you won't <filename>postgresql.conf</filename>. Note that this means you won't
be able to change the value on-the-fly by editing be able to change the value on-the-fly by editing
<filename>postgresql.conf</filename>, so while the command-line <filename>postgresql.conf</filename>, so while the command-line
method might be convenient, it can cost you flexibility later. method might be convenient, it can cost you flexibility later.
</para> </para>
<para> <para>
Occasionally it is useful to give a command line option to Occasionally it is useful to give a command line option to
one particular session only. The environment variable one particular session only. The environment variable
<envar>PGOPTIONS</envar> can be used for this purpose on the <envar>PGOPTIONS</envar> can be used for this purpose on the
client side: client side:
<programlisting> <programlisting>
env PGOPTIONS='-c geqo=off' psql env PGOPTIONS='-c geqo=off' psql
</programlisting> </programlisting>
(This works for any <application>libpq</>-based client application, not (This works for any <application>libpq</>-based client application, not
just <application>psql</application>.) Note that this won't work for just <application>psql</application>.) Note that this won't work for
parameters that are fixed when the server is started or that must be parameters that are fixed when the server is started or that must be
specified in <filename>postgresql.conf</filename>. specified in <filename>postgresql.conf</filename>.
</para> </para>
<para> <para>
Furthermore, it is possible to assign a set of parameter settings to Furthermore, it is possible to assign a set of parameter settings to
a user or a database. Whenever a session is started, the default a user or a database. Whenever a session is started, the default
settings for the user and database involved are loaded. The settings for the user and database involved are loaded. The
commands <xref linkend="sql-alterrole"> commands <xref linkend="sql-alterrole">
and <xref linkend="sql-alterdatabase">, and <xref linkend="sql-alterdatabase">,
respectively, are used to configure these settings. Per-database respectively, are used to configure these settings. Per-database
settings override anything received from the settings override anything received from the
<command>postgres</command> command-line or the configuration <command>postgres</command> command-line or the configuration
file, and in turn are overridden by per-user settings; both are file, and in turn are overridden by per-user settings; both are
overridden by per-session settings. overridden by per-session settings.
</para> </para>
<para> <para>
Some parameters can be changed in individual <acronym>SQL</acronym> Some parameters can be changed in individual <acronym>SQL</acronym>
sessions with the <xref linkend="SQL-SET"> sessions with the <xref linkend="SQL-SET">
command, for example: command, for example:
<screen> <screen>
SET ENABLE_SEQSCAN TO OFF; SET ENABLE_SEQSCAN TO OFF;
</screen> </screen>
If <command>SET</> is allowed, it overrides all other sources of If <command>SET</> is allowed, it overrides all other sources of
values for the parameter. Some parameters cannot be changed via values for the parameter. Some parameters cannot be changed via
<command>SET</command>: for example, if they control behavior that <command>SET</command>: for example, if they control behavior that
cannot be changed without restarting the entire cannot be changed without restarting the entire
<productname>PostgreSQL</productname> server. Also, <productname>PostgreSQL</productname> server. Also, some parameters
some <command>SET</command> or <command>ALTER</> parameter modifications require superuser permission to change via <command>SET</command> or
require superuser permission. <command>ALTER</>.
</para> </para>
</sect2>
<para> <sect2 id="config-setting-examining">
The <xref linkend="SQL-SHOW"> <title>Examining Parameter Settings</title>
command allows inspection of the current values of all parameters.
</para>
<para> <para>
The virtual table <structname>pg_settings</structname> also allows The <xref linkend="SQL-SHOW">
displaying and updating session run-time parameters; see <xref command allows inspection of the current values of all parameters.
linkend="view-pg-settings"> for details and a description of the </para>
different variable types and when they can be changed.
<structname>pg_settings</structname> is equivalent to <command>SHOW</> <para>
and <command>SET</>, but can be more convenient The virtual table <structname>pg_settings</structname> also allows
to use because it can be joined with other tables, or selected from using displaying and updating session run-time parameters; see <xref
any desired selection condition. It also contains more information about linkend="view-pg-settings"> for details and a description of the
what values are allowed for the parameters. different variable types and when they can be changed.
</para> <structname>pg_settings</structname> is equivalent to <command>SHOW</>
and <command>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 <command>SHOW</>.
</para>
</sect2>
</sect1> </sect1>
<sect1 id="runtime-config-file-locations"> <sect1 id="runtime-config-file-locations">