mirror of
https://github.com/postgres/postgres.git
synced 2025-07-09 22:41:56 +03:00
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
This commit is contained in:
@ -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">
|
||||||
|
Reference in New Issue
Block a user