12179 lines
525 KiB
Plaintext
12179 lines
525 KiB
Plaintext
<!-- doc/src/sgml/config.sgml -->
|
||
|
||
<chapter id="runtime-config">
|
||
<title>Server Configuration</title>
|
||
|
||
<indexterm>
|
||
<primary>configuration</primary>
|
||
<secondary>of the server</secondary>
|
||
</indexterm>
|
||
|
||
<para>
|
||
There are many configuration parameters that affect the behavior of
|
||
the database system. In the first section of this chapter we
|
||
describe how to interact with configuration parameters. The subsequent sections
|
||
discuss each parameter in detail.
|
||
</para>
|
||
|
||
<sect1 id="config-setting">
|
||
<title>Setting Parameters</title>
|
||
|
||
<sect2 id="config-setting-names-values">
|
||
<title>Parameter Names and Values</title>
|
||
|
||
<para>
|
||
All parameter names are case-insensitive. Every parameter takes a
|
||
value of one of five types: boolean, string, integer, floating point,
|
||
or enumerated (enum). The type determines the syntax for setting the
|
||
parameter:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<emphasis>Boolean:</emphasis>
|
||
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 one of these.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
<emphasis>String:</emphasis>
|
||
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.
|
||
(Values that match an SQL keyword require quoting in some contexts.)
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
<emphasis>Numeric (integer and floating point):</emphasis>
|
||
Numeric parameters can be specified in the customary integer and
|
||
floating-point formats; fractional values are rounded to the nearest
|
||
integer if the parameter is of integer type. Integer parameters
|
||
additionally accept hexadecimal input (beginning
|
||
with <literal>0x</literal>) and octal input (beginning
|
||
with <literal>0</literal>), but these formats cannot have a fraction.
|
||
Do not use thousands separators.
|
||
Quotes are not required, except for hexadecimal input.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
<emphasis>Numeric with Unit:</emphasis>
|
||
Some numeric parameters have an implicit unit, because they describe
|
||
quantities of memory or time. The unit might be bytes, 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
|
||
<structname>pg_settings</structname>.<structfield>unit</structfield>.
|
||
For convenience, settings can be given with a unit specified explicitly,
|
||
for example <literal>'120 ms'</literal> 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>
|
||
<listitem>
|
||
<para>
|
||
Valid memory units are <literal>B</literal> (bytes),
|
||
<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>us</literal> (microseconds),
|
||
<literal>ms</literal> (milliseconds),
|
||
<literal>s</literal> (seconds), <literal>min</literal> (minutes),
|
||
<literal>h</literal> (hours), and <literal>d</literal> (days).
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
If a fractional value is specified with a unit, it will be rounded
|
||
to a multiple of the next smaller unit if there is one.
|
||
For example, <literal>30.1 GB</literal> will be converted
|
||
to <literal>30822 MB</literal> not <literal>32319628902 B</literal>.
|
||
If the parameter is of integer type, a final rounding to integer
|
||
occurs after any unit conversion.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
<emphasis>Enumerated:</emphasis>
|
||
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
|
||
<structname>pg_settings</structname>.<structfield>enumvals</structfield>.
|
||
Enum parameter values are case-insensitive.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</sect2>
|
||
|
||
<sect2 id="config-setting-configuration-file">
|
||
<title>Parameter Interaction via the Configuration File</title>
|
||
|
||
<para>
|
||
The most fundamental way to set these parameters is to edit the file
|
||
<filename>postgresql.conf</filename><indexterm><primary>postgresql.conf</primary></indexterm>,
|
||
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:
|
||
<programlisting>
|
||
# This is a comment
|
||
log_connections = yes
|
||
log_destination = 'syslog'
|
||
search_path = '"$user", public'
|
||
shared_buffers = 128MB
|
||
</programlisting>
|
||
One parameter is specified per line. The equal sign between name and
|
||
value is optional. Whitespace is insignificant (except within a quoted
|
||
parameter value) and blank lines are
|
||
ignored. Hash marks (<literal>#</literal>) 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)
|
||
or backslash-quote.
|
||
If the file contains multiple entries for the same parameter,
|
||
all but the last one are ignored.
|
||
</para>
|
||
|
||
<para>
|
||
Parameters set in this way provide default values for the cluster.
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
<indexterm>
|
||
<primary>SIGHUP</primary>
|
||
</indexterm>
|
||
The configuration file is reread whenever the main server process
|
||
receives a <systemitem>SIGHUP</systemitem> signal; this signal is most easily
|
||
sent by running <literal>pg_ctl reload</literal> from the command line or by
|
||
calling the SQL function <function>pg_reload_conf()</function>. The main
|
||
server process also propagates this signal to all currently running
|
||
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 <systemitem>SIGHUP</systemitem> processing.
|
||
</para>
|
||
|
||
<para>
|
||
In addition to <filename>postgresql.conf</filename>,
|
||
a <productname>PostgreSQL</productname> data directory contains a file
|
||
<filename>postgresql.auto.conf</filename><indexterm><primary>postgresql.auto.conf</primary></indexterm>,
|
||
which has the same format as <filename>postgresql.conf</filename> but
|
||
is intended to be edited automatically, not manually. This file holds
|
||
settings provided through the <link linkend="sql-altersystem"><command>ALTER SYSTEM</command></link> command.
|
||
This file is read whenever <filename>postgresql.conf</filename> is,
|
||
and its settings take effect in the same way. Settings
|
||
in <filename>postgresql.auto.conf</filename> override those
|
||
in <filename>postgresql.conf</filename>.
|
||
</para>
|
||
|
||
<para>
|
||
External tools may also
|
||
modify <filename>postgresql.auto.conf</filename>. It is not
|
||
recommended to do this while the server is running unless <xref
|
||
linkend="guc-allow-alter-system"/> is set to <literal>off</literal>, since a
|
||
concurrent <command>ALTER SYSTEM</command> command could overwrite
|
||
such changes. Such tools might simply append new settings to the end,
|
||
or they might choose to remove duplicate settings and/or comments
|
||
(as <command>ALTER SYSTEM</command> will).
|
||
</para>
|
||
|
||
<para>
|
||
The system view
|
||
<link linkend="view-pg-file-settings"><structname>pg_file_settings</structname></link>
|
||
can be helpful for pre-testing changes to the configuration files, or for
|
||
diagnosing problems if a <systemitem>SIGHUP</systemitem> signal did not have the
|
||
desired effects.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="config-setting-sql">
|
||
<title>Parameter Interaction via SQL</title>
|
||
|
||
<para>
|
||
<productname>PostgreSQL</productname> provides three SQL
|
||
commands to establish configuration defaults.
|
||
The already-mentioned <command>ALTER SYSTEM</command> command
|
||
provides an SQL-accessible means of changing global defaults; it is
|
||
functionally equivalent to editing <filename>postgresql.conf</filename>.
|
||
In addition, there are two commands that allow setting of defaults
|
||
on a per-database or per-role basis:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
The <link linkend="sql-alterdatabase"><command>ALTER DATABASE</command></link> command allows global
|
||
settings to be overridden on a per-database basis.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
The <link linkend="sql-alterrole"><command>ALTER ROLE</command></link> command allows both global and
|
||
per-database settings to be overridden with user-specific values.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
Values set with <command>ALTER DATABASE</command> and <command>ALTER ROLE</command>
|
||
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).
|
||
</para>
|
||
|
||
<para>
|
||
Once a client is connected to the database, <productname>PostgreSQL</productname>
|
||
provides two additional SQL commands (and equivalent functions) to
|
||
interact with session-local configuration settings:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
The <link linkend="sql-show"><command>SHOW</command></link> command allows inspection of the
|
||
current value of any parameter. The corresponding SQL function is
|
||
<function>current_setting(setting_name text)</function>
|
||
(see <xref linkend="functions-admin-set"/>).
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
The <link linkend="sql-set"><command>SET</command></link> command allows modification of the
|
||
current value of those parameters that can be set locally to a
|
||
session; it has no effect on other sessions.
|
||
Many parameters can be set this way by any user, but some can
|
||
only be set by superusers and users who have been
|
||
granted <literal>SET</literal> privilege on that parameter.
|
||
The corresponding SQL function is
|
||
<function>set_config(setting_name, new_value, is_local)</function>
|
||
(see <xref linkend="functions-admin-set"/>).
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
In addition, the system view <link
|
||
linkend="view-pg-settings"><structname>pg_settings</structname></link> can be
|
||
used to view and change session-local values:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
Querying this view is similar to using <command>SHOW ALL</command> but
|
||
provides more detail. It is also more flexible, since it's possible
|
||
to specify filter conditions or join against other relations.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Using <command>UPDATE</command> on this view, specifically
|
||
updating the <structname>setting</structname> column, is the equivalent
|
||
of issuing <command>SET</command> commands. For example, the equivalent of
|
||
<programlisting>
|
||
SET configuration_parameter TO DEFAULT;
|
||
</programlisting>
|
||
is:
|
||
<programlisting>
|
||
UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
|
||
</programlisting>
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
</sect2>
|
||
|
||
<sect2 id="config-setting-shell">
|
||
<title>Parameter Interaction via the 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</application> client library
|
||
accept parameter values via the shell.
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
During server startup, parameter settings can be
|
||
passed to the <command>postgres</command> command via the
|
||
<option>-c name=value</option> command-line parameter, or its equivalent
|
||
<option>--name=value</option> variation. For example,
|
||
<programlisting>
|
||
postgres -c log_connections=yes --log-destination='syslog'
|
||
</programlisting>
|
||
Settings provided in this way override those set via
|
||
<filename>postgresql.conf</filename> or <command>ALTER SYSTEM</command>,
|
||
so they cannot be changed globally without restarting the server.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
When starting a client session via <application>libpq</application>,
|
||
parameter settings can be
|
||
specified using the <envar>PGOPTIONS</envar> environment variable.
|
||
Settings established in this way constitute defaults for the life
|
||
of the session, but do not affect other sessions.
|
||
For historical reasons, the format of <envar>PGOPTIONS</envar> is
|
||
similar to that used when launching the <command>postgres</command>
|
||
command; specifically, the <option>-c</option>, or prepended
|
||
<literal>--</literal>, before the name must be specified. For example,
|
||
<programlisting>
|
||
env PGOPTIONS="-c geqo=off --statement-timeout=5min" psql
|
||
</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
Other clients and libraries might provide their own mechanisms,
|
||
via the shell or otherwise, that allow the user to alter session
|
||
settings without direct use of SQL commands.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
</sect2>
|
||
|
||
<sect2 id="config-includes">
|
||
<title>Managing Configuration File Contents</title>
|
||
|
||
<para>
|
||
<productname>PostgreSQL</productname> provides several features for breaking
|
||
down complex <filename>postgresql.conf</filename> files into sub-files.
|
||
These features are especially useful when managing multiple servers
|
||
with related, but not identical, configurations.
|
||
</para>
|
||
|
||
<para>
|
||
<indexterm>
|
||
<primary><literal>include</literal></primary>
|
||
<secondary>in configuration file</secondary>
|
||
</indexterm>
|
||
In addition to individual parameter settings,
|
||
the <filename>postgresql.conf</filename> file can contain <firstterm>include
|
||
directives</firstterm>, 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:
|
||
<programlisting>
|
||
include 'filename'
|
||
</programlisting>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
<indexterm>
|
||
<primary><literal>include_if_exists</literal></primary>
|
||
<secondary>in configuration file</secondary>
|
||
</indexterm>
|
||
There is also an <literal>include_if_exists</literal> directive, which acts
|
||
the same as the <literal>include</literal> directive, except
|
||
when the referenced file does not exist or cannot be read. A regular
|
||
<literal>include</literal> will consider this an error condition, but
|
||
<literal>include_if_exists</literal> merely logs a message and continues
|
||
processing the referencing configuration file.
|
||
</para>
|
||
|
||
<para>
|
||
<indexterm>
|
||
<primary><literal>include_dir</literal></primary>
|
||
<secondary>in configuration file</secondary>
|
||
</indexterm>
|
||
The <filename>postgresql.conf</filename> file can also contain
|
||
<literal>include_dir</literal> directives, which specify an entire
|
||
directory of configuration files to include. These look like
|
||
<programlisting>
|
||
include_dir 'directory'
|
||
</programlisting>
|
||
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 <literal>.conf</literal> will be included. File names that
|
||
start with the <literal>.</literal> 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).
|
||
</para>
|
||
|
||
<para>
|
||
Include files or directories can be used to logically separate portions
|
||
of the database configuration, rather than having a single large
|
||
<filename>postgresql.conf</filename> 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 <filename>postgresql.conf</filename> file to include
|
||
them:
|
||
<programlisting>
|
||
include 'shared.conf'
|
||
include 'memory.conf'
|
||
include 'server.conf'
|
||
</programlisting>
|
||
All systems would have the same <filename>shared.conf</filename>. Each
|
||
server with a particular amount of memory could share the
|
||
same <filename>memory.conf</filename>; you might have one for all servers
|
||
with 8GB of RAM, another for those having 16GB. And
|
||
finally <filename>server.conf</filename> could have truly server-specific
|
||
configuration information in it.
|
||
</para>
|
||
|
||
<para>
|
||
Another possibility is to create a configuration file directory and
|
||
put this information into files there. For example, a <filename>conf.d</filename>
|
||
directory could be referenced at the end of <filename>postgresql.conf</filename>:
|
||
<programlisting>
|
||
include_dir 'conf.d'
|
||
</programlisting>
|
||
Then you could name the files in the <filename>conf.d</filename> directory
|
||
like this:
|
||
<programlisting>
|
||
00shared.conf
|
||
01memory.conf
|
||
02server.conf
|
||
</programlisting>
|
||
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 <filename>conf.d/02server.conf</filename> would override a
|
||
value set in <filename>conf.d/01memory.conf</filename>.
|
||
</para>
|
||
|
||
<para>
|
||
You might instead use this approach to naming the files
|
||
descriptively:
|
||
<programlisting>
|
||
00shared.conf
|
||
01memory-8GB.conf
|
||
02server-foo.conf
|
||
</programlisting>
|
||
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.)
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-file-locations">
|
||
<title>File Locations</title>
|
||
|
||
<para>
|
||
In addition to the <filename>postgresql.conf</filename> file
|
||
already mentioned, <productname>PostgreSQL</productname> uses
|
||
two other manually-edited configuration files, which control
|
||
client authentication (their use is discussed in <xref
|
||
linkend="client-authentication"/>). By default, all three
|
||
configuration files are stored in the database cluster's data
|
||
directory. The parameters described in this section allow the
|
||
configuration files to be placed elsewhere. (Doing so can ease
|
||
administration. In particular it is often easier to ensure that
|
||
the configuration files are properly backed-up when they are
|
||
kept separate.)
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-data-directory" xreflabel="data_directory">
|
||
<term><varname>data_directory</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>data_directory</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the directory to use for data storage.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-config-file" xreflabel="config_file">
|
||
<term><varname>config_file</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>config_file</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the main server configuration file
|
||
(customarily called <filename>postgresql.conf</filename>).
|
||
This parameter can only be set on the <command>postgres</command> command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-hba-file" xreflabel="hba_file">
|
||
<term><varname>hba_file</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>hba_file</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the configuration file for host-based authentication
|
||
(customarily called <filename>pg_hba.conf</filename>).
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ident-file" xreflabel="ident_file">
|
||
<term><varname>ident_file</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ident_file</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the configuration file for user name mapping
|
||
(customarily called <filename>pg_ident.conf</filename>).
|
||
This parameter can only be set at server start.
|
||
See also <xref linkend="auth-username-maps"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-external-pid-file" xreflabel="external_pid_file">
|
||
<term><varname>external_pid_file</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>external_pid_file</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of an additional process-ID (PID) file that the
|
||
server should create for use by server administration programs.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
In a default installation, none of the above parameters are set
|
||
explicitly. Instead, the
|
||
data directory is specified by the <option>-D</option> command-line
|
||
option or the <envar>PGDATA</envar> environment variable, and the
|
||
configuration files are all found within the data directory.
|
||
</para>
|
||
|
||
<para>
|
||
If you wish to keep the configuration files elsewhere than the
|
||
data directory, the <command>postgres</command> <option>-D</option>
|
||
command-line option or <envar>PGDATA</envar> environment variable
|
||
must point to the directory containing the configuration files,
|
||
and the <varname>data_directory</varname> parameter must be set in
|
||
<filename>postgresql.conf</filename> (or on the command line) to show
|
||
where the data directory is actually located. Notice that
|
||
<varname>data_directory</varname> overrides <option>-D</option> and
|
||
<envar>PGDATA</envar> for the location
|
||
of the data directory, but not for the location of the configuration
|
||
files.
|
||
</para>
|
||
|
||
<para>
|
||
If you wish, you can specify the configuration file names and locations
|
||
individually using the parameters <varname>config_file</varname>,
|
||
<varname>hba_file</varname> and/or <varname>ident_file</varname>.
|
||
<varname>config_file</varname> can only be specified on the
|
||
<command>postgres</command> command line, but the others can be
|
||
set within the main configuration file. If all three parameters plus
|
||
<varname>data_directory</varname> are explicitly set, then it is not necessary
|
||
to specify <option>-D</option> or <envar>PGDATA</envar>.
|
||
</para>
|
||
|
||
<para>
|
||
When setting any of these parameters, a relative path will be interpreted
|
||
with respect to the directory in which <command>postgres</command>
|
||
is started.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-connection">
|
||
<title>Connections and Authentication</title>
|
||
|
||
<sect2 id="runtime-config-connection-settings">
|
||
<title>Connection Settings</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-listen-addresses" xreflabel="listen_addresses">
|
||
<term><varname>listen_addresses</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>listen_addresses</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the TCP/IP address(es) on which the server is
|
||
to listen for connections from client applications.
|
||
The value takes the form of a comma-separated list of host names
|
||
and/or numeric IP addresses. The special entry <literal>*</literal>
|
||
corresponds to all available IP interfaces. The entry
|
||
<literal>0.0.0.0</literal> allows listening for all IPv4 addresses and
|
||
<literal>::</literal> allows listening for all IPv6 addresses.
|
||
If the list is empty, the server does not listen on any IP interface
|
||
at all, in which case only Unix-domain sockets can be used to connect
|
||
to it. If the list is not empty, the server will start if it
|
||
can listen on at least one TCP/IP address. A warning will be
|
||
emitted for any TCP/IP address which cannot be opened.
|
||
The default value is <systemitem class="systemname">localhost</systemitem>,
|
||
which allows only local TCP/IP <quote>loopback</quote> connections to be
|
||
made.
|
||
</para>
|
||
<para>
|
||
While client authentication (<xref
|
||
linkend="client-authentication"/>) allows fine-grained control
|
||
over who can access the server, <varname>listen_addresses</varname>
|
||
controls which interfaces accept connection attempts, which
|
||
can help prevent repeated malicious connection requests on
|
||
insecure network interfaces. This parameter can only be set
|
||
at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-port" xreflabel="port">
|
||
<term><varname>port</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>port</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The TCP port the server listens on; 5432 by default. Note that the
|
||
same port number is used for all IP addresses the server listens on.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-connections" xreflabel="max_connections">
|
||
<term><varname>max_connections</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_connections</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Determines the maximum number of concurrent connections to the
|
||
database server. The default is typically 100 connections, but
|
||
might be less if your kernel settings will not support it (as
|
||
determined during <application>initdb</application>). This parameter can
|
||
only be set at server start.
|
||
</para>
|
||
|
||
<para>
|
||
PostgreSQL sizes certain resources based directly on the value of
|
||
<varname>max_connections</varname>. Increasing its value leads to
|
||
higher allocation of those resources, including shared memory.
|
||
</para>
|
||
|
||
<para>
|
||
When running a standby server, you must set this parameter to the
|
||
same or higher value than on the primary server. Otherwise, queries
|
||
will not be allowed in the standby server.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-reserved-connections" xreflabel="reserved_connections">
|
||
<term><varname>reserved_connections</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>reserved_connections</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Determines the number of connection <quote>slots</quote> that are
|
||
reserved for connections by roles with privileges of the
|
||
<link linkend="predefined-roles-table"><literal>pg_use_reserved_connections</literal></link>
|
||
role. Whenever the number of free connection slots is greater than
|
||
<xref linkend="guc-superuser-reserved-connections"/> but less than or
|
||
equal to the sum of <varname>superuser_reserved_connections</varname>
|
||
and <varname>reserved_connections</varname>, new connections will be
|
||
accepted only for superusers and roles with privileges of
|
||
<literal>pg_use_reserved_connections</literal>. If
|
||
<varname>superuser_reserved_connections</varname> or fewer connection
|
||
slots are available, new connections will be accepted only for
|
||
superusers.
|
||
</para>
|
||
|
||
<para>
|
||
The default value is zero connections. The value must be less than
|
||
<varname>max_connections</varname> minus
|
||
<varname>superuser_reserved_connections</varname>. This parameter can
|
||
only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-superuser-reserved-connections"
|
||
xreflabel="superuser_reserved_connections">
|
||
<term><varname>superuser_reserved_connections</varname>
|
||
(<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>superuser_reserved_connections</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Determines the number of connection <quote>slots</quote> that
|
||
are reserved for connections by <productname>PostgreSQL</productname>
|
||
superusers. At most <xref linkend="guc-max-connections"/>
|
||
connections can ever be active simultaneously. Whenever the
|
||
number of active concurrent connections is at least
|
||
<varname>max_connections</varname> minus
|
||
<varname>superuser_reserved_connections</varname>, new
|
||
connections will be accepted only for superusers. The connection slots
|
||
reserved by this parameter are intended as final reserve for emergency
|
||
use after the slots reserved by
|
||
<xref linkend="guc-reserved-connections"/> have been exhausted.
|
||
</para>
|
||
|
||
<para>
|
||
The default value is three connections. The value must be less
|
||
than <varname>max_connections</varname> minus
|
||
<varname>reserved_connections</varname>.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-unix-socket-directories" xreflabel="unix_socket_directories">
|
||
<term><varname>unix_socket_directories</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>unix_socket_directories</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the directory of the Unix-domain socket(s) on which the
|
||
server is to listen for connections from client applications.
|
||
Multiple sockets can be created by listing multiple directories
|
||
separated by commas. Whitespace between entries is
|
||
ignored; surround a directory name with double quotes if you need
|
||
to include whitespace or commas in the name.
|
||
An empty value
|
||
specifies not listening on any Unix-domain sockets, in which case
|
||
only TCP/IP sockets can be used to connect to the server.
|
||
</para>
|
||
|
||
<para>
|
||
A value that starts with <literal>@</literal> specifies that a
|
||
Unix-domain socket in the abstract namespace should be created
|
||
(currently supported on Linux only). In that case, this value
|
||
does not specify a <quote>directory</quote> but a prefix from which
|
||
the actual socket name is computed in the same manner as for the
|
||
file-system namespace. While the abstract socket name prefix can be
|
||
chosen freely, since it is not a file-system location, the convention
|
||
is to nonetheless use file-system-like values such as
|
||
<literal>@/tmp</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
The default value is normally
|
||
<filename>/tmp</filename>, but that can be changed at build time.
|
||
On Windows, the default is empty, which means no Unix-domain socket is
|
||
created by default.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
|
||
<para>
|
||
In addition to the socket file itself, which is named
|
||
<literal>.s.PGSQL.<replaceable>nnnn</replaceable></literal> where
|
||
<replaceable>nnnn</replaceable> is the server's port number, an ordinary file
|
||
named <literal>.s.PGSQL.<replaceable>nnnn</replaceable>.lock</literal> will be
|
||
created in each of the <varname>unix_socket_directories</varname> directories.
|
||
Neither file should ever be removed manually.
|
||
For sockets in the abstract namespace, no lock file is created.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-unix-socket-group" xreflabel="unix_socket_group">
|
||
<term><varname>unix_socket_group</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>unix_socket_group</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the owning group of the Unix-domain socket(s). (The owning
|
||
user of the sockets is always the user that starts the
|
||
server.) In combination with the parameter
|
||
<varname>unix_socket_permissions</varname> this can be used as
|
||
an additional access control mechanism for Unix-domain connections.
|
||
By default this is the empty string, which uses the default
|
||
group of the server user. This parameter can only be set at
|
||
server start.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter is not supported on Windows. Any setting will be
|
||
ignored. Also, sockets in the abstract namespace have no file owner,
|
||
so this setting is also ignored in that case.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-unix-socket-permissions" xreflabel="unix_socket_permissions">
|
||
<term><varname>unix_socket_permissions</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>unix_socket_permissions</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the access permissions of the Unix-domain socket(s). Unix-domain
|
||
sockets use the usual Unix file system permission set.
|
||
The parameter value is expected to be a numeric mode
|
||
specified in the format accepted by the
|
||
<function>chmod</function> and <function>umask</function>
|
||
system calls. (To use the customary octal format the number
|
||
must start with a <literal>0</literal> (zero).)
|
||
</para>
|
||
|
||
<para>
|
||
The default permissions are <literal>0777</literal>, meaning
|
||
anyone can connect. Reasonable alternatives are
|
||
<literal>0770</literal> (only user and group, see also
|
||
<varname>unix_socket_group</varname>) and <literal>0700</literal>
|
||
(only user). (Note that for a Unix-domain socket, only write
|
||
permission matters, so there is no point in setting or revoking
|
||
read or execute permissions.)
|
||
</para>
|
||
|
||
<para>
|
||
This access control mechanism is independent of the one
|
||
described in <xref linkend="client-authentication"/>.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter is irrelevant on systems, notably Solaris as of Solaris
|
||
10, that ignore socket permissions entirely. There, one can achieve a
|
||
similar effect by pointing <varname>unix_socket_directories</varname> to a
|
||
directory having search permission limited to the desired audience.
|
||
</para>
|
||
|
||
<para>
|
||
Sockets in the abstract namespace have no file permissions, so this
|
||
setting is also ignored in that case.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-bonjour" xreflabel="bonjour">
|
||
<term><varname>bonjour</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>bonjour</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables advertising the server's existence via
|
||
<productname>Bonjour</productname>. The default is off.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-bonjour-name" xreflabel="bonjour_name">
|
||
<term><varname>bonjour_name</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>bonjour_name</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the <productname>Bonjour</productname> service
|
||
name. The computer name is used if this parameter is set to the
|
||
empty string <literal>''</literal> (which is the default). This parameter is
|
||
ignored if the server was not compiled with
|
||
<productname>Bonjour</productname> support.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-tcp-settings">
|
||
<title>TCP Settings</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-tcp-keepalives-idle" xreflabel="tcp_keepalives_idle">
|
||
<term><varname>tcp_keepalives_idle</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>tcp_keepalives_idle</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of time with no network activity after which
|
||
the operating system should send a TCP keepalive message to the client.
|
||
If this value is specified without units, it is taken as seconds.
|
||
A value of 0 (the default) selects the operating system's default.
|
||
On Windows, setting a value of 0 will set this parameter to 2 hours,
|
||
since Windows does not provide a way to read the system default value.
|
||
This parameter is supported only on systems that support
|
||
<symbol>TCP_KEEPIDLE</symbol> or an equivalent socket option, and on
|
||
Windows; on other systems, it must be zero.
|
||
In sessions connected via a Unix-domain socket, this parameter is
|
||
ignored and always reads as zero.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-tcp-keepalives-interval" xreflabel="tcp_keepalives_interval">
|
||
<term><varname>tcp_keepalives_interval</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>tcp_keepalives_interval</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of time after which a TCP keepalive message
|
||
that has not been acknowledged by the client should be retransmitted.
|
||
If this value is specified without units, it is taken as seconds.
|
||
A value of 0 (the default) selects the operating system's default.
|
||
On Windows, setting a value of 0 will set this parameter to 1 second,
|
||
since Windows does not provide a way to read the system default value.
|
||
This parameter is supported only on systems that support
|
||
<symbol>TCP_KEEPINTVL</symbol> or an equivalent socket option, and on
|
||
Windows; on other systems, it must be zero.
|
||
In sessions connected via a Unix-domain socket, this parameter is
|
||
ignored and always reads as zero.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-tcp-keepalives-count" xreflabel="tcp_keepalives_count">
|
||
<term><varname>tcp_keepalives_count</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>tcp_keepalives_count</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of TCP keepalive messages that can be lost before
|
||
the server's connection to the client is considered dead.
|
||
A value of 0 (the default) selects the operating system's default.
|
||
This parameter is supported only on systems that support
|
||
<symbol>TCP_KEEPCNT</symbol> or an equivalent socket option (which does not include Windows);
|
||
on other systems, it must be zero.
|
||
In sessions connected via a Unix-domain socket, this parameter is
|
||
ignored and always reads as zero.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-tcp-user-timeout" xreflabel="tcp_user_timeout">
|
||
<term><varname>tcp_user_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>tcp_user_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of time that transmitted data may
|
||
remain unacknowledged before the TCP connection is forcibly closed.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
A value of 0 (the default) selects the operating system's default.
|
||
This parameter is supported only on systems that support
|
||
<symbol>TCP_USER_TIMEOUT</symbol> (which does not include Windows); on other systems, it must be zero.
|
||
In sessions connected via a Unix-domain socket, this parameter is
|
||
ignored and always reads as zero.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-client-connection-check-interval" xreflabel="client_connection_check_interval">
|
||
<term><varname>client_connection_check_interval</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>client_connection_check_interval</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the time interval between optional checks that the client is still
|
||
connected, while running queries. The check is performed by polling
|
||
the socket, and allows long running queries to be aborted sooner if
|
||
the kernel reports that the connection is closed.
|
||
</para>
|
||
<para>
|
||
This option relies on kernel events exposed by Linux, macOS, illumos
|
||
and the BSD family of operating systems, and is not currently available
|
||
on other systems.
|
||
</para>
|
||
<para>
|
||
If the value is specified without units, it is taken as milliseconds.
|
||
The default value is <literal>0</literal>, which disables connection
|
||
checks. Without connection checks, the server will detect the loss of
|
||
the connection only at the next interaction with the socket, when it
|
||
waits for, receives or sends data.
|
||
</para>
|
||
<para>
|
||
For the kernel itself to detect lost TCP connections reliably and within
|
||
a known timeframe in all scenarios including network failure, it may
|
||
also be necessary to adjust the TCP keepalive settings of the operating
|
||
system, or the <xref linkend="guc-tcp-keepalives-idle"/>,
|
||
<xref linkend="guc-tcp-keepalives-interval"/> and
|
||
<xref linkend="guc-tcp-keepalives-count"/> settings of
|
||
<productname>PostgreSQL</productname>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-connection-authentication">
|
||
<title>Authentication</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-authentication-timeout" xreflabel="authentication_timeout">
|
||
<term><varname>authentication_timeout</varname> (<type>integer</type>)
|
||
<indexterm><primary>timeout</primary><secondary>client authentication</secondary></indexterm>
|
||
<indexterm><primary>client authentication</primary><secondary>timeout during</secondary></indexterm>
|
||
<indexterm>
|
||
<primary><varname>authentication_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
|
||
<listitem>
|
||
<para>
|
||
Maximum amount of time allowed to complete client authentication. If a
|
||
would-be client has not completed the authentication protocol in
|
||
this much time, the server closes the connection. This prevents
|
||
hung clients from occupying a connection indefinitely.
|
||
If this value is specified without units, it is taken as seconds.
|
||
The default is one minute (<literal>1m</literal>).
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-password-encryption" xreflabel="password_encryption">
|
||
<term><varname>password_encryption</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>password_encryption</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When a password is specified in <xref linkend="sql-createrole"/> or
|
||
<xref linkend="sql-alterrole"/>, this parameter determines the
|
||
algorithm to use to encrypt the password. Possible values are
|
||
<literal>scram-sha-256</literal>, which will encrypt the password with
|
||
SCRAM-SHA-256, and <literal>md5</literal>, which stores the password
|
||
as an MD5 hash. The default is <literal>scram-sha-256</literal>.
|
||
</para>
|
||
<para>
|
||
Note that older clients might lack support for the SCRAM authentication
|
||
mechanism, and hence not work with passwords encrypted with
|
||
SCRAM-SHA-256. See <xref linkend="auth-password"/> for more details.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-scram-iterations" xreflabel="scram_iterations">
|
||
<term><varname>scram_iterations</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>scram_iterations</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The number of computational iterations to be performed when encrypting
|
||
a password using SCRAM-SHA-256. The default is <literal>4096</literal>.
|
||
A higher number of iterations provides additional protection against
|
||
brute-force attacks on stored passwords, but makes authentication
|
||
slower. Changing the value has no effect on existing passwords
|
||
encrypted with SCRAM-SHA-256 as the iteration count is fixed at the
|
||
time of encryption. In order to make use of a changed value, a new
|
||
password must be set.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-krb-server-keyfile" xreflabel="krb_server_keyfile">
|
||
<term><varname>krb_server_keyfile</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>krb_server_keyfile</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the location of the server's Kerberos key file. The default is
|
||
<filename>FILE:/usr/local/pgsql/etc/krb5.keytab</filename>
|
||
(where the directory part is whatever was specified
|
||
as <varname>sysconfdir</varname> at build time; use
|
||
<literal>pg_config --sysconfdir</literal> to determine that).
|
||
If this parameter is set to an empty string, it is ignored and a
|
||
system-dependent default is used.
|
||
This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
See <xref linkend="gssapi-auth"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-krb-caseins-users" xreflabel="krb_caseins_users">
|
||
<term><varname>krb_caseins_users</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>krb_caseins_users</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets whether GSSAPI user names should be treated
|
||
case-insensitively.
|
||
The default is <literal>off</literal> (case sensitive). This parameter can only be
|
||
set in the <filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-gss-accept-delegation" xreflabel="gss_accept_delegation">
|
||
<term><varname>gss_accept_delegation</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>gss_accept_delegation</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets whether GSSAPI delegation should be accepted from the client.
|
||
The default is <literal>off</literal> meaning credentials from the client will
|
||
<emphasis>not</emphasis> be accepted. Changing this to <literal>on</literal> will make the server
|
||
accept credentials delegated to it from the client. This parameter can only be
|
||
set in the <filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-connection-ssl">
|
||
<title>SSL</title>
|
||
|
||
<para>
|
||
See <xref linkend="ssl-tcp"/> for more information about setting up
|
||
<acronym>SSL</acronym>. The configuration parameters for controlling
|
||
transfer encryption using <acronym>TLS</acronym> protocols are named
|
||
<literal>ssl</literal> for historic reasons, even though support for
|
||
the <acronym>SSL</acronym> protocol has been deprecated.
|
||
<acronym>SSL</acronym> is in this context used interchangeably with
|
||
<acronym>TLS</acronym>.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-ssl" xreflabel="ssl">
|
||
<term><varname>ssl</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables <acronym>SSL</acronym> connections.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
The default is <literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-ca-file" xreflabel="ssl_ca_file">
|
||
<term><varname>ssl_ca_file</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_ca_file</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the file containing the SSL server certificate
|
||
authority (CA).
|
||
Relative paths are relative to the data directory.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
The default is empty, meaning no CA file is loaded,
|
||
and client certificate verification is not performed.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-cert-file" xreflabel="ssl_cert_file">
|
||
<term><varname>ssl_cert_file</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_cert_file</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the file containing the SSL server certificate.
|
||
Relative paths are relative to the data directory.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
The default is <filename>server.crt</filename>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-crl-file" xreflabel="ssl_crl_file">
|
||
<term><varname>ssl_crl_file</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_crl_file</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the file containing the SSL client certificate
|
||
revocation list (CRL).
|
||
Relative paths are relative to the data directory.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
The default is empty, meaning no CRL file is loaded (unless
|
||
<xref linkend="guc-ssl-crl-dir"/> is set).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-crl-dir" xreflabel="ssl_crl_dir">
|
||
<term><varname>ssl_crl_dir</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_crl_dir</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the directory containing the SSL client
|
||
certificate revocation list (CRL). Relative paths are relative to the
|
||
data directory. This parameter can only be set in
|
||
the <filename>postgresql.conf</filename> file or on the server command
|
||
line. The default is empty, meaning no CRLs are used (unless
|
||
<xref linkend="guc-ssl-crl-file"/> is set).
|
||
</para>
|
||
|
||
<para>
|
||
The directory needs to be prepared with the
|
||
<productname>OpenSSL</productname> command
|
||
<literal>openssl rehash</literal> or <literal>c_rehash</literal>. See
|
||
its documentation for details.
|
||
</para>
|
||
|
||
<para>
|
||
When using this setting, CRLs in the specified directory are loaded
|
||
on-demand at connection time. New CRLs can be added to the directory
|
||
and will be used immediately. This is unlike <xref
|
||
linkend="guc-ssl-crl-file"/>, which causes the CRL in the file to be
|
||
loaded at server start time or when the configuration is reloaded.
|
||
Both settings can be used together.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-key-file" xreflabel="ssl_key_file">
|
||
<term><varname>ssl_key_file</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_key_file</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the file containing the SSL server private key.
|
||
Relative paths are relative to the data directory.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
The default is <filename>server.key</filename>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-ciphers" xreflabel="ssl_ciphers">
|
||
<term><varname>ssl_ciphers</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_ciphers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a list of <acronym>SSL</acronym> cipher suites that are
|
||
allowed to be used by SSL connections. See the
|
||
<citerefentry><refentrytitle>ciphers</refentrytitle></citerefentry>
|
||
manual page in the <productname>OpenSSL</productname> package for the
|
||
syntax of this setting and a list of supported values. Only
|
||
connections using TLS version 1.2 and lower are affected. There is
|
||
currently no setting that controls the cipher choices used by TLS
|
||
version 1.3 connections. The default value is
|
||
<literal>HIGH:MEDIUM:+3DES:!aNULL</literal>. The default is usually a
|
||
reasonable choice unless you have specific security requirements.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command
|
||
line.
|
||
</para>
|
||
|
||
<para>
|
||
Explanation of the default value:
|
||
<variablelist>
|
||
<varlistentry id="guc-ssl-ciphers-high">
|
||
<term><literal>HIGH</literal></term>
|
||
<listitem>
|
||
<para>
|
||
Cipher suites that use ciphers from <literal>HIGH</literal> group (e.g.,
|
||
AES, Camellia, 3DES)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-ciphers-medium">
|
||
<term><literal>MEDIUM</literal></term>
|
||
<listitem>
|
||
<para>
|
||
Cipher suites that use ciphers from <literal>MEDIUM</literal> group
|
||
(e.g., RC4, SEED)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-ciphers-plus-3des">
|
||
<term><literal>+3DES</literal></term>
|
||
<listitem>
|
||
<para>
|
||
The <productname>OpenSSL</productname> default order for
|
||
<literal>HIGH</literal> is problematic because it orders 3DES
|
||
higher than AES128. This is wrong because 3DES offers less
|
||
security than AES128, and it is also much slower.
|
||
<literal>+3DES</literal> reorders it after all other
|
||
<literal>HIGH</literal> and <literal>MEDIUM</literal> ciphers.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-ciphers-not-anull">
|
||
<term><literal>!aNULL</literal></term>
|
||
<listitem>
|
||
<para>
|
||
Disables anonymous cipher suites that do no authentication. Such
|
||
cipher suites are vulnerable to <acronym>MITM</acronym> attacks and
|
||
therefore should not be used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
|
||
<para>
|
||
Available cipher suite details will vary across
|
||
<productname>OpenSSL</productname> versions. Use the command
|
||
<literal>openssl ciphers -v 'HIGH:MEDIUM:+3DES:!aNULL'</literal> to
|
||
see actual details for the currently installed
|
||
<productname>OpenSSL</productname> version. Note that this list is
|
||
filtered at run time based on the server key type.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-prefer-server-ciphers" xreflabel="ssl_prefer_server_ciphers">
|
||
<term><varname>ssl_prefer_server_ciphers</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_prefer_server_ciphers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies whether to use the server's SSL cipher preferences, rather
|
||
than the client's.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
The default is <literal>on</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
Older PostgreSQL versions do not have this setting and always use the
|
||
client's preferences. This setting is mainly for backward
|
||
compatibility with those versions. Using the server's preferences is
|
||
usually better because it is more likely that the server is appropriately
|
||
configured.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-ecdh-curve" xreflabel="ssl_ecdh_curve">
|
||
<term><varname>ssl_ecdh_curve</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_ecdh_curve</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the curve to use in <acronym>ECDH</acronym> key
|
||
exchange. It needs to be supported by all clients that connect.
|
||
It does not need to be the same curve used by the server's Elliptic
|
||
Curve key.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
The default is <literal>prime256v1</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
<productname>OpenSSL</productname> names for the most common curves
|
||
are:
|
||
<literal>prime256v1</literal> (NIST P-256),
|
||
<literal>secp384r1</literal> (NIST P-384),
|
||
<literal>secp521r1</literal> (NIST P-521).
|
||
The full list of available curves can be shown with the command
|
||
<command>openssl ecparam -list_curves</command>. Not all of them
|
||
are usable in <acronym>TLS</acronym> though.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-min-protocol-version" xreflabel="ssl_min_protocol_version">
|
||
<term><varname>ssl_min_protocol_version</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_min_protocol_version</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the minimum SSL/TLS protocol version to use. Valid values are
|
||
currently: <literal>TLSv1</literal>, <literal>TLSv1.1</literal>,
|
||
<literal>TLSv1.2</literal>, <literal>TLSv1.3</literal>. Older
|
||
versions of the <productname>OpenSSL</productname> library do not
|
||
support all values; an error will be raised if an unsupported setting
|
||
is chosen. Protocol versions before TLS 1.0, namely SSL version 2 and
|
||
3, are always disabled.
|
||
</para>
|
||
|
||
<para>
|
||
The default is <literal>TLSv1.2</literal>, which satisfies industry
|
||
best practices as of this writing.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-max-protocol-version" xreflabel="ssl_max_protocol_version">
|
||
<term><varname>ssl_max_protocol_version</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_max_protocol_version</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum SSL/TLS protocol version to use. Valid values are as
|
||
for <xref linkend="guc-ssl-min-protocol-version"/>, with addition of
|
||
an empty string, which allows any protocol version. The default is to
|
||
allow any version. Setting the maximum protocol version is mainly
|
||
useful for testing or if some component has issues working with a
|
||
newer protocol.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-dh-params-file" xreflabel="ssl_dh_params_file">
|
||
<term><varname>ssl_dh_params_file</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_dh_params_file</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the file containing Diffie-Hellman parameters
|
||
used for so-called ephemeral DH family of SSL ciphers. The default is
|
||
empty, in which case compiled-in default DH parameters used. Using
|
||
custom DH parameters reduces the exposure if an attacker manages to
|
||
crack the well-known compiled-in DH parameters. You can create your own
|
||
DH parameters file with the command
|
||
<command>openssl dhparam -out dhparams.pem 2048</command>.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-passphrase-command" xreflabel="ssl_passphrase_command">
|
||
<term><varname>ssl_passphrase_command</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_passphrase_command</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets an external command to be invoked when a passphrase for
|
||
decrypting an SSL file such as a private key needs to be obtained. By
|
||
default, this parameter is empty, which means the built-in prompting
|
||
mechanism is used.
|
||
</para>
|
||
<para>
|
||
The command must print the passphrase to the standard output and exit
|
||
with code 0. In the parameter value, <literal>%p</literal> is
|
||
replaced by a prompt string. (Write <literal>%%</literal> for a
|
||
literal <literal>%</literal>.) Note that the prompt string will
|
||
probably contain whitespace, so be sure to quote adequately. A single
|
||
newline is stripped from the end of the output if present.
|
||
</para>
|
||
<para>
|
||
The command does not actually have to prompt the user for a
|
||
passphrase. It can read it from a file, obtain it from a keychain
|
||
facility, or similar. It is up to the user to make sure the chosen
|
||
mechanism is adequately secure.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-passphrase-command-supports-reload" xreflabel="ssl_passphrase_command_supports_reload">
|
||
<term><varname>ssl_passphrase_command_supports_reload</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_passphrase_command_supports_reload</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter determines whether the passphrase command set by
|
||
<varname>ssl_passphrase_command</varname> will also be called during a
|
||
configuration reload if a key file needs a passphrase. If this
|
||
parameter is off (the default), then
|
||
<varname>ssl_passphrase_command</varname> will be ignored during a
|
||
reload and the SSL configuration will not be reloaded if a passphrase
|
||
is needed. That setting is appropriate for a command that requires a
|
||
TTY for prompting, which might not be available when the server is
|
||
running. Setting this parameter to on might be appropriate if the
|
||
passphrase is obtained from a file, for example.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-resource">
|
||
<title>Resource Consumption</title>
|
||
|
||
<sect2 id="runtime-config-resource-memory">
|
||
<title>Memory</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-shared-buffers" xreflabel="shared_buffers">
|
||
<term><varname>shared_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>shared_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the amount of memory the database server uses for shared
|
||
memory buffers. The default is typically 128 megabytes
|
||
(<literal>128MB</literal>), but might be less if your kernel settings will
|
||
not support it (as determined during <application>initdb</application>).
|
||
This setting must be at least 128 kilobytes. However,
|
||
settings significantly higher than the minimum are usually needed
|
||
for good performance.
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
(Non-default values of <symbol>BLCKSZ</symbol> change the minimum
|
||
value.)
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
|
||
<para>
|
||
If you have a dedicated database server with 1GB or more of RAM, a
|
||
reasonable starting value for <varname>shared_buffers</varname> is 25%
|
||
of the memory in your system. There are some workloads where even
|
||
larger settings for <varname>shared_buffers</varname> are effective, but
|
||
because <productname>PostgreSQL</productname> also relies on the
|
||
operating system cache, it is unlikely that an allocation of more than
|
||
40% of RAM to <varname>shared_buffers</varname> will work better than a
|
||
smaller amount. Larger settings for <varname>shared_buffers</varname>
|
||
usually require a corresponding increase in
|
||
<varname>max_wal_size</varname>, in order to spread out the
|
||
process of writing large quantities of new or changed data over a
|
||
longer period of time.
|
||
</para>
|
||
|
||
<para>
|
||
On systems with less than 1GB of RAM, a smaller percentage of RAM is
|
||
appropriate, so as to leave adequate space for the operating system.
|
||
</para>
|
||
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-huge-pages" xreflabel="huge_pages">
|
||
<term><varname>huge_pages</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>huge_pages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls whether huge pages are requested for the main shared memory
|
||
area. Valid values are <literal>try</literal> (the default),
|
||
<literal>on</literal>, and <literal>off</literal>. With
|
||
<varname>huge_pages</varname> set to <literal>try</literal>, the
|
||
server will try to request huge pages, but fall back to the default if
|
||
that fails. With <literal>on</literal>, failure to request huge pages
|
||
will prevent the server from starting up. With <literal>off</literal>,
|
||
huge pages will not be requested. The actual state of huge pages is
|
||
indicated by the server variable
|
||
<xref linkend="guc-huge-pages-status"/>.
|
||
</para>
|
||
|
||
<para>
|
||
At present, this setting is supported only on Linux and Windows. The
|
||
setting is ignored on other systems when set to
|
||
<literal>try</literal>. On Linux, it is only supported when
|
||
<varname>shared_memory_type</varname> is set to <literal>mmap</literal>
|
||
(the default).
|
||
</para>
|
||
|
||
<para>
|
||
The use of huge pages results in smaller page tables and less CPU time
|
||
spent on memory management, increasing performance. For more details about
|
||
using huge pages on Linux, see <xref linkend="linux-huge-pages"/>.
|
||
</para>
|
||
|
||
<para>
|
||
Huge pages are known as large pages on Windows. To use them, you need to
|
||
assign the user right <quote>Lock pages in memory</quote> to the Windows user account
|
||
that runs <productname>PostgreSQL</productname>.
|
||
You can use Windows Group Policy tool (gpedit.msc) to assign the user right
|
||
<quote>Lock pages in memory</quote>.
|
||
To start the database server on the command prompt as a standalone process,
|
||
not as a Windows service, the command prompt must be run as an administrator or
|
||
User Access Control (UAC) must be disabled. When the UAC is enabled, the normal
|
||
command prompt revokes the user right <quote>Lock pages in memory</quote> when started.
|
||
</para>
|
||
|
||
<para>
|
||
Note that this setting only affects the main shared memory area.
|
||
Operating systems such as Linux, FreeBSD, and Illumos can also use
|
||
huge pages (also known as <quote>super</quote> pages or
|
||
<quote>large</quote> pages) automatically for normal memory
|
||
allocation, without an explicit request from
|
||
<productname>PostgreSQL</productname>. On Linux, this is called
|
||
<quote>transparent huge pages</quote><indexterm><primary>transparent
|
||
huge pages</primary></indexterm> (THP). That feature has been known to
|
||
cause performance degradation with
|
||
<productname>PostgreSQL</productname> for some users on some Linux
|
||
versions, so its use is currently discouraged (unlike explicit use of
|
||
<varname>huge_pages</varname>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-huge-page-size" xreflabel="huge_page_size">
|
||
<term><varname>huge_page_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>huge_page_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls the size of huge pages, when they are enabled with
|
||
<xref linkend="guc-huge-pages"/>.
|
||
The default is zero (<literal>0</literal>).
|
||
When set to <literal>0</literal>, the default huge page size on the
|
||
system will be used. This parameter can only be set at server start.
|
||
</para>
|
||
<para>
|
||
Some commonly available page sizes on modern 64 bit server architectures include:
|
||
<literal>2MB</literal> and <literal>1GB</literal> (Intel and AMD), <literal>16MB</literal> and
|
||
<literal>16GB</literal> (IBM POWER), and <literal>64kB</literal>, <literal>2MB</literal>,
|
||
<literal>32MB</literal> and <literal>1GB</literal> (ARM). For more information
|
||
about usage and support, see <xref linkend="linux-huge-pages"/>.
|
||
</para>
|
||
<para>
|
||
Non-default settings are currently supported only on Linux.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-temp-buffers" xreflabel="temp_buffers">
|
||
<term><varname>temp_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>temp_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum amount of memory used for temporary buffers within
|
||
each database session. These are session-local buffers used only
|
||
for access to temporary tables.
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default is eight megabytes (<literal>8MB</literal>).
|
||
(If <symbol>BLCKSZ</symbol> is not 8kB, the default value scales
|
||
proportionally to it.)
|
||
This setting can be changed within individual
|
||
sessions, but only before the first use of temporary tables
|
||
within the session; subsequent attempts to change the value will
|
||
have no effect on that session.
|
||
</para>
|
||
|
||
<para>
|
||
A session will allocate temporary buffers as needed up to the limit
|
||
given by <varname>temp_buffers</varname>. The cost of setting a large
|
||
value in sessions that do not actually need many temporary
|
||
buffers is only a buffer descriptor, or about 64 bytes, per
|
||
increment in <varname>temp_buffers</varname>. However if a buffer is
|
||
actually used an additional 8192 bytes will be consumed for it
|
||
(or in general, <symbol>BLCKSZ</symbol> bytes).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-prepared-transactions" xreflabel="max_prepared_transactions">
|
||
<term><varname>max_prepared_transactions</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_prepared_transactions</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum number of transactions that can be in the
|
||
<quote>prepared</quote> state simultaneously (see <xref
|
||
linkend="sql-prepare-transaction"/>).
|
||
Setting this parameter to zero (which is the default)
|
||
disables the prepared-transaction feature.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
|
||
<para>
|
||
If you are not planning to use prepared transactions, this parameter
|
||
should be set to zero to prevent accidental creation of prepared
|
||
transactions. If you are using prepared transactions, you will
|
||
probably want <varname>max_prepared_transactions</varname> to be at
|
||
least as large as <xref linkend="guc-max-connections"/>, so that every
|
||
session can have a prepared transaction pending.
|
||
</para>
|
||
|
||
<para>
|
||
When running a standby server, you must set this parameter to the
|
||
same or higher value than on the primary server. Otherwise, queries
|
||
will not be allowed in the standby server.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-work-mem" xreflabel="work_mem">
|
||
<term><varname>work_mem</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>work_mem</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the base maximum amount of memory to be used by a query operation
|
||
(such as a sort or hash table) before writing to temporary disk files.
|
||
If this value is specified without units, it is taken as kilobytes.
|
||
The default value is four megabytes (<literal>4MB</literal>).
|
||
Note that a complex query might perform several sort and hash
|
||
operations at the same time, with each operation generally being
|
||
allowed to use as much memory as this value specifies before
|
||
it starts
|
||
to write data into temporary files. Also, several running
|
||
sessions could be doing such operations concurrently.
|
||
Therefore, the total memory used could be many times the value
|
||
of <varname>work_mem</varname>; it is necessary to keep this
|
||
fact in mind when choosing the value. Sort operations are used
|
||
for <literal>ORDER BY</literal>, <literal>DISTINCT</literal>,
|
||
and merge joins.
|
||
Hash tables are used in hash joins, hash-based aggregation, memoize
|
||
nodes and hash-based processing of <literal>IN</literal> subqueries.
|
||
</para>
|
||
<para>
|
||
Hash-based operations are generally more sensitive to memory
|
||
availability than equivalent sort-based operations. The
|
||
memory limit for a hash table is computed by multiplying
|
||
<varname>work_mem</varname> by
|
||
<varname>hash_mem_multiplier</varname>. This makes it
|
||
possible for hash-based operations to use an amount of memory
|
||
that exceeds the usual <varname>work_mem</varname> base
|
||
amount.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-hash-mem-multiplier" xreflabel="hash_mem_multiplier">
|
||
<term><varname>hash_mem_multiplier</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>hash_mem_multiplier</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Used to compute the maximum amount of memory that hash-based
|
||
operations can use. The final limit is determined by
|
||
multiplying <varname>work_mem</varname> by
|
||
<varname>hash_mem_multiplier</varname>. The default value is
|
||
2.0, which makes hash-based operations use twice the usual
|
||
<varname>work_mem</varname> base amount.
|
||
</para>
|
||
<para>
|
||
Consider increasing <varname>hash_mem_multiplier</varname> in
|
||
environments where spilling by query operations is a regular
|
||
occurrence, especially when simply increasing
|
||
<varname>work_mem</varname> results in memory pressure (memory
|
||
pressure typically takes the form of intermittent out of
|
||
memory errors). The default setting of 2.0 is often effective with
|
||
mixed workloads. Higher settings in the range of 2.0 - 8.0 or
|
||
more may be effective in environments where
|
||
<varname>work_mem</varname> has already been increased to 40MB
|
||
or more.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-maintenance-work-mem" xreflabel="maintenance_work_mem">
|
||
<term><varname>maintenance_work_mem</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>maintenance_work_mem</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum amount of memory to be used by maintenance
|
||
operations, such as <command>VACUUM</command>, <command>CREATE
|
||
INDEX</command>, and <command>ALTER TABLE ADD FOREIGN KEY</command>.
|
||
If this value is specified without units, it is taken as kilobytes.
|
||
It defaults
|
||
to 64 megabytes (<literal>64MB</literal>). Since only one of these
|
||
operations can be executed at a time by a database session, and
|
||
an installation normally doesn't have many of them running
|
||
concurrently, it's safe to set this value significantly larger
|
||
than <varname>work_mem</varname>. Larger settings might improve
|
||
performance for vacuuming and for restoring database dumps.
|
||
</para>
|
||
<para>
|
||
Note that when autovacuum runs, up to
|
||
<xref linkend="guc-autovacuum-max-workers"/> times this memory
|
||
may be allocated, so be careful not to set the default value
|
||
too high. It may be useful to control for this by separately
|
||
setting <xref linkend="guc-autovacuum-work-mem"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-work-mem" xreflabel="autovacuum_work_mem">
|
||
<term><varname>autovacuum_work_mem</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_work_mem</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum amount of memory to be used by each
|
||
autovacuum worker process.
|
||
If this value is specified without units, it is taken as kilobytes.
|
||
It defaults to -1, indicating that
|
||
the value of <xref linkend="guc-maintenance-work-mem"/> should
|
||
be used instead. The setting has no effect on the behavior of
|
||
<command>VACUUM</command> when run in other contexts.
|
||
This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command
|
||
line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-buffer-usage-limit" xreflabel="vacuum_buffer_usage_limit">
|
||
<term>
|
||
<varname>vacuum_buffer_usage_limit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_buffer_usage_limit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the size of the
|
||
<glossterm linkend="glossary-buffer-access-strategy">Buffer Access Strategy</glossterm>
|
||
used by the <command>VACUUM</command> and <command>ANALYZE</command>
|
||
commands. A setting of <literal>0</literal> will allow the operation
|
||
to use any number of <varname>shared_buffers</varname>. Otherwise
|
||
valid sizes range from <literal>128 kB</literal> to
|
||
<literal>16 GB</literal>. If the specified size would exceed 1/8 the
|
||
size of <varname>shared_buffers</varname>, the size is silently capped
|
||
to that value. The default value is <literal>2MB</literal>. If
|
||
this value is specified without units, it is taken as kilobytes. This
|
||
parameter can be set at any time. It can be overridden for
|
||
<xref linkend="sql-vacuum"/> and <xref linkend="sql-analyze"/>
|
||
when passing the <option>BUFFER_USAGE_LIMIT</option> option. Higher
|
||
settings can allow <command>VACUUM</command> and
|
||
<command>ANALYZE</command> to run more quickly, but having too large a
|
||
setting may cause too many other useful pages to be evicted from
|
||
shared buffers.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-logical-decoding-work-mem" xreflabel="logical_decoding_work_mem">
|
||
<term><varname>logical_decoding_work_mem</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>logical_decoding_work_mem</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum amount of memory to be used by logical decoding,
|
||
before some of the decoded changes are written to local disk. This
|
||
limits the amount of memory used by logical streaming replication
|
||
connections. It defaults to 64 megabytes (<literal>64MB</literal>).
|
||
Since each replication connection only uses a single buffer of this size,
|
||
and an installation normally doesn't have many such connections
|
||
concurrently (as limited by <varname>max_wal_senders</varname>), it's
|
||
safe to set this value significantly higher than <varname>work_mem</varname>,
|
||
reducing the amount of decoded changes written to disk.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-commit-timestamp-buffers" xreflabel="commit_timestamp_buffers">
|
||
<term><varname>commit_timestamp_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>commit_timestamp_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of memory to use to cache the contents of
|
||
<literal>pg_commit_ts</literal> (see
|
||
<xref linkend="pgdata-contents-table"/>).
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default value is <literal>0</literal>, which requests
|
||
<varname>shared_buffers</varname>/512 up to 1024 blocks,
|
||
but not fewer than 16 blocks.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-multixact-member-buffers" xreflabel="multixact_member_buffers">
|
||
<term><varname>multixact_member_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>multixact_member_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of shared memory to use to cache the contents
|
||
of <literal>pg_multixact/members</literal> (see
|
||
<xref linkend="pgdata-contents-table"/>).
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default value is <literal>32</literal>.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-multixact-offset-buffers" xreflabel="multixact_offset_buffers">
|
||
<term><varname>multixact_offset_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>multixact_offset_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of shared memory to use to cache the contents
|
||
of <literal>pg_multixact/offsets</literal> (see
|
||
<xref linkend="pgdata-contents-table"/>).
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default value is <literal>16</literal>.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-notify-buffers" xreflabel="notify_buffers">
|
||
<term><varname>notify_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>notify_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of shared memory to use to cache the contents
|
||
of <literal>pg_notify</literal> (see
|
||
<xref linkend="pgdata-contents-table"/>).
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default value is <literal>16</literal>.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-serializable-buffers" xreflabel="serializable_buffers">
|
||
<term><varname>serializable_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>serializable_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of shared memory to use to cache the contents
|
||
of <literal>pg_serial</literal> (see
|
||
<xref linkend="pgdata-contents-table"/>).
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default value is <literal>32</literal>.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-subtransaction-buffers" xreflabel="subtransaction_buffers">
|
||
<term><varname>subtransaction_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>subtransaction_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of shared memory to use to cache the contents
|
||
of <literal>pg_subtrans</literal> (see
|
||
<xref linkend="pgdata-contents-table"/>).
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default value is <literal>0</literal>, which requests
|
||
<varname>shared_buffers</varname>/512 up to 1024 blocks,
|
||
but not fewer than 16 blocks.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-transaction-buffers" xreflabel="transaction_buffers">
|
||
<term><varname>transaction_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>transaction_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of shared memory to use to cache the contents
|
||
of <literal>pg_xact</literal> (see
|
||
<xref linkend="pgdata-contents-table"/>).
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default value is <literal>0</literal>, which requests
|
||
<varname>shared_buffers</varname>/512 up to 1024 blocks,
|
||
but not fewer than 16 blocks.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-stack-depth" xreflabel="max_stack_depth">
|
||
<term><varname>max_stack_depth</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_stack_depth</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum safe depth of the server's execution stack.
|
||
The ideal setting for this parameter is the actual stack size limit
|
||
enforced by the kernel (as set by <literal>ulimit -s</literal> or local
|
||
equivalent), less a safety margin of a megabyte or so. The safety
|
||
margin is needed because the stack depth is not checked in every
|
||
routine in the server, but only in key potentially-recursive routines.
|
||
If this value is specified without units, it is taken as kilobytes.
|
||
The default setting is two megabytes (<literal>2MB</literal>), which
|
||
is conservatively small and unlikely to risk crashes. However,
|
||
it might be too small to allow execution of complex functions.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<para>
|
||
Setting <varname>max_stack_depth</varname> higher than
|
||
the actual kernel limit will mean that a runaway recursive function
|
||
can crash an individual backend process. On platforms where
|
||
<productname>PostgreSQL</productname> can determine the kernel limit,
|
||
the server will not allow this variable to be set to an unsafe
|
||
value. However, not all platforms provide the information,
|
||
so caution is recommended in selecting a value.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-shared-memory-type" xreflabel="shared_memory_type">
|
||
<term><varname>shared_memory_type</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>shared_memory_type</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the shared memory implementation that the server
|
||
should use for the main shared memory region that holds
|
||
<productname>PostgreSQL</productname>'s shared buffers and other
|
||
shared data. Possible values are <literal>mmap</literal> (for
|
||
anonymous shared memory allocated using <function>mmap</function>),
|
||
<literal>sysv</literal> (for System V shared memory allocated via
|
||
<function>shmget</function>) and <literal>windows</literal> (for Windows
|
||
shared memory). Not all values are supported on all platforms; the
|
||
first supported option is the default for that platform. The use of
|
||
the <literal>sysv</literal> option, which is not the default on any
|
||
platform, is generally discouraged because it typically requires
|
||
non-default kernel settings to allow for large allocations (see <xref
|
||
linkend="sysvipc"/>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-dynamic-shared-memory-type" xreflabel="dynamic_shared_memory_type">
|
||
<term><varname>dynamic_shared_memory_type</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>dynamic_shared_memory_type</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the dynamic shared memory implementation that the server
|
||
should use. Possible values are <literal>posix</literal> (for POSIX shared
|
||
memory allocated using <literal>shm_open</literal>), <literal>sysv</literal>
|
||
(for System V shared memory allocated via <literal>shmget</literal>),
|
||
<literal>windows</literal> (for Windows shared memory),
|
||
and <literal>mmap</literal> (to simulate shared memory using
|
||
memory-mapped files stored in the data directory).
|
||
Not all values are supported on all platforms; the first supported
|
||
option is usually the default for that platform. The use of the
|
||
<literal>mmap</literal> option, which is not the default on any platform,
|
||
is generally discouraged because the operating system may write
|
||
modified pages back to disk repeatedly, increasing system I/O load;
|
||
however, it may be useful for debugging, when the
|
||
<literal>pg_dynshmem</literal> directory is stored on a RAM disk, or when
|
||
other shared memory facilities are not available.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-min-dynamic-shared-memory" xreflabel="min_dynamic_shared_memory">
|
||
<term><varname>min_dynamic_shared_memory</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>min_dynamic_shared_memory</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of memory that should be allocated at server
|
||
startup for use by parallel queries. When this memory region is
|
||
insufficient or exhausted by concurrent queries, new parallel queries
|
||
try to allocate extra shared memory temporarily from the operating
|
||
system using the method configured with
|
||
<varname>dynamic_shared_memory_type</varname>, which may be slower due
|
||
to memory management overheads. Memory that is allocated at startup
|
||
with <varname>min_dynamic_shared_memory</varname> is affected by
|
||
the <varname>huge_pages</varname> setting on operating systems where
|
||
that is supported, and may be more likely to benefit from larger pages
|
||
on operating systems where that is managed automatically.
|
||
The default value is <literal>0</literal> (none). This parameter can
|
||
only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-resource-disk">
|
||
<title>Disk</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-temp-file-limit" xreflabel="temp_file_limit">
|
||
<term><varname>temp_file_limit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>temp_file_limit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum amount of disk space that a process can use
|
||
for temporary files, such as sort and hash temporary files, or the
|
||
storage file for a held cursor. A transaction attempting to exceed
|
||
this limit will be canceled.
|
||
If this value is specified without units, it is taken as kilobytes.
|
||
<literal>-1</literal> (the default) means no limit.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
<para>
|
||
This setting constrains the total space used at any instant by all
|
||
temporary files used by a given <productname>PostgreSQL</productname> process.
|
||
It should be noted that disk space used for explicit temporary
|
||
tables, as opposed to temporary files used behind-the-scenes in query
|
||
execution, does <emphasis>not</emphasis> count against this limit.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-notify-queue-pages" xreflabel="max_notify_queue_pages">
|
||
<term><varname>max_notify_queue_pages</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_notify_queue_pages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum amount of allocated pages for
|
||
<xref linkend="sql-notify"/> / <xref linkend="sql-listen"/> queue.
|
||
The default value is 1048576. For 8 KB pages it allows to consume
|
||
up to 8 GB of disk space.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-resource-kernel">
|
||
<title>Kernel Resource Usage</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-max-files-per-process" xreflabel="max_files_per_process">
|
||
<term><varname>max_files_per_process</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_files_per_process</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum number of simultaneously open files allowed to each
|
||
server subprocess. The default is one thousand files. If the kernel is enforcing
|
||
a safe per-process limit, you don't need to worry about this setting.
|
||
But on some platforms (notably, most BSD systems), the kernel will
|
||
allow individual processes to open many more files than the system
|
||
can actually support if many processes all try to open
|
||
that many files. If you find yourself seeing <quote>Too many open
|
||
files</quote> failures, try reducing this setting.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-resource-vacuum-cost">
|
||
<title>Cost-based Vacuum Delay</title>
|
||
|
||
<para>
|
||
During the execution of <xref linkend="sql-vacuum"/>
|
||
and <xref linkend="sql-analyze"/>
|
||
commands, the system maintains an
|
||
internal counter that keeps track of the estimated cost of the
|
||
various I/O operations that are performed. When the accumulated
|
||
cost reaches a limit (specified by
|
||
<varname>vacuum_cost_limit</varname>), the process performing
|
||
the operation will sleep for a short period of time, as specified by
|
||
<varname>vacuum_cost_delay</varname>. Then it will reset the
|
||
counter and continue execution.
|
||
</para>
|
||
|
||
<para>
|
||
The intent of this feature is to allow administrators to reduce
|
||
the I/O impact of these commands on concurrent database
|
||
activity. There are many situations where it is not
|
||
important that maintenance commands like
|
||
<command>VACUUM</command> and <command>ANALYZE</command> finish
|
||
quickly; however, it is usually very important that these
|
||
commands do not significantly interfere with the ability of the
|
||
system to perform other database operations. Cost-based vacuum
|
||
delay provides a way for administrators to achieve this.
|
||
</para>
|
||
|
||
<para>
|
||
This feature is disabled by default for manually issued
|
||
<command>VACUUM</command> commands. To enable it, set the
|
||
<varname>vacuum_cost_delay</varname> variable to a nonzero
|
||
value.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-vacuum-cost-delay" xreflabel="vacuum_cost_delay">
|
||
<term><varname>vacuum_cost_delay</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_cost_delay</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The amount of time that the process will sleep
|
||
when the cost limit has been exceeded.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default value is zero, which disables the cost-based vacuum
|
||
delay feature. Positive values enable cost-based vacuuming.
|
||
</para>
|
||
|
||
<para>
|
||
When using cost-based vacuuming, appropriate values for
|
||
<varname>vacuum_cost_delay</varname> are usually quite small, perhaps
|
||
less than 1 millisecond. While <varname>vacuum_cost_delay</varname>
|
||
can be set to fractional-millisecond values, such delays may not be
|
||
measured accurately on older platforms. On such platforms,
|
||
increasing <command>VACUUM</command>'s throttled resource consumption
|
||
above what you get at 1ms will require changing the other vacuum cost
|
||
parameters. You should, nonetheless,
|
||
keep <varname>vacuum_cost_delay</varname> as small as your platform
|
||
will consistently measure; large delays are not helpful.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-cost-page-hit" xreflabel="vacuum_cost_page_hit">
|
||
<term><varname>vacuum_cost_page_hit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_cost_page_hit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The estimated cost for vacuuming a buffer found in the shared buffer
|
||
cache. It represents the cost to lock the buffer pool, lookup
|
||
the shared hash table and scan the content of the page. The
|
||
default value is one.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-cost-page-miss" xreflabel="vacuum_cost_page_miss">
|
||
<term><varname>vacuum_cost_page_miss</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_cost_page_miss</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The estimated cost for vacuuming a buffer that has to be read from
|
||
disk. This represents the effort to lock the buffer pool,
|
||
lookup the shared hash table, read the desired block in from
|
||
the disk and scan its content. The default value is 2.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-cost-page-dirty" xreflabel="vacuum_cost_page_dirty">
|
||
<term><varname>vacuum_cost_page_dirty</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_cost_page_dirty</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The estimated cost charged when vacuum modifies a block that was
|
||
previously clean. It represents the extra I/O required to
|
||
flush the dirty block out to disk again. The default value is
|
||
20.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-cost-limit" xreflabel="vacuum_cost_limit">
|
||
<term><varname>vacuum_cost_limit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_cost_limit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This is the accumulated cost that will cause the vacuuming process to sleep
|
||
for <varname>vacuum_cost_delay</varname>. The default is 200.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<note>
|
||
<para>
|
||
There are certain operations that hold critical locks and should
|
||
therefore complete as quickly as possible. Cost-based vacuum
|
||
delays do not occur during such operations. Therefore it is
|
||
possible that the cost accumulates far higher than the specified
|
||
limit. To avoid uselessly long delays in such cases, the actual
|
||
delay is calculated as <varname>vacuum_cost_delay</varname> *
|
||
<varname>accumulated_balance</varname> /
|
||
<varname>vacuum_cost_limit</varname> with a maximum of
|
||
<varname>vacuum_cost_delay</varname> * 4.
|
||
</para>
|
||
</note>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-resource-background-writer">
|
||
<title>Background Writer</title>
|
||
|
||
<para>
|
||
There is a separate server
|
||
process called the <firstterm>background writer</firstterm>, whose function
|
||
is to issue writes of <quote>dirty</quote> (new or modified) shared
|
||
buffers. When the number of clean shared buffers appears to be
|
||
insufficient, the background writer writes some dirty buffers to the
|
||
file system and marks them as clean. This reduces the likelihood
|
||
that server processes handling user queries will be unable to find
|
||
clean buffers and have to write dirty buffers themselves.
|
||
However, the background writer does cause a net overall
|
||
increase in I/O load, because while a repeatedly-dirtied page might
|
||
otherwise be written only once per checkpoint interval, the
|
||
background writer might write it several times as it is dirtied
|
||
in the same interval. The parameters discussed in this subsection
|
||
can be used to tune the behavior for local needs.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-bgwriter-delay" xreflabel="bgwriter_delay">
|
||
<term><varname>bgwriter_delay</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>bgwriter_delay</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the delay between activity rounds for the
|
||
background writer. In each round the writer issues writes
|
||
for some number of dirty buffers (controllable by the
|
||
following parameters). It then sleeps for
|
||
the length of <varname>bgwriter_delay</varname>, and repeats.
|
||
When there are no dirty buffers in the
|
||
buffer pool, though, it goes into a longer sleep regardless of
|
||
<varname>bgwriter_delay</varname>.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default value is 200
|
||
milliseconds (<literal>200ms</literal>). Note that on some systems, the
|
||
effective resolution of sleep delays is 10 milliseconds; setting
|
||
<varname>bgwriter_delay</varname> to a value that is not a multiple of 10
|
||
might have the same results as setting it to the next higher multiple
|
||
of 10. This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-bgwriter-lru-maxpages" xreflabel="bgwriter_lru_maxpages">
|
||
<term><varname>bgwriter_lru_maxpages</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>bgwriter_lru_maxpages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
In each round, no more than this many buffers will be written
|
||
by the background writer. Setting this to zero disables
|
||
background writing. (Note that checkpoints, which are managed by
|
||
a separate, dedicated auxiliary process, are unaffected.)
|
||
The default value is 100 buffers.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-bgwriter-lru-multiplier" xreflabel="bgwriter_lru_multiplier">
|
||
<term><varname>bgwriter_lru_multiplier</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>bgwriter_lru_multiplier</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The number of dirty buffers written in each round is based on the
|
||
number of new buffers that have been needed by server processes
|
||
during recent rounds. The average recent need is multiplied by
|
||
<varname>bgwriter_lru_multiplier</varname> to arrive at an estimate of the
|
||
number of buffers that will be needed during the next round. Dirty
|
||
buffers are written until there are that many clean, reusable buffers
|
||
available. (However, no more than <varname>bgwriter_lru_maxpages</varname>
|
||
buffers will be written per round.)
|
||
Thus, a setting of 1.0 represents a <quote>just in time</quote> policy
|
||
of writing exactly the number of buffers predicted to be needed.
|
||
Larger values provide some cushion against spikes in demand,
|
||
while smaller values intentionally leave writes to be done by
|
||
server processes.
|
||
The default is 2.0.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-bgwriter-flush-after" xreflabel="bgwriter_flush_after">
|
||
<term><varname>bgwriter_flush_after</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>bgwriter_flush_after</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Whenever more than this amount of data has
|
||
been written by the background writer, attempt to force the OS to issue these
|
||
writes to the underlying storage. Doing so will limit the amount of
|
||
dirty data in the kernel's page cache, reducing the likelihood of
|
||
stalls when an <function>fsync</function> is issued at the end of a checkpoint, or when
|
||
the OS writes data back in larger batches in the background. Often
|
||
that will result in greatly reduced transaction latency, but there
|
||
also are some cases, especially with workloads that are bigger than
|
||
<xref linkend="guc-shared-buffers"/>, but smaller than the OS's page
|
||
cache, where performance might degrade. This setting may have no
|
||
effect on some platforms.
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The valid range is between
|
||
<literal>0</literal>, which disables forced writeback, and
|
||
<literal>2MB</literal>. The default is <literal>512kB</literal> on Linux,
|
||
<literal>0</literal> elsewhere. (If <symbol>BLCKSZ</symbol> is not 8kB,
|
||
the default and maximum values scale proportionally to it.)
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
Smaller values of <varname>bgwriter_lru_maxpages</varname> and
|
||
<varname>bgwriter_lru_multiplier</varname> reduce the extra I/O load
|
||
caused by the background writer, but make it more likely that server
|
||
processes will have to issue writes for themselves, delaying interactive
|
||
queries.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-resource-async-behavior">
|
||
<title>Asynchronous Behavior</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-backend-flush-after" xreflabel="backend_flush_after">
|
||
<term><varname>backend_flush_after</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>backend_flush_after</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Whenever more than this amount of data has
|
||
been written by a single backend, attempt to force the OS to issue
|
||
these writes to the underlying storage. Doing so will limit the
|
||
amount of dirty data in the kernel's page cache, reducing the
|
||
likelihood of stalls when an <function>fsync</function> is issued at the end of a
|
||
checkpoint, or when the OS writes data back in larger batches in the
|
||
background. Often that will result in greatly reduced transaction
|
||
latency, but there also are some cases, especially with workloads
|
||
that are bigger than <xref linkend="guc-shared-buffers"/>, but smaller
|
||
than the OS's page cache, where performance might degrade. This
|
||
setting may have no effect on some platforms.
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The valid range is
|
||
between <literal>0</literal>, which disables forced writeback,
|
||
and <literal>2MB</literal>. The default is <literal>0</literal>, i.e., no
|
||
forced writeback. (If <symbol>BLCKSZ</symbol> is not 8kB,
|
||
the maximum value scales proportionally to it.)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-effective-io-concurrency" xreflabel="effective_io_concurrency">
|
||
<term><varname>effective_io_concurrency</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>effective_io_concurrency</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the number of concurrent disk I/O operations that
|
||
<productname>PostgreSQL</productname> expects can be executed
|
||
simultaneously. Raising this value will increase the number of I/O
|
||
operations that any individual <productname>PostgreSQL</productname> session
|
||
attempts to initiate in parallel. The allowed range is 1 to 1000,
|
||
or zero to disable issuance of asynchronous I/O requests. Currently,
|
||
this setting only affects bitmap heap scans.
|
||
</para>
|
||
|
||
<para>
|
||
For magnetic drives, a good starting point for this setting is the
|
||
number of separate
|
||
drives comprising a RAID 0 stripe or RAID 1 mirror being used for the
|
||
database. (For RAID 5 the parity drive should not be counted.)
|
||
However, if the database is often busy with multiple queries issued in
|
||
concurrent sessions, lower values may be sufficient to keep the disk
|
||
array busy. A value higher than needed to keep the disks busy will
|
||
only result in extra CPU overhead.
|
||
SSDs and other memory-based storage can often process many
|
||
concurrent requests, so the best value might be in the hundreds.
|
||
</para>
|
||
|
||
<para>
|
||
Asynchronous I/O depends on an effective <function>posix_fadvise</function>
|
||
function, which some operating systems lack. If the function is not
|
||
present then setting this parameter to anything but zero will result
|
||
in an error. On some operating systems (e.g., Solaris), the function
|
||
is present but does not actually do anything.
|
||
</para>
|
||
|
||
<para>
|
||
The default is 1 on supported systems, otherwise 0. This value can
|
||
be overridden for tables in a particular tablespace by setting the
|
||
tablespace parameter of the same name (see
|
||
<xref linkend="sql-altertablespace"/>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-maintenance-io-concurrency" xreflabel="maintenance_io_concurrency">
|
||
<term><varname>maintenance_io_concurrency</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>maintenance_io_concurrency</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Similar to <varname>effective_io_concurrency</varname>, but used
|
||
for maintenance work that is done on behalf of many client sessions.
|
||
</para>
|
||
<para>
|
||
The default is 10 on supported systems, otherwise 0. This value can
|
||
be overridden for tables in a particular tablespace by setting the
|
||
tablespace parameter of the same name (see
|
||
<xref linkend="sql-altertablespace"/>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-io-combine-limit" xreflabel="io_combine_limit">
|
||
<term><varname>io_combine_limit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>io_combine_limit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls the largest I/O size in operations that combine I/O.
|
||
The default is 128kB.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-worker-processes" xreflabel="max_worker_processes">
|
||
<term><varname>max_worker_processes</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_worker_processes</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum number of background processes that the cluster
|
||
can support. This parameter can only be set at server start. The
|
||
default is 8.
|
||
</para>
|
||
|
||
<para>
|
||
When running a standby server, you must set this parameter to the
|
||
same or higher value than on the primary server. Otherwise, queries
|
||
will not be allowed in the standby server.
|
||
</para>
|
||
|
||
<para>
|
||
When changing this value, consider also adjusting
|
||
<xref linkend="guc-max-parallel-workers"/>,
|
||
<xref linkend="guc-max-parallel-maintenance-workers"/>, and
|
||
<xref linkend="guc-max-parallel-workers-per-gather"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-parallel-workers-per-gather" xreflabel="max_parallel_workers_per_gather">
|
||
<term><varname>max_parallel_workers_per_gather</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_parallel_workers_per_gather</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum number of workers that can be started by a single
|
||
<literal>Gather</literal> or <literal>Gather Merge</literal> node.
|
||
Parallel workers are taken from the pool of processes established by
|
||
<xref linkend="guc-max-worker-processes"/>, limited by
|
||
<xref linkend="guc-max-parallel-workers"/>. Note that the requested
|
||
number of workers may not actually be available at run time. If this
|
||
occurs, the plan will run with fewer workers than expected, which may
|
||
be inefficient. The default value is 2. Setting this value to 0
|
||
disables parallel query execution.
|
||
</para>
|
||
|
||
<para>
|
||
Note that parallel queries may consume very substantially more
|
||
resources than non-parallel queries, because each worker process is
|
||
a completely separate process which has roughly the same impact on the
|
||
system as an additional user session. This should be taken into
|
||
account when choosing a value for this setting, as well as when
|
||
configuring other settings that control resource utilization, such
|
||
as <xref linkend="guc-work-mem"/>. Resource limits such as
|
||
<varname>work_mem</varname> are applied individually to each worker,
|
||
which means the total utilization may be much higher across all
|
||
processes than it would normally be for any single process.
|
||
For example, a parallel query using 4 workers may use up to 5 times
|
||
as much CPU time, memory, I/O bandwidth, and so forth as a query which
|
||
uses no workers at all.
|
||
</para>
|
||
|
||
<para>
|
||
For more information on parallel query, see
|
||
<xref linkend="parallel-query"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-parallel-maintenance-workers" xreflabel="max_parallel_maintenance_workers">
|
||
<term><varname>max_parallel_maintenance_workers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_parallel_maintenance_workers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum number of parallel workers that can be
|
||
started by a single utility command. Currently, the parallel
|
||
utility commands that support the use of parallel workers are
|
||
<command>CREATE INDEX</command> only when building a B-tree index,
|
||
and <command>VACUUM</command> without <literal>FULL</literal>
|
||
option. Parallel workers are taken from the pool of processes
|
||
established by <xref linkend="guc-max-worker-processes"/>, limited
|
||
by <xref linkend="guc-max-parallel-workers"/>. Note that the requested
|
||
number of workers may not actually be available at run time.
|
||
If this occurs, the utility operation will run with fewer
|
||
workers than expected. The default value is 2. Setting this
|
||
value to 0 disables the use of parallel workers by utility
|
||
commands.
|
||
</para>
|
||
|
||
<para>
|
||
Note that parallel utility commands should not consume
|
||
substantially more memory than equivalent non-parallel
|
||
operations. This strategy differs from that of parallel
|
||
query, where resource limits generally apply per worker
|
||
process. Parallel utility commands treat the resource limit
|
||
<varname>maintenance_work_mem</varname> as a limit to be applied to
|
||
the entire utility command, regardless of the number of
|
||
parallel worker processes. However, parallel utility
|
||
commands may still consume substantially more CPU resources
|
||
and I/O bandwidth.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-parallel-workers" xreflabel="max_parallel_workers">
|
||
<term><varname>max_parallel_workers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_parallel_workers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum number of workers that the cluster can support for
|
||
parallel operations. The default value is 8. When increasing or
|
||
decreasing this value, consider also adjusting
|
||
<xref linkend="guc-max-parallel-maintenance-workers"/> and
|
||
<xref linkend="guc-max-parallel-workers-per-gather"/>.
|
||
Also, note that a setting for this value which is higher than
|
||
<xref linkend="guc-max-worker-processes"/> will have no effect,
|
||
since parallel workers are taken from the pool of worker processes
|
||
established by that setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-parallel-leader-participation" xreflabel="parallel_leader_participation">
|
||
<term>
|
||
<varname>parallel_leader_participation</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>parallel_leader_participation</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Allows the leader process to execute the query plan under
|
||
<literal>Gather</literal> and <literal>Gather Merge</literal> nodes
|
||
instead of waiting for worker processes. The default is
|
||
<literal>on</literal>. Setting this value to <literal>off</literal>
|
||
reduces the likelihood that workers will become blocked because the
|
||
leader is not reading tuples fast enough, but requires the leader
|
||
process to wait for worker processes to start up before the first
|
||
tuples can be produced. The degree to which the leader can help or
|
||
hinder performance depends on the plan type, number of workers and
|
||
query duration.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-wal">
|
||
<title>Write Ahead Log</title>
|
||
|
||
<para>
|
||
For additional information on tuning these settings,
|
||
see <xref linkend="wal-configuration"/>.
|
||
</para>
|
||
|
||
<sect2 id="runtime-config-wal-settings">
|
||
<title>Settings</title>
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-wal-level" xreflabel="wal_level">
|
||
<term><varname>wal_level</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_level</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
<varname>wal_level</varname> determines how much information is written to
|
||
the WAL. The default value is <literal>replica</literal>, which writes enough
|
||
data to support WAL archiving and replication, including running
|
||
read-only queries on a standby server. <literal>minimal</literal> removes all
|
||
logging except the information required to recover from a crash or
|
||
immediate shutdown. Finally,
|
||
<literal>logical</literal> adds information necessary to support logical
|
||
decoding. Each level includes the information logged at all lower
|
||
levels. This parameter can only be set at server start.
|
||
</para>
|
||
<para>
|
||
The <literal>minimal</literal> level generates the least WAL
|
||
volume. It logs no row information for permanent relations
|
||
in transactions that create or
|
||
rewrite them. This can make operations much faster (see
|
||
<xref linkend="populate-pitr"/>). Operations that initiate this
|
||
optimization include:
|
||
<simplelist>
|
||
<member><command>ALTER ... SET TABLESPACE</command></member>
|
||
<member><command>CLUSTER</command></member>
|
||
<member><command>CREATE TABLE</command></member>
|
||
<member><command>REFRESH MATERIALIZED VIEW</command>
|
||
(without <option>CONCURRENTLY</option>)</member>
|
||
<member><command>REINDEX</command></member>
|
||
<member><command>TRUNCATE</command></member>
|
||
</simplelist>
|
||
However, minimal WAL does not contain sufficient information for
|
||
point-in-time recovery, so <literal>replica</literal> or
|
||
higher must be used to enable continuous archiving
|
||
(<xref linkend="guc-archive-mode"/>) and streaming binary replication.
|
||
In fact, the server will not even start in this mode if
|
||
<varname>max_wal_senders</varname> is non-zero.
|
||
Note that changing <varname>wal_level</varname> to
|
||
<literal>minimal</literal> makes previous base backups unusable
|
||
for point-in-time recovery and standby servers.
|
||
</para>
|
||
<para>
|
||
In <literal>logical</literal> level, the same information is logged as
|
||
with <literal>replica</literal>, plus information needed to
|
||
extract logical change sets from the WAL. Using a level of
|
||
<literal>logical</literal> will increase the WAL volume, particularly if many
|
||
tables are configured for <literal>REPLICA IDENTITY FULL</literal> and
|
||
many <command>UPDATE</command> and <command>DELETE</command> statements are
|
||
executed.
|
||
</para>
|
||
<para>
|
||
In releases prior to 9.6, this parameter also allowed the
|
||
values <literal>archive</literal> and <literal>hot_standby</literal>.
|
||
These are still accepted but mapped to <literal>replica</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-fsync" xreflabel="fsync">
|
||
<term><varname>fsync</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>fsync</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If this parameter is on, the <productname>PostgreSQL</productname> server
|
||
will try to make sure that updates are physically written to
|
||
disk, by issuing <function>fsync()</function> system calls or various
|
||
equivalent methods (see <xref linkend="guc-wal-sync-method"/>).
|
||
This ensures that the database cluster can recover to a
|
||
consistent state after an operating system or hardware crash.
|
||
</para>
|
||
|
||
<para>
|
||
While turning off <varname>fsync</varname> is often a performance
|
||
benefit, this can result in unrecoverable data corruption in
|
||
the event of a power failure or system crash. Thus it
|
||
is only advisable to turn off <varname>fsync</varname> if
|
||
you can easily recreate your entire database from external
|
||
data.
|
||
</para>
|
||
|
||
<para>
|
||
Examples of safe circumstances for turning off
|
||
<varname>fsync</varname> include the initial loading of a new
|
||
database cluster from a backup file, using a database cluster
|
||
for processing a batch of data after which the database
|
||
will be thrown away and recreated,
|
||
or for a read-only database clone which
|
||
gets recreated frequently and is not used for failover. High
|
||
quality hardware alone is not a sufficient justification for
|
||
turning off <varname>fsync</varname>.
|
||
</para>
|
||
|
||
<para>
|
||
For reliable recovery when changing <varname>fsync</varname>
|
||
off to on, it is necessary to force all modified buffers in the
|
||
kernel to durable storage. This can be done while the cluster
|
||
is shutdown or while <varname>fsync</varname> is on by running <command>initdb
|
||
--sync-only</command>, running <command>sync</command>, unmounting the
|
||
file system, or rebooting the server.
|
||
</para>
|
||
|
||
<para>
|
||
In many situations, turning off <xref linkend="guc-synchronous-commit"/>
|
||
for noncritical transactions can provide much of the potential
|
||
performance benefit of turning off <varname>fsync</varname>, without
|
||
the attendant risks of data corruption.
|
||
</para>
|
||
|
||
<para>
|
||
<varname>fsync</varname> can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
If you turn this parameter off, also consider turning off
|
||
<xref linkend="guc-full-page-writes"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-synchronous-commit" xreflabel="synchronous_commit">
|
||
<term><varname>synchronous_commit</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>synchronous_commit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies how much WAL processing must complete before
|
||
the database server returns a <quote>success</quote>
|
||
indication to the client. Valid values are
|
||
<literal>remote_apply</literal>, <literal>on</literal>
|
||
(the default), <literal>remote_write</literal>,
|
||
<literal>local</literal>, and <literal>off</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
If <varname>synchronous_standby_names</varname> is empty,
|
||
the only meaningful settings are <literal>on</literal> and
|
||
<literal>off</literal>; <literal>remote_apply</literal>,
|
||
<literal>remote_write</literal> and <literal>local</literal>
|
||
all provide the same local synchronization level
|
||
as <literal>on</literal>. The local behavior of all
|
||
non-<literal>off</literal> modes is to wait for local flush of WAL
|
||
to disk. In <literal>off</literal> mode, there is no waiting,
|
||
so there can be a delay between when success is reported to the
|
||
client and when the transaction is later guaranteed to be safe
|
||
against a server crash. (The maximum
|
||
delay is three times <xref linkend="guc-wal-writer-delay"/>.) Unlike
|
||
<xref linkend="guc-fsync"/>, setting this parameter to <literal>off</literal>
|
||
does not create any risk of database inconsistency: an operating
|
||
system or database crash might
|
||
result in some recent allegedly-committed transactions being lost, but
|
||
the database state will be just the same as if those transactions had
|
||
been aborted cleanly. So, turning <varname>synchronous_commit</varname> off
|
||
can be a useful alternative when performance is more important than
|
||
exact certainty about the durability of a transaction. For more
|
||
discussion see <xref linkend="wal-async-commit"/>.
|
||
</para>
|
||
|
||
<para>
|
||
If <xref linkend="guc-synchronous-standby-names"/> is non-empty,
|
||
<varname>synchronous_commit</varname> also controls whether
|
||
transaction commits will wait for their WAL records to be
|
||
processed on the standby server(s).
|
||
</para>
|
||
|
||
<para>
|
||
When set to <literal>remote_apply</literal>, commits will wait
|
||
until replies from the current synchronous standby(s) indicate they
|
||
have received the commit record of the transaction and applied
|
||
it, so that it has become visible to queries on the standby(s),
|
||
and also written to durable storage on the standbys. This will
|
||
cause much larger commit delays than previous settings since
|
||
it waits for WAL replay. When set to <literal>on</literal>,
|
||
commits wait until replies
|
||
from the current synchronous standby(s) indicate they have received
|
||
the commit record of the transaction and flushed it to durable storage. This
|
||
ensures the transaction will not be lost unless both the primary and
|
||
all synchronous standbys suffer corruption of their database storage.
|
||
When set to <literal>remote_write</literal>, commits will wait until replies
|
||
from the current synchronous standby(s) indicate they have
|
||
received the commit record of the transaction and written it to
|
||
their file systems. This setting ensures data preservation if a standby instance of
|
||
<productname>PostgreSQL</productname> crashes, but not if the standby
|
||
suffers an operating-system-level crash because the data has not
|
||
necessarily reached durable storage on the standby.
|
||
The setting <literal>local</literal> causes commits to wait for
|
||
local flush to disk, but not for replication. This is usually not
|
||
desirable when synchronous replication is in use, but is provided for
|
||
completeness.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can be changed at any time; the behavior for any
|
||
one transaction is determined by the setting in effect when it
|
||
commits. It is therefore possible, and useful, to have some
|
||
transactions commit synchronously and others asynchronously.
|
||
For example, to make a single multistatement transaction commit
|
||
asynchronously when the default is the opposite, issue <command>SET
|
||
LOCAL synchronous_commit TO OFF</command> within the transaction.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend="synchronous-commit-matrix"/> summarizes the
|
||
capabilities of the <varname>synchronous_commit</varname> settings.
|
||
</para>
|
||
|
||
<table id="synchronous-commit-matrix">
|
||
<title>synchronous_commit Modes</title>
|
||
<tgroup cols="5">
|
||
<colspec colname="col1" colwidth="1.5*"/>
|
||
<colspec colname="col2" colwidth="1*"/>
|
||
<colspec colname="col3" colwidth="1*"/>
|
||
<colspec colname="col4" colwidth="1*"/>
|
||
<colspec colname="col5" colwidth="1*"/>
|
||
<thead>
|
||
<row>
|
||
<entry>synchronous_commit setting</entry>
|
||
<entry>local durable commit</entry>
|
||
<entry>standby durable commit after PG crash</entry>
|
||
<entry>standby durable commit after OS crash</entry>
|
||
<entry>standby query consistency</entry>
|
||
</row>
|
||
</thead>
|
||
|
||
<tbody>
|
||
|
||
<row>
|
||
<entry>remote_apply</entry>
|
||
<entry align="center">•</entry>
|
||
<entry align="center">•</entry>
|
||
<entry align="center">•</entry>
|
||
<entry align="center">•</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>on</entry>
|
||
<entry align="center">•</entry>
|
||
<entry align="center">•</entry>
|
||
<entry align="center">•</entry>
|
||
<entry align="center"></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>remote_write</entry>
|
||
<entry align="center">•</entry>
|
||
<entry align="center">•</entry>
|
||
<entry align="center"></entry>
|
||
<entry align="center"></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>local</entry>
|
||
<entry align="center">•</entry>
|
||
<entry align="center"></entry>
|
||
<entry align="center"></entry>
|
||
<entry align="center"></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>off</entry>
|
||
<entry align="center"></entry>
|
||
<entry align="center"></entry>
|
||
<entry align="center"></entry>
|
||
<entry align="center"></entry>
|
||
</row>
|
||
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-sync-method" xreflabel="wal_sync_method">
|
||
<term><varname>wal_sync_method</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_sync_method</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Method used for forcing WAL updates out to disk.
|
||
If <varname>fsync</varname> is off then this setting is irrelevant,
|
||
since WAL file updates will not be forced out at all.
|
||
Possible values are:
|
||
</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<literal>open_datasync</literal> (write WAL files with <function>open()</function> option <symbol>O_DSYNC</symbol>)
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<literal>fdatasync</literal> (call <function>fdatasync()</function> at each commit)
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<literal>fsync</literal> (call <function>fsync()</function> at each commit)
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<literal>fsync_writethrough</literal> (call <function>fsync()</function> at each commit, forcing write-through of any disk write cache)
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<literal>open_sync</literal> (write WAL files with <function>open()</function> option <symbol>O_SYNC</symbol>)
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
Not all of these choices are available on all platforms.
|
||
The default is the first method in the above list that is supported
|
||
by the platform, except that <literal>fdatasync</literal> is the default on
|
||
Linux and FreeBSD. The default is not necessarily ideal; it might be
|
||
necessary to change this setting or other aspects of your system
|
||
configuration in order to create a crash-safe configuration or
|
||
achieve optimal performance.
|
||
These aspects are discussed in <xref linkend="wal-reliability"/>.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-full-page-writes" xreflabel="full_page_writes">
|
||
<term><varname>full_page_writes</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>full_page_writes</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When this parameter is on, the <productname>PostgreSQL</productname> server
|
||
writes the entire content of each disk page to WAL during the
|
||
first modification of that page after a checkpoint.
|
||
This is needed because
|
||
a page write that is in process during an operating system crash might
|
||
be only partially completed, leading to an on-disk page
|
||
that contains a mix of old and new data. The row-level change data
|
||
normally stored in WAL will not be enough to completely restore
|
||
such a page during post-crash recovery. Storing the full page image
|
||
guarantees that the page can be correctly restored, but at the price
|
||
of increasing the amount of data that must be written to WAL.
|
||
(Because WAL replay always starts from a checkpoint, it is sufficient
|
||
to do this during the first change of each page after a checkpoint.
|
||
Therefore, one way to reduce the cost of full-page writes is to
|
||
increase the checkpoint interval parameters.)
|
||
</para>
|
||
|
||
<para>
|
||
Turning this parameter off speeds normal operation, but
|
||
might lead to either unrecoverable data corruption, or silent
|
||
data corruption, after a system failure. The risks are similar to turning off
|
||
<varname>fsync</varname>, though smaller, and it should be turned off
|
||
only based on the same circumstances recommended for that parameter.
|
||
</para>
|
||
|
||
<para>
|
||
Turning off this parameter does not affect use of
|
||
WAL archiving for point-in-time recovery (PITR)
|
||
(see <xref linkend="continuous-archiving"/>).
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-log-hints" xreflabel="wal_log_hints">
|
||
<term><varname>wal_log_hints</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_log_hints</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When this parameter is <literal>on</literal>, the <productname>PostgreSQL</productname>
|
||
server writes the entire content of each disk page to WAL during the
|
||
first modification of that page after a checkpoint, even for
|
||
non-critical modifications of so-called hint bits.
|
||
</para>
|
||
|
||
<para>
|
||
If data checksums are enabled, hint bit updates are always WAL-logged
|
||
and this setting is ignored. You can use this setting to test how much
|
||
extra WAL-logging would occur if your database had data checksums
|
||
enabled.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set at server start. The default value is <literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-compression" xreflabel="wal_compression">
|
||
<term><varname>wal_compression</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_compression</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter enables compression of WAL using the specified
|
||
compression method.
|
||
When enabled, the <productname>PostgreSQL</productname>
|
||
server compresses full page images written to WAL when
|
||
<xref linkend="guc-full-page-writes"/> is on or during a base backup.
|
||
A compressed page image will be decompressed during WAL replay.
|
||
The supported methods are <literal>pglz</literal>,
|
||
<literal>lz4</literal> (if <productname>PostgreSQL</productname>
|
||
was compiled with <option>--with-lz4</option>) and
|
||
<literal>zstd</literal> (if <productname>PostgreSQL</productname>
|
||
was compiled with <option>--with-zstd</option>).
|
||
The default value is <literal>off</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<para>
|
||
Enabling compression can reduce the WAL volume without
|
||
increasing the risk of unrecoverable data corruption,
|
||
but at the cost of some extra CPU spent on the compression during
|
||
WAL logging and on the decompression during WAL replay.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-init-zero" xreflabel="wal_init_zero">
|
||
<term><varname>wal_init_zero</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_init_zero</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set to <literal>on</literal> (the default), this option causes new
|
||
WAL files to be filled with zeroes. On some file systems, this ensures
|
||
that space is allocated before we need to write WAL records. However,
|
||
<firstterm>Copy-On-Write</firstterm> (COW) file systems may not benefit
|
||
from this technique, so the option is given to skip the unnecessary
|
||
work. If set to <literal>off</literal>, only the final byte is written
|
||
when the file is created so that it has the expected size.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-recycle" xreflabel="wal_recycle">
|
||
<term><varname>wal_recycle</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_recycle</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set to <literal>on</literal> (the default), this option causes WAL
|
||
files to be recycled by renaming them, avoiding the need to create new
|
||
ones. On COW file systems, it may be faster to create new ones, so the
|
||
option is given to disable this behavior.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-buffers" xreflabel="wal_buffers">
|
||
<term><varname>wal_buffers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_buffers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The amount of shared memory used for WAL data that has not yet been
|
||
written to disk. The default setting of -1 selects a size equal to
|
||
1/32nd (about 3%) of <xref linkend="guc-shared-buffers"/>, but not less
|
||
than <literal>64kB</literal> nor more than the size of one WAL
|
||
segment, typically <literal>16MB</literal>. This value can be set
|
||
manually if the automatic choice is too large or too small,
|
||
but any positive value less than <literal>32kB</literal> will be
|
||
treated as <literal>32kB</literal>.
|
||
If this value is specified without units, it is taken as WAL blocks,
|
||
that is <symbol>XLOG_BLCKSZ</symbol> bytes, typically 8kB.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
|
||
<para>
|
||
The contents of the WAL buffers are written out to disk at every
|
||
transaction commit, so extremely large values are unlikely to
|
||
provide a significant benefit. However, setting this value to at
|
||
least a few megabytes can improve write performance on a busy
|
||
server where many clients are committing at once. The auto-tuning
|
||
selected by the default setting of -1 should give reasonable
|
||
results in most cases.
|
||
</para>
|
||
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-writer-delay" xreflabel="wal_writer_delay">
|
||
<term><varname>wal_writer_delay</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_writer_delay</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies how often the WAL writer flushes WAL, in time terms.
|
||
After flushing WAL the writer sleeps for the length of time given
|
||
by <varname>wal_writer_delay</varname>, unless woken up sooner
|
||
by an asynchronously committing transaction. If the last flush
|
||
happened less than <varname>wal_writer_delay</varname> ago and less
|
||
than <varname>wal_writer_flush_after</varname> worth of WAL has been
|
||
produced since, then WAL is only written to the operating system, not
|
||
flushed to disk.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default value is 200 milliseconds (<literal>200ms</literal>). Note that
|
||
on some systems, the effective resolution of sleep delays is 10
|
||
milliseconds; setting <varname>wal_writer_delay</varname> to a value that is
|
||
not a multiple of 10 might have the same results as setting it to the
|
||
next higher multiple of 10. This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-writer-flush-after" xreflabel="wal_writer_flush_after">
|
||
<term><varname>wal_writer_flush_after</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_writer_flush_after</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies how often the WAL writer flushes WAL, in volume terms.
|
||
If the last flush happened less
|
||
than <varname>wal_writer_delay</varname> ago and less
|
||
than <varname>wal_writer_flush_after</varname> worth of WAL has been
|
||
produced since, then WAL is only written to the operating system, not
|
||
flushed to disk. If <varname>wal_writer_flush_after</varname> is set
|
||
to <literal>0</literal> then WAL data is always flushed immediately.
|
||
If this value is specified without units, it is taken as WAL blocks,
|
||
that is <symbol>XLOG_BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default is <literal>1MB</literal>.
|
||
This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-skip-threshold" xreflabel="wal_skip_threshold">
|
||
<term><varname>wal_skip_threshold</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_skip_threshold</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When <varname>wal_level</varname> is <literal>minimal</literal> and a
|
||
transaction commits after creating or rewriting a permanent relation,
|
||
this setting determines how to persist the new data. If the data is
|
||
smaller than this setting, write it to the WAL log; otherwise, use an
|
||
fsync of affected files. Depending on the properties of your storage,
|
||
raising or lowering this value might help if such commits are slowing
|
||
concurrent transactions. If this value is specified without units, it
|
||
is taken as kilobytes. The default is two megabytes
|
||
(<literal>2MB</literal>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-commit-delay" xreflabel="commit_delay">
|
||
<term><varname>commit_delay</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>commit_delay</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Setting <varname>commit_delay</varname> adds a time delay
|
||
before a WAL flush is initiated. This can improve
|
||
group commit throughput by allowing a larger number of transactions
|
||
to commit via a single WAL flush, if system load is high enough
|
||
that additional transactions become ready to commit within the
|
||
given interval. However, it also increases latency by up to the
|
||
<varname>commit_delay</varname> for each WAL
|
||
flush. Because the delay is just wasted if no other transactions
|
||
become ready to commit, a delay is only performed if at least
|
||
<varname>commit_siblings</varname> other transactions are active
|
||
when a flush is about to be initiated. Also, no delays are
|
||
performed if <varname>fsync</varname> is disabled.
|
||
If this value is specified without units, it is taken as microseconds.
|
||
The default <varname>commit_delay</varname> is zero (no delay).
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
<para>
|
||
In <productname>PostgreSQL</productname> releases prior to 9.3,
|
||
<varname>commit_delay</varname> behaved differently and was much
|
||
less effective: it affected only commits, rather than all WAL flushes,
|
||
and waited for the entire configured delay even if the WAL flush
|
||
was completed sooner. Beginning in <productname>PostgreSQL</productname> 9.3,
|
||
the first process that becomes ready to flush waits for the configured
|
||
interval, while subsequent processes wait only until the leader
|
||
completes the flush operation.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-commit-siblings" xreflabel="commit_siblings">
|
||
<term><varname>commit_siblings</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>commit_siblings</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Minimum number of concurrent open transactions to require
|
||
before performing the <varname>commit_delay</varname> delay. A larger
|
||
value makes it more probable that at least one other
|
||
transaction will become ready to commit during the delay
|
||
interval. The default is five transactions.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
<sect2 id="runtime-config-wal-checkpoints">
|
||
<title>Checkpoints</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-checkpoint-timeout" xreflabel="checkpoint_timeout">
|
||
<term><varname>checkpoint_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>checkpoint_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Maximum time between automatic WAL checkpoints.
|
||
If this value is specified without units, it is taken as seconds.
|
||
The valid range is between 30 seconds and one day.
|
||
The default is five minutes (<literal>5min</literal>).
|
||
Increasing this parameter can increase the amount of time needed
|
||
for crash recovery.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-checkpoint-completion-target" xreflabel="checkpoint_completion_target">
|
||
<term><varname>checkpoint_completion_target</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>checkpoint_completion_target</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the target of checkpoint completion, as a fraction of
|
||
total time between checkpoints. The default is 0.9, which spreads the
|
||
checkpoint across almost all of the available interval, providing fairly
|
||
consistent I/O load while also leaving some time for checkpoint
|
||
completion overhead. Reducing this parameter is not recommended because
|
||
it causes the checkpoint to complete faster. This results in a higher
|
||
rate of I/O during the checkpoint followed by a period of less I/O between
|
||
the checkpoint completion and the next scheduled checkpoint. This
|
||
parameter can only be set in the <filename>postgresql.conf</filename> file
|
||
or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-checkpoint-flush-after" xreflabel="checkpoint_flush_after">
|
||
<term><varname>checkpoint_flush_after</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>checkpoint_flush_after</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Whenever more than this amount of data has been
|
||
written while performing a checkpoint, attempt to force the
|
||
OS to issue these writes to the underlying storage. Doing so will
|
||
limit the amount of dirty data in the kernel's page cache, reducing
|
||
the likelihood of stalls when an <function>fsync</function> is issued at the end of the
|
||
checkpoint, or when the OS writes data back in larger batches in the
|
||
background. Often that will result in greatly reduced transaction
|
||
latency, but there also are some cases, especially with workloads
|
||
that are bigger than <xref linkend="guc-shared-buffers"/>, but smaller
|
||
than the OS's page cache, where performance might degrade. This
|
||
setting may have no effect on some platforms.
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The valid range is
|
||
between <literal>0</literal>, which disables forced writeback,
|
||
and <literal>2MB</literal>. The default is <literal>256kB</literal> on
|
||
Linux, <literal>0</literal> elsewhere. (If <symbol>BLCKSZ</symbol> is not
|
||
8kB, the default and maximum values scale proportionally to it.)
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-checkpoint-warning" xreflabel="checkpoint_warning">
|
||
<term><varname>checkpoint_warning</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>checkpoint_warning</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Write a message to the server log if checkpoints caused by
|
||
the filling of WAL segment files happen closer together
|
||
than this amount of time (which suggests that
|
||
<varname>max_wal_size</varname> ought to be raised).
|
||
If this value is specified without units, it is taken as seconds.
|
||
The default is 30 seconds (<literal>30s</literal>).
|
||
Zero disables the warning.
|
||
No warnings will be generated if <varname>checkpoint_timeout</varname>
|
||
is less than <varname>checkpoint_warning</varname>.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-wal-size" xreflabel="max_wal_size">
|
||
<term><varname>max_wal_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_wal_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Maximum size to let the WAL grow during automatic
|
||
checkpoints. This is a soft limit; WAL size can exceed
|
||
<varname>max_wal_size</varname> under special circumstances, such as
|
||
heavy load, a failing <varname>archive_command</varname> or <varname>archive_library</varname>, or a high
|
||
<varname>wal_keep_size</varname> setting.
|
||
If this value is specified without units, it is taken as megabytes.
|
||
The default is 1 GB.
|
||
Increasing this parameter can increase the amount of time needed for
|
||
crash recovery.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-min-wal-size" xreflabel="min_wal_size">
|
||
<term><varname>min_wal_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>min_wal_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
As long as WAL disk usage stays below this setting, old WAL files are
|
||
always recycled for future use at a checkpoint, rather than removed.
|
||
This can be used to ensure that enough WAL space is reserved to
|
||
handle spikes in WAL usage, for example when running large batch
|
||
jobs.
|
||
If this value is specified without units, it is taken as megabytes.
|
||
The default is 80 MB.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
<sect2 id="runtime-config-wal-archiving">
|
||
<title>Archiving</title>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-archive-mode" xreflabel="archive_mode">
|
||
<term><varname>archive_mode</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>archive_mode</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When <varname>archive_mode</varname> is enabled, completed WAL segments
|
||
are sent to archive storage by setting
|
||
<xref linkend="guc-archive-command"/> or
|
||
<xref linkend="guc-archive-library"/>. In addition to <literal>off</literal>,
|
||
to disable, there are two modes: <literal>on</literal>, and
|
||
<literal>always</literal>. During normal operation, there is no
|
||
difference between the two modes, but when set to <literal>always</literal>
|
||
the WAL archiver is enabled also during archive recovery or standby
|
||
mode. In <literal>always</literal> mode, all files restored from the archive
|
||
or streamed with streaming replication will be archived (again). See
|
||
<xref linkend="continuous-archiving-in-standby"/> for details.
|
||
</para>
|
||
<para>
|
||
<varname>archive_mode</varname> is a separate setting from
|
||
<varname>archive_command</varname> and
|
||
<varname>archive_library</varname> so that
|
||
<varname>archive_command</varname> and
|
||
<varname>archive_library</varname> can be changed without leaving
|
||
archiving mode.
|
||
This parameter can only be set at server start.
|
||
<varname>archive_mode</varname> cannot be enabled when
|
||
<varname>wal_level</varname> is set to <literal>minimal</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-archive-command" xreflabel="archive_command">
|
||
<term><varname>archive_command</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>archive_command</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The local shell command to execute to archive a completed WAL file
|
||
segment. Any <literal>%p</literal> in the string is
|
||
replaced by the path name of the file to archive, and any
|
||
<literal>%f</literal> is replaced by only the file name.
|
||
(The path name is relative to the working directory of the server,
|
||
i.e., the cluster's data directory.)
|
||
Use <literal>%%</literal> to embed an actual <literal>%</literal> character in the
|
||
command. It is important for the command to return a zero
|
||
exit status only if it succeeds. For more information see
|
||
<xref linkend="backup-archiving-wal"/>.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line. It is only used if
|
||
<varname>archive_mode</varname> was enabled at server start and
|
||
<varname>archive_library</varname> is set to an empty string. If both
|
||
<varname>archive_command</varname> and <varname>archive_library</varname>
|
||
are set, an error will be raised.
|
||
If <varname>archive_command</varname> is an empty string (the default) while
|
||
<varname>archive_mode</varname> is enabled (and <varname>archive_library</varname>
|
||
is set to an empty string), WAL archiving is temporarily
|
||
disabled, but the server continues to accumulate WAL segment files in
|
||
the expectation that a command will soon be provided. Setting
|
||
<varname>archive_command</varname> to a command that does nothing but
|
||
return true, e.g., <literal>/bin/true</literal> (<literal>REM</literal> on
|
||
Windows), effectively disables
|
||
archiving, but also breaks the chain of WAL files needed for
|
||
archive recovery, so it should only be used in unusual circumstances.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-archive-library" xreflabel="archive_library">
|
||
<term><varname>archive_library</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>archive_library</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The library to use for archiving completed WAL file segments. If set to
|
||
an empty string (the default), archiving via shell is enabled, and
|
||
<xref linkend="guc-archive-command"/> is used. If both
|
||
<varname>archive_command</varname> and <varname>archive_library</varname>
|
||
are set, an error will be raised. Otherwise, the specified
|
||
shared library is used for archiving. The WAL archiver process is
|
||
restarted by the postmaster when this parameter changes. For more
|
||
information, see <xref linkend="backup-archiving-wal"/> and
|
||
<xref linkend="archive-modules"/>.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-archive-timeout" xreflabel="archive_timeout">
|
||
<term><varname>archive_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>archive_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The <xref linkend="guc-archive-command"/> or <xref linkend="guc-archive-library"/> is only invoked for
|
||
completed WAL segments. Hence, if your server generates little WAL
|
||
traffic (or has slack periods where it does so), there could be a
|
||
long delay between the completion of a transaction and its safe
|
||
recording in archive storage. To limit how old unarchived
|
||
data can be, you can set <varname>archive_timeout</varname> to force the
|
||
server to switch to a new WAL segment file periodically. When this
|
||
parameter is greater than zero, the server will switch to a new
|
||
segment file whenever this amount of time has elapsed since the last
|
||
segment file switch, and there has been any database activity,
|
||
including a single checkpoint (checkpoints are skipped if there is
|
||
no database activity). Note that archived files that are closed
|
||
early due to a forced switch are still the same length as completely
|
||
full files. Therefore, it is unwise to use a very short
|
||
<varname>archive_timeout</varname> — it will bloat your archive
|
||
storage. <varname>archive_timeout</varname> settings of a minute or so are
|
||
usually reasonable. You should consider using streaming replication,
|
||
instead of archiving, if you want data to be copied off the primary
|
||
server more quickly than that.
|
||
If this value is specified without units, it is taken as seconds.
|
||
This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-wal-recovery">
|
||
|
||
<title>Recovery</title>
|
||
|
||
<indexterm>
|
||
<primary>configuration</primary>
|
||
<secondary>of recovery</secondary>
|
||
<tertiary>general settings</tertiary>
|
||
</indexterm>
|
||
|
||
<para>
|
||
This section describes the settings that apply to recovery in general,
|
||
affecting crash recovery, streaming replication and archive-based
|
||
replication.
|
||
</para>
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-recovery-prefetch" xreflabel="recovery_prefetch">
|
||
<term><varname>recovery_prefetch</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_prefetch</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Whether to try to prefetch blocks that are referenced in the WAL that
|
||
are not yet in the buffer pool, during recovery. Valid values are
|
||
<literal>off</literal>, <literal>on</literal> and
|
||
<literal>try</literal> (the default). The setting
|
||
<literal>try</literal> enables
|
||
prefetching only if the operating system provides the
|
||
<function>posix_fadvise</function> function, which is currently used
|
||
to implement prefetching. Note that some operating systems provide the
|
||
function, but it doesn't do anything.
|
||
</para>
|
||
<para>
|
||
Prefetching blocks that will soon be needed can reduce I/O wait times
|
||
during recovery with some workloads.
|
||
See also the <xref linkend="guc-wal-decode-buffer-size"/> and
|
||
<xref linkend="guc-maintenance-io-concurrency"/> settings, which limit
|
||
prefetching activity.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-decode-buffer-size" xreflabel="wal_decode_buffer_size">
|
||
<term><varname>wal_decode_buffer_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_decode_buffer_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A limit on how far ahead the server can look in the WAL, to find
|
||
blocks to prefetch. If this value is specified without units, it is
|
||
taken as bytes.
|
||
The default is 512kB.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-wal-archive-recovery">
|
||
|
||
<title>Archive Recovery</title>
|
||
|
||
<indexterm>
|
||
<primary>configuration</primary>
|
||
<secondary>of recovery</secondary>
|
||
<tertiary>of a standby server</tertiary>
|
||
</indexterm>
|
||
|
||
<para>
|
||
This section describes the settings that apply only for the duration of
|
||
the recovery. They must be reset for any subsequent recovery you wish to
|
||
perform.
|
||
</para>
|
||
|
||
<para>
|
||
<quote>Recovery</quote> covers using the server as a standby or for
|
||
executing a targeted recovery. Typically, standby mode would be used to
|
||
provide high availability and/or read scalability, whereas a targeted
|
||
recovery is used to recover from data loss.
|
||
</para>
|
||
|
||
<para>
|
||
To start the server in standby mode, create a file called
|
||
<filename>standby.signal</filename><indexterm><primary>standby.signal</primary></indexterm>
|
||
in the data directory. The server will enter recovery and will not stop
|
||
recovery when the end of archived WAL is reached, but will keep trying to
|
||
continue recovery by connecting to the sending server as specified by the
|
||
<varname>primary_conninfo</varname> setting and/or by fetching new WAL
|
||
segments using <varname>restore_command</varname>. For this mode, the
|
||
parameters from this section and <xref
|
||
linkend="runtime-config-replication-standby"/> are of interest.
|
||
Parameters from <xref linkend="runtime-config-wal-recovery-target"/> will
|
||
also be applied but are typically not useful in this mode.
|
||
</para>
|
||
|
||
<para>
|
||
To start the server in targeted recovery mode, create a file called
|
||
<filename>recovery.signal</filename><indexterm><primary>recovery.signal</primary></indexterm>
|
||
in the data directory. If both <filename>standby.signal</filename> and
|
||
<filename>recovery.signal</filename> files are created, standby mode
|
||
takes precedence. Targeted recovery mode ends when the archived WAL is
|
||
fully replayed, or when <varname>recovery_target</varname> is reached.
|
||
In this mode, the parameters from both this section and <xref
|
||
linkend="runtime-config-wal-recovery-target"/> will be used.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-restore-command" xreflabel="restore_command">
|
||
<term><varname>restore_command</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>restore_command</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The local shell command to execute to retrieve an archived segment of
|
||
the WAL file series. This parameter is required for archive recovery,
|
||
but optional for streaming replication.
|
||
Any <literal>%f</literal> in the string is
|
||
replaced by the name of the file to retrieve from the archive,
|
||
and any <literal>%p</literal> is replaced by the copy destination path name
|
||
on the server.
|
||
(The path name is relative to the current working directory,
|
||
i.e., the cluster's data directory.)
|
||
Any <literal>%r</literal> is replaced by the name of the file containing the
|
||
last valid restart point. That is the earliest file that must be kept
|
||
to allow a restore to be restartable, so this information can be used
|
||
to truncate the archive to just the minimum required to support
|
||
restarting from the current restore. <literal>%r</literal> is typically only
|
||
used by warm-standby configurations
|
||
(see <xref linkend="warm-standby"/>).
|
||
Write <literal>%%</literal> to embed an actual <literal>%</literal> character.
|
||
</para>
|
||
|
||
<para>
|
||
It is important for the command to return a zero exit status
|
||
only if it succeeds. The command <emphasis>will</emphasis> be asked for file
|
||
names that are not present in the archive; it must return nonzero
|
||
when so asked. Examples:
|
||
<programlisting>
|
||
restore_command = 'cp /mnt/server/archivedir/%f "%p"'
|
||
restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
|
||
</programlisting>
|
||
An exception is that if the command was terminated by a signal (other
|
||
than <systemitem>SIGTERM</systemitem>, which is used as part of a
|
||
database server shutdown) or an error by the shell (such as command
|
||
not found), then recovery will abort and the server will not start up.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-archive-cleanup-command" xreflabel="archive_cleanup_command">
|
||
<term><varname>archive_cleanup_command</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>archive_cleanup_command</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This optional parameter specifies a shell command that will be executed
|
||
at every restartpoint. The purpose of
|
||
<varname>archive_cleanup_command</varname> is to provide a mechanism for
|
||
cleaning up old archived WAL files that are no longer needed by the
|
||
standby server.
|
||
Any <literal>%r</literal> is replaced by the name of the file containing the
|
||
last valid restart point.
|
||
That is the earliest file that must be <emphasis>kept</emphasis> to allow a
|
||
restore to be restartable, and so all files earlier than <literal>%r</literal>
|
||
may be safely removed.
|
||
This information can be used to truncate the archive to just the
|
||
minimum required to support restart from the current restore.
|
||
The <xref linkend="pgarchivecleanup"/> module
|
||
is often used in <varname>archive_cleanup_command</varname> for
|
||
single-standby configurations, for example:
|
||
<programlisting>archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'</programlisting>
|
||
Note however that if multiple standby servers are restoring from the
|
||
same archive directory, you will need to ensure that you do not delete
|
||
WAL files until they are no longer needed by any of the servers.
|
||
<varname>archive_cleanup_command</varname> would typically be used in a
|
||
warm-standby configuration (see <xref linkend="warm-standby"/>).
|
||
Write <literal>%%</literal> to embed an actual <literal>%</literal> character in the
|
||
command.
|
||
</para>
|
||
<para>
|
||
If the command returns a nonzero exit status then a warning log
|
||
message will be written. An exception is that if the command was
|
||
terminated by a signal or an error by the shell (such as command not
|
||
found), a fatal error will be raised.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recovery-end-command" xreflabel="recovery_end_command">
|
||
<term><varname>recovery_end_command</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_end_command</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter specifies a shell command that will be executed once only
|
||
at the end of recovery. This parameter is optional. The purpose of the
|
||
<varname>recovery_end_command</varname> is to provide a mechanism for cleanup
|
||
following replication or recovery.
|
||
Any <literal>%r</literal> is replaced by the name of the file containing the
|
||
last valid restart point, like in <xref linkend="guc-archive-cleanup-command"/>.
|
||
</para>
|
||
<para>
|
||
If the command returns a nonzero exit status then a warning log
|
||
message will be written and the database will proceed to start up
|
||
anyway. An exception is that if the command was terminated by a
|
||
signal or an error by the shell (such as command not found), the
|
||
database will not proceed with startup.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-wal-recovery-target">
|
||
|
||
<title>Recovery Target</title>
|
||
|
||
<para>
|
||
By default, recovery will recover to the end of the WAL log. The
|
||
following parameters can be used to specify an earlier stopping point.
|
||
At most one of <varname>recovery_target</varname>,
|
||
<varname>recovery_target_lsn</varname>, <varname>recovery_target_name</varname>,
|
||
<varname>recovery_target_time</varname>, or <varname>recovery_target_xid</varname>
|
||
can be used; if more than one of these is specified in the configuration
|
||
file, an error will be raised.
|
||
These parameters can only be set at server start.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-recovery-target" xreflabel="recovery_target">
|
||
<term><varname>recovery_target</varname><literal> = 'immediate'</literal>
|
||
<indexterm>
|
||
<primary><varname>recovery_target</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter specifies that recovery should end as soon as a
|
||
consistent state is reached, i.e., as early as possible. When restoring
|
||
from an online backup, this means the point where taking the backup
|
||
ended.
|
||
</para>
|
||
<para>
|
||
Technically, this is a string parameter, but <literal>'immediate'</literal>
|
||
is currently the only allowed value.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recovery-target-name" xreflabel="recovery_target_name">
|
||
<term><varname>recovery_target_name</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_target_name</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter specifies the named restore point (created with
|
||
<function>pg_create_restore_point()</function>) to which recovery will proceed.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recovery-target-time" xreflabel="recovery_target_time">
|
||
<term><varname>recovery_target_time</varname> (<type>timestamp</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_target_time</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter specifies the time stamp up to which recovery
|
||
will proceed.
|
||
The precise stopping point is also influenced by
|
||
<xref linkend="guc-recovery-target-inclusive"/>.
|
||
</para>
|
||
|
||
<para>
|
||
The value of this parameter is a time stamp in the same format
|
||
accepted by the <type>timestamp with time zone</type> data type,
|
||
except that you cannot use a time zone abbreviation (unless the
|
||
<xref linkend="guc-timezone-abbreviations"/> variable has been set
|
||
earlier in the configuration file). Preferred style is to use a
|
||
numeric offset from UTC, or you can write a full time zone name,
|
||
e.g., <literal>Europe/Helsinki</literal> not <literal>EEST</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recovery-target-xid" xreflabel="recovery_target_xid">
|
||
<term><varname>recovery_target_xid</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_target_xid</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter specifies the transaction ID up to which recovery
|
||
will proceed. Keep in mind
|
||
that while transaction IDs are assigned sequentially at transaction
|
||
start, transactions can complete in a different numeric order.
|
||
The transactions that will be recovered are those that committed
|
||
before (and optionally including) the specified one.
|
||
The precise stopping point is also influenced by
|
||
<xref linkend="guc-recovery-target-inclusive"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recovery-target-lsn" xreflabel="recovery_target_lsn">
|
||
<term><varname>recovery_target_lsn</varname> (<type>pg_lsn</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_target_lsn</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter specifies the LSN of the write-ahead log location up
|
||
to which recovery will proceed. The precise stopping point is also
|
||
influenced by <xref linkend="guc-recovery-target-inclusive"/>. This
|
||
parameter is parsed using the system data type
|
||
<link linkend="datatype-pg-lsn"><type>pg_lsn</type></link>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The following options further specify the recovery target, and affect
|
||
what happens when the target is reached:
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-recovery-target-inclusive"
|
||
xreflabel="recovery_target_inclusive">
|
||
<term><varname>recovery_target_inclusive</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_target_inclusive</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies whether to stop just after the specified recovery target
|
||
(<literal>on</literal>), or just before the recovery target
|
||
(<literal>off</literal>).
|
||
Applies when <xref linkend="guc-recovery-target-lsn"/>,
|
||
<xref linkend="guc-recovery-target-time"/>, or
|
||
<xref linkend="guc-recovery-target-xid"/> is specified.
|
||
This setting controls whether transactions
|
||
having exactly the target WAL location (LSN), commit time, or transaction ID, respectively, will
|
||
be included in the recovery. Default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recovery-target-timeline"
|
||
xreflabel="recovery_target_timeline">
|
||
<term><varname>recovery_target_timeline</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_target_timeline</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies recovering into a particular timeline. The value can be a
|
||
numeric timeline ID or a special value. The value
|
||
<literal>current</literal> recovers along the same timeline that was
|
||
current when the base backup was taken. The
|
||
value <literal>latest</literal> recovers
|
||
to the latest timeline found in the archive, which is useful in
|
||
a standby server. <literal>latest</literal> is the default.
|
||
</para>
|
||
|
||
<para>
|
||
To specify a timeline ID in hexadecimal (for example, if extracted
|
||
from a WAL file name or history file), prefix it with a
|
||
<literal>0x</literal>. For instance, if the WAL file name is
|
||
<filename>00000011000000A10000004F</filename>, then the timeline ID is
|
||
<literal>0x11</literal> (or 17 decimal).
|
||
</para>
|
||
|
||
<para>
|
||
You usually only need to set this parameter
|
||
in complex re-recovery situations, where you need to return to
|
||
a state that itself was reached after a point-in-time recovery.
|
||
See <xref linkend="backup-timelines"/> for discussion.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recovery-target-action"
|
||
xreflabel="recovery_target_action">
|
||
<term><varname>recovery_target_action</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_target_action</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies what action the server should take once the recovery target is
|
||
reached. The default is <literal>pause</literal>, which means recovery will
|
||
be paused. <literal>promote</literal> means the recovery process will finish
|
||
and the server will start to accept connections.
|
||
Finally <literal>shutdown</literal> will stop the server after reaching the
|
||
recovery target.
|
||
</para>
|
||
<para>
|
||
The intended use of the <literal>pause</literal> setting is to allow queries
|
||
to be executed against the database to check if this recovery target
|
||
is the most desirable point for recovery.
|
||
The paused state can be resumed by
|
||
using <function>pg_wal_replay_resume()</function> (see
|
||
<xref linkend="functions-recovery-control-table"/>), which then
|
||
causes recovery to end. If this recovery target is not the
|
||
desired stopping point, then shut down the server, change the
|
||
recovery target settings to a later target and restart to
|
||
continue recovery.
|
||
</para>
|
||
<para>
|
||
The <literal>shutdown</literal> setting is useful to have the instance ready
|
||
at the exact replay point desired. The instance will still be able to
|
||
replay more WAL records (and in fact will have to replay WAL records
|
||
since the last checkpoint next time it is started).
|
||
</para>
|
||
<para>
|
||
Note that because <filename>recovery.signal</filename> will not be
|
||
removed when <varname>recovery_target_action</varname> is set to <literal>shutdown</literal>,
|
||
any subsequent start will end with immediate shutdown unless the
|
||
configuration is changed or the <filename>recovery.signal</filename>
|
||
file is removed manually.
|
||
</para>
|
||
<para>
|
||
This setting has no effect if no recovery target is set.
|
||
If <xref linkend="guc-hot-standby"/> is not enabled, a setting of
|
||
<literal>pause</literal> will act the same as <literal>shutdown</literal>.
|
||
If the recovery target is reached while a promotion is ongoing,
|
||
a setting of <literal>pause</literal> will act the same as
|
||
<literal>promote</literal>.
|
||
</para>
|
||
<para>
|
||
In any case, if a recovery target is configured but the archive
|
||
recovery ends before the target is reached, the server will shut down
|
||
with a fatal error.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-wal-summarization">
|
||
<title>WAL Summarization</title>
|
||
|
||
<para>
|
||
These settings control WAL summarization, a feature which must be
|
||
enabled in order to perform an
|
||
<link linkend="backup-incremental-backup">incremental backup</link>.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-summarize-wal" xreflabel="summarize_wal">
|
||
<term><varname>summarize_wal</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>summarize_wal</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables the WAL summarizer process. Note that WAL summarization can
|
||
be enabled either on a primary or on a standby. WAL summarization
|
||
cannot be enabled when <varname>wal_level</varname> is set to
|
||
<literal>minimal</literal>. This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
The default is <literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-summary-keep-time" xreflabel="wal_summary_keep_time">
|
||
<term><varname>wal_summary_keep_time</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_summary_keep_time</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Configures the amount of time after which the WAL summarizer
|
||
automatically removes old WAL summaries. The file timestamp is used to
|
||
determine which files are old enough to remove. Typically, you should set
|
||
this comfortably higher than the time that could pass between a backup
|
||
and a later incremental backup that depends on it. WAL summaries must
|
||
be available for the entire range of WAL records between the preceding
|
||
backup and the new one being taken; if not, the incremental backup will
|
||
fail. If this parameter is set to zero, WAL summaries will not be
|
||
automatically deleted, but it is safe to manually remove files that you
|
||
know will not be required for future incremental backups.
|
||
This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
If this value is specified without units, it is taken as minutes.
|
||
The default is 10 days. If <literal>summarize_wal = off</literal>,
|
||
existing WAL summaries will not be removed regardless of the value of
|
||
this parameter, because the WAL summarizer will not run.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</sect2>
|
||
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-replication">
|
||
<title>Replication</title>
|
||
|
||
<para>
|
||
These settings control the behavior of the built-in
|
||
<firstterm>streaming replication</firstterm> feature (see
|
||
<xref linkend="streaming-replication"/>), and the built-in
|
||
<firstterm>logical replication</firstterm> feature (see
|
||
<xref linkend="logical-replication"/>).
|
||
</para>
|
||
|
||
<para>
|
||
For <emphasis>streaming replication</emphasis>, servers will be either a
|
||
primary or a standby server. Primaries can send data, while standbys
|
||
are always receivers of replicated data. When cascading replication
|
||
(see <xref linkend="cascading-replication"/>) is used, standby servers
|
||
can also be senders, as well as receivers.
|
||
Parameters are mainly for sending and standby servers, though some
|
||
parameters have meaning only on the primary server. Settings may vary
|
||
across the cluster without problems if that is required.
|
||
</para>
|
||
|
||
<para>
|
||
For <emphasis>logical replication</emphasis>, <firstterm>publishers</firstterm>
|
||
(servers that do <link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>)
|
||
replicate data to <firstterm>subscribers</firstterm>
|
||
(servers that do <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>).
|
||
Servers can also be publishers and subscribers at the same time. Note,
|
||
the following sections refer to publishers as "senders". For more details
|
||
about logical replication configuration settings refer to
|
||
<xref linkend="logical-replication-config"/>.
|
||
</para>
|
||
|
||
<sect2 id="runtime-config-replication-sender">
|
||
<title>Sending Servers</title>
|
||
|
||
<para>
|
||
These parameters can be set on any server that is
|
||
to send replication data to one or more standby servers.
|
||
The primary is always a sending server, so these parameters must
|
||
always be set on the primary.
|
||
The role and meaning of these parameters does not change after a
|
||
standby becomes the primary.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-max-wal-senders" xreflabel="max_wal_senders">
|
||
<term><varname>max_wal_senders</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_wal_senders</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum number of concurrent connections from standby
|
||
servers or streaming base backup clients (i.e., the maximum number of
|
||
simultaneously running WAL sender processes). The default is
|
||
<literal>10</literal>. The value <literal>0</literal> means
|
||
replication is disabled. Abrupt disconnection of a streaming client might
|
||
leave an orphaned connection slot behind until a timeout is reached,
|
||
so this parameter should be set slightly higher than the maximum
|
||
number of expected clients so disconnected clients can immediately
|
||
reconnect. This parameter can only be set at server start. Also,
|
||
<varname>wal_level</varname> must be set to
|
||
<literal>replica</literal> or higher to allow connections from standby
|
||
servers.
|
||
</para>
|
||
|
||
<para>
|
||
When running a standby server, you must set this parameter to the
|
||
same or higher value than on the primary server. Otherwise, queries
|
||
will not be allowed in the standby server.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-replication-slots" xreflabel="max_replication_slots">
|
||
<term><varname>max_replication_slots</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_replication_slots</varname> configuration parameter</primary>
|
||
<secondary>in a sending server</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum number of replication slots
|
||
(see <xref linkend="streaming-replication-slots"/>) that the server
|
||
can support. The default is 10. This parameter can only be set at
|
||
server start.
|
||
Setting it to a lower value than the number of currently
|
||
existing replication slots will prevent the server from starting.
|
||
Also, <varname>wal_level</varname> must be set
|
||
to <literal>replica</literal> or higher to allow replication slots to
|
||
be used.
|
||
</para>
|
||
|
||
<para>
|
||
Note that this parameter also applies on the subscriber side, but with
|
||
a different meaning.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-keep-size" xreflabel="wal_keep_size">
|
||
<term><varname>wal_keep_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_keep_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the minimum size of past WAL files kept in the
|
||
<filename>pg_wal</filename>
|
||
directory, in case a standby server needs to fetch them for streaming
|
||
replication. If a standby
|
||
server connected to the sending server falls behind by more than
|
||
<varname>wal_keep_size</varname> megabytes, the sending server might
|
||
remove a WAL segment still needed by the standby, in which case the
|
||
replication connection will be terminated. Downstream connections
|
||
will also eventually fail as a result. (However, the standby
|
||
server can recover by fetching the segment from archive, if WAL
|
||
archiving is in use.)
|
||
</para>
|
||
|
||
<para>
|
||
This sets only the minimum size of segments retained in
|
||
<filename>pg_wal</filename>; the system might need to retain more segments
|
||
for WAL archival or to recover from a checkpoint. If
|
||
<varname>wal_keep_size</varname> is zero (the default), the system
|
||
doesn't keep any extra segments for standby purposes, so the number
|
||
of old WAL segments available to standby servers is a function of
|
||
the location of the previous checkpoint and status of WAL
|
||
archiving.
|
||
If this value is specified without units, it is taken as megabytes.
|
||
This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-slot-wal-keep-size" xreflabel="max_slot_wal_keep_size">
|
||
<term><varname>max_slot_wal_keep_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_slot_wal_keep_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specify the maximum size of WAL files
|
||
that <link linkend="streaming-replication-slots">replication
|
||
slots</link> are allowed to retain in the <filename>pg_wal</filename>
|
||
directory at checkpoint time.
|
||
If <varname>max_slot_wal_keep_size</varname> is -1 (the default),
|
||
replication slots may retain an unlimited amount of WAL files. Otherwise, if
|
||
restart_lsn of a replication slot falls behind the current LSN by more
|
||
than the given size, the standby using the slot may no longer be able
|
||
to continue replication due to removal of required WAL files. You
|
||
can see the WAL availability of replication slots
|
||
in <link linkend="view-pg-replication-slots">pg_replication_slots</link>.
|
||
If this value is specified without units, it is taken as megabytes.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-sender-timeout" xreflabel="wal_sender_timeout">
|
||
<term><varname>wal_sender_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_sender_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Terminate replication connections that are inactive for longer
|
||
than this amount of time. This is useful for
|
||
the sending server to detect a standby crash or network outage.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default value is 60 seconds.
|
||
A value of zero disables the timeout mechanism.
|
||
</para>
|
||
<para>
|
||
With a cluster distributed across multiple geographic
|
||
locations, using different values per location brings more flexibility
|
||
in the cluster management. A smaller value is useful for faster
|
||
failure detection with a standby having a low-latency network
|
||
connection, and a larger value helps in judging better the health
|
||
of a standby if located on a remote location, with a high-latency
|
||
network connection.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-track-commit-timestamp" xreflabel="track_commit_timestamp">
|
||
<term><varname>track_commit_timestamp</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>track_commit_timestamp</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Record commit time of transactions. This parameter
|
||
can only be set in <filename>postgresql.conf</filename> file or on the server
|
||
command line. The default value is <literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-standby-slot-names" xreflabel="standby_slot_names">
|
||
<term><varname>standby_slot_names</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>standby_slot_names</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A comma-separated list of streaming replication standby server slot names
|
||
that logical WAL sender processes will wait for. Logical WAL sender processes
|
||
will send decoded changes to plugins only after the specified replication
|
||
slots confirm receiving WAL. This guarantees that logical replication
|
||
failover slots do not consume changes until those changes are received
|
||
and flushed to corresponding physical standbys. If a
|
||
logical replication connection is meant to switch to a physical standby
|
||
after the standby is promoted, the physical replication slot for the
|
||
standby should be listed here. Note that logical replication will not
|
||
proceed if the slots specified in the
|
||
<varname>standby_slot_names</varname> do not exist or are invalidated.
|
||
Additionally, the replication management functions
|
||
<link linkend="pg-replication-slot-advance">
|
||
<function>pg_replication_slot_advance</function></link>,
|
||
<link linkend="pg-logical-slot-get-changes">
|
||
<function>pg_logical_slot_get_changes</function></link>, and
|
||
<link linkend="pg-logical-slot-peek-changes">
|
||
<function>pg_logical_slot_peek_changes</function></link>,
|
||
when used with logical failover slots, will block until all
|
||
physical slots specified in <varname>standby_slot_names</varname> have
|
||
confirmed WAL receipt.
|
||
</para>
|
||
<para>
|
||
The standbys corresponding to the physical replication slots in
|
||
<varname>standby_slot_names</varname> must configure
|
||
<literal>sync_replication_slots = true</literal> so they can receive
|
||
logical failover slot changes from the primary.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-replication-primary">
|
||
<title>Primary Server</title>
|
||
|
||
<para>
|
||
These parameters can be set on the primary server that is
|
||
to send replication data to one or more standby servers.
|
||
Note that in addition to these parameters,
|
||
<xref linkend="guc-wal-level"/> must be set appropriately on the primary
|
||
server, and optionally WAL archiving can be enabled as
|
||
well (see <xref linkend="runtime-config-wal-archiving"/>).
|
||
The values of these parameters on standby servers are irrelevant,
|
||
although you may wish to set them there in preparation for the
|
||
possibility of a standby becoming the primary.
|
||
</para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-synchronous-standby-names" xreflabel="synchronous_standby_names">
|
||
<term><varname>synchronous_standby_names</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>synchronous_standby_names</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a list of standby servers that can support
|
||
<firstterm>synchronous replication</firstterm>, as described in
|
||
<xref linkend="synchronous-replication"/>.
|
||
There will be one or more active synchronous standbys;
|
||
transactions waiting for commit will be allowed to proceed after
|
||
these standby servers confirm receipt of their data.
|
||
The synchronous standbys will be those whose names appear
|
||
in this list, and
|
||
that are both currently connected and streaming data in real-time
|
||
(as shown by a state of <literal>streaming</literal> in the
|
||
<link linkend="monitoring-pg-stat-replication-view">
|
||
<structname>pg_stat_replication</structname></link> view).
|
||
Specifying more than one synchronous standby can allow for very high
|
||
availability and protection against data loss.
|
||
</para>
|
||
<para>
|
||
The name of a standby server for this purpose is the
|
||
<varname>application_name</varname> setting of the standby, as set in the
|
||
standby's connection information. In case of a physical replication
|
||
standby, this should be set in the <varname>primary_conninfo</varname>
|
||
setting; the default is the setting of <xref linkend="guc-cluster-name"/>
|
||
if set, else <literal>walreceiver</literal>.
|
||
For logical replication, this can be set in the connection
|
||
information of the subscription, and it defaults to the
|
||
subscription name. For other replication stream consumers,
|
||
consult their documentation.
|
||
</para>
|
||
<para>
|
||
This parameter specifies a list of standby servers using
|
||
either of the following syntaxes:
|
||
<synopsis>
|
||
[FIRST] <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="parameter">standby_name</replaceable> [, ...] )
|
||
ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="parameter">standby_name</replaceable> [, ...] )
|
||
<replaceable class="parameter">standby_name</replaceable> [, ...]
|
||
</synopsis>
|
||
where <replaceable class="parameter">num_sync</replaceable> is
|
||
the number of synchronous standbys that transactions need to
|
||
wait for replies from,
|
||
and <replaceable class="parameter">standby_name</replaceable>
|
||
is the name of a standby server.
|
||
<literal>FIRST</literal> and <literal>ANY</literal> specify the method to choose
|
||
synchronous standbys from the listed servers.
|
||
</para>
|
||
<para>
|
||
The keyword <literal>FIRST</literal>, coupled with
|
||
<replaceable class="parameter">num_sync</replaceable>, specifies a
|
||
priority-based synchronous replication and makes transaction commits
|
||
wait until their WAL records are replicated to
|
||
<replaceable class="parameter">num_sync</replaceable> synchronous
|
||
standbys chosen based on their priorities. For example, a setting of
|
||
<literal>FIRST 3 (s1, s2, s3, s4)</literal> will cause each commit to wait for
|
||
replies from three higher-priority standbys chosen from standby servers
|
||
<literal>s1</literal>, <literal>s2</literal>, <literal>s3</literal> and <literal>s4</literal>.
|
||
The standbys whose names appear earlier in the list are given higher
|
||
priority and will be considered as synchronous. Other standby servers
|
||
appearing later in this list represent potential synchronous standbys.
|
||
If any of the current synchronous standbys disconnects for whatever
|
||
reason, it will be replaced immediately with the next-highest-priority
|
||
standby. The keyword <literal>FIRST</literal> is optional.
|
||
</para>
|
||
<para>
|
||
The keyword <literal>ANY</literal>, coupled with
|
||
<replaceable class="parameter">num_sync</replaceable>, specifies a
|
||
quorum-based synchronous replication and makes transaction commits
|
||
wait until their WAL records are replicated to <emphasis>at least</emphasis>
|
||
<replaceable class="parameter">num_sync</replaceable> listed standbys.
|
||
For example, a setting of <literal>ANY 3 (s1, s2, s3, s4)</literal> will cause
|
||
each commit to proceed as soon as at least any three standbys of
|
||
<literal>s1</literal>, <literal>s2</literal>, <literal>s3</literal> and <literal>s4</literal>
|
||
reply.
|
||
</para>
|
||
<para>
|
||
<literal>FIRST</literal> and <literal>ANY</literal> are case-insensitive. If these
|
||
keywords are used as the name of a standby server,
|
||
its <replaceable class="parameter">standby_name</replaceable> must
|
||
be double-quoted.
|
||
</para>
|
||
<para>
|
||
The third syntax was used before <productname>PostgreSQL</productname>
|
||
version 9.6 and is still supported. It's the same as the first syntax
|
||
with <literal>FIRST</literal> and
|
||
<replaceable class="parameter">num_sync</replaceable> equal to 1.
|
||
For example, <literal>FIRST 1 (s1, s2)</literal> and <literal>s1, s2</literal> have
|
||
the same meaning: either <literal>s1</literal> or <literal>s2</literal> is chosen
|
||
as a synchronous standby.
|
||
</para>
|
||
<para>
|
||
The special entry <literal>*</literal> matches any standby name.
|
||
</para>
|
||
<para>
|
||
There is no mechanism to enforce uniqueness of standby names. In case
|
||
of duplicates one of the matching standbys will be considered as
|
||
higher priority, though exactly which one is indeterminate.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
Each <replaceable class="parameter">standby_name</replaceable>
|
||
should have the form of a valid SQL identifier, unless it
|
||
is <literal>*</literal>. You can use double-quoting if necessary. But note
|
||
that <replaceable class="parameter">standby_name</replaceable>s are
|
||
compared to standby application names case-insensitively, whether
|
||
double-quoted or not.
|
||
</para>
|
||
</note>
|
||
<para>
|
||
If no synchronous standby names are specified here, then synchronous
|
||
replication is not enabled and transaction commits will not wait for
|
||
replication. This is the default configuration. Even when
|
||
synchronous replication is enabled, individual transactions can be
|
||
configured not to wait for replication by setting the
|
||
<xref linkend="guc-synchronous-commit"/> parameter to
|
||
<literal>local</literal> or <literal>off</literal>.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-replication-standby">
|
||
<title>Standby Servers</title>
|
||
|
||
<para>
|
||
These settings control the behavior of a
|
||
<link linkend="standby-server-operation">standby server</link>
|
||
that is
|
||
to receive replication data. Their values on the primary server
|
||
are irrelevant.
|
||
</para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-primary-conninfo" xreflabel="primary_conninfo">
|
||
<term><varname>primary_conninfo</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>primary_conninfo</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a connection string to be used for the standby server
|
||
to connect with a sending server. This string is in the format
|
||
described in <xref linkend="libpq-connstring"/>. If any option is
|
||
unspecified in this string, then the corresponding environment
|
||
variable (see <xref linkend="libpq-envars"/>) is checked. If the
|
||
environment variable is not set either, then
|
||
defaults are used.
|
||
</para>
|
||
<para>
|
||
The connection string should specify the host name (or address)
|
||
of the sending server, as well as the port number if it is not
|
||
the same as the standby server's default.
|
||
Also specify a user name corresponding to a suitably-privileged role
|
||
on the sending server (see
|
||
<xref linkend="streaming-replication-authentication"/>).
|
||
A password needs to be provided too, if the sender demands password
|
||
authentication. It can be provided in the
|
||
<varname>primary_conninfo</varname> string, or in a separate
|
||
<filename>~/.pgpass</filename> file on the standby server (use
|
||
<literal>replication</literal> as the database name).
|
||
</para>
|
||
<para>
|
||
For replication slot synchronization (see
|
||
<xref linkend="logicaldecoding-replication-slots-synchronization"/>),
|
||
it is also necessary to specify a valid <literal>dbname</literal>
|
||
in the <varname>primary_conninfo</varname> string. This will only be
|
||
used for slot synchronization. It is ignored for streaming.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
If this parameter is changed while the WAL receiver process is
|
||
running, that process is signaled to shut down and expected to
|
||
restart with the new setting (except if <varname>primary_conninfo</varname>
|
||
is an empty string).
|
||
This setting has no effect if the server is not in standby mode.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry id="guc-primary-slot-name" xreflabel="primary_slot_name">
|
||
<term><varname>primary_slot_name</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>primary_slot_name</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Optionally specifies an existing replication slot to be used when
|
||
connecting to the sending server via streaming replication to control
|
||
resource removal on the upstream node
|
||
(see <xref linkend="streaming-replication-slots"/>).
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
If this parameter is changed while the WAL receiver process is running,
|
||
that process is signaled to shut down and expected to restart with the
|
||
new setting.
|
||
This setting has no effect if <varname>primary_conninfo</varname> is not
|
||
set or the server is not in standby mode.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-hot-standby" xreflabel="hot_standby">
|
||
<term><varname>hot_standby</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>hot_standby</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies whether or not you can connect and run queries during
|
||
recovery, as described in <xref linkend="hot-standby"/>.
|
||
The default value is <literal>on</literal>.
|
||
This parameter can only be set at server start. It only has effect
|
||
during archive recovery or in standby mode.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-standby-archive-delay" xreflabel="max_standby_archive_delay">
|
||
<term><varname>max_standby_archive_delay</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_standby_archive_delay</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When hot standby is active, this parameter determines how long the
|
||
standby server should wait before canceling standby queries that
|
||
conflict with about-to-be-applied WAL entries, as described in
|
||
<xref linkend="hot-standby-conflict"/>.
|
||
<varname>max_standby_archive_delay</varname> applies when WAL data is
|
||
being read from WAL archive (and is therefore not current).
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default is 30 seconds.
|
||
A value of -1 allows the standby to wait forever for conflicting
|
||
queries to complete.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
<para>
|
||
Note that <varname>max_standby_archive_delay</varname> is not the same as the
|
||
maximum length of time a query can run before cancellation; rather it
|
||
is the maximum total time allowed to apply any one WAL segment's data.
|
||
Thus, if one query has resulted in significant delay earlier in the
|
||
WAL segment, subsequent conflicting queries will have much less grace
|
||
time.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-standby-streaming-delay" xreflabel="max_standby_streaming_delay">
|
||
<term><varname>max_standby_streaming_delay</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_standby_streaming_delay</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When hot standby is active, this parameter determines how long the
|
||
standby server should wait before canceling standby queries that
|
||
conflict with about-to-be-applied WAL entries, as described in
|
||
<xref linkend="hot-standby-conflict"/>.
|
||
<varname>max_standby_streaming_delay</varname> applies when WAL data is
|
||
being received via streaming replication.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default is 30 seconds.
|
||
A value of -1 allows the standby to wait forever for conflicting
|
||
queries to complete.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
<para>
|
||
Note that <varname>max_standby_streaming_delay</varname> is not the same as
|
||
the maximum length of time a query can run before cancellation; rather
|
||
it is the maximum total time allowed to apply WAL data once it has
|
||
been received from the primary server. Thus, if one query has
|
||
resulted in significant delay, subsequent conflicting queries will
|
||
have much less grace time until the standby server has caught up
|
||
again.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-receiver-create-temp-slot" xreflabel="wal_receiver_create_temp_slot">
|
||
<term><varname>wal_receiver_create_temp_slot</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_receiver_create_temp_slot</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies whether the WAL receiver process should create a temporary replication
|
||
slot on the remote instance when no permanent replication slot to use
|
||
has been configured (using <xref linkend="guc-primary-slot-name"/>).
|
||
The default is off. This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
If this parameter is changed while the WAL receiver process is running,
|
||
that process is signaled to shut down and expected to restart with
|
||
the new setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-receiver-status-interval" xreflabel="wal_receiver_status_interval">
|
||
<term><varname>wal_receiver_status_interval</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_receiver_status_interval</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the minimum frequency for the WAL receiver
|
||
process on the standby to send information about replication progress
|
||
to the primary or upstream standby, where it can be seen using the
|
||
<link linkend="monitoring-pg-stat-replication-view">
|
||
<structname>pg_stat_replication</structname></link>
|
||
view. The standby will report
|
||
the last write-ahead log location it has written, the last position it
|
||
has flushed to disk, and the last position it has applied.
|
||
This parameter's value is the maximum amount of time between reports.
|
||
Updates are sent each time the write or flush positions change, or as
|
||
often as specified by this parameter if set to a non-zero value.
|
||
There are additional cases where updates are sent while ignoring this
|
||
parameter; for example, when processing of the existing WAL completes
|
||
or when <varname>synchronous_commit</varname> is set to
|
||
<literal>remote_apply</literal>.
|
||
Thus, the apply position may lag slightly behind the true position.
|
||
If this value is specified without units, it is taken as seconds.
|
||
The default value is 10 seconds. This parameter can only be set in
|
||
the <filename>postgresql.conf</filename> file or on the server
|
||
command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-hot-standby-feedback" xreflabel="hot_standby_feedback">
|
||
<term><varname>hot_standby_feedback</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>hot_standby_feedback</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies whether or not a hot standby will send feedback to the primary
|
||
or upstream standby
|
||
about queries currently executing on the standby. This parameter can
|
||
be used to eliminate query cancels caused by cleanup records, but
|
||
can cause database bloat on the primary for some workloads.
|
||
Feedback messages will not be sent more frequently than once per
|
||
<varname>wal_receiver_status_interval</varname>. The default value is
|
||
<literal>off</literal>. This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
<para>
|
||
If cascaded replication is in use the feedback is passed upstream
|
||
until it eventually reaches the primary. Standbys make no other use
|
||
of feedback they receive other than to pass upstream.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-receiver-timeout" xreflabel="wal_receiver_timeout">
|
||
<term><varname>wal_receiver_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_receiver_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Terminate replication connections that are inactive for longer
|
||
than this amount of time. This is useful for
|
||
the receiving standby server to detect a primary node crash or network
|
||
outage.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default value is 60 seconds.
|
||
A value of zero disables the timeout mechanism.
|
||
This parameter can only be set in
|
||
the <filename>postgresql.conf</filename> file or on the server
|
||
command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-retrieve-retry-interval" xreflabel="wal_retrieve_retry_interval">
|
||
<term><varname>wal_retrieve_retry_interval</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_retrieve_retry_interval</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies how long the standby server should wait when WAL data is not
|
||
available from any sources (streaming replication,
|
||
local <filename>pg_wal</filename> or WAL archive) before trying
|
||
again to retrieve WAL data.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default value is 5 seconds.
|
||
This parameter can only be set in
|
||
the <filename>postgresql.conf</filename> file or on the server
|
||
command line.
|
||
</para>
|
||
<para>
|
||
This parameter is useful in configurations where a node in recovery
|
||
needs to control the amount of time to wait for new WAL data to be
|
||
available. For example, in archive recovery, it is possible to
|
||
make the recovery more responsive in the detection of a new WAL
|
||
file by reducing the value of this parameter. On a system with
|
||
low WAL activity, increasing it reduces the amount of requests necessary
|
||
to access WAL archives, something useful for example in cloud
|
||
environments where the number of times an infrastructure is accessed
|
||
is taken into account.
|
||
</para>
|
||
<para>
|
||
In logical replication, this parameter also limits how often a failing
|
||
replication apply worker will be respawned.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recovery-min-apply-delay" xreflabel="recovery_min_apply_delay">
|
||
<term><varname>recovery_min_apply_delay</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_min_apply_delay</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
By default, a standby server restores WAL records from the
|
||
sending server as soon as possible. It may be useful to have a time-delayed
|
||
copy of the data, offering opportunities to correct data loss errors.
|
||
This parameter allows you to delay recovery by a specified amount
|
||
of time. For example, if
|
||
you set this parameter to <literal>5min</literal>, the standby will
|
||
replay each transaction commit only when the system time on the standby
|
||
is at least five minutes past the commit time reported by the primary.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default is zero, adding no delay.
|
||
</para>
|
||
<para>
|
||
It is possible that the replication delay between servers exceeds the
|
||
value of this parameter, in which case no delay is added.
|
||
Note that the delay is calculated between the WAL time stamp as written
|
||
on primary and the current time on the standby. Delays in transfer
|
||
because of network lag or cascading replication configurations
|
||
may reduce the actual wait time significantly. If the system
|
||
clocks on primary and standby are not synchronized, this may lead to
|
||
recovery applying records earlier than expected; but that is not a
|
||
major issue because useful settings of this parameter are much larger
|
||
than typical time deviations between servers.
|
||
</para>
|
||
<para>
|
||
The delay occurs only on WAL records for transaction commits.
|
||
Other records are replayed as quickly as possible, which
|
||
is not a problem because MVCC visibility rules ensure their effects
|
||
are not visible until the corresponding commit record is applied.
|
||
</para>
|
||
<para>
|
||
The delay occurs once the database in recovery has reached a consistent
|
||
state, until the standby is promoted or triggered. After that the standby
|
||
will end recovery without further waiting.
|
||
</para>
|
||
<para>
|
||
WAL records must be kept on the standby until they are ready to be
|
||
applied. Therefore, longer delays will result in a greater accumulation
|
||
of WAL files, increasing disk space requirements for the standby's
|
||
<filename>pg_wal</filename> directory.
|
||
</para>
|
||
<para>
|
||
This parameter is intended for use with streaming replication deployments;
|
||
however, if the parameter is specified it will be honored in all cases
|
||
except crash recovery.
|
||
|
||
<varname>hot_standby_feedback</varname> will be delayed by use of this feature
|
||
which could lead to bloat on the primary; use both together with care.
|
||
|
||
<warning>
|
||
<para>
|
||
Synchronous replication is affected by this setting when <varname>synchronous_commit</varname>
|
||
is set to <literal>remote_apply</literal>; every <literal>COMMIT</literal>
|
||
will need to wait to be applied.
|
||
</para>
|
||
</warning>
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-sync-replication-slots" xreflabel="sync_replication_slots">
|
||
<term><varname>sync_replication_slots</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>sync_replication_slots</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
It enables a physical standby to synchronize logical failover slots
|
||
from the primary server so that logical subscribers can resume
|
||
replication from the new primary server after failover.
|
||
</para>
|
||
<para>
|
||
It is disabled by default. This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-replication-subscriber">
|
||
<title>Subscribers</title>
|
||
|
||
<para>
|
||
These settings control the behavior of a logical replication subscriber.
|
||
Their values on the publisher are irrelevant.
|
||
See <xref linkend="logical-replication-config"/> for more details.
|
||
</para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-max-replication-slots-subscriber" xreflabel="max_replication_slots">
|
||
<term><varname>max_replication_slots</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_replication_slots</varname> configuration parameter</primary>
|
||
<secondary>in a subscriber</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies how many replication origins (see
|
||
<xref linkend="replication-origins"/>) can be tracked simultaneously,
|
||
effectively limiting how many logical replication subscriptions can
|
||
be created on the server. Setting it to a lower value than the current
|
||
number of tracked replication origins (reflected in
|
||
<link linkend="view-pg-replication-origin-status">pg_replication_origin_status</link>)
|
||
will prevent the server from starting.
|
||
<literal>max_replication_slots</literal> must be set to at least the
|
||
number of subscriptions that will be added to the subscriber, plus some
|
||
reserve for table synchronization.
|
||
</para>
|
||
|
||
<para>
|
||
Note that this parameter also applies on a sending server, but with
|
||
a different meaning.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-logical-replication-workers" xreflabel="max_logical_replication_workers">
|
||
<term><varname>max_logical_replication_workers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_logical_replication_workers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies maximum number of logical replication workers. This includes
|
||
leader apply workers, parallel apply workers, and table synchronization
|
||
workers.
|
||
</para>
|
||
<para>
|
||
Logical replication workers are taken from the pool defined by
|
||
<varname>max_worker_processes</varname>.
|
||
</para>
|
||
<para>
|
||
The default value is 4. This parameter can only be set at server
|
||
start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-sync-workers-per-subscription" xreflabel="max_sync_workers_per_subscription">
|
||
<term><varname>max_sync_workers_per_subscription</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_sync_workers_per_subscription</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Maximum number of synchronization workers per subscription. This
|
||
parameter controls the amount of parallelism of the initial data copy
|
||
during the subscription initialization or when new tables are added.
|
||
</para>
|
||
<para>
|
||
Currently, there can be only one synchronization worker per table.
|
||
</para>
|
||
<para>
|
||
The synchronization workers are taken from the pool defined by
|
||
<varname>max_logical_replication_workers</varname>.
|
||
</para>
|
||
<para>
|
||
The default value is 2. This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command
|
||
line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-parallel-apply-workers-per-subscription" xreflabel="max_parallel_apply_workers_per_subscription">
|
||
<term><varname>max_parallel_apply_workers_per_subscription</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_parallel_apply_workers_per_subscription</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Maximum number of parallel apply workers per subscription. This
|
||
parameter controls the amount of parallelism for streaming of
|
||
in-progress transactions with subscription parameter
|
||
<literal>streaming = parallel</literal>.
|
||
</para>
|
||
<para>
|
||
The parallel apply workers are taken from the pool defined by
|
||
<varname>max_logical_replication_workers</varname>.
|
||
</para>
|
||
<para>
|
||
The default value is 2. This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command
|
||
line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-query">
|
||
<title>Query Planning</title>
|
||
|
||
<sect2 id="runtime-config-query-enable">
|
||
<title>Planner Method Configuration</title>
|
||
|
||
<para>
|
||
These configuration parameters provide a crude method of
|
||
influencing the query plans chosen by the query optimizer. If
|
||
the default plan chosen by the optimizer for a particular query
|
||
is not optimal, a <emphasis>temporary</emphasis> solution is to use one
|
||
of these configuration parameters to force the optimizer to
|
||
choose a different plan.
|
||
Better ways to improve the quality of the
|
||
plans chosen by the optimizer include adjusting the planner cost
|
||
constants (see <xref linkend="runtime-config-query-constants"/>),
|
||
running <link linkend="sql-analyze"><command>ANALYZE</command></link> manually, increasing
|
||
the value of the <xref
|
||
linkend="guc-default-statistics-target"/> configuration parameter,
|
||
and increasing the amount of statistics collected for
|
||
specific columns using <command>ALTER TABLE SET
|
||
STATISTICS</command>.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-enable-async-append" xreflabel="enable_async_append">
|
||
<term><varname>enable_async_append</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_async_append</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of async-aware
|
||
append plan types. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-bitmapscan" xreflabel="enable_bitmapscan">
|
||
<term><varname>enable_bitmapscan</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary>bitmap scan</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>enable_bitmapscan</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of bitmap-scan plan
|
||
types. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-gathermerge" xreflabel="enable_gathermerge">
|
||
<term><varname>enable_gathermerge</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_gathermerge</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of gather
|
||
merge plan types. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-hashagg" xreflabel="enable_hashagg">
|
||
<term><varname>enable_hashagg</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_hashagg</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of hashed
|
||
aggregation plan types. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-hashjoin" xreflabel="enable_hashjoin">
|
||
<term><varname>enable_hashjoin</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_hashjoin</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of hash-join plan
|
||
types. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-incremental-sort" xreflabel="enable_incremental_sort">
|
||
<term><varname>enable_incremental_sort</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_incremental_sort</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of incremental sort steps.
|
||
The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-indexscan" xreflabel="enable_indexscan">
|
||
<term><varname>enable_indexscan</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary>index scan</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>enable_indexscan</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of index-scan plan
|
||
types. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-indexonlyscan" xreflabel="enable_indexonlyscan">
|
||
<term><varname>enable_indexonlyscan</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_indexonlyscan</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of index-only-scan plan
|
||
types (see <xref linkend="indexes-index-only-scans"/>).
|
||
The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-material" xreflabel="enable_material">
|
||
<term><varname>enable_material</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_material</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of materialization.
|
||
It is impossible to suppress materialization entirely,
|
||
but turning this variable off prevents the planner from inserting
|
||
materialize nodes except in cases where it is required for correctness.
|
||
The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-memoize" xreflabel="enable_memoize">
|
||
<term><varname>enable_memoize</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_memoize</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of memoize plans for
|
||
caching results from parameterized scans inside nested-loop joins.
|
||
This plan type allows scans to the underlying plans to be skipped when
|
||
the results for the current parameters are already in the cache. Less
|
||
commonly looked up results may be evicted from the cache when more
|
||
space is required for new entries. The default is
|
||
<literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-mergejoin" xreflabel="enable_mergejoin">
|
||
<term><varname>enable_mergejoin</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_mergejoin</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of merge-join plan
|
||
types. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-nestloop" xreflabel="enable_nestloop">
|
||
<term><varname>enable_nestloop</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_nestloop</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of nested-loop join
|
||
plans. It is impossible to suppress nested-loop joins entirely,
|
||
but turning this variable off discourages the planner from using
|
||
one if there are other methods available. The default is
|
||
<literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-parallel-append" xreflabel="enable_parallel_append">
|
||
<term><varname>enable_parallel_append</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_parallel_append</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of parallel-aware
|
||
append plan types. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-parallel-hash" xreflabel="enable_parallel_hash">
|
||
<term><varname>enable_parallel_hash</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_parallel_hash</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of hash-join plan
|
||
types with parallel hash. Has no effect if hash-join plans are not
|
||
also enabled. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-partition-pruning" xreflabel="enable_partition_pruning">
|
||
<term><varname>enable_partition_pruning</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_partition_pruning</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's ability to eliminate a
|
||
partitioned table's partitions from query plans. This also controls
|
||
the planner's ability to generate query plans which allow the query
|
||
executor to remove (ignore) partitions during query execution. The
|
||
default is <literal>on</literal>.
|
||
See <xref linkend="ddl-partition-pruning"/> for details.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-partitionwise-join" xreflabel="enable_partitionwise_join">
|
||
<term><varname>enable_partitionwise_join</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_partitionwise_join</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of partitionwise join,
|
||
which allows a join between partitioned tables to be performed by
|
||
joining the matching partitions. Partitionwise join currently applies
|
||
only when the join conditions include all the partition keys, which
|
||
must be of the same data type and have one-to-one matching sets of
|
||
child partitions. Because partitionwise join planning can use
|
||
significantly more CPU time and memory during planning, the default is
|
||
<literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-partitionwise-aggregate" xreflabel="enable_partitionwise_aggregate">
|
||
<term><varname>enable_partitionwise_aggregate</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_partitionwise_aggregate</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of partitionwise grouping
|
||
or aggregation, which allows grouping or aggregation on partitioned
|
||
tables to be performed separately for each partition. If the
|
||
<literal>GROUP BY</literal> clause does not include the partition
|
||
keys, only partial aggregation can be performed on a per-partition
|
||
basis, and finalization must be performed later. Because
|
||
partitionwise grouping or aggregation can use significantly more CPU
|
||
time and memory during planning, the default is
|
||
<literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-presorted-aggregate" xreflabel="enable_presorted_aggregate">
|
||
<term><varname>enable_presorted_aggregate</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_presorted_aggregate</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls if the query planner will produce a plan which will provide
|
||
rows which are presorted in the order required for the query's
|
||
<literal>ORDER BY</literal> / <literal>DISTINCT</literal> aggregate
|
||
functions. When disabled, the query planner will produce a plan which
|
||
will always require the executor to perform a sort before performing
|
||
aggregation of each aggregate function containing an
|
||
<literal>ORDER BY</literal> or <literal>DISTINCT</literal> clause.
|
||
When enabled, the planner will try to produce a more efficient plan
|
||
which provides input to the aggregate functions which is presorted in
|
||
the order they require for aggregation. The default value is
|
||
<literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-seqscan" xreflabel="enable_seqscan">
|
||
<term><varname>enable_seqscan</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary>sequential scan</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>enable_seqscan</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of sequential scan
|
||
plan types. It is impossible to suppress sequential scans
|
||
entirely, but turning this variable off discourages the planner
|
||
from using one if there are other methods available. The
|
||
default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-sort" xreflabel="enable_sort">
|
||
<term><varname>enable_sort</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_sort</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of explicit sort
|
||
steps. It is impossible to suppress explicit sorts entirely,
|
||
but turning this variable off discourages the planner from
|
||
using one if there are other methods available. The default
|
||
is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-enable-tidscan" xreflabel="enable_tidscan">
|
||
<term><varname>enable_tidscan</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>enable_tidscan</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables the query planner's use of <acronym>TID</acronym>
|
||
scan plan types. The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
<sect2 id="runtime-config-query-constants">
|
||
<title>Planner Cost Constants</title>
|
||
|
||
<para>
|
||
The <firstterm>cost</firstterm> variables described in this section are measured
|
||
on an arbitrary scale. Only their relative values matter, hence
|
||
scaling them all up or down by the same factor will result in no change
|
||
in the planner's choices. By default, these cost variables are based on
|
||
the cost of sequential page fetches; that is,
|
||
<varname>seq_page_cost</varname> is conventionally set to <literal>1.0</literal>
|
||
and the other cost variables are set with reference to that. But
|
||
you can use a different scale if you prefer, such as actual execution
|
||
times in milliseconds on a particular machine.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
Unfortunately, there is no well-defined method for determining ideal
|
||
values for the cost variables. They are best treated as averages over
|
||
the entire mix of queries that a particular installation will receive. This
|
||
means that changing them on the basis of just a few experiments is very
|
||
risky.
|
||
</para>
|
||
</note>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-seq-page-cost" xreflabel="seq_page_cost">
|
||
<term><varname>seq_page_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>seq_page_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's estimate of the cost of a disk page fetch
|
||
that is part of a series of sequential fetches. The default is 1.0.
|
||
This value can be overridden for tables and indexes in a particular
|
||
tablespace by setting the tablespace parameter of the same name
|
||
(see <xref linkend="sql-altertablespace"/>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-random-page-cost" xreflabel="random_page_cost">
|
||
<term><varname>random_page_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>random_page_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's estimate of the cost of a
|
||
non-sequentially-fetched disk page. The default is 4.0.
|
||
This value can be overridden for tables and indexes in a particular
|
||
tablespace by setting the tablespace parameter of the same name
|
||
(see <xref linkend="sql-altertablespace"/>).
|
||
</para>
|
||
|
||
<para>
|
||
Reducing this value relative to <varname>seq_page_cost</varname>
|
||
will cause the system to prefer index scans; raising it will
|
||
make index scans look relatively more expensive. You can raise
|
||
or lower both values together to change the importance of disk I/O
|
||
costs relative to CPU costs, which are described by the following
|
||
parameters.
|
||
</para>
|
||
|
||
<para>
|
||
Random access to mechanical disk storage is normally much more expensive
|
||
than four times sequential access. However, a lower default is used
|
||
(4.0) because the majority of random accesses to disk, such as indexed
|
||
reads, are assumed to be in cache. The default value can be thought of
|
||
as modeling random access as 40 times slower than sequential, while
|
||
expecting 90% of random reads to be cached.
|
||
</para>
|
||
|
||
<para>
|
||
If you believe a 90% cache rate is an incorrect assumption
|
||
for your workload, you can increase random_page_cost to better
|
||
reflect the true cost of random storage reads. Correspondingly,
|
||
if your data is likely to be completely in cache, such as when
|
||
the database is smaller than the total server memory, decreasing
|
||
random_page_cost can be appropriate. Storage that has a low random
|
||
read cost relative to sequential, e.g., solid-state drives, might
|
||
also be better modeled with a lower value for random_page_cost,
|
||
e.g., <literal>1.1</literal>.
|
||
</para>
|
||
|
||
<tip>
|
||
<para>
|
||
Although the system will let you set <varname>random_page_cost</varname> to
|
||
less than <varname>seq_page_cost</varname>, it is not physically sensible
|
||
to do so. However, setting them equal makes sense if the database
|
||
is entirely cached in RAM, since in that case there is no penalty
|
||
for touching pages out of sequence. Also, in a heavily-cached
|
||
database you should lower both values relative to the CPU parameters,
|
||
since the cost of fetching a page already in RAM is much smaller
|
||
than it would normally be.
|
||
</para>
|
||
</tip>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-cpu-tuple-cost" xreflabel="cpu_tuple_cost">
|
||
<term><varname>cpu_tuple_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>cpu_tuple_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's estimate of the cost of processing
|
||
each row during a query.
|
||
The default is 0.01.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-cpu-index-tuple-cost" xreflabel="cpu_index_tuple_cost">
|
||
<term><varname>cpu_index_tuple_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>cpu_index_tuple_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's estimate of the cost of processing
|
||
each index entry during an index scan.
|
||
The default is 0.005.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-cpu-operator-cost" xreflabel="cpu_operator_cost">
|
||
<term><varname>cpu_operator_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>cpu_operator_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's estimate of the cost of processing each
|
||
operator or function executed during a query.
|
||
The default is 0.0025.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-parallel-setup-cost" xreflabel="parallel_setup_cost">
|
||
<term><varname>parallel_setup_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>parallel_setup_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's estimate of the cost of launching parallel worker
|
||
processes.
|
||
The default is 1000.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-parallel-tuple-cost" xreflabel="parallel_tuple_cost">
|
||
<term><varname>parallel_tuple_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>parallel_tuple_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's estimate of the cost of transferring one tuple
|
||
from a parallel worker process to another process.
|
||
The default is 0.1.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-min-parallel-table-scan-size" xreflabel="min_parallel_table_scan_size">
|
||
<term><varname>min_parallel_table_scan_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>min_parallel_table_scan_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the minimum amount of table data that must be scanned in order
|
||
for a parallel scan to be considered. For a parallel sequential scan,
|
||
the amount of table data scanned is always equal to the size of the
|
||
table, but when indexes are used the amount of table data
|
||
scanned will normally be less.
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default is 8 megabytes (<literal>8MB</literal>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-min-parallel-index-scan-size" xreflabel="min_parallel_index_scan_size">
|
||
<term><varname>min_parallel_index_scan_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>min_parallel_index_scan_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the minimum amount of index data that must be scanned in order
|
||
for a parallel scan to be considered. Note that a parallel index scan
|
||
typically won't touch the entire index; it is the number of pages
|
||
which the planner believes will actually be touched by the scan which
|
||
is relevant. This parameter is also used to decide whether a
|
||
particular index can participate in a parallel vacuum. See
|
||
<xref linkend="sql-vacuum"/>.
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default is 512 kilobytes (<literal>512kB</literal>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-effective-cache-size" xreflabel="effective_cache_size">
|
||
<term><varname>effective_cache_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>effective_cache_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's assumption about the effective size of the
|
||
disk cache that is available to a single query. This is
|
||
factored into estimates of the cost of using an index; a
|
||
higher value makes it more likely index scans will be used, a
|
||
lower value makes it more likely sequential scans will be
|
||
used. When setting this parameter you should consider both
|
||
<productname>PostgreSQL</productname>'s shared buffers and the
|
||
portion of the kernel's disk cache that will be used for
|
||
<productname>PostgreSQL</productname> data files, though some
|
||
data might exist in both places. Also, take
|
||
into account the expected number of concurrent queries on different
|
||
tables, since they will have to share the available
|
||
space. This parameter has no effect on the size of shared
|
||
memory allocated by <productname>PostgreSQL</productname>, nor
|
||
does it reserve kernel disk cache; it is used only for estimation
|
||
purposes. The system also does not assume data remains in
|
||
the disk cache between queries.
|
||
If this value is specified without units, it is taken as blocks,
|
||
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB.
|
||
The default is 4 gigabytes (<literal>4GB</literal>).
|
||
(If <symbol>BLCKSZ</symbol> is not 8kB, the default value scales
|
||
proportionally to it.)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit-above-cost" xreflabel="jit_above_cost">
|
||
<term><varname>jit_above_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>jit_above_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the query cost above which JIT compilation is activated, if
|
||
enabled (see <xref linkend="jit"/>).
|
||
Performing <acronym>JIT</acronym> costs planning time but can
|
||
accelerate query execution.
|
||
Setting this to <literal>-1</literal> disables JIT compilation.
|
||
The default is <literal>100000</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit-inline-above-cost" xreflabel="jit_inline_above_cost">
|
||
<term><varname>jit_inline_above_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>jit_inline_above_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the query cost above which JIT compilation attempts to inline
|
||
functions and operators. Inlining adds planning time, but can
|
||
improve execution speed. It is not meaningful to set this to less
|
||
than <varname>jit_above_cost</varname>.
|
||
Setting this to <literal>-1</literal> disables inlining.
|
||
The default is <literal>500000</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit-optimize-above-cost" xreflabel="jit_optimize_above_cost">
|
||
<term><varname>jit_optimize_above_cost</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>jit_optimize_above_cost</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the query cost above which JIT compilation applies expensive
|
||
optimizations. Such optimization adds planning time, but can improve
|
||
execution speed. It is not meaningful to set this to less
|
||
than <varname>jit_above_cost</varname>, and it is unlikely to be
|
||
beneficial to set it to more
|
||
than <varname>jit_inline_above_cost</varname>.
|
||
Setting this to <literal>-1</literal> disables expensive optimizations.
|
||
The default is <literal>500000</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</sect2>
|
||
<sect2 id="runtime-config-query-geqo">
|
||
<title>Genetic Query Optimizer</title>
|
||
|
||
<para>
|
||
The genetic query optimizer (GEQO) is an algorithm that does query
|
||
planning using heuristic searching. This reduces planning time for
|
||
complex queries (those joining many relations), at the cost of producing
|
||
plans that are sometimes inferior to those found by the normal
|
||
exhaustive-search algorithm.
|
||
For more information see <xref linkend="geqo"/>.
|
||
</para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-geqo" xreflabel="geqo">
|
||
<term><varname>geqo</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary>genetic query optimization</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary>GEQO</primary>
|
||
<see>genetic query optimization</see>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>geqo</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables or disables genetic query optimization.
|
||
This is on by default. It is usually best not to turn it off in
|
||
production; the <varname>geqo_threshold</varname> variable provides
|
||
more granular control of GEQO.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-geqo-threshold" xreflabel="geqo_threshold">
|
||
<term><varname>geqo_threshold</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>geqo_threshold</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Use genetic query optimization to plan queries with at least
|
||
this many <literal>FROM</literal> items involved. (Note that a
|
||
<literal>FULL OUTER JOIN</literal> construct counts as only one <literal>FROM</literal>
|
||
item.) The default is 12. For simpler queries it is usually best
|
||
to use the regular, exhaustive-search planner, but for queries with
|
||
many tables the exhaustive search takes too long, often
|
||
longer than the penalty of executing a suboptimal plan. Thus,
|
||
a threshold on the size of the query is a convenient way to manage
|
||
use of GEQO.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-geqo-effort" xreflabel="geqo_effort">
|
||
<term><varname>geqo_effort</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>geqo_effort</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls the trade-off between planning time and query plan
|
||
quality in GEQO. This variable must be an integer in the
|
||
range from 1 to 10. The default value is five. Larger values
|
||
increase the time spent doing query planning, but also
|
||
increase the likelihood that an efficient query plan will be
|
||
chosen.
|
||
</para>
|
||
|
||
<para>
|
||
<varname>geqo_effort</varname> doesn't actually do anything
|
||
directly; it is only used to compute the default values for
|
||
the other variables that influence GEQO behavior (described
|
||
below). If you prefer, you can set the other parameters by
|
||
hand instead.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-geqo-pool-size" xreflabel="geqo_pool_size">
|
||
<term><varname>geqo_pool_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>geqo_pool_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls the pool size used by GEQO, that is the
|
||
number of individuals in the genetic population. It must be
|
||
at least two, and useful values are typically 100 to 1000. If
|
||
it is set to zero (the default setting) then a suitable
|
||
value is chosen based on <varname>geqo_effort</varname> and
|
||
the number of tables in the query.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-geqo-generations" xreflabel="geqo_generations">
|
||
<term><varname>geqo_generations</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>geqo_generations</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls the number of generations used by GEQO, that is
|
||
the number of iterations of the algorithm. It must
|
||
be at least one, and useful values are in the same range as
|
||
the pool size. If it is set to zero (the default setting)
|
||
then a suitable value is chosen based on
|
||
<varname>geqo_pool_size</varname>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-geqo-selection-bias" xreflabel="geqo_selection_bias">
|
||
<term><varname>geqo_selection_bias</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>geqo_selection_bias</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls the selection bias used by GEQO. The selection bias
|
||
is the selective pressure within the population. Values can be
|
||
from 1.50 to 2.00; the latter is the default.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-geqo-seed" xreflabel="geqo_seed">
|
||
<term><varname>geqo_seed</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>geqo_seed</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls the initial value of the random number generator used
|
||
by GEQO to select random paths through the join order search space.
|
||
The value can range from zero (the default) to one. Varying the
|
||
value changes the set of join paths explored, and may result in a
|
||
better or worse best path being found.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
<sect2 id="runtime-config-query-other">
|
||
<title>Other Planner Options</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-default-statistics-target" xreflabel="default_statistics_target">
|
||
<term><varname>default_statistics_target</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>default_statistics_target</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the default statistics target for table columns without
|
||
a column-specific target set via <command>ALTER TABLE
|
||
SET STATISTICS</command>. Larger values increase the time needed to
|
||
do <command>ANALYZE</command>, but might improve the quality of the
|
||
planner's estimates. The default is 100. For more information
|
||
on the use of statistics by the <productname>PostgreSQL</productname>
|
||
query planner, refer to <xref linkend="planner-stats"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-constraint-exclusion" xreflabel="constraint_exclusion">
|
||
<term><varname>constraint_exclusion</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary>constraint exclusion</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>constraint_exclusion</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls the query planner's use of table constraints to
|
||
optimize queries.
|
||
The allowed values of <varname>constraint_exclusion</varname> are
|
||
<literal>on</literal> (examine constraints for all tables),
|
||
<literal>off</literal> (never examine constraints), and
|
||
<literal>partition</literal> (examine constraints only for inheritance
|
||
child tables and <literal>UNION ALL</literal> subqueries).
|
||
<literal>partition</literal> is the default setting.
|
||
It is often used with traditional inheritance trees to improve
|
||
performance.
|
||
</para>
|
||
|
||
<para>
|
||
When this parameter allows it for a particular table, the planner
|
||
compares query conditions with the table's <literal>CHECK</literal>
|
||
constraints, and omits scanning tables for which the conditions
|
||
contradict the constraints. For example:
|
||
|
||
<programlisting>
|
||
CREATE TABLE parent(key integer, ...);
|
||
CREATE TABLE child1000(check (key between 1000 and 1999)) INHERITS(parent);
|
||
CREATE TABLE child2000(check (key between 2000 and 2999)) INHERITS(parent);
|
||
...
|
||
SELECT * FROM parent WHERE key = 2400;
|
||
</programlisting>
|
||
|
||
With constraint exclusion enabled, this <command>SELECT</command>
|
||
will not scan <structname>child1000</structname> at all, improving performance.
|
||
</para>
|
||
|
||
<para>
|
||
Currently, constraint exclusion is enabled by default
|
||
only for cases that are often used to implement table partitioning via
|
||
inheritance trees. Turning it on for all tables imposes extra
|
||
planning overhead that is quite noticeable on simple queries, and most
|
||
often will yield no benefit for simple queries. If you have no
|
||
tables that are partitioned using traditional inheritance, you might
|
||
prefer to turn it off entirely. (Note that the equivalent feature for
|
||
partitioned tables is controlled by a separate parameter,
|
||
<xref linkend="guc-enable-partition-pruning"/>.)
|
||
</para>
|
||
|
||
<para>
|
||
Refer to <xref linkend="ddl-partitioning-constraint-exclusion"/> for
|
||
more information on using constraint exclusion to implement
|
||
partitioning.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-cursor-tuple-fraction" xreflabel="cursor_tuple_fraction">
|
||
<term><varname>cursor_tuple_fraction</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>cursor_tuple_fraction</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's estimate of the fraction of a cursor's rows that
|
||
will be retrieved. The default is 0.1. Smaller values of this
|
||
setting bias the planner towards using <quote>fast start</quote> plans
|
||
for cursors, which will retrieve the first few rows quickly while
|
||
perhaps taking a long time to fetch all rows. Larger values
|
||
put more emphasis on the total estimated time. At the maximum
|
||
setting of 1.0, cursors are planned exactly like regular queries,
|
||
considering only the total estimated time and not how soon the
|
||
first rows might be delivered.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-from-collapse-limit" xreflabel="from_collapse_limit">
|
||
<term><varname>from_collapse_limit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>from_collapse_limit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The planner will merge sub-queries into upper queries if the
|
||
resulting <literal>FROM</literal> list would have no more than
|
||
this many items. Smaller values reduce planning time but might
|
||
yield inferior query plans. The default is eight.
|
||
For more information see <xref linkend="explicit-joins"/>.
|
||
</para>
|
||
|
||
<para>
|
||
Setting this value to <xref linkend="guc-geqo-threshold"/> or more
|
||
may trigger use of the GEQO planner, resulting in non-optimal
|
||
plans. See <xref linkend="runtime-config-query-geqo"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit" xreflabel="jit">
|
||
<term><varname>jit</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>jit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Determines whether <acronym>JIT</acronym> compilation may be used by
|
||
<productname>PostgreSQL</productname>, if available (see <xref
|
||
linkend="jit"/>).
|
||
The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-join-collapse-limit" xreflabel="join_collapse_limit">
|
||
<term><varname>join_collapse_limit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>join_collapse_limit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The planner will rewrite explicit <literal>JOIN</literal>
|
||
constructs (except <literal>FULL JOIN</literal>s) into lists of
|
||
<literal>FROM</literal> items whenever a list of no more than this many items
|
||
would result. Smaller values reduce planning time but might
|
||
yield inferior query plans.
|
||
</para>
|
||
|
||
<para>
|
||
By default, this variable is set the same as
|
||
<varname>from_collapse_limit</varname>, which is appropriate
|
||
for most uses. Setting it to 1 prevents any reordering of
|
||
explicit <literal>JOIN</literal>s. Thus, the explicit join order
|
||
specified in the query will be the actual order in which the
|
||
relations are joined. Because the query planner does not always choose
|
||
the optimal join order, advanced users can elect to
|
||
temporarily set this variable to 1, and then specify the join
|
||
order they desire explicitly.
|
||
For more information see <xref linkend="explicit-joins"/>.
|
||
</para>
|
||
|
||
<para>
|
||
Setting this value to <xref linkend="guc-geqo-threshold"/> or more
|
||
may trigger use of the GEQO planner, resulting in non-optimal
|
||
plans. See <xref linkend="runtime-config-query-geqo"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-plan-cache-mode" xreflabel="plan_cache_mode">
|
||
<term><varname>plan_cache_mode</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>plan_cache_mode</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Prepared statements (either explicitly prepared or implicitly
|
||
generated, for example by PL/pgSQL) can be executed using custom or
|
||
generic plans. Custom plans are made afresh for each execution
|
||
using its specific set of parameter values, while generic plans do
|
||
not rely on the parameter values and can be re-used across
|
||
executions. Thus, use of a generic plan saves planning time, but if
|
||
the ideal plan depends strongly on the parameter values then a
|
||
generic plan may be inefficient. The choice between these options
|
||
is normally made automatically, but it can be overridden
|
||
with <varname>plan_cache_mode</varname>.
|
||
The allowed values are <literal>auto</literal> (the default),
|
||
<literal>force_custom_plan</literal> and
|
||
<literal>force_generic_plan</literal>.
|
||
This setting is considered when a cached plan is to be executed,
|
||
not when it is prepared.
|
||
For more information see <xref linkend="sql-prepare"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recursive-worktable-factor" xreflabel="recursive_worktable_factor">
|
||
<term><varname>recursive_worktable_factor</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>recursive_worktable_factor</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the planner's estimate of the average size of the working
|
||
table of a <link linkend="queries-with-recursive">recursive
|
||
query</link>, as a multiple of the estimated size of the initial
|
||
non-recursive term of the query. This helps the planner choose
|
||
the most appropriate method for joining the working table to the
|
||
query's other tables.
|
||
The default value is <literal>10.0</literal>. A smaller value
|
||
such as <literal>1.0</literal> can be helpful when the recursion
|
||
has low <quote>fan-out</quote> from one step to the next, as for
|
||
example in shortest-path queries. Graph analytics queries may
|
||
benefit from larger-than-default values.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-logging">
|
||
<title>Error Reporting and Logging</title>
|
||
|
||
<indexterm zone="runtime-config-logging">
|
||
<primary>server log</primary>
|
||
</indexterm>
|
||
|
||
<sect2 id="runtime-config-logging-where">
|
||
<title>Where to Log</title>
|
||
|
||
<indexterm zone="runtime-config-logging-where">
|
||
<primary>where to log</primary>
|
||
</indexterm>
|
||
|
||
<indexterm>
|
||
<primary>current_logfiles</primary>
|
||
<secondary>and the log_destination configuration parameter</secondary>
|
||
</indexterm>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-log-destination" xreflabel="log_destination">
|
||
<term><varname>log_destination</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>log_destination</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
<productname>PostgreSQL</productname> supports several methods
|
||
for logging server messages, including
|
||
<systemitem>stderr</systemitem>, <systemitem>csvlog</systemitem>,
|
||
<systemitem>jsonlog</systemitem>, and
|
||
<systemitem>syslog</systemitem>. On Windows,
|
||
<systemitem>eventlog</systemitem> is also supported. Set this
|
||
parameter to a list of desired log destinations separated by
|
||
commas. The default is to log to <systemitem>stderr</systemitem>
|
||
only.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
<para>
|
||
If <systemitem>csvlog</systemitem> is included in <varname>log_destination</varname>,
|
||
log entries are output in <quote>comma separated
|
||
value</quote> (<acronym>CSV</acronym>) format, which is convenient for
|
||
loading logs into programs.
|
||
See <xref linkend="runtime-config-logging-csvlog"/> for details.
|
||
<xref linkend="guc-logging-collector"/> must be enabled to generate
|
||
CSV-format log output.
|
||
</para>
|
||
<para>
|
||
If <systemitem>jsonlog</systemitem> is included in
|
||
<varname>log_destination</varname>, log entries are output in
|
||
<acronym>JSON</acronym> format, which is convenient for loading logs
|
||
into programs.
|
||
See <xref linkend="runtime-config-logging-jsonlog"/> for details.
|
||
<xref linkend="guc-logging-collector"/> must be enabled to generate
|
||
JSON-format log output.
|
||
</para>
|
||
<para>
|
||
When either <systemitem>stderr</systemitem>,
|
||
<systemitem>csvlog</systemitem> or <systemitem>jsonlog</systemitem> are
|
||
included, the file <filename>current_logfiles</filename> is created to
|
||
record the location of the log file(s) currently in use by the logging
|
||
collector and the associated logging destination. This provides a
|
||
convenient way to find the logs currently in use by the instance. Here
|
||
is an example of this file's content:
|
||
<programlisting>
|
||
stderr log/postgresql.log
|
||
csvlog log/postgresql.csv
|
||
jsonlog log/postgresql.json
|
||
</programlisting>
|
||
|
||
<filename>current_logfiles</filename> is recreated when a new log file
|
||
is created as an effect of rotation, and
|
||
when <varname>log_destination</varname> is reloaded. It is removed when
|
||
none of <systemitem>stderr</systemitem>,
|
||
<systemitem>csvlog</systemitem> or <systemitem>jsonlog</systemitem> are
|
||
included in <varname>log_destination</varname>, and when the logging
|
||
collector is disabled.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
On most Unix systems, you will need to alter the configuration of
|
||
your system's <application>syslog</application> daemon in order
|
||
to make use of the <systemitem>syslog</systemitem> option for
|
||
<varname>log_destination</varname>. <productname>PostgreSQL</productname>
|
||
can log to <application>syslog</application> facilities
|
||
<literal>LOCAL0</literal> through <literal>LOCAL7</literal> (see <xref
|
||
linkend="guc-syslog-facility"/>), but the default
|
||
<application>syslog</application> configuration on most platforms
|
||
will discard all such messages. You will need to add something like:
|
||
<programlisting>
|
||
local0.* /var/log/postgresql
|
||
</programlisting>
|
||
to the <application>syslog</application> daemon's configuration file
|
||
to make it work.
|
||
</para>
|
||
<para>
|
||
On Windows, when you use the <literal>eventlog</literal>
|
||
option for <varname>log_destination</varname>, you should
|
||
register an event source and its library with the operating
|
||
system so that the Windows Event Viewer can display event
|
||
log messages cleanly.
|
||
See <xref linkend="event-log-registration"/> for details.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-logging-collector" xreflabel="logging_collector">
|
||
<term><varname>logging_collector</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>logging_collector</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter enables the <firstterm>logging collector</firstterm>, which
|
||
is a background process that captures log messages
|
||
sent to <systemitem>stderr</systemitem> and redirects them into log files.
|
||
This approach is often more useful than
|
||
logging to <application>syslog</application>, since some types of messages
|
||
might not appear in <application>syslog</application> output. (One common
|
||
example is dynamic-linker failure messages; another is error messages
|
||
produced by scripts such as <varname>archive_command</varname>.)
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
It is possible to log to <systemitem>stderr</systemitem> without using the
|
||
logging collector; the log messages will just go to wherever the
|
||
server's <systemitem>stderr</systemitem> is directed. However, that method is
|
||
only suitable for low log volumes, since it provides no convenient
|
||
way to rotate log files. Also, on some platforms not using the
|
||
logging collector can result in lost or garbled log output, because
|
||
multiple processes writing concurrently to the same log file can
|
||
overwrite each other's output.
|
||
</para>
|
||
</note>
|
||
|
||
<note>
|
||
<para>
|
||
The logging collector is designed to never lose messages. This means
|
||
that in case of extremely high load, server processes could be
|
||
blocked while trying to send additional log messages when the
|
||
collector has fallen behind. In contrast, <application>syslog</application>
|
||
prefers to drop messages if it cannot write them, which means it
|
||
may fail to log some messages in such cases but it will not block
|
||
the rest of the system.
|
||
</para>
|
||
</note>
|
||
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-directory" xreflabel="log_directory">
|
||
<term><varname>log_directory</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>log_directory</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When <varname>logging_collector</varname> is enabled,
|
||
this parameter determines the directory in which log files will be created.
|
||
It can be specified as an absolute path, or relative to the
|
||
cluster data directory.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
The default is <literal>log</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-filename" xreflabel="log_filename">
|
||
<term><varname>log_filename</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>log_filename</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When <varname>logging_collector</varname> is enabled,
|
||
this parameter sets the file names of the created log files. The value
|
||
is treated as a <function>strftime</function> pattern,
|
||
so <literal>%</literal>-escapes can be used to specify time-varying
|
||
file names. (Note that if there are
|
||
any time-zone-dependent <literal>%</literal>-escapes, the computation
|
||
is done in the zone specified
|
||
by <xref linkend="guc-log-timezone"/>.)
|
||
The supported <literal>%</literal>-escapes are similar to those
|
||
listed in the Open Group's <ulink
|
||
url="https://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html">strftime
|
||
</ulink> specification.
|
||
Note that the system's <function>strftime</function> is not used
|
||
directly, so platform-specific (nonstandard) extensions do not work.
|
||
The default is <literal>postgresql-%Y-%m-%d_%H%M%S.log</literal>.
|
||
</para>
|
||
<para>
|
||
If you specify a file name without escapes, you should plan to
|
||
use a log rotation utility to avoid eventually filling the
|
||
entire disk. In releases prior to 8.4, if
|
||
no <literal>%</literal> escapes were
|
||
present, <productname>PostgreSQL</productname> would append
|
||
the epoch of the new log file's creation time, but this is no
|
||
longer the case.
|
||
</para>
|
||
<para>
|
||
If CSV-format output is enabled in <varname>log_destination</varname>,
|
||
<literal>.csv</literal> will be appended to the timestamped
|
||
log file name to create the file name for CSV-format output.
|
||
(If <varname>log_filename</varname> ends in <literal>.log</literal>, the suffix is
|
||
replaced instead.)
|
||
</para>
|
||
<para>
|
||
If JSON-format output is enabled in <varname>log_destination</varname>,
|
||
<literal>.json</literal> will be appended to the timestamped
|
||
log file name to create the file name for JSON-format output.
|
||
(If <varname>log_filename</varname> ends in <literal>.log</literal>, the suffix is
|
||
replaced instead.)
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-file-mode" xreflabel="log_file_mode">
|
||
<term><varname>log_file_mode</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_file_mode</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
On Unix systems this parameter sets the permissions for log files
|
||
when <varname>logging_collector</varname> is enabled. (On Microsoft
|
||
Windows this parameter is ignored.)
|
||
The parameter value is expected to be a numeric mode
|
||
specified in the format accepted by the
|
||
<function>chmod</function> and <function>umask</function>
|
||
system calls. (To use the customary octal format the number
|
||
must start with a <literal>0</literal> (zero).)
|
||
</para>
|
||
<para>
|
||
The default permissions are <literal>0600</literal>, meaning only the
|
||
server owner can read or write the log files. The other commonly
|
||
useful setting is <literal>0640</literal>, allowing members of the owner's
|
||
group to read the files. Note however that to make use of such a
|
||
setting, you'll need to alter <xref linkend="guc-log-directory"/> to
|
||
store the files somewhere outside the cluster data directory. In
|
||
any case, it's unwise to make the log files world-readable, since
|
||
they might contain sensitive data.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-rotation-age" xreflabel="log_rotation_age">
|
||
<term><varname>log_rotation_age</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_rotation_age</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When <varname>logging_collector</varname> is enabled,
|
||
this parameter determines the maximum amount of time to use an
|
||
individual log file, after which a new log file will be created.
|
||
If this value is specified without units, it is taken as minutes.
|
||
The default is 24 hours.
|
||
Set to zero to disable time-based creation of new log files.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-rotation-size" xreflabel="log_rotation_size">
|
||
<term><varname>log_rotation_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_rotation_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When <varname>logging_collector</varname> is enabled,
|
||
this parameter determines the maximum size of an individual log file.
|
||
After this amount of data has been emitted into a log file,
|
||
a new log file will be created.
|
||
If this value is specified without units, it is taken as kilobytes.
|
||
The default is 10 megabytes.
|
||
Set to zero to disable size-based creation of new log files.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-truncate-on-rotation" xreflabel="log_truncate_on_rotation">
|
||
<term><varname>log_truncate_on_rotation</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_truncate_on_rotation</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When <varname>logging_collector</varname> is enabled,
|
||
this parameter will cause <productname>PostgreSQL</productname> to truncate (overwrite),
|
||
rather than append to, any existing log file of the same name.
|
||
However, truncation will occur only when a new file is being opened
|
||
due to time-based rotation, not during server startup or size-based
|
||
rotation. When off, pre-existing files will be appended to in
|
||
all cases. For example, using this setting in combination with
|
||
a <varname>log_filename</varname> like <literal>postgresql-%H.log</literal>
|
||
would result in generating twenty-four hourly log files and then
|
||
cyclically overwriting them.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
<para>
|
||
Example: To keep 7 days of logs, one log file per day named
|
||
<literal>server_log.Mon</literal>, <literal>server_log.Tue</literal>,
|
||
etc., and automatically overwrite last week's log with this week's log,
|
||
set <varname>log_filename</varname> to <literal>server_log.%a</literal>,
|
||
<varname>log_truncate_on_rotation</varname> to <literal>on</literal>, and
|
||
<varname>log_rotation_age</varname> to <literal>1440</literal>.
|
||
</para>
|
||
<para>
|
||
Example: To keep 24 hours of logs, one log file per hour, but
|
||
also rotate sooner if the log file size exceeds 1GB, set
|
||
<varname>log_filename</varname> to <literal>server_log.%H%M</literal>,
|
||
<varname>log_truncate_on_rotation</varname> to <literal>on</literal>,
|
||
<varname>log_rotation_age</varname> to <literal>60</literal>, and
|
||
<varname>log_rotation_size</varname> to <literal>1000000</literal>.
|
||
Including <literal>%M</literal> in <varname>log_filename</varname> allows
|
||
any size-driven rotations that might occur to select a file name
|
||
different from the hour's initial file name.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-syslog-facility" xreflabel="syslog_facility">
|
||
<term><varname>syslog_facility</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>syslog_facility</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When logging to <application>syslog</application> is enabled, this parameter
|
||
determines the <application>syslog</application>
|
||
<quote>facility</quote> to be used. You can choose
|
||
from <literal>LOCAL0</literal>, <literal>LOCAL1</literal>,
|
||
<literal>LOCAL2</literal>, <literal>LOCAL3</literal>, <literal>LOCAL4</literal>,
|
||
<literal>LOCAL5</literal>, <literal>LOCAL6</literal>, <literal>LOCAL7</literal>;
|
||
the default is <literal>LOCAL0</literal>. See also the
|
||
documentation of your system's
|
||
<application>syslog</application> daemon.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-syslog-ident" xreflabel="syslog_ident">
|
||
<term><varname>syslog_ident</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>syslog_ident</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When logging to <application>syslog</application> is enabled, this parameter
|
||
determines the program name used to identify
|
||
<productname>PostgreSQL</productname> messages in
|
||
<application>syslog</application> logs. The default is
|
||
<literal>postgres</literal>.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-syslog-sequence-numbers" xreflabel="syslog_sequence_numbers">
|
||
<term><varname>syslog_sequence_numbers</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>syslog_sequence_numbers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
|
||
<listitem>
|
||
<para>
|
||
When logging to <application>syslog</application> and this is on (the
|
||
default), then each message will be prefixed by an increasing
|
||
sequence number (such as <literal>[2]</literal>). This circumvents
|
||
the <quote>--- last message repeated N times ---</quote> suppression
|
||
that many syslog implementations perform by default. In more modern
|
||
syslog implementations, repeated message suppression can be configured
|
||
(for example, <literal>$RepeatedMsgReduction</literal>
|
||
in <productname>rsyslog</productname>), so this might not be
|
||
necessary. Also, you could turn this off if you actually want to
|
||
suppress repeated messages.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-syslog-split-messages" xreflabel="syslog_split_messages">
|
||
<term><varname>syslog_split_messages</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>syslog_split_messages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When logging to <application>syslog</application> is enabled, this parameter
|
||
determines how messages are delivered to syslog. When on (the
|
||
default), messages are split by lines, and long lines are split so
|
||
that they will fit into 1024 bytes, which is a typical size limit for
|
||
traditional syslog implementations. When off, PostgreSQL server log
|
||
messages are delivered to the syslog service as is, and it is up to
|
||
the syslog service to cope with the potentially bulky messages.
|
||
</para>
|
||
|
||
<para>
|
||
If syslog is ultimately logging to a text file, then the effect will
|
||
be the same either way, and it is best to leave the setting on, since
|
||
most syslog implementations either cannot handle large messages or
|
||
would need to be specially configured to handle them. But if syslog
|
||
is ultimately writing into some other medium, it might be necessary or
|
||
more useful to keep messages logically together.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-event-source" xreflabel="event_source">
|
||
<term><varname>event_source</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>event_source</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When logging to <application>event log</application> is enabled, this parameter
|
||
determines the program name used to identify
|
||
<productname>PostgreSQL</productname> messages in
|
||
the log. The default is <literal>PostgreSQL</literal>.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
<sect2 id="runtime-config-logging-when">
|
||
<title>When to Log</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-log-min-messages" xreflabel="log_min_messages">
|
||
<term><varname>log_min_messages</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>log_min_messages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls which <link linkend="runtime-config-severity-levels">message
|
||
levels</link> are written to the server log.
|
||
Valid values are <literal>DEBUG5</literal>, <literal>DEBUG4</literal>,
|
||
<literal>DEBUG3</literal>, <literal>DEBUG2</literal>, <literal>DEBUG1</literal>,
|
||
<literal>INFO</literal>, <literal>NOTICE</literal>, <literal>WARNING</literal>,
|
||
<literal>ERROR</literal>, <literal>LOG</literal>, <literal>FATAL</literal>, and
|
||
<literal>PANIC</literal>. Each level includes all the levels that
|
||
follow it. The later the level, the fewer messages are sent
|
||
to the log. The default is <literal>WARNING</literal>. Note that
|
||
<literal>LOG</literal> has a different rank here than in
|
||
<xref linkend="guc-client-min-messages"/>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-min-error-statement" xreflabel="log_min_error_statement">
|
||
<term><varname>log_min_error_statement</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>log_min_error_statement</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls which SQL statements that cause an error
|
||
condition are recorded in the server log. The current
|
||
SQL statement is included in the log entry for any message of
|
||
the specified
|
||
<link linkend="runtime-config-severity-levels">severity</link>
|
||
or higher.
|
||
Valid values are <literal>DEBUG5</literal>,
|
||
<literal>DEBUG4</literal>, <literal>DEBUG3</literal>,
|
||
<literal>DEBUG2</literal>, <literal>DEBUG1</literal>,
|
||
<literal>INFO</literal>, <literal>NOTICE</literal>,
|
||
<literal>WARNING</literal>, <literal>ERROR</literal>,
|
||
<literal>LOG</literal>,
|
||
<literal>FATAL</literal>, and <literal>PANIC</literal>.
|
||
The default is <literal>ERROR</literal>, which means statements
|
||
causing errors, log messages, fatal errors, or panics will be logged.
|
||
To effectively turn off logging of failing statements,
|
||
set this parameter to <literal>PANIC</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-min-duration-statement" xreflabel="log_min_duration_statement">
|
||
<term><varname>log_min_duration_statement</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_min_duration_statement</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Causes the duration of each completed statement to be logged
|
||
if the statement ran for at least the specified amount of time.
|
||
For example, if you set it to <literal>250ms</literal>
|
||
then all SQL statements that run 250ms or longer will be
|
||
logged. Enabling this parameter can be helpful in tracking down
|
||
unoptimized queries in your applications.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
Setting this to zero prints all statement durations.
|
||
<literal>-1</literal> (the default) disables logging statement
|
||
durations.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<para>
|
||
This overrides <xref linkend="guc-log-min-duration-sample"/>,
|
||
meaning that queries with duration exceeding this setting are not
|
||
subject to sampling and are always logged.
|
||
</para>
|
||
|
||
<para>
|
||
For clients using extended query protocol, durations of the Parse,
|
||
Bind, and Execute steps are logged independently.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
When using this option together with
|
||
<xref linkend="guc-log-statement"/>,
|
||
the text of statements that are logged because of
|
||
<varname>log_statement</varname> will not be repeated in the
|
||
duration log message.
|
||
If you are not using <application>syslog</application>, it is recommended
|
||
that you log the PID or session ID using
|
||
<xref linkend="guc-log-line-prefix"/>
|
||
so that you can link the statement message to the later
|
||
duration message using the process ID or session ID.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-min-duration-sample" xreflabel="log_min_duration_sample">
|
||
<term><varname>log_min_duration_sample</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_min_duration_sample</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Allows sampling the duration of completed statements that ran for
|
||
at least the specified amount of time. This produces the same
|
||
kind of log entries as
|
||
<xref linkend="guc-log-min-duration-statement"/>, but only for a
|
||
subset of the executed statements, with sample rate controlled by
|
||
<xref linkend="guc-log-statement-sample-rate"/>.
|
||
For example, if you set it to <literal>100ms</literal> then all
|
||
SQL statements that run 100ms or longer will be considered for
|
||
sampling. Enabling this parameter can be helpful when the
|
||
traffic is too high to log all queries.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
Setting this to zero samples all statement durations.
|
||
<literal>-1</literal> (the default) disables sampling statement
|
||
durations.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<para>
|
||
This setting has lower priority
|
||
than <varname>log_min_duration_statement</varname>, meaning that
|
||
statements with durations
|
||
exceeding <varname>log_min_duration_statement</varname> are not
|
||
subject to sampling and are always logged.
|
||
</para>
|
||
|
||
<para>
|
||
Other notes for <varname>log_min_duration_statement</varname>
|
||
apply also to this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-statement-sample-rate" xreflabel="log_statement_sample_rate">
|
||
<term><varname>log_statement_sample_rate</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>log_statement_sample_rate</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Determines the fraction of statements with duration exceeding
|
||
<xref linkend="guc-log-min-duration-sample"/> that will be logged.
|
||
Sampling is stochastic, for example <literal>0.5</literal> means
|
||
there is statistically one chance in two that any given statement
|
||
will be logged.
|
||
The default is <literal>1.0</literal>, meaning to log all sampled
|
||
statements.
|
||
Setting this to zero disables sampled statement-duration logging,
|
||
the same as setting
|
||
<varname>log_min_duration_sample</varname> to
|
||
<literal>-1</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-transaction-sample-rate" xreflabel="log_transaction_sample_rate">
|
||
<term><varname>log_transaction_sample_rate</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>log_transaction_sample_rate</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the fraction of transactions whose statements are all logged,
|
||
in addition to statements logged for other reasons. It applies to
|
||
each new transaction regardless of its statements' durations.
|
||
Sampling is stochastic, for example <literal>0.1</literal> means
|
||
there is statistically one chance in ten that any given transaction
|
||
will be logged.
|
||
<varname>log_transaction_sample_rate</varname> can be helpful to
|
||
construct a sample of transactions.
|
||
The default is <literal>0</literal>, meaning not to log
|
||
statements from any additional transactions. Setting this
|
||
to <literal>1</literal> logs all statements of all transactions.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
Like all statement-logging options, this option can add significant
|
||
overhead.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-startup-progress-interval" xreflabel="log_startup_progress_interval">
|
||
<term><varname>log_startup_progress_interval</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_startup_progress_interval</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the amount of time after which the startup process will log
|
||
a message about a long-running operation that is still in progress,
|
||
as well as the interval between further progress messages for that
|
||
operation. The default is 10 seconds. A setting of <literal>0</literal>
|
||
disables the feature. If this value is specified without units,
|
||
it is taken as milliseconds. This setting is applied separately to
|
||
each operation.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
|
||
<para>
|
||
For example, if syncing the data directory takes 25 seconds and
|
||
thereafter resetting unlogged relations takes 8 seconds, and if this
|
||
setting has the default value of 10 seconds, then a messages will be
|
||
logged for syncing the data directory after it has been in progress
|
||
for 10 seconds and again after it has been in progress for 20 seconds,
|
||
but nothing will be logged for resetting unlogged relations.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend="runtime-config-severity-levels"/> explains the message
|
||
severity levels used by <productname>PostgreSQL</productname>. If logging output
|
||
is sent to <systemitem>syslog</systemitem> or Windows'
|
||
<systemitem>eventlog</systemitem>, the severity levels are translated
|
||
as shown in the table.
|
||
</para>
|
||
|
||
<table id="runtime-config-severity-levels">
|
||
<title>Message Severity Levels</title>
|
||
<tgroup cols="4">
|
||
<colspec colname="col1" colwidth="1*"/>
|
||
<colspec colname="col2" colwidth="2*"/>
|
||
<colspec colname="col3" colwidth="1*"/>
|
||
<colspec colname="col4" colwidth="1*"/>
|
||
<thead>
|
||
<row>
|
||
<entry>Severity</entry>
|
||
<entry>Usage</entry>
|
||
<entry><systemitem>syslog</systemitem></entry>
|
||
<entry><systemitem>eventlog</systemitem></entry>
|
||
</row>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<row>
|
||
<entry><literal>DEBUG1 .. DEBUG5</literal></entry>
|
||
<entry>Provides successively-more-detailed information for use by
|
||
developers.</entry>
|
||
<entry><literal>DEBUG</literal></entry>
|
||
<entry><literal>INFORMATION</literal></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry><literal>INFO</literal></entry>
|
||
<entry>Provides information implicitly requested by the user,
|
||
e.g., output from <command>VACUUM VERBOSE</command>.</entry>
|
||
<entry><literal>INFO</literal></entry>
|
||
<entry><literal>INFORMATION</literal></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry><literal>NOTICE</literal></entry>
|
||
<entry>Provides information that might be helpful to users, e.g.,
|
||
notice of truncation of long identifiers.</entry>
|
||
<entry><literal>NOTICE</literal></entry>
|
||
<entry><literal>INFORMATION</literal></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry><literal>WARNING</literal></entry>
|
||
<entry>Provides warnings of likely problems, e.g., <command>COMMIT</command>
|
||
outside a transaction block.</entry>
|
||
<entry><literal>NOTICE</literal></entry>
|
||
<entry><literal>WARNING</literal></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry><literal>ERROR</literal></entry>
|
||
<entry>Reports an error that caused the current command to
|
||
abort.</entry>
|
||
<entry><literal>WARNING</literal></entry>
|
||
<entry><literal>ERROR</literal></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry><literal>LOG</literal></entry>
|
||
<entry>Reports information of interest to administrators, e.g.,
|
||
checkpoint activity.</entry>
|
||
<entry><literal>INFO</literal></entry>
|
||
<entry><literal>INFORMATION</literal></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry><literal>FATAL</literal></entry>
|
||
<entry>Reports an error that caused the current session to
|
||
abort.</entry>
|
||
<entry><literal>ERR</literal></entry>
|
||
<entry><literal>ERROR</literal></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry><literal>PANIC</literal></entry>
|
||
<entry>Reports an error that caused all database sessions to abort.</entry>
|
||
<entry><literal>CRIT</literal></entry>
|
||
<entry><literal>ERROR</literal></entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
</sect2>
|
||
<sect2 id="runtime-config-logging-what">
|
||
<title>What to Log</title>
|
||
|
||
<note>
|
||
<para>
|
||
What you choose to log can have security implications; see
|
||
<xref linkend="logfile-maintenance"/>.
|
||
</para>
|
||
</note>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-application-name" xreflabel="application_name">
|
||
<term><varname>application_name</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>application_name</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The <varname>application_name</varname> can be any string of less than
|
||
<symbol>NAMEDATALEN</symbol> characters (64 characters in a standard build).
|
||
It is typically set by an application upon connection to the server.
|
||
The name will be displayed in the <structname>pg_stat_activity</structname> view
|
||
and included in CSV log entries. It can also be included in regular
|
||
log entries via the <xref linkend="guc-log-line-prefix"/> parameter.
|
||
Only printable ASCII characters may be used in the
|
||
<varname>application_name</varname> value.
|
||
Other characters are replaced with <link
|
||
linkend="sql-syntax-strings-escape">C-style hexadecimal escapes</link>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-debug-print-parse">
|
||
<term><varname>debug_print_parse</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_print_parse</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<term><varname>debug_print_rewritten</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_print_rewritten</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<term><varname>debug_print_plan</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_print_plan</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
These parameters enable various debugging output to be emitted.
|
||
When set, they print the resulting parse tree, the query rewriter
|
||
output, or the execution plan for each executed query.
|
||
These messages are emitted at <literal>LOG</literal> message level, so by
|
||
default they will appear in the server log but will not be sent to the
|
||
client. You can change that by adjusting
|
||
<xref linkend="guc-client-min-messages"/> and/or
|
||
<xref linkend="guc-log-min-messages"/>.
|
||
These parameters are off by default.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-debug-pretty-print">
|
||
<term><varname>debug_pretty_print</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_pretty_print</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When set, <varname>debug_pretty_print</varname> indents the messages
|
||
produced by <varname>debug_print_parse</varname>,
|
||
<varname>debug_print_rewritten</varname>, or
|
||
<varname>debug_print_plan</varname>. This results in more readable
|
||
but much longer output than the <quote>compact</quote> format used when
|
||
it is off. It is on by default.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-autovacuum-min-duration" xreflabel="log_autovacuum_min_duration">
|
||
<term><varname>log_autovacuum_min_duration</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_autovacuum_min_duration</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Causes each action executed by autovacuum to be logged if it ran for at
|
||
least the specified amount of time. Setting this to zero logs
|
||
all autovacuum actions. <literal>-1</literal> disables logging autovacuum
|
||
actions. If this value is specified without units, it is taken as milliseconds.
|
||
For example, if you set this to
|
||
<literal>250ms</literal> then all automatic vacuums and analyzes that run
|
||
250ms or longer will be logged. In addition, when this parameter is
|
||
set to any value other than <literal>-1</literal>, a message will be
|
||
logged if an autovacuum action is skipped due to a conflicting lock or a
|
||
concurrently dropped relation. The default is <literal>10min</literal>.
|
||
Enabling this parameter can be helpful in tracking autovacuum activity.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line; but the setting can be overridden for
|
||
individual tables by changing table storage parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-checkpoints" xreflabel="log_checkpoints">
|
||
<term><varname>log_checkpoints</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_checkpoints</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Causes checkpoints and restartpoints to be logged in the server log.
|
||
Some statistics are included in the log messages, including the number
|
||
of buffers written and the time spent writing them.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line. The default is on.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-connections" xreflabel="log_connections">
|
||
<term><varname>log_connections</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_connections</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Causes each attempted connection to the server to be logged,
|
||
as well as successful completion of both client authentication (if
|
||
necessary) and authorization.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this parameter at session start,
|
||
and it cannot be changed at all within a session.
|
||
The default is <literal>off</literal>.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
Some client programs, like <application>psql</application>, attempt
|
||
to connect twice while determining if a password is required, so
|
||
duplicate <quote>connection received</quote> messages do not
|
||
necessarily indicate a problem.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-disconnections" xreflabel="log_disconnections">
|
||
<term><varname>log_disconnections</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_disconnections</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Causes session terminations to be logged. The log output
|
||
provides information similar to <varname>log_connections</varname>,
|
||
plus the duration of the session.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this parameter at session start,
|
||
and it cannot be changed at all within a session.
|
||
The default is <literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry id="guc-log-duration" xreflabel="log_duration">
|
||
<term><varname>log_duration</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_duration</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Causes the duration of every completed statement to be logged.
|
||
The default is <literal>off</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<para>
|
||
For clients using extended query protocol, durations of the Parse,
|
||
Bind, and Execute steps are logged independently.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
The difference between enabling <varname>log_duration</varname> and setting
|
||
<xref linkend="guc-log-min-duration-statement"/> to zero is that
|
||
exceeding <varname>log_min_duration_statement</varname> forces the text of
|
||
the query to be logged, but this option doesn't. Thus, if
|
||
<varname>log_duration</varname> is <literal>on</literal> and
|
||
<varname>log_min_duration_statement</varname> has a positive value, all
|
||
durations are logged but the query text is included only for
|
||
statements exceeding the threshold. This behavior can be useful for
|
||
gathering statistics in high-load installations.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-error-verbosity" xreflabel="log_error_verbosity">
|
||
<term><varname>log_error_verbosity</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>log_error_verbosity</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls the amount of detail written in the server log for each
|
||
message that is logged. Valid values are <literal>TERSE</literal>,
|
||
<literal>DEFAULT</literal>, and <literal>VERBOSE</literal>, each adding more
|
||
fields to displayed messages. <literal>TERSE</literal> excludes
|
||
the logging of <literal>DETAIL</literal>, <literal>HINT</literal>,
|
||
<literal>QUERY</literal>, and <literal>CONTEXT</literal> error information.
|
||
<literal>VERBOSE</literal> output includes the <symbol>SQLSTATE</symbol> error
|
||
code (see also <xref linkend="errcodes-appendix"/>) and the source code file name, function name,
|
||
and line number that generated the error.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-hostname" xreflabel="log_hostname">
|
||
<term><varname>log_hostname</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_hostname</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
By default, connection log messages only show the IP address of the
|
||
connecting host. Turning this parameter on causes logging of the
|
||
host name as well. Note that depending on your host name resolution
|
||
setup this might impose a non-negligible performance penalty.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-line-prefix" xreflabel="log_line_prefix">
|
||
<term><varname>log_line_prefix</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>log_line_prefix</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This is a <function>printf</function>-style string that is output at the
|
||
beginning of each log line.
|
||
<literal>%</literal> characters begin <quote>escape sequences</quote>
|
||
that are replaced with status information as outlined below.
|
||
Unrecognized escapes are ignored. Other
|
||
characters are copied straight to the log line. Some escapes are
|
||
only recognized by session processes, and will be treated as empty by
|
||
background processes such as the main server process. Status
|
||
information may be aligned either left or right by specifying a
|
||
numeric literal after the % and before the option. A negative
|
||
value will cause the status information to be padded on the
|
||
right with spaces to give it a minimum width, whereas a positive
|
||
value will pad on the left. Padding can be useful to aid human
|
||
readability in log files.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line. The default is
|
||
<literal>'%m [%p] '</literal> which logs a time stamp and the process ID.
|
||
</para>
|
||
|
||
<informaltable>
|
||
<tgroup cols="3">
|
||
<thead>
|
||
<row>
|
||
<entry>Escape</entry>
|
||
<entry>Effect</entry>
|
||
<entry>Session only</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><literal>%a</literal></entry>
|
||
<entry>Application name</entry>
|
||
<entry>yes</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%u</literal></entry>
|
||
<entry>User name</entry>
|
||
<entry>yes</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%d</literal></entry>
|
||
<entry>Database name</entry>
|
||
<entry>yes</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%r</literal></entry>
|
||
<entry>Remote host name or IP address, and remote port</entry>
|
||
<entry>yes</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%h</literal></entry>
|
||
<entry>Remote host name or IP address</entry>
|
||
<entry>yes</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%b</literal></entry>
|
||
<entry>Backend type</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%p</literal></entry>
|
||
<entry>Process ID</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%P</literal></entry>
|
||
<entry>Process ID of the parallel group leader, if this process
|
||
is a parallel query worker</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%t</literal></entry>
|
||
<entry>Time stamp without milliseconds</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%m</literal></entry>
|
||
<entry>Time stamp with milliseconds</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%n</literal></entry>
|
||
<entry>Time stamp with milliseconds (as a Unix epoch)</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%i</literal></entry>
|
||
<entry>Command tag: type of session's current command</entry>
|
||
<entry>yes</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%e</literal></entry>
|
||
<entry>SQLSTATE error code</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%c</literal></entry>
|
||
<entry>Session ID: see below</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%l</literal></entry>
|
||
<entry>Number of the log line for each session or process, starting at 1</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%s</literal></entry>
|
||
<entry>Process start time stamp</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%v</literal></entry>
|
||
<entry>Virtual transaction ID (procNumber/localXID); see
|
||
<xref linkend="transaction-id"/></entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%x</literal></entry>
|
||
<entry>Transaction ID (0 if none is assigned); see
|
||
<xref linkend="transaction-id"/></entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%q</literal></entry>
|
||
<entry>Produces no output, but tells non-session
|
||
processes to stop at this point in the string; ignored by
|
||
session processes</entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%Q</literal></entry>
|
||
<entry>Query identifier of the current query. Query
|
||
identifiers are not computed by default, so this field
|
||
will be zero unless <xref linkend="guc-compute-query-id"/>
|
||
parameter is enabled or a third-party module that computes
|
||
query identifiers is configured.</entry>
|
||
<entry>yes</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>%%</literal></entry>
|
||
<entry>Literal <literal>%</literal></entry>
|
||
<entry>no</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
The backend type corresponds to the column
|
||
<structfield>backend_type</structfield> in the view
|
||
<link linkend="monitoring-pg-stat-activity-view">
|
||
<structname>pg_stat_activity</structname></link>,
|
||
but additional types can appear
|
||
in the log that don't show in that view.
|
||
</para>
|
||
|
||
<para>
|
||
The <literal>%c</literal> escape prints a quasi-unique session identifier,
|
||
consisting of two 4-byte hexadecimal numbers (without leading zeros)
|
||
separated by a dot. The numbers are the process start time and the
|
||
process ID, so <literal>%c</literal> can also be used as a space saving way
|
||
of printing those items. For example, to generate the session
|
||
identifier from <literal>pg_stat_activity</literal>, use this query:
|
||
<programlisting>
|
||
SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' ||
|
||
to_hex(pid)
|
||
FROM pg_stat_activity;
|
||
</programlisting>
|
||
|
||
</para>
|
||
|
||
<tip>
|
||
<para>
|
||
If you set a nonempty value for <varname>log_line_prefix</varname>,
|
||
you should usually make its last character be a space, to provide
|
||
visual separation from the rest of the log line. A punctuation
|
||
character can be used too.
|
||
</para>
|
||
</tip>
|
||
|
||
<tip>
|
||
<para>
|
||
<application>Syslog</application> produces its own
|
||
time stamp and process ID information, so you probably do not want to
|
||
include those escapes if you are logging to <application>syslog</application>.
|
||
</para>
|
||
</tip>
|
||
|
||
<tip>
|
||
<para>
|
||
The <literal>%q</literal> escape is useful when including information that is
|
||
only available in session (backend) context like user or database
|
||
name. For example:
|
||
<programlisting>
|
||
log_line_prefix = '%m [%p] %q%u@%d/%a '
|
||
</programlisting>
|
||
</para>
|
||
</tip>
|
||
|
||
<note>
|
||
<para>
|
||
The <literal>%Q</literal> escape always reports a zero identifier
|
||
for lines output by <xref linkend="guc-log-statement"/> because
|
||
<varname>log_statement</varname> generates output before an
|
||
identifier can be calculated, including invalid statements for
|
||
which an identifier cannot be calculated.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-lock-waits" xreflabel="log_lock_waits">
|
||
<term><varname>log_lock_waits</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_lock_waits</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls whether a log message is produced when a session waits
|
||
longer than <xref linkend="guc-deadlock-timeout"/> to acquire a
|
||
lock. This is useful in determining if lock waits are causing
|
||
poor performance. The default is <literal>off</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-recovery-conflict-waits" xreflabel="log_recovery_conflict_waits">
|
||
<term><varname>log_recovery_conflict_waits</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_recovery_conflict_waits</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls whether a log message is produced when the startup process
|
||
waits longer than <varname>deadlock_timeout</varname>
|
||
for recovery conflicts. This is useful in determining if recovery
|
||
conflicts prevent the recovery from applying WAL.
|
||
</para>
|
||
|
||
<para>
|
||
The default is <literal>off</literal>. This parameter can only be set
|
||
in the <filename>postgresql.conf</filename> file or on the server
|
||
command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-parameter-max-length" xreflabel="log_parameter_max_length">
|
||
<term><varname>log_parameter_max_length</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_parameter_max_length</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If greater than zero, each bind parameter value logged with a
|
||
non-error statement-logging message is trimmed to this many bytes.
|
||
Zero disables logging of bind parameters for non-error statement logs.
|
||
<literal>-1</literal> (the default) allows bind parameters to be
|
||
logged in full.
|
||
If this value is specified without units, it is taken as bytes.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<para>
|
||
This setting only affects log messages printed as a result of
|
||
<xref linkend="guc-log-statement"/>,
|
||
<xref linkend="guc-log-duration"/>, and related settings. Non-zero
|
||
values of this setting add some overhead, particularly if parameters
|
||
are sent in binary form, since then conversion to text is required.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-parameter-max-length-on-error" xreflabel="log_parameter_max_length_on_error">
|
||
<term><varname>log_parameter_max_length_on_error</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_parameter_max_length_on_error</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If greater than zero, each bind parameter value reported in error
|
||
messages is trimmed to this many bytes.
|
||
Zero (the default) disables including bind parameters in error
|
||
messages.
|
||
<literal>-1</literal> allows bind parameters to be printed in full.
|
||
If this value is specified without units, it is taken as bytes.
|
||
</para>
|
||
|
||
<para>
|
||
Non-zero values of this setting add overhead, as
|
||
<productname>PostgreSQL</productname> will need to store textual
|
||
representations of parameter values in memory at the start of each
|
||
statement, whether or not an error eventually occurs. The overhead
|
||
is greater when bind parameters are sent in binary form than when
|
||
they are sent as text, since the former case requires data
|
||
conversion while the latter only requires copying the string.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-statement" xreflabel="log_statement">
|
||
<term><varname>log_statement</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>log_statement</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls which SQL statements are logged. Valid values are
|
||
<literal>none</literal> (off), <literal>ddl</literal>, <literal>mod</literal>, and
|
||
<literal>all</literal> (all statements). <literal>ddl</literal> logs all data definition
|
||
statements, such as <command>CREATE</command>, <command>ALTER</command>, and
|
||
<command>DROP</command> statements. <literal>mod</literal> logs all
|
||
<literal>ddl</literal> statements, plus data-modifying statements
|
||
such as <command>INSERT</command>,
|
||
<command>UPDATE</command>, <command>DELETE</command>, <command>TRUNCATE</command>,
|
||
and <command>COPY FROM</command>.
|
||
<command>PREPARE</command>, <command>EXECUTE</command>, and
|
||
<command>EXPLAIN ANALYZE</command> statements are also logged if their
|
||
contained command is of an appropriate type. For clients using
|
||
extended query protocol, logging occurs when an Execute message
|
||
is received, and values of the Bind parameters are included
|
||
(with any embedded single-quote marks doubled).
|
||
</para>
|
||
|
||
<para>
|
||
The default is <literal>none</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
Statements that contain simple syntax errors are not logged
|
||
even by the <varname>log_statement</varname> = <literal>all</literal> setting,
|
||
because the log message is emitted only after basic parsing has
|
||
been done to determine the statement type. In the case of extended
|
||
query protocol, this setting likewise does not log statements that
|
||
fail before the Execute phase (i.e., during parse analysis or
|
||
planning). Set <varname>log_min_error_statement</varname> to
|
||
<literal>ERROR</literal> (or lower) to log such statements.
|
||
</para>
|
||
<para>
|
||
Logged statements might reveal sensitive data and even contain
|
||
plaintext passwords.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-replication-commands" xreflabel="log_replication_commands">
|
||
<term><varname>log_replication_commands</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_replication_commands</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Causes each replication command and <literal>walsender</literal>
|
||
process's replication slot acquisition/release to be logged in the
|
||
server log. See <xref linkend="protocol-replication"/> for more
|
||
information about replication command. The default value is
|
||
<literal>off</literal>. Only superusers and users with the appropriate
|
||
<literal>SET</literal> privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-temp-files" xreflabel="log_temp_files">
|
||
<term><varname>log_temp_files</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>log_temp_files</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls logging of temporary file names and sizes.
|
||
Temporary files can be
|
||
created for sorts, hashes, and temporary query results.
|
||
If enabled by this setting, a log entry is emitted for each
|
||
temporary file, with the file size specified in bytes, when it is deleted.
|
||
A value of zero logs all temporary file information, while positive
|
||
values log only files whose size is greater than or equal to
|
||
the specified amount of data.
|
||
If this value is specified without units, it is taken as kilobytes.
|
||
The default setting is -1, which disables such logging.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-timezone" xreflabel="log_timezone">
|
||
<term><varname>log_timezone</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>log_timezone</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the time zone used for timestamps written in the server log.
|
||
Unlike <xref linkend="guc-timezone"/>, this value is cluster-wide,
|
||
so that all sessions will report timestamps consistently.
|
||
The built-in default is <literal>GMT</literal>, but that is typically
|
||
overridden in <filename>postgresql.conf</filename>; <application>initdb</application>
|
||
will install a setting there corresponding to its system environment.
|
||
See <xref linkend="datatype-timezones"/> for more information.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
<sect2 id="runtime-config-logging-csvlog">
|
||
<title>Using CSV-Format Log Output</title>
|
||
|
||
<para>
|
||
Including <literal>csvlog</literal> in the <varname>log_destination</varname> list
|
||
provides a convenient way to import log files into a database table.
|
||
This option emits log lines in comma-separated-values
|
||
(<acronym>CSV</acronym>) format,
|
||
with these columns:
|
||
time stamp with milliseconds,
|
||
user name,
|
||
database name,
|
||
process ID,
|
||
client host:port number,
|
||
session ID,
|
||
per-session line number,
|
||
command tag,
|
||
session start time,
|
||
virtual transaction ID,
|
||
regular transaction ID,
|
||
error severity,
|
||
SQLSTATE code,
|
||
error message,
|
||
error message detail,
|
||
hint,
|
||
internal query that led to the error (if any),
|
||
character count of the error position therein,
|
||
error context,
|
||
user query that led to the error (if any and enabled by
|
||
<varname>log_min_error_statement</varname>),
|
||
character count of the error position therein,
|
||
location of the error in the PostgreSQL source code
|
||
(if <varname>log_error_verbosity</varname> is set to <literal>verbose</literal>),
|
||
application name, backend type, process ID of parallel group leader,
|
||
and query id.
|
||
Here is a sample table definition for storing CSV-format log output:
|
||
|
||
<programlisting>
|
||
CREATE TABLE postgres_log
|
||
(
|
||
log_time timestamp(3) with time zone,
|
||
user_name text,
|
||
database_name text,
|
||
process_id integer,
|
||
connection_from text,
|
||
session_id text,
|
||
session_line_num bigint,
|
||
command_tag text,
|
||
session_start_time timestamp with time zone,
|
||
virtual_transaction_id text,
|
||
transaction_id bigint,
|
||
error_severity text,
|
||
sql_state_code text,
|
||
message text,
|
||
detail text,
|
||
hint text,
|
||
internal_query text,
|
||
internal_query_pos integer,
|
||
context text,
|
||
query text,
|
||
query_pos integer,
|
||
location text,
|
||
application_name text,
|
||
backend_type text,
|
||
leader_pid integer,
|
||
query_id bigint,
|
||
PRIMARY KEY (session_id, session_line_num)
|
||
);
|
||
</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
To import a log file into this table, use the <command>COPY FROM</command>
|
||
command:
|
||
|
||
<programlisting>
|
||
COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
|
||
</programlisting>
|
||
It is also possible to access the file as a foreign table, using
|
||
the supplied <xref linkend="file-fdw"/> module.
|
||
</para>
|
||
|
||
<para>
|
||
There are a few things you need to do to simplify importing CSV log
|
||
files:
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
Set <varname>log_filename</varname> and
|
||
<varname>log_rotation_age</varname> to provide a consistent,
|
||
predictable naming scheme for your log files. This lets you
|
||
predict what the file name will be and know when an individual log
|
||
file is complete and therefore ready to be imported.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Set <varname>log_rotation_size</varname> to 0 to disable
|
||
size-based log rotation, as it makes the log file name difficult
|
||
to predict.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
Set <varname>log_truncate_on_rotation</varname> to <literal>on</literal> so
|
||
that old log data isn't mixed with the new in the same file.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
The table definition above includes a primary key specification.
|
||
This is useful to protect against accidentally importing the same
|
||
information twice. The <command>COPY</command> command commits all of the
|
||
data it imports at one time, so any error will cause the entire
|
||
import to fail. If you import a partial log file and later import
|
||
the file again when it is complete, the primary key violation will
|
||
cause the import to fail. Wait until the log is complete and
|
||
closed before importing. This procedure will also protect against
|
||
accidentally importing a partial line that hasn't been completely
|
||
written, which would also cause <command>COPY</command> to fail.
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</para>
|
||
</sect2>
|
||
<sect2 id="runtime-config-logging-jsonlog">
|
||
<title>Using JSON-Format Log Output</title>
|
||
|
||
<para>
|
||
Including <literal>jsonlog</literal> in the
|
||
<varname>log_destination</varname> list provides a convenient way to
|
||
import log files into many different programs. This option emits log
|
||
lines in <acronym>JSON</acronym> format.
|
||
</para>
|
||
|
||
<para>
|
||
String fields with null values are excluded from output.
|
||
Additional fields may be added in the future. User applications that
|
||
process <literal>jsonlog</literal> output should ignore unknown fields.
|
||
</para>
|
||
|
||
<para>
|
||
Each log line is serialized as a JSON object with the set of keys and
|
||
their associated values shown in <xref
|
||
linkend="runtime-config-logging-jsonlog-keys-values"/>.
|
||
</para>
|
||
|
||
<table id="runtime-config-logging-jsonlog-keys-values">
|
||
<title>Keys and Values of JSON Log Entries</title>
|
||
<tgroup cols="3">
|
||
<thead>
|
||
<row>
|
||
<entry>Key name</entry>
|
||
<entry>Type</entry>
|
||
<entry>Description</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><literal>timestamp</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Time stamp with milliseconds</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>user</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>User name</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>dbname</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Database name</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>pid</literal></entry>
|
||
<entry>number</entry>
|
||
<entry>Process ID</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>remote_host</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Client host</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>remote_port</literal></entry>
|
||
<entry>number</entry>
|
||
<entry>Client port</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>session_id</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Session ID</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>line_num</literal></entry>
|
||
<entry>number</entry>
|
||
<entry>Per-session line number</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>ps</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Current ps display</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>session_start</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Session start time</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>vxid</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Virtual transaction ID</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>txid</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Regular transaction ID</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>error_severity</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Error severity</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>state_code</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>SQLSTATE code</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>message</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Error message</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>detail</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Error message detail</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>hint</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Error message hint</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>internal_query</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Internal query that led to the error</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>internal_position</literal></entry>
|
||
<entry>number</entry>
|
||
<entry>Cursor index into internal query</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>context</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Error context</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>statement</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Client-supplied query string</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>cursor_position</literal></entry>
|
||
<entry>number</entry>
|
||
<entry>Cursor index into query string</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>func_name</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Error location function name</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>file_name</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>File name of error location</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>file_line_num</literal></entry>
|
||
<entry>number</entry>
|
||
<entry>File line number of the error location</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>application_name</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Client application name</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>backend_type</literal></entry>
|
||
<entry>string</entry>
|
||
<entry>Type of backend</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>leader_pid</literal></entry>
|
||
<entry>number</entry>
|
||
<entry>Process ID of leader for active parallel workers</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>query_id</literal></entry>
|
||
<entry>number</entry>
|
||
<entry>Query ID</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-logging-proc-title">
|
||
<title>Process Title</title>
|
||
|
||
<para>
|
||
These settings control how process titles of server processes are
|
||
modified. Process titles are typically viewed using programs like
|
||
<application>ps</application> or, on Windows, <application>Process Explorer</application>.
|
||
See <xref linkend="monitoring-ps"/> for details.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-cluster-name" xreflabel="cluster_name">
|
||
<term><varname>cluster_name</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>cluster_name</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets a name that identifies this database cluster (instance) for
|
||
various purposes. The cluster name appears in the process title for
|
||
all server processes in this cluster. Moreover, it is the default
|
||
application name for a standby connection (see <xref
|
||
linkend="guc-synchronous-standby-names"/>.)
|
||
</para>
|
||
|
||
<para>
|
||
The name can be any string of less
|
||
than <symbol>NAMEDATALEN</symbol> characters (64 characters in a standard
|
||
build). Only printable ASCII characters may be used in the
|
||
<varname>cluster_name</varname> value.
|
||
Other characters are replaced with <link
|
||
linkend="sql-syntax-strings-escape">C-style hexadecimal escapes</link>.
|
||
No name is shown if this parameter is set to the empty string
|
||
<literal>''</literal> (which is the default).
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-update-process-title" xreflabel="update_process_title">
|
||
<term><varname>update_process_title</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>update_process_title</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables updating of the process title every time a new SQL command
|
||
is received by the server.
|
||
This setting defaults to <literal>on</literal> on most platforms, but it
|
||
defaults to <literal>off</literal> on Windows due to that platform's larger
|
||
overhead for updating the process title.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-statistics">
|
||
<title>Run-time Statistics</title>
|
||
|
||
<sect2 id="runtime-config-cumulative-statistics">
|
||
<title>Cumulative Query and Index Statistics</title>
|
||
|
||
<para>
|
||
These parameters control the server-wide cumulative statistics system.
|
||
When enabled, the data that is collected can be accessed via the
|
||
<structname>pg_stat</structname> and <structname>pg_statio</structname>
|
||
family of system views. Refer to <xref linkend="monitoring"/> for more
|
||
information.
|
||
</para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-track-activities" xreflabel="track_activities">
|
||
<term><varname>track_activities</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>track_activities</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables the collection of information on the currently
|
||
executing command of each session, along with its identifier and the
|
||
time when that command began execution. This parameter is on by
|
||
default. Note that even when enabled, this information is only
|
||
visible to superusers, roles with privileges of the
|
||
<literal>pg_read_all_stats</literal> role and the user owning the
|
||
sessions being reported on (including sessions belonging to a role they
|
||
have the privileges of), so it should not represent a security risk.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-track-activity-query-size" xreflabel="track_activity_query_size">
|
||
<term><varname>track_activity_query_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>track_activity_query_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the amount of memory reserved to store the text of the
|
||
currently executing command for each active session, for the
|
||
<structname>pg_stat_activity</structname>.<structfield>query</structfield> field.
|
||
If this value is specified without units, it is taken as bytes.
|
||
The default value is 1024 bytes.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-track-counts" xreflabel="track_counts">
|
||
<term><varname>track_counts</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>track_counts</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables collection of statistics on database activity.
|
||
This parameter is on by default, because the autovacuum
|
||
daemon needs the collected information.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-track-io-timing" xreflabel="track_io_timing">
|
||
<term><varname>track_io_timing</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>track_io_timing</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables timing of database I/O calls. This parameter is off by
|
||
default, as it will repeatedly query the operating system for
|
||
the current time, which may cause significant overhead on some
|
||
platforms. You can use the <xref linkend="pgtesttiming"/> tool to
|
||
measure the overhead of timing on your system.
|
||
I/O timing information is
|
||
displayed in <link linkend="monitoring-pg-stat-database-view">
|
||
<structname>pg_stat_database</structname></link>, in the output of
|
||
<xref linkend="sql-explain"/> when the <literal>BUFFERS</literal> option
|
||
is used, in the output of <xref linkend="sql-vacuum"/> when
|
||
the <literal>VERBOSE</literal> option is used, by autovacuum
|
||
for auto-vacuums and auto-analyzes, when <xref
|
||
linkend="guc-log-autovacuum-min-duration"/> is set and by
|
||
<xref linkend="pgstatstatements"/>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-track-wal-io-timing" xreflabel="track_wal_io_timing">
|
||
<term><varname>track_wal_io_timing</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>track_wal_io_timing</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables timing of WAL I/O calls. This parameter is off by default,
|
||
as it will repeatedly query the operating system for the current time,
|
||
which may cause significant overhead on some platforms.
|
||
You can use the <application>pg_test_timing</application> tool to
|
||
measure the overhead of timing on your system.
|
||
I/O timing information is
|
||
displayed in <link linkend="monitoring-pg-stat-wal-view">
|
||
<structname>pg_stat_wal</structname></link>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-track-functions" xreflabel="track_functions">
|
||
<term><varname>track_functions</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>track_functions</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables tracking of function call counts and time used. Specify
|
||
<literal>pl</literal> to track only procedural-language functions,
|
||
<literal>all</literal> to also track SQL and C language functions.
|
||
The default is <literal>none</literal>, which disables function
|
||
statistics tracking.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
SQL-language functions that are simple enough to be <quote>inlined</quote>
|
||
into the calling query will not be tracked, regardless of this
|
||
setting.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-stats-fetch-consistency" xreflabel="stats_fetch_consistency">
|
||
<term><varname>stats_fetch_consistency</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>stats_fetch_consistency</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Determines the behavior when cumulative statistics are accessed
|
||
multiple times within a transaction. When set to
|
||
<literal>none</literal>, each access re-fetches counters from shared
|
||
memory. When set to <literal>cache</literal>, the first access to
|
||
statistics for an object caches those statistics until the end of the
|
||
transaction unless <function>pg_stat_clear_snapshot()</function> is
|
||
called. When set to <literal>snapshot</literal>, the first statistics
|
||
access caches all statistics accessible in the current database, until
|
||
the end of the transaction unless
|
||
<function>pg_stat_clear_snapshot()</function> is called. Changing this
|
||
parameter in a transaction discards the statistics snapshot.
|
||
The default is <literal>cache</literal>.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
<literal>none</literal> is most suitable for monitoring systems. If
|
||
values are only accessed once, it is the most
|
||
efficient. <literal>cache</literal> ensures repeat accesses yield the
|
||
same values, which is important for queries involving
|
||
e.g. self-joins. <literal>snapshot</literal> can be useful when
|
||
interactively inspecting statistics, but has higher overhead,
|
||
particularly if many database objects exist.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-statistics-monitor">
|
||
<title>Statistics Monitoring</title>
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-compute-query-id" xreflabel="compute_query_id">
|
||
<term><varname>compute_query_id</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>compute_query_id</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Enables in-core computation of a query identifier.
|
||
Query identifiers can be displayed in the <link
|
||
linkend="monitoring-pg-stat-activity-view"><structname>pg_stat_activity</structname></link>
|
||
view, using <command>EXPLAIN</command>, or emitted in the log if
|
||
configured via the <xref linkend="guc-log-line-prefix"/> parameter.
|
||
The <xref linkend="pgstatstatements"/> extension also requires a query
|
||
identifier to be computed. Note that an external module can
|
||
alternatively be used if the in-core query identifier computation
|
||
method is not acceptable. In this case, in-core computation
|
||
must be always disabled.
|
||
Valid values are <literal>off</literal> (always disabled),
|
||
<literal>on</literal> (always enabled), <literal>auto</literal>,
|
||
which lets modules such as <xref linkend="pgstatstatements"/>
|
||
automatically enable it, and <literal>regress</literal> which
|
||
has the same effect as <literal>auto</literal>, except that the
|
||
query identifier is not shown in the <literal>EXPLAIN</literal> output
|
||
in order to facilitate automated regression testing.
|
||
The default is <literal>auto</literal>.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
To ensure that only one query identifier is calculated and
|
||
displayed, extensions that calculate query identifiers should
|
||
throw an error if a query identifier has already been computed.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-statement-stats">
|
||
<term><varname>log_statement_stats</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_statement_stats</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<term><varname>log_parser_stats</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_parser_stats</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<term><varname>log_planner_stats</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_planner_stats</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<term><varname>log_executor_stats</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_executor_stats</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
For each query, output performance statistics of the respective
|
||
module to the server log. This is a crude profiling
|
||
instrument, similar to the Unix <function>getrusage()</function> operating
|
||
system facility. <varname>log_statement_stats</varname> reports total
|
||
statement statistics, while the others report per-module statistics.
|
||
<varname>log_statement_stats</varname> cannot be enabled together with
|
||
any of the per-module options. All of these options are disabled by
|
||
default.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change these settings.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-autovacuum">
|
||
<title>Automatic Vacuuming</title>
|
||
|
||
<indexterm>
|
||
<primary>autovacuum</primary>
|
||
<secondary>configuration parameters</secondary>
|
||
</indexterm>
|
||
|
||
<para>
|
||
These settings control the behavior of the <firstterm>autovacuum</firstterm>
|
||
feature. Refer to <xref linkend="autovacuum"/> for more information.
|
||
Note that many of these settings can be overridden on a per-table
|
||
basis; see <xref linkend="sql-createtable-storage-parameters"/>.
|
||
</para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-autovacuum" xreflabel="autovacuum">
|
||
<term><varname>autovacuum</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls whether the server should run the
|
||
autovacuum launcher daemon. This is on by default; however,
|
||
<xref linkend="guc-track-counts"/> must also be enabled for
|
||
autovacuum to work.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line; however, autovacuuming can be
|
||
disabled for individual tables by changing table storage parameters.
|
||
</para>
|
||
<para>
|
||
Note that even when this parameter is disabled, the system
|
||
will launch autovacuum processes if necessary to
|
||
prevent transaction ID wraparound. See <xref
|
||
linkend="vacuum-for-wraparound"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-max-workers" xreflabel="autovacuum_max_workers">
|
||
<term><varname>autovacuum_max_workers</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_max_workers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum number of autovacuum processes (other than the
|
||
autovacuum launcher) that may be running at any one time. The default
|
||
is three. This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-naptime" xreflabel="autovacuum_naptime">
|
||
<term><varname>autovacuum_naptime</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_naptime</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the minimum delay between autovacuum runs on any given
|
||
database. In each round the daemon examines the
|
||
database and issues <command>VACUUM</command> and <command>ANALYZE</command> commands
|
||
as needed for tables in that database.
|
||
If this value is specified without units, it is taken as seconds.
|
||
The default is one minute (<literal>1min</literal>).
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-vacuum-threshold" xreflabel="autovacuum_vacuum_threshold">
|
||
<term><varname>autovacuum_vacuum_threshold</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_vacuum_threshold</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the minimum number of updated or deleted tuples needed
|
||
to trigger a <command>VACUUM</command> in any one table.
|
||
The default is 50 tuples.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line;
|
||
but the setting can be overridden for individual tables by
|
||
changing table storage parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-vacuum-insert-threshold" xreflabel="autovacuum_vacuum_insert_threshold">
|
||
<term><varname>autovacuum_vacuum_insert_threshold</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_vacuum_insert_threshold</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of inserted tuples needed to trigger a
|
||
<command>VACUUM</command> in any one table.
|
||
The default is 1000 tuples. If -1 is specified, autovacuum will not
|
||
trigger a <command>VACUUM</command> operation on any tables based on
|
||
the number of inserts.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line;
|
||
but the setting can be overridden for individual tables by
|
||
changing table storage parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-analyze-threshold" xreflabel="autovacuum_analyze_threshold">
|
||
<term><varname>autovacuum_analyze_threshold</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_analyze_threshold</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the minimum number of inserted, updated or deleted tuples
|
||
needed to trigger an <command>ANALYZE</command> in any one table.
|
||
The default is 50 tuples.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line;
|
||
but the setting can be overridden for individual tables by
|
||
changing table storage parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-vacuum-scale-factor" xreflabel="autovacuum_vacuum_scale_factor">
|
||
<term><varname>autovacuum_vacuum_scale_factor</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_vacuum_scale_factor</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a fraction of the table size to add to
|
||
<varname>autovacuum_vacuum_threshold</varname>
|
||
when deciding whether to trigger a <command>VACUUM</command>.
|
||
The default is 0.2 (20% of table size).
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line;
|
||
but the setting can be overridden for individual tables by
|
||
changing table storage parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-vacuum-insert-scale-factor" xreflabel="autovacuum_vacuum_insert_scale_factor">
|
||
<term><varname>autovacuum_vacuum_insert_scale_factor</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_vacuum_insert_scale_factor</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a fraction of the table size to add to
|
||
<varname>autovacuum_vacuum_insert_threshold</varname>
|
||
when deciding whether to trigger a <command>VACUUM</command>.
|
||
The default is 0.2 (20% of table size).
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line;
|
||
but the setting can be overridden for individual tables by
|
||
changing table storage parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-analyze-scale-factor" xreflabel="autovacuum_analyze_scale_factor">
|
||
<term><varname>autovacuum_analyze_scale_factor</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_analyze_scale_factor</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a fraction of the table size to add to
|
||
<varname>autovacuum_analyze_threshold</varname>
|
||
when deciding whether to trigger an <command>ANALYZE</command>.
|
||
The default is 0.1 (10% of table size).
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line;
|
||
but the setting can be overridden for individual tables by
|
||
changing table storage parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-freeze-max-age" xreflabel="autovacuum_freeze_max_age">
|
||
<term><varname>autovacuum_freeze_max_age</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_freeze_max_age</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum age (in transactions) that a table's
|
||
<structname>pg_class</structname>.<structfield>relfrozenxid</structfield> field can
|
||
attain before a <command>VACUUM</command> operation is forced
|
||
to prevent transaction ID wraparound within the table.
|
||
Note that the system will launch autovacuum processes to
|
||
prevent wraparound even when autovacuum is otherwise disabled.
|
||
</para>
|
||
|
||
<para>
|
||
Vacuum also allows removal of old files from the
|
||
<filename>pg_xact</filename> subdirectory, which is why the default
|
||
is a relatively low 200 million transactions.
|
||
This parameter can only be set at server start, but the setting
|
||
can be reduced for individual tables by
|
||
changing table storage parameters.
|
||
For more information see <xref linkend="vacuum-for-wraparound"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-multixact-freeze-max-age" xreflabel="autovacuum_multixact_freeze_max_age">
|
||
<term><varname>autovacuum_multixact_freeze_max_age</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_multixact_freeze_max_age</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum age (in multixacts) that a table's
|
||
<structname>pg_class</structname>.<structfield>relminmxid</structfield> field can
|
||
attain before a <command>VACUUM</command> operation is forced to
|
||
prevent multixact ID wraparound within the table.
|
||
Note that the system will launch autovacuum processes to
|
||
prevent wraparound even when autovacuum is otherwise disabled.
|
||
</para>
|
||
|
||
<para>
|
||
Vacuuming multixacts also allows removal of old files from the
|
||
<filename>pg_multixact/members</filename> and <filename>pg_multixact/offsets</filename>
|
||
subdirectories, which is why the default is a relatively low
|
||
400 million multixacts.
|
||
This parameter can only be set at server start, but the setting can
|
||
be reduced for individual tables by changing table storage parameters.
|
||
For more information see <xref linkend="vacuum-for-multixact-wraparound"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-vacuum-cost-delay" xreflabel="autovacuum_vacuum_cost_delay">
|
||
<term><varname>autovacuum_vacuum_cost_delay</varname> (<type>floating point</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_vacuum_cost_delay</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the cost delay value that will be used in automatic
|
||
<command>VACUUM</command> operations. If -1 is specified, the regular
|
||
<xref linkend="guc-vacuum-cost-delay"/> value will be used.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default value is 2 milliseconds.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line;
|
||
but the setting can be overridden for individual tables by
|
||
changing table storage parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-autovacuum-vacuum-cost-limit" xreflabel="autovacuum_vacuum_cost_limit">
|
||
<term><varname>autovacuum_vacuum_cost_limit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>autovacuum_vacuum_cost_limit</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the cost limit value that will be used in automatic
|
||
<command>VACUUM</command> operations. If -1 is specified (which is the
|
||
default), the regular
|
||
<xref linkend="guc-vacuum-cost-limit"/> value will be used. Note that
|
||
the value is distributed proportionally among the running autovacuum
|
||
workers, if there is more than one, so that the sum of the limits for
|
||
each worker does not exceed the value of this variable.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line;
|
||
but the setting can be overridden for individual tables by
|
||
changing table storage parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-client">
|
||
<title>Client Connection Defaults</title>
|
||
|
||
<sect2 id="runtime-config-client-statement">
|
||
<title>Statement Behavior</title>
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-client-min-messages" xreflabel="client_min_messages">
|
||
<term><varname>client_min_messages</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>client_min_messages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls which
|
||
<link linkend="runtime-config-severity-levels">message levels</link>
|
||
are sent to the client.
|
||
Valid values are <literal>DEBUG5</literal>,
|
||
<literal>DEBUG4</literal>, <literal>DEBUG3</literal>, <literal>DEBUG2</literal>,
|
||
<literal>DEBUG1</literal>, <literal>LOG</literal>, <literal>NOTICE</literal>,
|
||
<literal>WARNING</literal>, and <literal>ERROR</literal>.
|
||
Each level includes all the levels that follow it. The later the level,
|
||
the fewer messages are sent. The default is
|
||
<literal>NOTICE</literal>. Note that <literal>LOG</literal> has a different
|
||
rank here than in <xref linkend="guc-log-min-messages"/>.
|
||
</para>
|
||
<para>
|
||
<literal>INFO</literal> level messages are always sent to the client.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-search-path" xreflabel="search_path">
|
||
<term><varname>search_path</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>search_path</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm><primary>path</primary><secondary>for schemas</secondary></indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This variable specifies the order in which schemas are searched
|
||
when an object (table, data type, function, etc.) is referenced by a
|
||
simple name with no schema specified. When there are objects of
|
||
identical names in different schemas, the one found first
|
||
in the search path is used. An object that is not in any of the
|
||
schemas in the search path can only be referenced by specifying
|
||
its containing schema with a qualified (dotted) name.
|
||
</para>
|
||
|
||
<para>
|
||
The value for <varname>search_path</varname> must be a comma-separated
|
||
list of schema names. Any name that is not an existing schema, or is
|
||
a schema for which the user does not have <literal>USAGE</literal>
|
||
permission, is silently ignored.
|
||
</para>
|
||
|
||
<para>
|
||
If one of the list items is the special name
|
||
<literal>$user</literal>, then the schema having the name returned by
|
||
<function>CURRENT_USER</function> is substituted, if there is such a schema
|
||
and the user has <literal>USAGE</literal> permission for it.
|
||
(If not, <literal>$user</literal> is ignored.)
|
||
</para>
|
||
|
||
<para>
|
||
The system catalog schema, <literal>pg_catalog</literal>, is always
|
||
searched, whether it is mentioned in the path or not. If it is
|
||
mentioned in the path then it will be searched in the specified
|
||
order. If <literal>pg_catalog</literal> is not in the path then it will
|
||
be searched <emphasis>before</emphasis> searching any of the path items.
|
||
</para>
|
||
|
||
<!-- To further split hairs, funcname('foo') does not use the temporary
|
||
schema, even when it considers typname='funcname'. This paragraph
|
||
refers to function names in a loose sense, "pg_proc.proname or
|
||
func_name grammar production". -->
|
||
<para>
|
||
Likewise, the current session's temporary-table schema,
|
||
<literal>pg_temp_<replaceable>nnn</replaceable></literal>, is always searched if it
|
||
exists. It can be explicitly listed in the path by using the
|
||
alias <literal>pg_temp</literal><indexterm><primary>pg_temp</primary></indexterm>. If it is not listed in the path then
|
||
it is searched first (even before <literal>pg_catalog</literal>). However,
|
||
the temporary schema is only searched for relation (table, view,
|
||
sequence, etc.) and data type names. It is never searched for
|
||
function or operator names.
|
||
</para>
|
||
|
||
<para>
|
||
When objects are created without specifying a particular target
|
||
schema, they will be placed in the first valid schema named in
|
||
<varname>search_path</varname>. An error is reported if the search
|
||
path is empty.
|
||
</para>
|
||
|
||
<para>
|
||
The default value for this parameter is
|
||
<literal>"$user", public</literal>.
|
||
This setting supports shared use of a database (where no users
|
||
have private schemas, and all share use of <literal>public</literal>),
|
||
private per-user schemas, and combinations of these. Other
|
||
effects can be obtained by altering the default search path
|
||
setting, either globally or per-user.
|
||
</para>
|
||
|
||
<para>
|
||
For more information on schema handling, see
|
||
<xref linkend="ddl-schemas"/>. In particular, the default
|
||
configuration is suitable only when the database has a single user or
|
||
a few mutually-trusting users.
|
||
</para>
|
||
|
||
<para>
|
||
The current effective value of the search path can be examined
|
||
via the <acronym>SQL</acronym> function
|
||
<function>current_schemas</function>
|
||
(see <xref linkend="functions-info"/>).
|
||
This is not quite the same as
|
||
examining the value of <varname>search_path</varname>, since
|
||
<function>current_schemas</function> shows how the items
|
||
appearing in <varname>search_path</varname> were resolved.
|
||
</para>
|
||
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-row-security" xreflabel="row_security">
|
||
<term><varname>row_security</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>row_security</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This variable controls whether to raise an error in lieu of applying a
|
||
row security policy. When set to <literal>on</literal>, policies apply
|
||
normally. When set to <literal>off</literal>, queries fail which would
|
||
otherwise apply at least one policy. The default is <literal>on</literal>.
|
||
Change to <literal>off</literal> where limited row visibility could cause
|
||
incorrect results; for example, <application>pg_dump</application> makes that
|
||
change by default. This variable has no effect on roles which bypass
|
||
every row security policy, to wit, superusers and roles with
|
||
the <literal>BYPASSRLS</literal> attribute.
|
||
</para>
|
||
|
||
<para>
|
||
For more information on row security policies,
|
||
see <xref linkend="sql-createpolicy"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-default-table-access-method" xreflabel="default_table_access_method">
|
||
<term><varname>default_table_access_method</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>default_table_access_method</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter specifies the default table access method to use when
|
||
creating tables or materialized views if the <command>CREATE</command>
|
||
command does not explicitly specify an access method, or when
|
||
<command>SELECT ... INTO</command> is used, which does not allow
|
||
specifying a table access method. The default is <literal>heap</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-default-tablespace" xreflabel="default_tablespace">
|
||
<term><varname>default_tablespace</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>default_tablespace</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm><primary>tablespace</primary><secondary>default</secondary></indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This variable specifies the default tablespace in which to create
|
||
objects (tables and indexes) when a <command>CREATE</command> command does
|
||
not explicitly specify a tablespace.
|
||
</para>
|
||
|
||
<para>
|
||
The value is either the name of a tablespace, or an empty string
|
||
to specify using the default tablespace of the current database.
|
||
If the value does not match the name of any existing tablespace,
|
||
<productname>PostgreSQL</productname> will automatically use the default
|
||
tablespace of the current database. If a nondefault tablespace
|
||
is specified, the user must have <literal>CREATE</literal> privilege
|
||
for it, or creation attempts will fail.
|
||
</para>
|
||
|
||
<para>
|
||
This variable is not used for temporary tables; for them,
|
||
<xref linkend="guc-temp-tablespaces"/> is consulted instead.
|
||
</para>
|
||
|
||
<para>
|
||
This variable is also not used when creating databases.
|
||
By default, a new database inherits its tablespace setting from
|
||
the template database it is copied from.
|
||
</para>
|
||
|
||
<para>
|
||
If this parameter is set to a value other than the empty string
|
||
when a partitioned table is created, the partitioned table's
|
||
tablespace will be set to that value, which will be used as
|
||
the default tablespace for partitions created in the future,
|
||
even if <varname>default_tablespace</varname> has changed since then.
|
||
</para>
|
||
|
||
<para>
|
||
For more information on tablespaces,
|
||
see <xref linkend="manage-ag-tablespaces"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-default-toast-compression" xreflabel="default_toast_compression">
|
||
<term><varname>default_toast_compression</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>default_toast_compression</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This variable sets the default
|
||
<link linkend="storage-toast">TOAST</link>
|
||
compression method for values of compressible columns.
|
||
(This can be overridden for individual columns by setting
|
||
the <literal>COMPRESSION</literal> column option in
|
||
<command>CREATE TABLE</command> or
|
||
<command>ALTER TABLE</command>.)
|
||
The supported compression methods are <literal>pglz</literal> and
|
||
(if <productname>PostgreSQL</productname> was compiled with
|
||
<option>--with-lz4</option>) <literal>lz4</literal>.
|
||
The default is <literal>pglz</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-temp-tablespaces" xreflabel="temp_tablespaces">
|
||
<term><varname>temp_tablespaces</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>temp_tablespaces</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm><primary>tablespace</primary><secondary>temporary</secondary></indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This variable specifies tablespaces in which to create temporary
|
||
objects (temp tables and indexes on temp tables) when a
|
||
<command>CREATE</command> command does not explicitly specify a tablespace.
|
||
Temporary files for purposes such as sorting large data sets
|
||
are also created in these tablespaces.
|
||
</para>
|
||
|
||
<para>
|
||
The value is a list of names of tablespaces. When there is more than
|
||
one name in the list, <productname>PostgreSQL</productname> chooses a random
|
||
member of the list each time a temporary object is to be created;
|
||
except that within a transaction, successively created temporary
|
||
objects are placed in successive tablespaces from the list.
|
||
If the selected element of the list is an empty string,
|
||
<productname>PostgreSQL</productname> will automatically use the default
|
||
tablespace of the current database instead.
|
||
</para>
|
||
|
||
<para>
|
||
When <varname>temp_tablespaces</varname> is set interactively, specifying a
|
||
nonexistent tablespace is an error, as is specifying a tablespace for
|
||
which the user does not have <literal>CREATE</literal> privilege. However,
|
||
when using a previously set value, nonexistent tablespaces are
|
||
ignored, as are tablespaces for which the user lacks
|
||
<literal>CREATE</literal> privilege. In particular, this rule applies when
|
||
using a value set in <filename>postgresql.conf</filename>.
|
||
</para>
|
||
|
||
<para>
|
||
The default value is an empty string, which results in all temporary
|
||
objects being created in the default tablespace of the current
|
||
database.
|
||
</para>
|
||
|
||
<para>
|
||
See also <xref linkend="guc-default-tablespace"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-check-function-bodies" xreflabel="check_function_bodies">
|
||
<term><varname>check_function_bodies</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>check_function_bodies</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter is normally on. When set to <literal>off</literal>, it
|
||
disables validation of the routine body string during <xref
|
||
linkend="sql-createfunction"/> and <xref
|
||
linkend="sql-createprocedure"/>. Disabling validation avoids side
|
||
effects of the validation process, in particular preventing false
|
||
positives due to problems such as forward references.
|
||
Set this parameter
|
||
to <literal>off</literal> before loading functions on behalf of other
|
||
users; <application>pg_dump</application> does so automatically.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-default-transaction-isolation" xreflabel="default_transaction_isolation">
|
||
<term><varname>default_transaction_isolation</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary>transaction isolation level</primary>
|
||
<secondary>setting default</secondary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>default_transaction_isolation</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Each SQL transaction has an isolation level, which can be
|
||
either <quote>read uncommitted</quote>, <quote>read
|
||
committed</quote>, <quote>repeatable read</quote>, or
|
||
<quote>serializable</quote>. This parameter controls the
|
||
default isolation level of each new transaction. The default
|
||
is <quote>read committed</quote>.
|
||
</para>
|
||
|
||
<para>
|
||
Consult <xref linkend="mvcc"/> and <xref
|
||
linkend="sql-set-transaction"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-default-transaction-read-only" xreflabel="default_transaction_read_only">
|
||
<term><varname>default_transaction_read_only</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary>read-only transaction</primary>
|
||
<secondary>setting default</secondary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>default_transaction_read_only</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A read-only SQL transaction cannot alter non-temporary tables.
|
||
This parameter controls the default read-only status of each new
|
||
transaction. The default is <literal>off</literal> (read/write).
|
||
</para>
|
||
|
||
<para>
|
||
Consult <xref linkend="sql-set-transaction"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-default-transaction-deferrable" xreflabel="default_transaction_deferrable">
|
||
<term><varname>default_transaction_deferrable</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary>deferrable transaction</primary>
|
||
<secondary>setting default</secondary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>default_transaction_deferrable</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When running at the <literal>serializable</literal> isolation level,
|
||
a deferrable read-only SQL transaction may be delayed before
|
||
it is allowed to proceed. However, once it begins executing
|
||
it does not incur any of the overhead required to ensure
|
||
serializability; so serialization code will have no reason to
|
||
force it to abort because of concurrent updates, making this
|
||
option suitable for long-running read-only transactions.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter controls the default deferrable status of each
|
||
new transaction. It currently has no effect on read-write
|
||
transactions or those operating at isolation levels lower
|
||
than <literal>serializable</literal>. The default is <literal>off</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
Consult <xref linkend="sql-set-transaction"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-transaction-isolation" xreflabel="transaction_isolation">
|
||
<term><varname>transaction_isolation</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary>transaction isolation level</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>transaction_isolation</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter reflects the current transaction's isolation level.
|
||
At the beginning of each transaction, it is set to the current value
|
||
of <xref linkend="guc-default-transaction-isolation"/>.
|
||
Any subsequent attempt to change it is equivalent to a <xref
|
||
linkend="sql-set-transaction"/> command.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-transaction-read-only" xreflabel="transaction_read_only">
|
||
<term><varname>transaction_read_only</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary>read-only transaction</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>transaction_read_only</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter reflects the current transaction's read-only status.
|
||
At the beginning of each transaction, it is set to the current value
|
||
of <xref linkend="guc-default-transaction-read-only"/>.
|
||
Any subsequent attempt to change it is equivalent to a <xref
|
||
linkend="sql-set-transaction"/> command.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-transaction-deferrable" xreflabel="transaction_deferrable">
|
||
<term><varname>transaction_deferrable</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary>deferrable transaction</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>transaction_deferrable</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter reflects the current transaction's deferrability status.
|
||
At the beginning of each transaction, it is set to the current value
|
||
of <xref linkend="guc-default-transaction-deferrable"/>.
|
||
Any subsequent attempt to change it is equivalent to a <xref
|
||
linkend="sql-set-transaction"/> command.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry id="guc-session-replication-role" xreflabel="session_replication_role">
|
||
<term><varname>session_replication_role</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>session_replication_role</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls firing of replication-related triggers and rules for the
|
||
current session.
|
||
Possible values are <literal>origin</literal> (the default),
|
||
<literal>replica</literal> and <literal>local</literal>.
|
||
Setting this parameter results in discarding any previously cached
|
||
query plans.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<para>
|
||
The intended use of this setting is that logical replication systems
|
||
set it to <literal>replica</literal> when they are applying replicated
|
||
changes. The effect of that will be that triggers and rules (that
|
||
have not been altered from their default configuration) will not fire
|
||
on the replica. See the <link linkend="sql-altertable"><command>ALTER TABLE</command></link> clauses
|
||
<literal>ENABLE TRIGGER</literal> and <literal>ENABLE RULE</literal>
|
||
for more information.
|
||
</para>
|
||
|
||
<para>
|
||
PostgreSQL treats the settings <literal>origin</literal> and
|
||
<literal>local</literal> the same internally. Third-party replication
|
||
systems may use these two values for their internal purposes, for
|
||
example using <literal>local</literal> to designate a session whose
|
||
changes should not be replicated.
|
||
</para>
|
||
|
||
<para>
|
||
Since foreign keys are implemented as triggers, setting this parameter
|
||
to <literal>replica</literal> also disables all foreign key checks,
|
||
which can leave data in an inconsistent state if improperly used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-statement-timeout" xreflabel="statement_timeout">
|
||
<term><varname>statement_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>statement_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Abort any statement that takes more than the specified amount of time.
|
||
If <varname>log_min_error_statement</varname> is set
|
||
to <literal>ERROR</literal> or lower, the statement that timed out
|
||
will also be logged.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
A value of zero (the default) disables the timeout.
|
||
</para>
|
||
|
||
<para>
|
||
The timeout is measured from the time a command arrives at the
|
||
server until it is completed by the server. If multiple SQL
|
||
statements appear in a single simple-query message, the timeout
|
||
is applied to each statement separately.
|
||
(<productname>PostgreSQL</productname> versions before 13 usually
|
||
treated the timeout as applying to the whole query string.)
|
||
In extended query protocol, the timeout starts running when any
|
||
query-related message (Parse, Bind, Execute, Describe) arrives, and
|
||
it is canceled by completion of an Execute or Sync message.
|
||
</para>
|
||
|
||
<para>
|
||
Setting <varname>statement_timeout</varname> in
|
||
<filename>postgresql.conf</filename> is not recommended because it would
|
||
affect all sessions.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-transaction-timeout" xreflabel="transaction_timeout">
|
||
<term><varname>transaction_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>transaction_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Terminate any session that spans longer than the specified amount of
|
||
time in a transaction. The limit applies both to explicit transactions
|
||
(started with <command>BEGIN</command>) and to an implicitly started
|
||
transaction corresponding to a single statement.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
A value of zero (the default) disables the timeout.
|
||
</para>
|
||
|
||
<para>
|
||
If <varname>transaction_timeout</varname> is shorter or equal to
|
||
<varname>idle_in_transaction_session_timeout</varname> or <varname>statement_timeout</varname>
|
||
then the longer timeout is ignored.
|
||
</para>
|
||
|
||
<para>
|
||
Setting <varname>transaction_timeout</varname> in
|
||
<filename>postgresql.conf</filename> is not recommended because it would
|
||
affect all sessions.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
Prepared transactions are not subject to this timeout.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-lock-timeout" xreflabel="lock_timeout">
|
||
<term><varname>lock_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>lock_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Abort any statement that waits longer than the specified amount of
|
||
time while attempting to acquire a lock on a table, index,
|
||
row, or other database object. The time limit applies separately to
|
||
each lock acquisition attempt. The limit applies both to explicit
|
||
locking requests (such as <command>LOCK TABLE</command>, or <command>SELECT
|
||
FOR UPDATE</command> without <literal>NOWAIT</literal>) and to implicitly-acquired
|
||
locks.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
A value of zero (the default) disables the timeout.
|
||
</para>
|
||
|
||
<para>
|
||
Unlike <varname>statement_timeout</varname>, this timeout can only occur
|
||
while waiting for locks. Note that if <varname>statement_timeout</varname>
|
||
is nonzero, it is rather pointless to set <varname>lock_timeout</varname> to
|
||
the same or larger value, since the statement timeout would always
|
||
trigger first. If <varname>log_min_error_statement</varname> is set to
|
||
<literal>ERROR</literal> or lower, the statement that timed out will be
|
||
logged.
|
||
</para>
|
||
|
||
<para>
|
||
Setting <varname>lock_timeout</varname> in
|
||
<filename>postgresql.conf</filename> is not recommended because it would
|
||
affect all sessions.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-idle-in-transaction-session-timeout" xreflabel="idle_in_transaction_session_timeout">
|
||
<term><varname>idle_in_transaction_session_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>idle_in_transaction_session_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Terminate any session that has been idle (that is, waiting for a
|
||
client query) within an open transaction for longer than the
|
||
specified amount of time.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
A value of zero (the default) disables the timeout.
|
||
</para>
|
||
|
||
<para>
|
||
This option can be used to ensure that idle sessions do not hold
|
||
locks for an unreasonable amount of time. Even when no significant
|
||
locks are held, an open transaction prevents vacuuming away
|
||
recently-dead tuples that may be visible only to this transaction;
|
||
so remaining idle for a long time can contribute to table bloat.
|
||
See <xref linkend="routine-vacuuming"/> for more details.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-idle-session-timeout" xreflabel="idle_session_timeout">
|
||
<term><varname>idle_session_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>idle_session_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Terminate any session that has been idle (that is, waiting for a
|
||
client query), but not within an open transaction, for longer than
|
||
the specified amount of time.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
A value of zero (the default) disables the timeout.
|
||
</para>
|
||
|
||
<para>
|
||
Unlike the case with an open transaction, an idle session without a
|
||
transaction imposes no large costs on the server, so there is less
|
||
need to enable this timeout
|
||
than <varname>idle_in_transaction_session_timeout</varname>.
|
||
</para>
|
||
|
||
<para>
|
||
Be wary of enforcing this timeout on connections made through
|
||
connection-pooling software or other middleware, as such a layer
|
||
may not react well to unexpected connection closure. It may be
|
||
helpful to enable this timeout only for interactive sessions,
|
||
perhaps by applying it only to particular users.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-freeze-table-age" xreflabel="vacuum_freeze_table_age">
|
||
<term><varname>vacuum_freeze_table_age</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_freeze_table_age</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
<command>VACUUM</command> performs an aggressive scan if the table's
|
||
<structname>pg_class</structname>.<structfield>relfrozenxid</structfield> field has reached
|
||
the age specified by this setting. An aggressive scan differs from
|
||
a regular <command>VACUUM</command> in that it visits every page that might
|
||
contain unfrozen XIDs or MXIDs, not just those that might contain dead
|
||
tuples. The default is 150 million transactions. Although users can
|
||
set this value anywhere from zero to two billion, <command>VACUUM</command>
|
||
will silently limit the effective value to 95% of
|
||
<xref linkend="guc-autovacuum-freeze-max-age"/>, so that a
|
||
periodic manual <command>VACUUM</command> has a chance to run before an
|
||
anti-wraparound autovacuum is launched for the table. For more
|
||
information see
|
||
<xref linkend="vacuum-for-wraparound"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-freeze-min-age" xreflabel="vacuum_freeze_min_age">
|
||
<term><varname>vacuum_freeze_min_age</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_freeze_min_age</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the cutoff age (in transactions) that
|
||
<command>VACUUM</command> should use to decide whether to
|
||
trigger freezing of pages that have an older XID.
|
||
The default is 50 million transactions. Although
|
||
users can set this value anywhere from zero to one billion,
|
||
<command>VACUUM</command> will silently limit the effective value to half
|
||
the value of <xref linkend="guc-autovacuum-freeze-max-age"/>, so
|
||
that there is not an unreasonably short time between forced
|
||
autovacuums. For more information see <xref
|
||
linkend="vacuum-for-wraparound"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-failsafe-age" xreflabel="vacuum_failsafe_age">
|
||
<term><varname>vacuum_failsafe_age</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_failsafe_age</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum age (in transactions) that a table's
|
||
<structname>pg_class</structname>.<structfield>relfrozenxid</structfield>
|
||
field can attain before <command>VACUUM</command> takes
|
||
extraordinary measures to avoid system-wide transaction ID
|
||
wraparound failure. This is <command>VACUUM</command>'s
|
||
strategy of last resort. The failsafe typically triggers
|
||
when an autovacuum to prevent transaction ID wraparound has
|
||
already been running for some time, though it's possible for
|
||
the failsafe to trigger during any <command>VACUUM</command>.
|
||
</para>
|
||
<para>
|
||
When the failsafe is triggered, any cost-based delay that is
|
||
in effect will no longer be applied, further non-essential
|
||
maintenance tasks (such as index vacuuming) are bypassed, and any
|
||
<glossterm linkend="glossary-buffer-access-strategy">Buffer Access Strategy</glossterm>
|
||
in use will be disabled resulting in <command>VACUUM</command> being
|
||
free to make use of all of
|
||
<glossterm linkend="glossary-shared-memory">shared buffers</glossterm>.
|
||
</para>
|
||
<para>
|
||
The default is 1.6 billion transactions. Although users can
|
||
set this value anywhere from zero to 2.1 billion,
|
||
<command>VACUUM</command> will silently adjust the effective
|
||
value to no less than 105% of <xref
|
||
linkend="guc-autovacuum-freeze-max-age"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-multixact-freeze-table-age" xreflabel="vacuum_multixact_freeze_table_age">
|
||
<term><varname>vacuum_multixact_freeze_table_age</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_multixact_freeze_table_age</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
<command>VACUUM</command> performs an aggressive scan if the table's
|
||
<structname>pg_class</structname>.<structfield>relminmxid</structfield> field has reached
|
||
the age specified by this setting. An aggressive scan differs from
|
||
a regular <command>VACUUM</command> in that it visits every page that might
|
||
contain unfrozen XIDs or MXIDs, not just those that might contain dead
|
||
tuples. The default is 150 million multixacts.
|
||
Although users can set this value anywhere from zero to two billion,
|
||
<command>VACUUM</command> will silently limit the effective value to 95% of
|
||
<xref linkend="guc-autovacuum-multixact-freeze-max-age"/>, so that a
|
||
periodic manual <command>VACUUM</command> has a chance to run before an
|
||
anti-wraparound is launched for the table.
|
||
For more information see <xref linkend="vacuum-for-multixact-wraparound"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-multixact-freeze-min-age" xreflabel="vacuum_multixact_freeze_min_age">
|
||
<term><varname>vacuum_multixact_freeze_min_age</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_multixact_freeze_min_age</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the cutoff age (in multixacts) that <command>VACUUM</command>
|
||
should use to decide whether to trigger freezing of pages with
|
||
an older multixact ID. The default is 5 million multixacts.
|
||
Although users can set this value anywhere from zero to one billion,
|
||
<command>VACUUM</command> will silently limit the effective value to half
|
||
the value of <xref linkend="guc-autovacuum-multixact-freeze-max-age"/>,
|
||
so that there is not an unreasonably short time between forced
|
||
autovacuums.
|
||
For more information see <xref linkend="vacuum-for-multixact-wraparound"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-vacuum-multixact-failsafe-age" xreflabel="vacuum_multixact_failsafe_age">
|
||
<term><varname>vacuum_multixact_failsafe_age</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>vacuum_multixact_failsafe_age</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the maximum age (in multixacts) that a table's
|
||
<structname>pg_class</structname>.<structfield>relminmxid</structfield>
|
||
field can attain before <command>VACUUM</command> takes
|
||
extraordinary measures to avoid system-wide multixact ID
|
||
wraparound failure. This is <command>VACUUM</command>'s
|
||
strategy of last resort. The failsafe typically triggers when
|
||
an autovacuum to prevent transaction ID wraparound has already
|
||
been running for some time, though it's possible for the
|
||
failsafe to trigger during any <command>VACUUM</command>.
|
||
</para>
|
||
<para>
|
||
When the failsafe is triggered, any cost-based delay that is
|
||
in effect will no longer be applied, and further non-essential
|
||
maintenance tasks (such as index vacuuming) are bypassed.
|
||
</para>
|
||
<para>
|
||
The default is 1.6 billion multixacts. Although users can set
|
||
this value anywhere from zero to 2.1 billion,
|
||
<command>VACUUM</command> will silently adjust the effective
|
||
value to no less than 105% of <xref
|
||
linkend="guc-autovacuum-multixact-freeze-max-age"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-bytea-output" xreflabel="bytea_output">
|
||
<term><varname>bytea_output</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>bytea_output</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the output format for values of type <type>bytea</type>.
|
||
Valid values are <literal>hex</literal> (the default)
|
||
and <literal>escape</literal> (the traditional PostgreSQL
|
||
format). See <xref linkend="datatype-binary"/> for more
|
||
information. The <type>bytea</type> type always
|
||
accepts both formats on input, regardless of this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-xmlbinary" xreflabel="xmlbinary">
|
||
<term><varname>xmlbinary</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>xmlbinary</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets how binary values are to be encoded in XML. This applies
|
||
for example when <type>bytea</type> values are converted to
|
||
XML by the functions <function>xmlelement</function> or
|
||
<function>xmlforest</function>. Possible values are
|
||
<literal>base64</literal> and <literal>hex</literal>, which
|
||
are both defined in the XML Schema standard. The default is
|
||
<literal>base64</literal>. For further information about
|
||
XML-related functions, see <xref linkend="functions-xml"/>.
|
||
</para>
|
||
|
||
<para>
|
||
The actual choice here is mostly a matter of taste,
|
||
constrained only by possible restrictions in client
|
||
applications. Both methods support all possible values,
|
||
although the hex encoding will be somewhat larger than the
|
||
base64 encoding.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-xmloption" xreflabel="xmloption">
|
||
<term><varname>xmloption</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>xmloption</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>SET XML OPTION</varname></primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary>XML option</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets whether <literal>DOCUMENT</literal> or
|
||
<literal>CONTENT</literal> is implicit when converting between
|
||
XML and character string values. See <xref
|
||
linkend="datatype-xml"/> for a description of this. Valid
|
||
values are <literal>DOCUMENT</literal> and
|
||
<literal>CONTENT</literal>. The default is
|
||
<literal>CONTENT</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
According to the SQL standard, the command to set this option is
|
||
<synopsis>
|
||
SET XML OPTION { DOCUMENT | CONTENT };
|
||
</synopsis>
|
||
This syntax is also available in PostgreSQL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-gin-pending-list-limit" xreflabel="gin_pending_list_limit">
|
||
<term><varname>gin_pending_list_limit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>gin_pending_list_limit</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the maximum size of a GIN index's pending list, which is used
|
||
when <literal>fastupdate</literal> is enabled. If the list grows
|
||
larger than this maximum size, it is cleaned up by moving
|
||
the entries in it to the index's main GIN data structure in bulk.
|
||
If this value is specified without units, it is taken as kilobytes.
|
||
The default is four megabytes (<literal>4MB</literal>). This setting
|
||
can be overridden for individual GIN indexes by changing
|
||
index storage parameters.
|
||
See <xref linkend="gin-fast-update"/> and <xref linkend="gin-tips"/>
|
||
for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-createrole-self-grant" xreflabel="createrole_self_grant">
|
||
<term><varname>createrole_self_grant</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>createrole_self_grant</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If a user who has <literal>CREATEROLE</literal> but not
|
||
<literal>SUPERUSER</literal> creates a role, and if this
|
||
is set to a non-empty value, the newly-created role will be granted
|
||
to the creating user with the options specified. The value must be
|
||
<literal>set</literal>, <literal>inherit</literal>, or a
|
||
comma-separated list of these. The default value is an empty string,
|
||
which disables the feature.
|
||
</para>
|
||
<para>
|
||
The purpose of this option is to allow a <literal>CREATEROLE</literal>
|
||
user who is not a superuser to automatically inherit, or automatically
|
||
gain the ability to <literal>SET ROLE</literal> to, any created users.
|
||
Since a <literal>CREATEROLE</literal> user is always implicitly granted
|
||
<literal>ADMIN OPTION</literal> on created roles, that user could
|
||
always execute a <literal>GRANT</literal> statement that would achieve
|
||
the same effect as this setting. However, it can be convenient for
|
||
usability reasons if the grant happens automatically. A superuser
|
||
automatically inherits the privileges of every role and can always
|
||
<literal>SET ROLE</literal> to any role, and this setting can be used
|
||
to produce a similar behavior for <literal>CREATEROLE</literal> users
|
||
for users which they create.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-event-triggers" xreflabel="event_triggers">
|
||
<term><varname>event_triggers</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>event_triggers</varname></primary>
|
||
<secondary>configuration parameter</secondary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Allow temporarily disabling execution of event triggers in order to
|
||
troubleshoot and repair faulty event triggers. All event triggers will
|
||
be disabled by setting it to <literal>false</literal>. Setting the value
|
||
to <literal>true</literal> allows all event triggers to fire, this
|
||
is the default value. Only superusers and users with the appropriate
|
||
<literal>SET</literal> privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
<sect2 id="runtime-config-client-format">
|
||
<title>Locale and Formatting</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-datestyle" xreflabel="DateStyle">
|
||
<term><varname>DateStyle</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>DateStyle</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the display format for date and time values, as well as the
|
||
rules for interpreting ambiguous date input values. For
|
||
historical reasons, this variable contains two independent
|
||
components: the output format specification (<literal>ISO</literal>,
|
||
<literal>Postgres</literal>, <literal>SQL</literal>, or <literal>German</literal>)
|
||
and the input/output specification for year/month/day ordering
|
||
(<literal>DMY</literal>, <literal>MDY</literal>, or <literal>YMD</literal>). These
|
||
can be set separately or together. The keywords <literal>Euro</literal>
|
||
and <literal>European</literal> are synonyms for <literal>DMY</literal>; the
|
||
keywords <literal>US</literal>, <literal>NonEuro</literal>, and
|
||
<literal>NonEuropean</literal> are synonyms for <literal>MDY</literal>. See
|
||
<xref linkend="datatype-datetime"/> for more information. The
|
||
built-in default is <literal>ISO, MDY</literal>, but
|
||
<application>initdb</application> will initialize the
|
||
configuration file with a setting that corresponds to the
|
||
behavior of the chosen <varname>lc_time</varname> locale.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-intervalstyle" xreflabel="IntervalStyle">
|
||
<term><varname>IntervalStyle</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>IntervalStyle</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the display format for interval values.
|
||
The value <literal>sql_standard</literal> will produce
|
||
output matching <acronym>SQL</acronym> standard interval literals.
|
||
The value <literal>postgres</literal> (which is the default) will produce
|
||
output matching <productname>PostgreSQL</productname> releases prior to 8.4
|
||
when the <xref linkend="guc-datestyle"/>
|
||
parameter was set to <literal>ISO</literal>.
|
||
The value <literal>postgres_verbose</literal> will produce output
|
||
matching <productname>PostgreSQL</productname> releases prior to 8.4
|
||
when the <varname>DateStyle</varname>
|
||
parameter was set to non-<literal>ISO</literal> output.
|
||
The value <literal>iso_8601</literal> will produce output matching the time
|
||
interval <quote>format with designators</quote> defined in section
|
||
4.4.3.2 of ISO 8601.
|
||
</para>
|
||
<para>
|
||
The <varname>IntervalStyle</varname> parameter also affects the
|
||
interpretation of ambiguous interval input. See
|
||
<xref linkend="datatype-interval-input"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-timezone" xreflabel="TimeZone">
|
||
<term><varname>TimeZone</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>TimeZone</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm><primary>time zone</primary></indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the time zone for displaying and interpreting time stamps.
|
||
The built-in default is <literal>GMT</literal>, but that is typically
|
||
overridden in <filename>postgresql.conf</filename>; <application>initdb</application>
|
||
will install a setting there corresponding to its system environment.
|
||
See <xref linkend="datatype-timezones"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-timezone-abbreviations" xreflabel="timezone_abbreviations">
|
||
<term><varname>timezone_abbreviations</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>timezone_abbreviations</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm><primary>time zone names</primary></indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the collection of time zone abbreviations that will be accepted
|
||
by the server for datetime input. The default is <literal>'Default'</literal>,
|
||
which is a collection that works in most of the world; there are
|
||
also <literal>'Australia'</literal> and <literal>'India'</literal>,
|
||
and other collections can be defined for a particular installation.
|
||
See <xref linkend="datetime-config-files"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-extra-float-digits" xreflabel="extra_float_digits">
|
||
<term><varname>extra_float_digits</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary>significant digits</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary>floating-point</primary>
|
||
<secondary>display</secondary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>extra_float_digits</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter adjusts the number of digits used for textual output of
|
||
floating-point values, including <type>float4</type>, <type>float8</type>,
|
||
and geometric data types.
|
||
</para>
|
||
<para>
|
||
If the value is 1 (the default) or above, float values are output in
|
||
shortest-precise format; see <xref linkend="datatype-float"/>. The
|
||
actual number of digits generated depends only on the value being
|
||
output, not on the value of this parameter. At most 17 digits are
|
||
required for <type>float8</type> values, and 9 for <type>float4</type>
|
||
values. This format is both fast and precise, preserving the original
|
||
binary float value exactly when correctly read. For historical
|
||
compatibility, values up to 3 are permitted.
|
||
</para>
|
||
<para>
|
||
If the value is zero or negative, then the output is rounded to a
|
||
given decimal precision. The precision used is the standard number of
|
||
digits for the type (<literal>FLT_DIG</literal>
|
||
or <literal>DBL_DIG</literal> as appropriate) reduced according to the
|
||
value of this parameter. (For example, specifying -1 will cause
|
||
<type>float4</type> values to be output rounded to 5 significant
|
||
digits, and <type>float8</type> values
|
||
rounded to 14 digits.) This format is slower and does not preserve all
|
||
the bits of the binary float value, but may be more human-readable.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
The meaning of this parameter, and its default value, changed
|
||
in <productname>PostgreSQL</productname> 12;
|
||
see <xref linkend="datatype-float"/> for further discussion.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-client-encoding" xreflabel="client_encoding">
|
||
<term><varname>client_encoding</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>client_encoding</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm><primary>character set</primary></indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the client-side encoding (character set).
|
||
The default is to use the database encoding.
|
||
The character sets supported by the <productname>PostgreSQL</productname>
|
||
server are described in <xref linkend="multibyte-charset-supported"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-lc-messages" xreflabel="lc_messages">
|
||
<term><varname>lc_messages</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>lc_messages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the language in which messages are displayed. Acceptable
|
||
values are system-dependent; see <xref linkend="locale"/> for
|
||
more information. If this variable is set to the empty string
|
||
(which is the default) then the value is inherited from the
|
||
execution environment of the server in a system-dependent way.
|
||
</para>
|
||
|
||
<para>
|
||
On some systems, this locale category does not exist. Setting
|
||
this variable will still work, but there will be no effect.
|
||
Also, there is a chance that no translated messages for the
|
||
desired language exist. In that case you will continue to see
|
||
the English messages.
|
||
</para>
|
||
|
||
<para>
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-lc-monetary" xreflabel="lc_monetary">
|
||
<term><varname>lc_monetary</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>lc_monetary</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the locale to use for formatting monetary amounts, for
|
||
example with the <function>to_char</function> family of
|
||
functions. Acceptable values are system-dependent; see <xref
|
||
linkend="locale"/> for more information. If this variable is
|
||
set to the empty string (which is the default) then the value
|
||
is inherited from the execution environment of the server in a
|
||
system-dependent way.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-lc-numeric" xreflabel="lc_numeric">
|
||
<term><varname>lc_numeric</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>lc_numeric</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the locale to use for formatting numbers, for example
|
||
with the <function>to_char</function> family of
|
||
functions. Acceptable values are system-dependent; see <xref
|
||
linkend="locale"/> for more information. If this variable is
|
||
set to the empty string (which is the default) then the value
|
||
is inherited from the execution environment of the server in a
|
||
system-dependent way.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-lc-time" xreflabel="lc_time">
|
||
<term><varname>lc_time</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>lc_time</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the locale to use for formatting dates and times, for example
|
||
with the <function>to_char</function> family of
|
||
functions. Acceptable values are system-dependent; see <xref
|
||
linkend="locale"/> for more information. If this variable is
|
||
set to the empty string (which is the default) then the value
|
||
is inherited from the execution environment of the server in a
|
||
system-dependent way.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-icu-validation-level" xreflabel="icu_validation_level">
|
||
<term><varname>icu_validation_level</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>icu_validation_level</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When ICU locale validation problems are encountered, controls which
|
||
<link linkend="runtime-config-severity-levels">message level</link> is
|
||
used to report the problem. Valid values are
|
||
<literal>DISABLED</literal>, <literal>DEBUG5</literal>,
|
||
<literal>DEBUG4</literal>, <literal>DEBUG3</literal>,
|
||
<literal>DEBUG2</literal>, <literal>DEBUG1</literal>,
|
||
<literal>INFO</literal>, <literal>NOTICE</literal>,
|
||
<literal>WARNING</literal>, <literal>ERROR</literal>, and
|
||
<literal>LOG</literal>.
|
||
</para>
|
||
<para>
|
||
If set to <literal>DISABLED</literal>, does not report validation
|
||
problems at all. Otherwise reports problems at the given message
|
||
level. The default is <literal>WARNING</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-default-text-search-config" xreflabel="default_text_search_config">
|
||
<term><varname>default_text_search_config</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>default_text_search_config</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Selects the text search configuration that is used by those variants
|
||
of the text search functions that do not have an explicit argument
|
||
specifying the configuration.
|
||
See <xref linkend="textsearch"/> for further information.
|
||
The built-in default is <literal>pg_catalog.simple</literal>, but
|
||
<application>initdb</application> will initialize the
|
||
configuration file with a setting that corresponds to the
|
||
chosen <varname>lc_ctype</varname> locale, if a configuration
|
||
matching that locale can be identified.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-client-preload">
|
||
<title>Shared Library Preloading</title>
|
||
|
||
<para>
|
||
Several settings are available for preloading shared libraries into the
|
||
server, in order to load additional functionality or achieve performance
|
||
benefits. For example, a setting of
|
||
<literal>'$libdir/mylib'</literal> would cause
|
||
<literal>mylib.so</literal> (or on some platforms,
|
||
<literal>mylib.sl</literal>) to be preloaded from the installation's standard
|
||
library directory. The differences between the settings are when they
|
||
take effect and what privileges are required to change them.
|
||
</para>
|
||
|
||
<para>
|
||
<productname>PostgreSQL</productname> procedural language libraries can
|
||
be preloaded in this way, typically by using the
|
||
syntax <literal>'$libdir/plXXX'</literal> where
|
||
<literal>XXX</literal> is <literal>pgsql</literal>, <literal>perl</literal>,
|
||
<literal>tcl</literal>, or <literal>python</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
Only shared libraries specifically intended to be used with PostgreSQL
|
||
can be loaded this way. Every PostgreSQL-supported library has
|
||
a <quote>magic block</quote> that is checked to guarantee compatibility. For
|
||
this reason, non-PostgreSQL libraries cannot be loaded in this way. You
|
||
might be able to use operating-system facilities such
|
||
as <envar>LD_PRELOAD</envar> for that.
|
||
</para>
|
||
|
||
<para>
|
||
In general, refer to the documentation of a specific module for the
|
||
recommended way to load that module.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-local-preload-libraries" xreflabel="local_preload_libraries">
|
||
<term><varname>local_preload_libraries</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>local_preload_libraries</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><filename>$libdir/plugins</filename></primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This variable specifies one or more shared libraries that are to be
|
||
preloaded at connection start.
|
||
It contains a comma-separated list of library names, where each name
|
||
is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> command.
|
||
Whitespace between entries is ignored; surround a library name with
|
||
double quotes if you need to include whitespace or commas in the name.
|
||
The parameter value only takes effect at the start of the connection.
|
||
Subsequent changes have no effect. If a specified library is not
|
||
found, the connection attempt will fail.
|
||
</para>
|
||
|
||
<para>
|
||
This option can be set by any user. Because of that, the libraries
|
||
that can be loaded are restricted to those appearing in the
|
||
<filename>plugins</filename> subdirectory of the installation's
|
||
standard library directory. (It is the database administrator's
|
||
responsibility to ensure that only <quote>safe</quote> libraries
|
||
are installed there.) Entries in <varname>local_preload_libraries</varname>
|
||
can specify this directory explicitly, for example
|
||
<literal>$libdir/plugins/mylib</literal>, or just specify
|
||
the library name — <literal>mylib</literal> would have
|
||
the same effect as <literal>$libdir/plugins/mylib</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
The intent of this feature is to allow unprivileged users to load
|
||
debugging or performance-measurement libraries into specific sessions
|
||
without requiring an explicit <command>LOAD</command> command. To that end,
|
||
it would be typical to set this parameter using
|
||
the <envar>PGOPTIONS</envar> environment variable on the client or by
|
||
using
|
||
<command>ALTER ROLE SET</command>.
|
||
</para>
|
||
|
||
<para>
|
||
However, unless a module is specifically designed to be used in this way by
|
||
non-superusers, this is usually not the right setting to use. Look
|
||
at <xref linkend="guc-session-preload-libraries"/> instead.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry id="guc-session-preload-libraries" xreflabel="session_preload_libraries">
|
||
<term><varname>session_preload_libraries</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>session_preload_libraries</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This variable specifies one or more shared libraries that are to be
|
||
preloaded at connection start.
|
||
It contains a comma-separated list of library names, where each name
|
||
is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> command.
|
||
Whitespace between entries is ignored; surround a library name with
|
||
double quotes if you need to include whitespace or commas in the name.
|
||
The parameter value only takes effect at the start of the connection.
|
||
Subsequent changes have no effect. If a specified library is not
|
||
found, the connection attempt will fail.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<para>
|
||
The intent of this feature is to allow debugging or
|
||
performance-measurement libraries to be loaded into specific sessions
|
||
without an explicit
|
||
<command>LOAD</command> command being given. For
|
||
example, <xref linkend="auto-explain"/> could be enabled for all
|
||
sessions under a given user name by setting this parameter
|
||
with <command>ALTER ROLE SET</command>. Also, this parameter can be changed
|
||
without restarting the server (but changes only take effect when a new
|
||
session is started), so it is easier to add new modules this way, even
|
||
if they should apply to all sessions.
|
||
</para>
|
||
|
||
<para>
|
||
Unlike <xref linkend="guc-shared-preload-libraries"/>, there is no large
|
||
performance advantage to loading a library at session start rather than
|
||
when it is first used. There is some advantage, however, when
|
||
connection pooling is used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-shared-preload-libraries" xreflabel="shared_preload_libraries">
|
||
<term><varname>shared_preload_libraries</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>shared_preload_libraries</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This variable specifies one or more shared libraries to be preloaded at
|
||
server start.
|
||
It contains a comma-separated list of library names, where each name
|
||
is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> command.
|
||
Whitespace between entries is ignored; surround a library name with
|
||
double quotes if you need to include whitespace or commas in the name.
|
||
This parameter can only be set at server start. If a specified
|
||
library is not found, the server will fail to start.
|
||
</para>
|
||
|
||
<para>
|
||
Some libraries need to perform certain operations that can only take
|
||
place at postmaster start, such as allocating shared memory, reserving
|
||
light-weight locks, or starting background workers. Those libraries
|
||
must be loaded at server start through this parameter. See the
|
||
documentation of each library for details.
|
||
</para>
|
||
|
||
<para>
|
||
Other libraries can also be preloaded. By preloading a shared library,
|
||
the library startup time is avoided when the library is first used.
|
||
However, the time to start each new server process might increase
|
||
slightly, even if that process never uses the library. So this
|
||
parameter is recommended only for libraries that will be used in most
|
||
sessions. Also, changing this parameter requires a server restart, so
|
||
this is not the right setting to use for short-term debugging tasks,
|
||
say. Use <xref linkend="guc-session-preload-libraries"/> for that
|
||
instead.
|
||
</para>
|
||
|
||
<note>
|
||
<para>
|
||
On Windows hosts, preloading a library at server start will not reduce
|
||
the time required to start each new server process; each server process
|
||
will re-load all preload libraries. However, <varname>shared_preload_libraries
|
||
</varname> is still useful on Windows hosts for libraries that need to
|
||
perform operations at postmaster start time.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit-provider" xreflabel="jit_provider">
|
||
<term><varname>jit_provider</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>jit_provider</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This variable is the name of the JIT provider library to be used
|
||
(see <xref linkend="jit-pluggable"/>).
|
||
The default is <literal>llvmjit</literal>.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
|
||
<para>
|
||
If set to a non-existent library, <acronym>JIT</acronym> will not be
|
||
available, but no error will be raised. This allows JIT support to be
|
||
installed separately from the main
|
||
<productname>PostgreSQL</productname> package.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-client-other">
|
||
<title>Other Defaults</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-dynamic-library-path" xreflabel="dynamic_library_path">
|
||
<term><varname>dynamic_library_path</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>dynamic_library_path</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm><primary>dynamic loading</primary></indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If a dynamically loadable module needs to be opened and the
|
||
file name specified in the <command>CREATE FUNCTION</command> or
|
||
<command>LOAD</command> command
|
||
does not have a directory component (i.e., the
|
||
name does not contain a slash), the system will search this
|
||
path for the required file.
|
||
</para>
|
||
|
||
<para>
|
||
The value for <varname>dynamic_library_path</varname> must be a
|
||
list of absolute directory paths separated by colons (or semi-colons
|
||
on Windows). If a list element starts
|
||
with the special string <literal>$libdir</literal>, the
|
||
compiled-in <productname>PostgreSQL</productname> package
|
||
library directory is substituted for <literal>$libdir</literal>; this
|
||
is where the modules provided by the standard
|
||
<productname>PostgreSQL</productname> distribution are installed.
|
||
(Use <literal>pg_config --pkglibdir</literal> to find out the name of
|
||
this directory.) For example:
|
||
<programlisting>
|
||
dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
|
||
</programlisting>
|
||
or, in a Windows environment:
|
||
<programlisting>
|
||
dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
|
||
</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
The default value for this parameter is
|
||
<literal>'$libdir'</literal>. If the value is set to an empty
|
||
string, the automatic path search is turned off.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can be changed at run time by superusers and users
|
||
with the appropriate <literal>SET</literal> privilege, but a
|
||
setting done that way will only persist until the end of the
|
||
client connection, so this method should be reserved for
|
||
development purposes. The recommended way to set this parameter
|
||
is in the <filename>postgresql.conf</filename> configuration
|
||
file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-gin-fuzzy-search-limit" xreflabel="gin_fuzzy_search_limit">
|
||
<term><varname>gin_fuzzy_search_limit</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>gin_fuzzy_search_limit</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Soft upper limit of the size of the set returned by GIN index scans. For more
|
||
information see <xref linkend="gin-tips"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-locks">
|
||
<title>Lock Management</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-deadlock-timeout" xreflabel="deadlock_timeout">
|
||
<term><varname>deadlock_timeout</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary>deadlock</primary>
|
||
<secondary>timeout during</secondary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary>timeout</primary>
|
||
<secondary>deadlock</secondary>
|
||
</indexterm>
|
||
<indexterm>
|
||
<primary><varname>deadlock_timeout</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This is the amount of time to wait on a lock
|
||
before checking to see if there is a deadlock condition. The
|
||
check for deadlock is relatively expensive, so the server doesn't run
|
||
it every time it waits for a lock. We optimistically assume
|
||
that deadlocks are not common in production applications and
|
||
just wait on the lock for a while before checking for a
|
||
deadlock. Increasing this value reduces the amount of time
|
||
wasted in needless deadlock checks, but slows down reporting of
|
||
real deadlock errors.
|
||
If this value is specified without units, it is taken as milliseconds.
|
||
The default is one second (<literal>1s</literal>),
|
||
which is probably about the smallest value you would want in
|
||
practice. On a heavily loaded server you might want to raise it.
|
||
Ideally the setting should exceed your typical transaction time,
|
||
so as to improve the odds that a lock will be released before
|
||
the waiter decides to check for deadlock.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
|
||
<para>
|
||
When <xref linkend="guc-log-lock-waits"/> is set,
|
||
this parameter also determines the amount of time to wait before
|
||
a log message is issued about the lock wait. If you are trying
|
||
to investigate locking delays you might want to set a shorter than
|
||
normal <varname>deadlock_timeout</varname>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-locks-per-transaction" xreflabel="max_locks_per_transaction">
|
||
<term><varname>max_locks_per_transaction</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_locks_per_transaction</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The shared lock table has space for
|
||
<varname>max_locks_per_transaction</varname> objects
|
||
(e.g., tables) per server process or prepared transaction;
|
||
hence, no more than this many distinct objects can be locked at
|
||
any one time. This parameter limits the average number of object
|
||
locks used by each transaction; individual transactions
|
||
can lock more objects as long as the locks of all transactions
|
||
fit in the lock table. This is <emphasis>not</emphasis> the number of
|
||
rows that can be locked; that value is unlimited. The default,
|
||
64, has historically proven sufficient, but you might need to
|
||
raise this value if you have queries that touch many different
|
||
tables in a single transaction, e.g., query of a parent table with
|
||
many children. This parameter can only be set at server start.
|
||
</para>
|
||
|
||
<para>
|
||
When running a standby server, you must set this parameter to have the
|
||
same or higher value as on the primary server. Otherwise, queries
|
||
will not be allowed in the standby server.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-pred-locks-per-transaction" xreflabel="max_pred_locks_per_transaction">
|
||
<term><varname>max_pred_locks_per_transaction</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_pred_locks_per_transaction</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The shared predicate lock table has space for
|
||
<varname>max_pred_locks_per_transaction</varname> objects
|
||
(e.g., tables) per server process or prepared transaction;
|
||
hence, no more than this many distinct objects can be locked at
|
||
any one time. This parameter limits the average number of object
|
||
locks used by each transaction; individual transactions
|
||
can lock more objects as long as the locks of all transactions
|
||
fit in the lock table. This is <emphasis>not</emphasis> the number of
|
||
rows that can be locked; that value is unlimited. The default,
|
||
64, has historically proven sufficient, but you might need to
|
||
raise this value if you have clients that touch many different
|
||
tables in a single serializable transaction. This parameter can
|
||
only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-pred-locks-per-relation" xreflabel="max_pred_locks_per_relation">
|
||
<term><varname>max_pred_locks_per_relation</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_pred_locks_per_relation</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This controls how many pages or tuples of a single relation can be
|
||
predicate-locked before the lock is promoted to covering the whole
|
||
relation. Values greater than or equal to zero mean an absolute
|
||
limit, while negative values
|
||
mean <xref linkend="guc-max-pred-locks-per-transaction"/> divided by
|
||
the absolute value of this setting. The default is -2, which keeps
|
||
the behavior from previous versions of <productname>PostgreSQL</productname>.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-pred-locks-per-page" xreflabel="max_pred_locks_per_page">
|
||
<term><varname>max_pred_locks_per_page</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_pred_locks_per_page</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This controls how many rows on a single page can be predicate-locked
|
||
before the lock is promoted to covering the whole page. The default
|
||
is 2. This parameter can only be set in
|
||
the <filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-compatible">
|
||
<title>Version and Platform Compatibility</title>
|
||
|
||
<sect2 id="runtime-config-compatible-version">
|
||
<title>Previous PostgreSQL Versions</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-array-nulls" xreflabel="array_nulls">
|
||
<term><varname>array_nulls</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>array_nulls</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This controls whether the array input parser recognizes
|
||
unquoted <literal>NULL</literal> as specifying a null array element.
|
||
By default, this is <literal>on</literal>, allowing array values containing
|
||
null values to be entered. However, <productname>PostgreSQL</productname> versions
|
||
before 8.2 did not support null values in arrays, and therefore would
|
||
treat <literal>NULL</literal> as specifying a normal array element with
|
||
the string value <quote>NULL</quote>. For backward compatibility with
|
||
applications that require the old behavior, this variable can be
|
||
turned <literal>off</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
Note that it is possible to create array values containing null values
|
||
even when this variable is <literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-backslash-quote" xreflabel="backslash_quote">
|
||
<term><varname>backslash_quote</varname> (<type>enum</type>)
|
||
<indexterm><primary>strings</primary><secondary>backslash quotes</secondary></indexterm>
|
||
<indexterm>
|
||
<primary><varname>backslash_quote</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This controls whether a quote mark can be represented by
|
||
<literal>\'</literal> in a string literal. The preferred, SQL-standard way
|
||
to represent a quote mark is by doubling it (<literal>''</literal>) but
|
||
<productname>PostgreSQL</productname> has historically also accepted
|
||
<literal>\'</literal>. However, use of <literal>\'</literal> creates security risks
|
||
because in some client character set encodings, there are multibyte
|
||
characters in which the last byte is numerically equivalent to ASCII
|
||
<literal>\</literal>. If client-side code does escaping incorrectly then an
|
||
SQL-injection attack is possible. This risk can be prevented by
|
||
making the server reject queries in which a quote mark appears to be
|
||
escaped by a backslash.
|
||
The allowed values of <varname>backslash_quote</varname> are
|
||
<literal>on</literal> (allow <literal>\'</literal> always),
|
||
<literal>off</literal> (reject always), and
|
||
<literal>safe_encoding</literal> (allow only if client encoding does not
|
||
allow ASCII <literal>\</literal> within a multibyte character).
|
||
<literal>safe_encoding</literal> is the default setting.
|
||
</para>
|
||
|
||
<para>
|
||
Note that in a standard-conforming string literal, <literal>\</literal> just
|
||
means <literal>\</literal> anyway. This parameter only affects the handling of
|
||
non-standard-conforming literals, including
|
||
escape string syntax (<literal>E'...'</literal>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-escape-string-warning" xreflabel="escape_string_warning">
|
||
<term><varname>escape_string_warning</varname> (<type>boolean</type>)
|
||
<indexterm><primary>strings</primary><secondary>escape warning</secondary></indexterm>
|
||
<indexterm>
|
||
<primary><varname>escape_string_warning</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When on, a warning is issued if a backslash (<literal>\</literal>)
|
||
appears in an ordinary string literal (<literal>'...'</literal>
|
||
syntax) and <varname>standard_conforming_strings</varname> is off.
|
||
The default is <literal>on</literal>.
|
||
</para>
|
||
<para>
|
||
Applications that wish to use backslash as escape should be
|
||
modified to use escape string syntax (<literal>E'...'</literal>),
|
||
because the default behavior of ordinary strings is now to treat
|
||
backslash as an ordinary character, per SQL standard. This variable
|
||
can be enabled to help locate code that needs to be changed.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-lo-compat-privileges" xreflabel="lo_compat_privileges">
|
||
<term><varname>lo_compat_privileges</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>lo_compat_privileges</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
In <productname>PostgreSQL</productname> releases prior to 9.0, large objects
|
||
did not have access privileges and were, therefore, always readable
|
||
and writable by all users. Setting this variable to <literal>on</literal>
|
||
disables the new privilege checks, for compatibility with prior
|
||
releases. The default is <literal>off</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
<para>
|
||
Setting this variable does not disable all security checks related to
|
||
large objects — only those for which the default behavior has
|
||
changed in <productname>PostgreSQL</productname> 9.0.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-quote-all-identifiers" xreflabel="quote-all-identifiers">
|
||
<term><varname>quote_all_identifiers</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>quote_all_identifiers</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When the database generates SQL, force all identifiers to be quoted,
|
||
even if they are not (currently) keywords. This will affect the
|
||
output of <command>EXPLAIN</command> as well as the results of functions
|
||
like <function>pg_get_viewdef</function>. See also the
|
||
<option>--quote-all-identifiers</option> option of
|
||
<xref linkend="app-pgdump"/> and <xref linkend="app-pg-dumpall"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-standard-conforming-strings" xreflabel="standard_conforming_strings">
|
||
<term><varname>standard_conforming_strings</varname> (<type>boolean</type>)
|
||
<indexterm><primary>strings</primary><secondary>standard conforming</secondary></indexterm>
|
||
<indexterm>
|
||
<primary><varname>standard_conforming_strings</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This controls whether ordinary string literals
|
||
(<literal>'...'</literal>) treat backslashes literally, as specified in
|
||
the SQL standard.
|
||
Beginning in <productname>PostgreSQL</productname> 9.1, the default is
|
||
<literal>on</literal> (prior releases defaulted to <literal>off</literal>).
|
||
Applications can check this
|
||
parameter to determine how string literals will be processed.
|
||
The presence of this parameter can also be taken as an indication
|
||
that the escape string syntax (<literal>E'...'</literal>) is supported.
|
||
Escape string syntax (<xref linkend="sql-syntax-strings-escape"/>)
|
||
should be used if an application desires
|
||
backslashes to be treated as escape characters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-synchronize-seqscans" xreflabel="synchronize_seqscans">
|
||
<term><varname>synchronize_seqscans</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>synchronize_seqscans</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This allows sequential scans of large tables to synchronize with each
|
||
other, so that concurrent scans read the same block at about the
|
||
same time and hence share the I/O workload. When this is enabled,
|
||
a scan might start in the middle of the table and then <quote>wrap
|
||
around</quote> the end to cover all rows, so as to synchronize with the
|
||
activity of scans already in progress. This can result in
|
||
unpredictable changes in the row ordering returned by queries that
|
||
have no <literal>ORDER BY</literal> clause. Setting this parameter to
|
||
<literal>off</literal> ensures the pre-8.3 behavior in which a sequential
|
||
scan always starts from the beginning of the table. The default
|
||
is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
|
||
<sect2 id="runtime-config-compatible-clients">
|
||
<title>Platform and Client Compatibility</title>
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-transform-null-equals" xreflabel="transform_null_equals">
|
||
<term><varname>transform_null_equals</varname> (<type>boolean</type>)
|
||
<indexterm><primary>IS NULL</primary></indexterm>
|
||
<indexterm>
|
||
<primary><varname>transform_null_equals</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When on, expressions of the form <literal><replaceable>expr</replaceable> =
|
||
NULL</literal> (or <literal>NULL =
|
||
<replaceable>expr</replaceable></literal>) are treated as
|
||
<literal><replaceable>expr</replaceable> IS NULL</literal>, that is, they
|
||
return true if <replaceable>expr</replaceable> evaluates to the null value,
|
||
and false otherwise. The correct SQL-spec-compliant behavior of
|
||
<literal><replaceable>expr</replaceable> = NULL</literal> is to always
|
||
return null (unknown). Therefore this parameter defaults to
|
||
<literal>off</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
However, filtered forms in <productname>Microsoft
|
||
Access</productname> generate queries that appear to use
|
||
<literal><replaceable>expr</replaceable> = NULL</literal> to test for
|
||
null values, so if you use that interface to access the database you
|
||
might want to turn this option on. Since expressions of the
|
||
form <literal><replaceable>expr</replaceable> = NULL</literal> always
|
||
return the null value (using the SQL standard interpretation), they are not
|
||
very useful and do not appear often in normal applications so
|
||
this option does little harm in practice. But new users are
|
||
frequently confused about the semantics of expressions
|
||
involving null values, so this option is off by default.
|
||
</para>
|
||
|
||
<para>
|
||
Note that this option only affects the exact form <literal>= NULL</literal>,
|
||
not other comparison operators or other expressions
|
||
that are computationally equivalent to some expression
|
||
involving the equals operator (such as <literal>IN</literal>).
|
||
Thus, this option is not a general fix for bad programming.
|
||
</para>
|
||
|
||
<para>
|
||
Refer to <xref linkend="functions-comparison"/> for related information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-allow-alter-system" xreflabel="allow_alter_system">
|
||
<term><varname>allow_alter_system</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>allow_alter_system</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When <literal>allow_alter_system</literal> is set to
|
||
<literal>off</literal>, an error is returned if the <command>ALTER
|
||
SYSTEM</command> command is executed. This parameter can only be set in
|
||
the <filename>postgresql.conf</filename> file or on the server command
|
||
line. The default value is <literal>on</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
Note that this setting must not be regarded as a security feature. It
|
||
only disables the <literal>ALTER SYSTEM</literal> command. It does not
|
||
prevent a superuser from changing the configuration using other SQL
|
||
commands. A superuser has many ways of executing shell commands at
|
||
the operating system level, and can therefore modify
|
||
<literal>postgresql.auto.conf</literal> regardless of the value of
|
||
this setting.
|
||
</para>
|
||
|
||
<para>
|
||
Turning this setting off is intended for environments where the
|
||
configuration of <productname>PostgreSQL</productname> is managed by
|
||
some external tool.
|
||
In such environments, a well intentioned superuser might
|
||
<emphasis>mistakenly</emphasis> use <command>ALTER SYSTEM</command>
|
||
to change the configuration instead of using the external tool.
|
||
This might result in unintended behavior, such as the external tool
|
||
overwriting the change at some later point in time when it updates the
|
||
configuration.
|
||
Setting this parameter to <literal>off</literal> can
|
||
help avoid such mistakes.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter only controls the use of <command>ALTER SYSTEM</command>.
|
||
The settings stored in <filename>postgresql.auto.conf</filename>
|
||
take effect even if <literal>allow_alter_system</literal> is set to
|
||
<literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-error-handling">
|
||
<title>Error Handling</title>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-exit-on-error" xreflabel="exit_on_error">
|
||
<term><varname>exit_on_error</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>exit_on_error</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If on, any error will terminate the current session. By default,
|
||
this is set to off, so that only FATAL errors will terminate the
|
||
session.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-restart-after-crash" xreflabel="restart_after_crash">
|
||
<term><varname>restart_after_crash</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>restart_after_crash</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When set to on, which is the default, <productname>PostgreSQL</productname>
|
||
will automatically reinitialize after a backend crash. Leaving this
|
||
value set to on is normally the best way to maximize the availability
|
||
of the database. However, in some circumstances, such as when
|
||
<productname>PostgreSQL</productname> is being invoked by clusterware, it may be
|
||
useful to disable the restart so that the clusterware can gain
|
||
control and take any actions it deems appropriate.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-data-sync-retry" xreflabel="data_sync_retry">
|
||
<term><varname>data_sync_retry</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>data_sync_retry</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When set to off, which is the default, <productname>PostgreSQL</productname>
|
||
will raise a PANIC-level error on failure to flush modified data files
|
||
to the file system. This causes the database server to crash. This
|
||
parameter can only be set at server start.
|
||
</para>
|
||
<para>
|
||
On some operating systems, the status of data in the kernel's page
|
||
cache is unknown after a write-back failure. In some cases it might
|
||
have been entirely forgotten, making it unsafe to retry; the second
|
||
attempt may be reported as successful, when in fact the data has been
|
||
lost. In these circumstances, the only way to avoid data loss is to
|
||
recover from the WAL after any failure is reported, preferably
|
||
after investigating the root cause of the failure and replacing any
|
||
faulty hardware.
|
||
</para>
|
||
<para>
|
||
If set to on, <productname>PostgreSQL</productname> will instead
|
||
report an error but continue to run so that the data flushing
|
||
operation can be retried in a later checkpoint. Only set it to on
|
||
after investigating the operating system's treatment of buffered data
|
||
in case of write-back failure.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-recovery-init-sync-method" xreflabel="recovery_init_sync_method">
|
||
<term><varname>recovery_init_sync_method</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>recovery_init_sync_method</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When set to <literal>fsync</literal>, which is the default,
|
||
<productname>PostgreSQL</productname> will recursively open and
|
||
synchronize all files in the data directory before crash recovery
|
||
begins. The search for files will follow symbolic links for the WAL
|
||
directory and each configured tablespace (but not any other symbolic
|
||
links). This is intended to make sure that all WAL and data files are
|
||
durably stored on disk before replaying changes. This applies whenever
|
||
starting a database cluster that did not shut down cleanly, including
|
||
copies created with <application>pg_basebackup</application>.
|
||
</para>
|
||
<para>
|
||
On Linux, <literal>syncfs</literal> may be used instead, to ask the
|
||
operating system to synchronize the file systems that contain the
|
||
data directory, the WAL files and each tablespace (but not any other
|
||
file systems that may be reachable through symbolic links). This may
|
||
be a lot faster than the <literal>fsync</literal> setting, because it
|
||
doesn't need to open each file one by one. On the other hand, it may
|
||
be slower if a file system is shared by other applications that
|
||
modify a lot of files, since those files will also be written to disk.
|
||
Furthermore, on versions of Linux before 5.8, I/O errors encountered
|
||
while writing data to disk may not be reported to
|
||
<productname>PostgreSQL</productname>, and relevant error messages may
|
||
appear only in kernel logs.
|
||
</para>
|
||
<para>
|
||
This parameter can only be set in the
|
||
<filename>postgresql.conf</filename> file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-preset">
|
||
<title>Preset Options</title>
|
||
|
||
<para>
|
||
The following <quote>parameters</quote> are read-only.
|
||
As such, they have been excluded from the sample
|
||
<filename>postgresql.conf</filename> file. These options report
|
||
various aspects of <productname>PostgreSQL</productname> behavior
|
||
that might be of interest to certain applications, particularly
|
||
administrative front-ends.
|
||
Most of them are determined when <productname>PostgreSQL</productname>
|
||
is compiled or when it is installed.
|
||
</para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry id="guc-block-size" xreflabel="block_size">
|
||
<term><varname>block_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>block_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the size of a disk block. It is determined by the value
|
||
of <literal>BLCKSZ</literal> when building the server. The default
|
||
value is 8192 bytes. The meaning of some configuration
|
||
variables (such as <xref linkend="guc-shared-buffers"/>) is
|
||
influenced by <varname>block_size</varname>. See <xref
|
||
linkend="runtime-config-resource"/> for information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-data-checksums" xreflabel="data_checksums">
|
||
<term><varname>data_checksums</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>data_checksums</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports whether data checksums are enabled for this cluster.
|
||
See <xref linkend="app-initdb-data-checksums"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-data-directory-mode" xreflabel="data_directory_mode">
|
||
<term><varname>data_directory_mode</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>data_directory_mode</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
On Unix systems this parameter reports the permissions the data
|
||
directory (defined by <xref linkend="guc-data-directory"/>)
|
||
had at server startup.
|
||
(On Microsoft Windows this parameter will always display
|
||
<literal>0700</literal>.) See
|
||
<xref linkend="app-initdb-allow-group-access"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-debug-assertions" xreflabel="debug_assertions">
|
||
<term><varname>debug_assertions</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_assertions</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports whether <productname>PostgreSQL</productname> has been built
|
||
with assertions enabled. That is the case if the
|
||
macro <symbol>USE_ASSERT_CHECKING</symbol> is defined
|
||
when <productname>PostgreSQL</productname> is built (accomplished
|
||
e.g., by the <command>configure</command> option
|
||
<option>--enable-cassert</option>). By
|
||
default <productname>PostgreSQL</productname> is built without
|
||
assertions.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-huge-pages-status" xreflabel="huge_pages_status">
|
||
<term><varname>huge_pages_status</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>huge_pages_status</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the state of huge pages in the current instance:
|
||
<literal>on</literal>, <literal>off</literal>, or
|
||
<literal>unknown</literal> (if displayed with
|
||
<literal>postgres -C</literal>).
|
||
This parameter is useful to determine whether allocation of huge pages
|
||
was successful under <literal>huge_pages=try</literal>.
|
||
See <xref linkend="guc-huge-pages"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-integer-datetimes" xreflabel="integer_datetimes">
|
||
<term><varname>integer_datetimes</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>integer_datetimes</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports whether <productname>PostgreSQL</productname> was built with support for
|
||
64-bit-integer dates and times. As of <productname>PostgreSQL</productname> 10,
|
||
this is always <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-in-hot-standby" xreflabel="in_hot_standby">
|
||
<term><varname>in_hot_standby</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>in_hot_standby</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports whether the server is currently in hot standby mode. When
|
||
this is <literal>on</literal>, all transactions are forced to be
|
||
read-only. Within a session, this can change only if the server is
|
||
promoted to be primary. See <xref linkend="hot-standby"/> for more
|
||
information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-function-args" xreflabel="max_function_args">
|
||
<term><varname>max_function_args</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_function_args</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the maximum number of function arguments. It is determined by
|
||
the value of <literal>FUNC_MAX_ARGS</literal> when building the server. The
|
||
default value is 100 arguments.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-identifier-length" xreflabel="max_identifier_length">
|
||
<term><varname>max_identifier_length</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_identifier_length</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the maximum identifier length. It is determined as one
|
||
less than the value of <literal>NAMEDATALEN</literal> when building
|
||
the server. The default value of <literal>NAMEDATALEN</literal> is
|
||
64; therefore the default
|
||
<varname>max_identifier_length</varname> is 63 bytes, which
|
||
can be less than 63 characters when using multibyte encodings.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-max-index-keys" xreflabel="max_index_keys">
|
||
<term><varname>max_index_keys</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>max_index_keys</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the maximum number of index keys. It is determined by
|
||
the value of <literal>INDEX_MAX_KEYS</literal> when building the server. The
|
||
default value is 32 keys.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-segment-size" xreflabel="segment_size">
|
||
<term><varname>segment_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>segment_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the number of blocks (pages) that can be stored within a file
|
||
segment. It is determined by the value of <literal>RELSEG_SIZE</literal>
|
||
when building the server. The maximum size of a segment file in bytes
|
||
is equal to <varname>segment_size</varname> multiplied by
|
||
<varname>block_size</varname>; by default this is 1GB.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-server-encoding" xreflabel="server_encoding">
|
||
<term><varname>server_encoding</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>server_encoding</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
<indexterm><primary>character set</primary></indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the database encoding (character set).
|
||
It is determined when the database is created. Ordinarily,
|
||
clients need only be concerned with the value of <xref
|
||
linkend="guc-client-encoding"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-server-version" xreflabel="server_version">
|
||
<term><varname>server_version</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>server_version</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the version number of the server. It is determined by the
|
||
value of <literal>PG_VERSION</literal> when building the server.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-server-version-num" xreflabel="server_version_num">
|
||
<term><varname>server_version_num</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>server_version_num</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the version number of the server as an integer. It is determined
|
||
by the value of <literal>PG_VERSION_NUM</literal> when building the server.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-shared-memory-size" xreflabel="shared_memory_size">
|
||
<term><varname>shared_memory_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>shared_memory_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the size of the main shared memory area, rounded up to the
|
||
nearest megabyte.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-shared-memory-size-in-huge-pages" xreflabel="shared_memory_size_in_huge_pages">
|
||
<term><varname>shared_memory_size_in_huge_pages</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>shared_memory_size_in_huge_pages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the number of huge pages that are needed for the main shared
|
||
memory area based on the specified <xref linkend="guc-huge-page-size"/>.
|
||
If huge pages are not supported, this will be <literal>-1</literal>.
|
||
</para>
|
||
<para>
|
||
This setting is supported only on <productname>Linux</productname>. It
|
||
is always set to <literal>-1</literal> on other platforms. For more
|
||
details about using huge pages on <productname>Linux</productname>, see
|
||
<xref linkend="linux-huge-pages"/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ssl-library" xreflabel="ssl_library">
|
||
<term><varname>ssl_library</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>ssl_library</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the name of the SSL library that this
|
||
<productname>PostgreSQL</productname> server was built with (even if
|
||
SSL is not currently configured or in use on this instance), for
|
||
example <literal>OpenSSL</literal>, or an empty string if none.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-block-size" xreflabel="wal_block_size">
|
||
<term><varname>wal_block_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_block_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the size of a WAL disk block. It is determined by the value
|
||
of <literal>XLOG_BLCKSZ</literal> when building the server. The default value
|
||
is 8192 bytes.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-segment-size" xreflabel="wal_segment_size">
|
||
<term><varname>wal_segment_size</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_segment_size</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Reports the size of write ahead log segments. The default value is
|
||
16MB. See <xref linkend="wal-configuration"/> for more information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-custom">
|
||
<title>Customized Options</title>
|
||
|
||
<para>
|
||
This feature was designed to allow parameters not normally known to
|
||
<productname>PostgreSQL</productname> to be added by add-on modules
|
||
(such as procedural languages). This allows extension modules to be
|
||
configured in the standard ways.
|
||
</para>
|
||
|
||
<para>
|
||
Custom options have two-part names: an extension name, then a dot, then
|
||
the parameter name proper, much like qualified names in SQL. An example
|
||
is <literal>plpgsql.variable_conflict</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
Because custom options may need to be set in processes that have not
|
||
loaded the relevant extension module, <productname>PostgreSQL</productname>
|
||
will accept a setting for any two-part parameter name. Such variables
|
||
are treated as placeholders and have no function until the module that
|
||
defines them is loaded. When an extension module is loaded, it will add
|
||
its variable definitions and convert any placeholder values according to
|
||
those definitions. If there are any unrecognized placeholders
|
||
that begin with its extension name, warnings are issued and those
|
||
placeholders are removed.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="runtime-config-developer">
|
||
<title>Developer Options</title>
|
||
|
||
<para>
|
||
The following parameters are intended for developer testing, and
|
||
should never be used on a production database. However, some of
|
||
them can be used to assist with the recovery of severely damaged
|
||
databases. As such, they have been excluded from the sample
|
||
<filename>postgresql.conf</filename> file. Note that many of these
|
||
parameters require special source compilation flags to work at all.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry id="guc-allow-in-place-tablespaces" xreflabel="allow_in_place_tablespaces">
|
||
<term><varname>allow_in_place_tablespaces</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>allow_in_place_tablespaces</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Allows tablespaces to be created as directories inside
|
||
<filename>pg_tblspc</filename>, when an empty location string
|
||
is provided to the <command>CREATE TABLESPACE</command> command. This
|
||
is intended to allow testing replication scenarios where primary and
|
||
standby servers are running on the same machine. Such directories
|
||
are likely to confuse backup tools that expect to find only symbolic
|
||
links in that location.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-allow-system-table-mods" xreflabel="allow_system_table_mods">
|
||
<term><varname>allow_system_table_mods</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>allow_system_table_mods</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Allows modification of the structure of system tables as well as
|
||
certain other risky actions on system tables. This is otherwise not
|
||
allowed even for superusers. Ill-advised use of this setting can
|
||
cause irretrievable data loss or seriously corrupt the database
|
||
system.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-backtrace-functions" xreflabel="backtrace_functions">
|
||
<term><varname>backtrace_functions</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>backtrace_functions</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter contains a comma-separated list of C function names.
|
||
If an error is raised and the name of the internal C function where
|
||
the error happens matches a value in the list, then a backtrace is
|
||
written to the server log together with the error message. This can
|
||
be used to debug specific areas of the source code.
|
||
</para>
|
||
|
||
<para>
|
||
Backtrace support is not available on all platforms, and the quality
|
||
of the backtraces depends on compilation options.
|
||
</para>
|
||
|
||
<para>
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-debug-discard-caches" xreflabel="debug_discard_caches">
|
||
<term><varname>debug_discard_caches</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_discard_caches</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When set to <literal>1</literal>, each system catalog cache entry is
|
||
invalidated at the first possible opportunity, whether or not
|
||
anything that would render it invalid really occurred. Caching of
|
||
system catalogs is effectively disabled as a result, so the server
|
||
will run extremely slowly. Higher values run the cache invalidation
|
||
recursively, which is even slower and only useful for testing
|
||
the caching logic itself. The default value of <literal>0</literal>
|
||
selects normal catalog caching behavior.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter can be very helpful when trying to trigger
|
||
hard-to-reproduce bugs involving concurrent catalog changes, but it
|
||
is otherwise rarely needed. See the source code files
|
||
<filename>inval.c</filename> and
|
||
<filename>pg_config_manual.h</filename> for details.
|
||
</para>
|
||
|
||
<para>
|
||
This parameter is supported when
|
||
<symbol>DISCARD_CACHES_ENABLED</symbol> was defined at compile time
|
||
(which happens automatically when using the
|
||
<application>configure</application> option
|
||
<option>--enable-cassert</option>). In production builds, its value
|
||
will always be <literal>0</literal> and attempts to set it to another
|
||
value will raise an error.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-debug-io-direct" xreflabel="debug_io_direct">
|
||
<term><varname>debug_io_direct</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_io_direct</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Ask the kernel to minimize caching effects for relation data and WAL
|
||
files using <literal>O_DIRECT</literal> (most Unix-like systems),
|
||
<literal>F_NOCACHE</literal> (macOS) or
|
||
<literal>FILE_FLAG_NO_BUFFERING</literal> (Windows).
|
||
</para>
|
||
<para>
|
||
May be set to an empty string (the default) to disable use of direct
|
||
I/O, or a comma-separated list of operations that should use direct I/O.
|
||
The valid options are <literal>data</literal> for
|
||
main data files, <literal>wal</literal> for WAL files, and
|
||
<literal>wal_init</literal> for WAL files when being initially
|
||
allocated.
|
||
</para>
|
||
<para>
|
||
Some operating systems and file systems do not support direct I/O, so
|
||
non-default settings may be rejected at startup or cause errors.
|
||
</para>
|
||
<para>
|
||
Currently this feature reduces performance, and is intended for
|
||
developer testing only.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-debug-parallel-query" xreflabel="debug_parallel_query">
|
||
<term><varname>debug_parallel_query</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_parallel_query</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Allows the use of parallel queries for testing purposes even in cases
|
||
where no performance benefit is expected.
|
||
The allowed values of <varname>debug_parallel_query</varname> are
|
||
<literal>off</literal> (use parallel mode only when it is expected to improve
|
||
performance), <literal>on</literal> (force parallel query for all queries
|
||
for which it is thought to be safe), and <literal>regress</literal> (like
|
||
<literal>on</literal>, but with additional behavior changes as explained
|
||
below).
|
||
</para>
|
||
|
||
<para>
|
||
More specifically, setting this value to <literal>on</literal> will add
|
||
a <literal>Gather</literal> node to the top of any query plan for which this
|
||
appears to be safe, so that the query runs inside of a parallel worker.
|
||
Even when a parallel worker is not available or cannot be used,
|
||
operations such as starting a subtransaction that would be prohibited
|
||
in a parallel query context will be prohibited unless the planner
|
||
believes that this will cause the query to fail. If failures or
|
||
unexpected results occur when this option is set, some functions used
|
||
by the query may need to be marked <literal>PARALLEL UNSAFE</literal>
|
||
(or, possibly, <literal>PARALLEL RESTRICTED</literal>).
|
||
</para>
|
||
|
||
<para>
|
||
Setting this value to <literal>regress</literal> has all of the same effects
|
||
as setting it to <literal>on</literal> plus some additional effects that are
|
||
intended to facilitate automated regression testing. Normally,
|
||
messages from a parallel worker include a context line indicating that,
|
||
but a setting of <literal>regress</literal> suppresses this line so that the
|
||
output is the same as in non-parallel execution. Also,
|
||
the <literal>Gather</literal> nodes added to plans by this setting are hidden
|
||
in <literal>EXPLAIN</literal> output so that the output matches what
|
||
would be obtained if this setting were turned <literal>off</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ignore-system-indexes" xreflabel="ignore_system_indexes">
|
||
<term><varname>ignore_system_indexes</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>ignore_system_indexes</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Ignore system indexes when reading system tables (but still
|
||
update the indexes when modifying the tables). This is useful
|
||
when recovering from damaged system indexes.
|
||
This parameter cannot be changed after session start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-post-auth-delay" xreflabel="post_auth_delay">
|
||
<term><varname>post_auth_delay</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>post_auth_delay</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The amount of time to delay when a new
|
||
server process is started, after it conducts the
|
||
authentication procedure. This is intended to give developers an
|
||
opportunity to attach to the server process with a debugger.
|
||
If this value is specified without units, it is taken as seconds.
|
||
A value of zero (the default) disables the delay.
|
||
This parameter cannot be changed after session start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-pre-auth-delay" xreflabel="pre_auth_delay">
|
||
<term><varname>pre_auth_delay</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>pre_auth_delay</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The amount of time to delay just after a
|
||
new server process is forked, before it conducts the
|
||
authentication procedure. This is intended to give developers an
|
||
opportunity to attach to the server process with a debugger to
|
||
trace down misbehavior in authentication.
|
||
If this value is specified without units, it is taken as seconds.
|
||
A value of zero (the default) disables the delay.
|
||
This parameter can only be set in the <filename>postgresql.conf</filename>
|
||
file or on the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-trace-notify" xreflabel="trace_notify">
|
||
<term><varname>trace_notify</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>trace_notify</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Generates a great amount of debugging output for the
|
||
<command>LISTEN</command> and <command>NOTIFY</command>
|
||
commands. <xref linkend="guc-client-min-messages"/> or
|
||
<xref linkend="guc-log-min-messages"/> must be
|
||
<literal>DEBUG1</literal> or lower to send this output to the
|
||
client or server logs, respectively.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-trace-sort" xreflabel="trace_sort">
|
||
<term><varname>trace_sort</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>trace_sort</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If on, emit information about resource usage during sort operations.
|
||
This parameter is only available if the <symbol>TRACE_SORT</symbol> macro
|
||
was defined when <productname>PostgreSQL</productname> was compiled.
|
||
(However, <symbol>TRACE_SORT</symbol> is currently defined by default.)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-trace-locks" xreflabel="trace_locks">
|
||
<term><varname>trace_locks</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>trace_locks</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If on, emit information about lock usage. Information dumped
|
||
includes the type of lock operation, the type of lock and the unique
|
||
identifier of the object being locked or unlocked. Also included
|
||
are bit masks for the lock types already granted on this object as
|
||
well as for the lock types awaited on this object. For each lock
|
||
type a count of the number of granted locks and waiting locks is
|
||
also dumped as well as the totals. An example of the log file output
|
||
is shown here:
|
||
<screen>
|
||
LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1)
|
||
grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0
|
||
wait(0) type(AccessShareLock)
|
||
LOG: GrantLock: lock(0xb7acd844) id(24688,24696,0,0,0,1)
|
||
grantMask(2) req(1,0,0,0,0,0,0)=1 grant(1,0,0,0,0,0,0)=1
|
||
wait(0) type(AccessShareLock)
|
||
LOG: UnGrantLock: updated: lock(0xb7acd844) id(24688,24696,0,0,0,1)
|
||
grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0
|
||
wait(0) type(AccessShareLock)
|
||
LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
|
||
grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0
|
||
wait(0) type(INVALID)
|
||
</screen>
|
||
Details of the structure being dumped may be found in
|
||
<filename>src/include/storage/lock.h</filename>.
|
||
</para>
|
||
<para>
|
||
This parameter is only available if the <symbol>LOCK_DEBUG</symbol>
|
||
macro was defined when <productname>PostgreSQL</productname> was
|
||
compiled.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-trace-lwlocks" xreflabel="trace_lwlocks">
|
||
<term><varname>trace_lwlocks</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>trace_lwlocks</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If on, emit information about lightweight lock usage. Lightweight
|
||
locks are intended primarily to provide mutual exclusion of access
|
||
to shared-memory data structures.
|
||
</para>
|
||
<para>
|
||
This parameter is only available if the <symbol>LOCK_DEBUG</symbol>
|
||
macro was defined when <productname>PostgreSQL</productname> was
|
||
compiled.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-trace-userlocks" xreflabel="trace_userlocks">
|
||
<term><varname>trace_userlocks</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>trace_userlocks</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If on, emit information about user lock usage. Output is the same
|
||
as for <symbol>trace_locks</symbol>, only for advisory locks.
|
||
</para>
|
||
<para>
|
||
This parameter is only available if the <symbol>LOCK_DEBUG</symbol>
|
||
macro was defined when <productname>PostgreSQL</productname> was
|
||
compiled.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-trace-lock-oidmin" xreflabel="trace_lock_oidmin">
|
||
<term><varname>trace_lock_oidmin</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>trace_lock_oidmin</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set, do not trace locks for tables below this OID (used to avoid
|
||
output on system tables).
|
||
</para>
|
||
<para>
|
||
This parameter is only available if the <symbol>LOCK_DEBUG</symbol>
|
||
macro was defined when <productname>PostgreSQL</productname> was
|
||
compiled.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-trace-lock-table" xreflabel="trace_lock_table">
|
||
<term><varname>trace_lock_table</varname> (<type>integer</type>)
|
||
<indexterm>
|
||
<primary><varname>trace_lock_table</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Unconditionally trace locks on this table (OID).
|
||
</para>
|
||
<para>
|
||
This parameter is only available if the <symbol>LOCK_DEBUG</symbol>
|
||
macro was defined when <productname>PostgreSQL</productname> was
|
||
compiled.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-debug-deadlocks" xreflabel="debug_deadlocks">
|
||
<term><varname>debug_deadlocks</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_deadlocks</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set, dumps information about all current locks when a
|
||
deadlock timeout occurs.
|
||
</para>
|
||
<para>
|
||
This parameter is only available if the <symbol>LOCK_DEBUG</symbol>
|
||
macro was defined when <productname>PostgreSQL</productname> was
|
||
compiled.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-log-btree-build-stats" xreflabel="log_btree_build_stats">
|
||
<term><varname>log_btree_build_stats</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>log_btree_build_stats</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set, logs system resource usage statistics (memory and CPU) on
|
||
various B-tree operations.
|
||
</para>
|
||
<para>
|
||
This parameter is only available if the <symbol>BTREE_BUILD_STATS</symbol>
|
||
macro was defined when <productname>PostgreSQL</productname> was
|
||
compiled.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-consistency-checking" xreflabel="wal_consistency_checking">
|
||
<term><varname>wal_consistency_checking</varname> (<type>string</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_consistency_checking</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This parameter is intended to be used to check for bugs in the WAL
|
||
redo routines. When enabled, full-page images of any buffers modified
|
||
in conjunction with the WAL record are added to the record.
|
||
If the record is subsequently replayed, the system will first apply
|
||
each record and then test whether the buffers modified by the record
|
||
match the stored images. In certain cases (such as hint bits), minor
|
||
variations are acceptable, and will be ignored. Any unexpected
|
||
differences will result in a fatal error, terminating recovery.
|
||
</para>
|
||
|
||
<para>
|
||
The default value of this setting is the empty string, which disables
|
||
the feature. It can be set to <literal>all</literal> to check all
|
||
records, or to a comma-separated list of resource managers to check
|
||
only records originating from those resource managers. Currently,
|
||
the supported resource managers are <literal>heap</literal>,
|
||
<literal>heap2</literal>, <literal>btree</literal>, <literal>hash</literal>,
|
||
<literal>gin</literal>, <literal>gist</literal>, <literal>sequence</literal>,
|
||
<literal>spgist</literal>, <literal>brin</literal>, and <literal>generic</literal>.
|
||
Extensions may define additional resource managers. Only superusers and users with
|
||
the appropriate <literal>SET</literal> privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-wal-debug" xreflabel="wal_debug">
|
||
<term><varname>wal_debug</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>wal_debug</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If on, emit WAL-related debugging output. This parameter is
|
||
only available if the <symbol>WAL_DEBUG</symbol> macro was
|
||
defined when <productname>PostgreSQL</productname> was
|
||
compiled.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ignore-checksum-failure" xreflabel="ignore_checksum_failure">
|
||
<term><varname>ignore_checksum_failure</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>ignore_checksum_failure</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Only has effect if <xref linkend="app-initdb-data-checksums"/> are enabled.
|
||
</para>
|
||
<para>
|
||
Detection of a checksum failure during a read normally causes
|
||
<productname>PostgreSQL</productname> to report an error, aborting the current
|
||
transaction. Setting <varname>ignore_checksum_failure</varname> to on causes
|
||
the system to ignore the failure (but still report a warning), and
|
||
continue processing. This behavior may <emphasis>cause crashes, propagate
|
||
or hide corruption, or other serious problems</emphasis>. However, it may allow
|
||
you to get past the error and retrieve undamaged tuples that might still be
|
||
present in the table if the block header is still sane. If the header is
|
||
corrupt an error will be reported even if this option is enabled. The
|
||
default setting is <literal>off</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-zero-damaged-pages" xreflabel="zero_damaged_pages">
|
||
<term><varname>zero_damaged_pages</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>zero_damaged_pages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Detection of a damaged page header normally causes
|
||
<productname>PostgreSQL</productname> to report an error, aborting the current
|
||
transaction. Setting <varname>zero_damaged_pages</varname> to on causes
|
||
the system to instead report a warning, zero out the damaged
|
||
page in memory, and continue processing. This behavior <emphasis>will destroy data</emphasis>,
|
||
namely all the rows on the damaged page. However, it does allow you to get
|
||
past the error and retrieve rows from any undamaged pages that might
|
||
be present in the table. It is useful for recovering data if
|
||
corruption has occurred due to a hardware or software error. You should
|
||
generally not set this on until you have given up hope of recovering
|
||
data from the damaged pages of a table. Zeroed-out pages are not
|
||
forced to disk so it is recommended to recreate the table or
|
||
the index before turning this parameter off again. The
|
||
default setting is <literal>off</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-ignore-invalid-pages" xreflabel="ignore_invalid_pages">
|
||
<term><varname>ignore_invalid_pages</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>ignore_invalid_pages</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set to <literal>off</literal> (the default), detection of
|
||
WAL records having references to invalid pages during
|
||
recovery causes <productname>PostgreSQL</productname> to
|
||
raise a PANIC-level error, aborting the recovery. Setting
|
||
<varname>ignore_invalid_pages</varname> to <literal>on</literal>
|
||
causes the system to ignore invalid page references in WAL records
|
||
(but still report a warning), and continue the recovery.
|
||
This behavior may <emphasis>cause crashes, data loss,
|
||
propagate or hide corruption, or other serious problems</emphasis>.
|
||
However, it may allow you to get past the PANIC-level error,
|
||
to finish the recovery, and to cause the server to start up.
|
||
The parameter can only be set at server start. It only has effect
|
||
during recovery or in standby mode.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit-debugging-support" xreflabel="jit_debugging_support">
|
||
<term><varname>jit_debugging_support</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>jit_debugging_support</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If LLVM has the required functionality, register generated functions
|
||
with <productname>GDB</productname>. This makes debugging easier.
|
||
The default setting is <literal>off</literal>.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit-dump-bitcode" xreflabel="jit_dump_bitcode">
|
||
<term><varname>jit_dump_bitcode</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>jit_dump_bitcode</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Writes the generated <productname>LLVM</productname> IR out to the
|
||
file system, inside <xref linkend="guc-data-directory"/>. This is only
|
||
useful for working on the internals of the JIT implementation.
|
||
The default setting is <literal>off</literal>.
|
||
Only superusers and users with the appropriate <literal>SET</literal>
|
||
privilege can change this setting.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit-expressions" xreflabel="jit_expressions">
|
||
<term><varname>jit_expressions</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>jit_expressions</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Determines whether expressions are JIT compiled, when JIT compilation
|
||
is activated (see <xref linkend="jit-decision"/>). The default is
|
||
<literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit-profiling-support" xreflabel="jit_profiling_support">
|
||
<term><varname>jit_profiling_support</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>jit_profiling_support</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If LLVM has the required functionality, emit the data needed to allow
|
||
<productname>perf</productname> to profile functions generated by JIT.
|
||
This writes out files to <filename>~/.debug/jit/</filename>; the
|
||
user is responsible for performing cleanup when desired.
|
||
The default setting is <literal>off</literal>.
|
||
This parameter can only be set at server start.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-jit-tuple-deforming" xreflabel="jit_tuple_deforming">
|
||
<term><varname>jit_tuple_deforming</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>jit_tuple_deforming</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Determines whether tuple deforming is JIT compiled, when JIT
|
||
compilation is activated (see <xref linkend="jit-decision"/>).
|
||
The default is <literal>on</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-remove-temp-files-after-crash" xreflabel="remove_temp_files_after_crash">
|
||
<term><varname>remove_temp_files_after_crash</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>remove_temp_files_after_crash</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
When set to <literal>on</literal>, which is the default,
|
||
<productname>PostgreSQL</productname> will automatically remove
|
||
temporary files after a backend crash. If disabled, the files will be
|
||
retained and may be used for debugging, for example. Repeated crashes
|
||
may however result in accumulation of useless files. This parameter
|
||
can only be set in the <filename>postgresql.conf</filename> file or on
|
||
the server command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-send-abort-for-crash" xreflabel="send_abort_for_crash">
|
||
<term><varname>send_abort_for_crash</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>send_abort_for_crash</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
By default, after a backend crash the postmaster will stop remaining
|
||
child processes by sending them <systemitem>SIGQUIT</systemitem>
|
||
signals, which permits them to exit more-or-less gracefully. When
|
||
this option is set to <literal>on</literal>,
|
||
<systemitem>SIGABRT</systemitem> is sent instead. That normally
|
||
results in production of a core dump file for each such child
|
||
process.
|
||
This can be handy for investigating the states of other processes
|
||
after a crash. It can also consume lots of disk space in the event
|
||
of repeated crashes, so do not enable this on systems you are not
|
||
monitoring carefully.
|
||
Beware that no support exists for cleaning up the core file(s)
|
||
automatically.
|
||
This parameter can only be set in
|
||
the <filename>postgresql.conf</filename> file or on the server
|
||
command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-send-abort-for-kill" xreflabel="send_abort_for_kill">
|
||
<term><varname>send_abort_for_kill</varname> (<type>boolean</type>)
|
||
<indexterm>
|
||
<primary><varname>send_abort_for_kill</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
By default, after attempting to stop a child process with
|
||
<systemitem>SIGQUIT</systemitem>, the postmaster will wait five
|
||
seconds and then send <systemitem>SIGKILL</systemitem> to force
|
||
immediate termination. When this option is set
|
||
to <literal>on</literal>, <systemitem>SIGABRT</systemitem> is sent
|
||
instead of <systemitem>SIGKILL</systemitem>. That normally results
|
||
in production of a core dump file for each such child process.
|
||
This can be handy for investigating the states
|
||
of <quote>stuck</quote> child processes. It can also consume lots
|
||
of disk space in the event of repeated crashes, so do not enable
|
||
this on systems you are not monitoring carefully.
|
||
Beware that no support exists for cleaning up the core file(s)
|
||
automatically.
|
||
This parameter can only be set in
|
||
the <filename>postgresql.conf</filename> file or on the server
|
||
command line.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry id="guc-debug-logical-replication-streaming" xreflabel="debug_logical_replication_streaming">
|
||
<term><varname>debug_logical_replication_streaming</varname> (<type>enum</type>)
|
||
<indexterm>
|
||
<primary><varname>debug_logical_replication_streaming</varname> configuration parameter</primary>
|
||
</indexterm>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The allowed values are <literal>buffered</literal> and
|
||
<literal>immediate</literal>. The default is <literal>buffered</literal>.
|
||
This parameter is intended to be used to test logical decoding and
|
||
replication of large transactions. The effect of
|
||
<varname>debug_logical_replication_streaming</varname> is different for the
|
||
publisher and subscriber:
|
||
</para>
|
||
|
||
<para>
|
||
On the publisher side, <varname>debug_logical_replication_streaming</varname>
|
||
allows streaming or serializing changes immediately in logical decoding.
|
||
When set to <literal>immediate</literal>, stream each change if the
|
||
<link linkend="sql-createsubscription-params-with-streaming"><literal>streaming</literal></link>
|
||
option of
|
||
<link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>
|
||
is enabled, otherwise, serialize each change. When set to
|
||
<literal>buffered</literal>, the decoding will stream or serialize
|
||
changes when <varname>logical_decoding_work_mem</varname> is reached.
|
||
</para>
|
||
|
||
<para>
|
||
On the subscriber side, if the <literal>streaming</literal> option is set to
|
||
<literal>parallel</literal>, <varname>debug_logical_replication_streaming</varname>
|
||
can be used to direct the leader apply worker to send changes to the
|
||
shared memory queue or to serialize all changes to the file. When set to
|
||
<literal>buffered</literal>, the leader sends changes to parallel apply
|
||
workers via a shared memory queue. When set to
|
||
<literal>immediate</literal>, the leader serializes all changes to files
|
||
and notifies the parallel apply workers to read and apply them at the
|
||
end of the transaction.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</sect1>
|
||
<sect1 id="runtime-config-short">
|
||
<title>Short Options</title>
|
||
|
||
<para>
|
||
For convenience there are also single letter command-line option
|
||
switches available for some parameters. They are described in
|
||
<xref linkend="runtime-config-short-table"/>. Some of these
|
||
options exist for historical reasons, and their presence as a
|
||
single-letter option does not necessarily indicate an endorsement
|
||
to use the option heavily.
|
||
</para>
|
||
|
||
<table id="runtime-config-short-table">
|
||
<title>Short Option Key</title>
|
||
<tgroup cols="2">
|
||
<colspec colname="col1" colwidth="1*"/>
|
||
<colspec colname="col2" colwidth="2*"/>
|
||
<thead>
|
||
<row>
|
||
<entry>Short Option</entry>
|
||
<entry>Equivalent</entry>
|
||
</row>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<row>
|
||
<entry><option>-B <replaceable>x</replaceable></option></entry>
|
||
<entry><literal>shared_buffers = <replaceable>x</replaceable></literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-d <replaceable>x</replaceable></option></entry>
|
||
<entry><literal>log_min_messages = DEBUG<replaceable>x</replaceable></literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-e</option></entry>
|
||
<entry><literal>datestyle = euro</literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry>
|
||
<option>-fb</option>, <option>-fh</option>, <option>-fi</option>,
|
||
<option>-fm</option>, <option>-fn</option>, <option>-fo</option>,
|
||
<option>-fs</option>, <option>-ft</option>
|
||
</entry>
|
||
<entry>
|
||
<literal>enable_bitmapscan = off</literal>,
|
||
<literal>enable_hashjoin = off</literal>,
|
||
<literal>enable_indexscan = off</literal>,
|
||
<literal>enable_mergejoin = off</literal>,
|
||
<literal>enable_nestloop = off</literal>,
|
||
<literal>enable_indexonlyscan = off</literal>,
|
||
<literal>enable_seqscan = off</literal>,
|
||
<literal>enable_tidscan = off</literal>
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-F</option></entry>
|
||
<entry><literal>fsync = off</literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-h <replaceable>x</replaceable></option></entry>
|
||
<entry><literal>listen_addresses = <replaceable>x</replaceable></literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-i</option></entry>
|
||
<entry><literal>listen_addresses = '*'</literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-k <replaceable>x</replaceable></option></entry>
|
||
<entry><literal>unix_socket_directories = <replaceable>x</replaceable></literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-l</option></entry>
|
||
<entry><literal>ssl = on</literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-N <replaceable>x</replaceable></option></entry>
|
||
<entry><literal>max_connections = <replaceable>x</replaceable></literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-O</option></entry>
|
||
<entry><literal>allow_system_table_mods = on</literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-p <replaceable>x</replaceable></option></entry>
|
||
<entry><literal>port = <replaceable>x</replaceable></literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-P</option></entry>
|
||
<entry><literal>ignore_system_indexes = on</literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-s</option></entry>
|
||
<entry><literal>log_statement_stats = on</literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-S <replaceable>x</replaceable></option></entry>
|
||
<entry><literal>work_mem = <replaceable>x</replaceable></literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-tpa</option>, <option>-tpl</option>, <option>-te</option></entry>
|
||
<entry><literal>log_parser_stats = on</literal>,
|
||
<literal>log_planner_stats = on</literal>,
|
||
<literal>log_executor_stats = on</literal></entry>
|
||
</row>
|
||
<row>
|
||
<entry><option>-W <replaceable>x</replaceable></option></entry>
|
||
<entry><literal>post_auth_delay = <replaceable>x</replaceable></literal></entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
</sect1>
|
||
</chapter>
|