mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-30 19:01:19 +02:00
doc: improve configuration management section
Patch by David Johnston Backpatch through 9.4
This commit is contained in:
parent
acc8e41681
commit
4c4654afeb
@ -10,8 +10,8 @@
|
|||||||
|
|
||||||
<para>
|
<para>
|
||||||
There are many configuration parameters that affect the behavior of
|
There are many configuration parameters that affect the behavior of
|
||||||
the database system. In the first section of this chapter, we
|
the database system. In the first section of this chapter we
|
||||||
describe how to set configuration parameters. The subsequent sections
|
describe how to interact with configuration parameters. The subsequent sections
|
||||||
discuss each parameter in detail.
|
discuss each parameter in detail.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
@ -23,47 +23,100 @@
|
|||||||
|
|
||||||
<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, integer, floating point,
|
||||||
string or enum. Boolean values can be written as <literal>on</literal>,
|
string, or enum.
|
||||||
<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>
|
<itemizedlist>
|
||||||
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 <structname>pg_settings</>.<structfield>unit</>.
|
|
||||||
For convenience,
|
|
||||||
a different unit can also be specified explicitly. Valid memory units
|
|
||||||
are <literal>kB</literal> (kilobytes), <literal>MB</literal>
|
|
||||||
(megabytes), <literal>GB</literal> (gigabytes), and <literal>TB</literal> (terabytes); 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>
|
<listitem>
|
||||||
Parameters of type <quote>enum</> are specified in the same way as string
|
<para>
|
||||||
parameters, but are restricted to a limited set of values. The allowed
|
<emphasis>Boolean:</emphasis> Values can be written as
|
||||||
values can be found
|
<literal>on</literal>,
|
||||||
from <structname>pg_settings</>.<structfield>enumvals</>.
|
<literal>off</literal>,
|
||||||
Enum parameter values are case-insensitive.
|
<literal>true</literal>,
|
||||||
</para>
|
<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>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<emphasis>String:</emphasis> Enclose the value in
|
||||||
|
single-quotes. Values are case-insensitive. If multiple values
|
||||||
|
are allowed, separate them with commas.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<emphasis>Numeric (integer and floating point):</emphasis> Do
|
||||||
|
not use single-quotes (unless otherwise required) or thousand
|
||||||
|
separators.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<emphasis>Numeric or String with Unit (Memory &
|
||||||
|
Time):</emphasis> 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
|
||||||
|
<structname>pg_settings</>.<structfield>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.
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Valid memory units are <literal>kB</literal> (kilobytes),
|
||||||
|
<literal>MB</literal> (megabytes), <literal>GB</literal>
|
||||||
|
(gigabytes), and <literal>TB</literal> (terabytes).
|
||||||
|
The multiplier for memory units is 1024, not 1000.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
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).
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<emphasis><quote>enum</>:</emphasis> These are specified
|
||||||
|
in the same way as string parameters, but are restricted
|
||||||
|
to a limited set of values that can be queried from
|
||||||
|
<structname>pg_settings</>.<structfield>enumvals</>:
|
||||||
|
<programlisting>
|
||||||
|
SELECT name, setting, enumvals FROM pg_settings WHERE enumvals IS NOT NULL;
|
||||||
|
</programlisting>
|
||||||
|
Enum parameter values are case-insensitive.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="config-setting-configuration-file">
|
<sect2 id="config-setting-configuration-file">
|
||||||
<title>Setting Parameters via the Configuration File</title>
|
<title>Parameter Interaction via Configuration File</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
One way to set these parameters is to edit the file
|
The primary 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 there when the database cluster directory is
|
installed when the database cluster directory is initialized.)
|
||||||
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
|
||||||
log_connections = yes
|
log_connections = yes
|
||||||
@ -73,125 +126,186 @@ 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 remainder of the
|
ignored. Hash marks (<literal>#</literal>) designate the remainder
|
||||||
line as a comment. Parameter values that are not simple identifiers or
|
of the line as a comment. Parameter values that are not simple
|
||||||
numbers must be single-quoted. To embed a single quote in a parameter
|
identifiers or numbers must be single-quoted. To embed a single
|
||||||
value, write either two quotes (preferred) or backslash-quote.
|
quote in a parameter value write either two quotes (preferred)
|
||||||
|
or backslash-quote.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
</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 is most easily done by
|
||||||
running <literal>pg_ctl reload</> from the command-line or by calling
|
running <literal>pg_ctl reload</> from the command-line or by calling
|
||||||
the SQL function <function>pg_reload_conf()</function>. The main
|
the SQL function <function>pg_reload_conf()</function>. The main
|
||||||
server process
|
server process also propagates this signal to all currently running
|
||||||
also propagates this signal to all currently running server
|
server processes so that existing sessions also get the new value
|
||||||
processes so that existing sessions also get the new
|
when they complete their transactions. Alternatively, you can
|
||||||
value. Alternatively, you can send the signal to a single server
|
send the signal to a single server process directly. Some parameters
|
||||||
process directly. Some parameters can only be set at server start;
|
can only be set at server start; any changes to their entries in the
|
||||||
any changes to their entries in the configuration file will be ignored
|
configuration file will be ignored until the server is restarted.
|
||||||
until the server is restarted. Invalid parameter settings in the
|
Invalid parameter settings in the configuration file are likewise
|
||||||
configuration file are likewise ignored (but logged) during
|
ignored (but logged) during <systemitem>SIGHUP</> processing.
|
||||||
<systemitem>SIGHUP</> processing.
|
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="config-setting-other-methods">
|
<sect2 id="config-setting-sql-command-interaction">
|
||||||
<title>Other Ways to Set Parameters</title>
|
<title>Parameter Interaction via SQL</title>
|
||||||
|
<para>
|
||||||
|
<productname>PostgreSQL</productname> 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 <xref
|
||||||
|
linkend="SQL-DISCARD">, or if the server forces the session to
|
||||||
|
reload its configuration after a <systemitem>SIGHUP</systemitem>
|
||||||
|
signal.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The <xref linkend="SQL-ALTERSYSTEM"> command provides an
|
||||||
|
SQL-accessible means of changing global defaults.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The <xref linkend="sql-alterdatabase"> command allows database
|
||||||
|
administrators to override global settings on a per-database basis.
|
||||||
|
</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>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The <xref linkend="SQL-SHOW"> command allows inspection of the
|
||||||
|
current value of all parameters. The corresponding function is
|
||||||
|
<function>current_setting(setting_name text)</function>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The <xref linkend="SQL-SET"> command allows modification of the
|
||||||
|
current value of some parameters. The corresponding function is
|
||||||
|
<function>set_config(setting_name, new_value, is_local)</function>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
A second way to set these configuration parameters is to give them
|
Both <command>SELECT</> and <command>UPDATE</>
|
||||||
as a command-line option to the <command>postgres</command> command,
|
can be issued against the system view <link
|
||||||
such as:
|
linkend="view-pg-settings"><structname>pg_settings</></> to view
|
||||||
|
and change session-local values.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Querying this view is the same as <command>SHOW</> but provides
|
||||||
|
more detail, as well as allowing for joins against other relations
|
||||||
|
and the specification of filter criteria.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Using <xref linkend="SQL-UPDATE"> on this relation, specifically
|
||||||
|
updating the <structname>setting</> column, is the equivalent
|
||||||
|
of issuing SQL <command>SET</>, though all values must be
|
||||||
|
single-quoted. Note that the equivalent of
|
||||||
|
<programlisting>
|
||||||
|
SET configuration_parameter TO DEFAULT;
|
||||||
|
</>
|
||||||
|
is:
|
||||||
|
<programlisting>
|
||||||
|
UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Parameter Interaction via Shell</title>
|
||||||
|
<para>
|
||||||
|
In addition to setting global defaults or attaching
|
||||||
|
overrides at the database or role level, you can pass settings to
|
||||||
|
<productname>PostgreSQL</productname> via shell facilities.
|
||||||
|
Both the server and <application>libpq</> client library
|
||||||
|
accept parameter values via the shell.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
On the <emphasis>server</emphasis>, command-line options can be
|
||||||
|
passed to the <command>postgres</command> command directly via the
|
||||||
|
<option>-c</> parameter.
|
||||||
<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
|
Settings provided this way override those resolved globally (via
|
||||||
<filename>postgresql.conf</filename>. Note that this means you won't
|
<filename>postgresql.conf</> or <command>ALTER SYSTEM</>) but
|
||||||
be able to change the value on-the-fly by editing
|
are otherwise treated as being global for the purpose of database
|
||||||
<filename>postgresql.conf</filename>, so while the command-line
|
and role overrides.
|
||||||
method might be convenient, it can cost you flexibility later.
|
</para>
|
||||||
</para>
|
</listitem>
|
||||||
|
|
||||||
<para>
|
<listitem>
|
||||||
Occasionally it is useful to give a command line option to
|
<para>
|
||||||
one particular session only. The environment variable
|
On the <emphasis>libpq-client</emphasis>, command-line options can be
|
||||||
<envar>PGOPTIONS</envar> can be used for this purpose on the
|
specified using the <envar>PGOPTIONS</envar> environment variable.
|
||||||
client side:
|
When connecting to the server, the contents of this variable are
|
||||||
|
sent to the server as if they were being executed via SQL <xref
|
||||||
|
linkend="SQL-SET"> at the beginning of the session.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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' psql
|
env PGOPTIONS="-c geqo=off -c statement_timeout='5 min'" psql
|
||||||
</programlisting>
|
</programlisting>
|
||||||
(This works for any <application>libpq</>-based client application, not
|
</para>
|
||||||
just <application>psql</application>.) Note that this won't work for
|
|
||||||
parameters that are fixed when the server is started or that must be
|
|
||||||
specified in <filename>postgresql.conf</filename>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Furthermore, it is possible to assign a set of parameter settings to
|
Other clients and libraries might provide their own mechanisms,
|
||||||
a user or a database. Whenever a session is started, the default
|
via the shell or otherwise, that allow the user to alter session
|
||||||
settings for the user and database involved are loaded. The
|
settings without requiring the user to issue SQL commands.
|
||||||
commands <xref linkend="sql-alterrole">
|
</para>
|
||||||
and <xref linkend="sql-alterdatabase">,
|
</listitem>
|
||||||
respectively, are used to configure these settings. Per-database
|
</itemizedlist>
|
||||||
settings override anything received from the
|
|
||||||
<command>postgres</command> command-line or the configuration
|
|
||||||
file, and in turn are overridden by per-user settings; both are
|
|
||||||
overridden by per-session settings.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Some parameters can be changed in individual <acronym>SQL</acronym>
|
|
||||||
sessions with the <xref linkend="SQL-SET">
|
|
||||||
command, for example:
|
|
||||||
<screen>
|
|
||||||
SET ENABLE_SEQSCAN TO OFF;
|
|
||||||
</screen>
|
|
||||||
If <command>SET</> is allowed, it overrides all other sources of
|
|
||||||
values for the parameter. Some parameters cannot be changed via
|
|
||||||
<command>SET</command>: for example, if they control behavior that
|
|
||||||
cannot be changed without restarting the entire
|
|
||||||
<productname>PostgreSQL</productname> server. Also, some parameters
|
|
||||||
require superuser permission to change via <command>SET</command> or
|
|
||||||
<command>ALTER</>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Another way to change configuration parameters persistently is by
|
|
||||||
use of <xref linkend="SQL-ALTERSYSTEM">
|
|
||||||
command, for example:
|
|
||||||
<screen>
|
|
||||||
ALTER SYSTEM SET checkpoint_timeout TO 600;
|
|
||||||
</screen>
|
|
||||||
This command will allow users to change values persistently
|
|
||||||
through SQL command. The values will be effective after reload of server configuration
|
|
||||||
(<acronym>SIGHUP</>) or server startup. The effect of this command is similar to when
|
|
||||||
user manually changes values in <filename>postgresql.conf</filename>.
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2 id="config-setting-examining">
|
|
||||||
<title>Examining Parameter Settings</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <xref linkend="SQL-SHOW">
|
|
||||||
command allows inspection of the current values of all parameters.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The virtual table <structname>pg_settings</structname> also allows
|
|
||||||
displaying and updating session run-time parameters; see <xref
|
|
||||||
linkend="view-pg-settings"> for details and a description of the
|
|
||||||
different variable types and when they can be changed.
|
|
||||||
<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>
|
</sect2>
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user