11394 lines
489 KiB
Plaintext
11394 lines
489 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, 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-command-interaction">
|
|
<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.
|
|
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>
|
|
<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</option> command-line parameter. For example,
|
|
<programlisting>
|
|
postgres -c log_connections=yes -c 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> flag must be specified.
|
|
For example,
|
|
<programlisting>
|
|
env PGOPTIONS="-c geqo=off -c 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.
|
|
The default value is <systemitem class="systemname">localhost</systemitem>,
|
|
which allows only local TCP/IP <quote>loopback</quote> connections to be
|
|
made. 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>
|
|
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-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, and no
|
|
new replication connections will be accepted.
|
|
</para>
|
|
|
|
<para>
|
|
The default value is three connections. The value must be less
|
|
than <varname>max_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 and Windows). 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>
|
|
|
|
<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.
|
|
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>
|
|
<note>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
</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.
|
|
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>
|
|
<note>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
</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;
|
|
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>
|
|
<note>
|
|
<para>
|
|
This parameter is not supported on Windows, and must be zero.
|
|
</para>
|
|
</note>
|
|
</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>; 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>
|
|
<note>
|
|
<para>
|
|
This parameter is not supported on Windows, and must be zero.
|
|
</para>
|
|
</note>
|
|
</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 is currently available only on systems that support the
|
|
non-standard <symbol>POLLRDHUP</symbol> extension to the
|
|
<symbol>poll</symbol> system call, including Linux.
|
|
</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-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-db-user-namespace" xreflabel="db_user_namespace">
|
|
<term><varname>db_user_namespace</varname> (<type>boolean</type>)
|
|
<indexterm>
|
|
<primary><varname>db_user_namespace</varname> configuration parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This parameter enables per-database user names. It is off by default.
|
|
This parameter can only be set in the <filename>postgresql.conf</filename>
|
|
file or on the server command line.
|
|
</para>
|
|
|
|
<para>
|
|
If this is on, you should create users as <replaceable>username@dbname</replaceable>.
|
|
When <replaceable>username</replaceable> is passed by a connecting client,
|
|
<literal>@</literal> and the database name are appended to the user
|
|
name and that database-specific user name is looked up by the
|
|
server. Note that when you create users with names containing
|
|
<literal>@</literal> within the SQL environment, you will need to
|
|
quote the user name.
|
|
</para>
|
|
|
|
<para>
|
|
With this parameter enabled, you can still create ordinary global
|
|
users. Simply append <literal>@</literal> when specifying the user
|
|
name in the client, e.g., <literal>joe@</literal>. The <literal>@</literal>
|
|
will be stripped off before the user name is looked up by the
|
|
server.
|
|
</para>
|
|
|
|
<para>
|
|
<varname>db_user_namespace</varname> causes the client's and
|
|
server's user name representation to differ.
|
|
Authentication checks are always done with the server's user name
|
|
so authentication methods must be configured for the
|
|
server's user name, not the client's. Because
|
|
<literal>md5</literal> uses the user name as salt on both the
|
|
client and server, <literal>md5</literal> cannot be used with
|
|
<varname>db_user_namespace</varname>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
This feature is intended as a temporary measure until a
|
|
complete solution is found. At that time, this option will
|
|
be removed.
|
|
</para>
|
|
</note>
|
|
</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 SSL.
|
|
</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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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.
|
|
</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 for a complex query, several sort or hash operations might be
|
|
running in parallel; each operation will generally be 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, result
|
|
cache 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 available for hash tables 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
|
|
1.0, which makes hash-based operations subject to the same
|
|
simple <varname>work_mem</varname> maximum as sort-based
|
|
operations.
|
|
</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). A setting of 1.5 or 2.0 may be 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>
|
|
<para>
|
|
Note that for the collection of dead tuple identifiers,
|
|
<command>VACUUM</command> is only able to utilize up to a maximum of
|
|
<literal>1GB</literal> of memory.
|
|
</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>
|
|
<para>
|
|
For the collection of dead tuple identifiers, autovacuum is only able
|
|
to utilize up to a maximum of <literal>1GB</literal> of memory, so
|
|
setting <varname>autovacuum_work_mem</varname> to a value higher than
|
|
that has no effect on the number of dead tuples that autovacuum can
|
|
collect while scanning a table.
|
|
</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-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 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 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 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>
|
|
|
|
</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>
|
|
The accumulated cost that will cause the vacuuming process to sleep.
|
|
The default value 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 many 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-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 system
|
|
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 system 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>
|
|
|
|
<varlistentry id="guc-old-snapshot-threshold" xreflabel="old_snapshot_threshold">
|
|
<term><varname>old_snapshot_threshold</varname> (<type>integer</type>)
|
|
<indexterm>
|
|
<primary><varname>old_snapshot_threshold</varname> configuration parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets the minimum amount of time that a query snapshot can be used
|
|
without risk of a <quote>snapshot too old</quote> error occurring
|
|
when using the snapshot. Data that has been dead for longer than
|
|
this threshold is allowed to be vacuumed away. This can help
|
|
prevent bloat in the face of snapshots which remain in use for a
|
|
long time. To prevent incorrect results due to cleanup of data which
|
|
would otherwise be visible to the snapshot, an error is generated
|
|
when the snapshot is older than this threshold and the snapshot is
|
|
used to read a page which has been modified since the snapshot was
|
|
built.
|
|
</para>
|
|
|
|
<para>
|
|
If this value is specified without units, it is taken as minutes.
|
|
A value of <literal>-1</literal> (the default) disables this feature,
|
|
effectively setting the snapshot age limit to infinity.
|
|
This parameter can only be set at server start.
|
|
</para>
|
|
|
|
<para>
|
|
Useful values for production work probably range from a small number
|
|
of hours to a few days. Small values (such as <literal>0</literal> or
|
|
<literal>1min</literal>) are only allowed because they may sometimes be
|
|
useful for testing. While a setting as high as <literal>60d</literal> is
|
|
allowed, please note that in many workloads extreme bloat or
|
|
transaction ID wraparound may occur in much shorter time frames.
|
|
</para>
|
|
|
|
<para>
|
|
When this feature is enabled, freed space at the end of a relation
|
|
cannot be released to the operating system, since that could remove
|
|
information needed to detect the <quote>snapshot too old</quote>
|
|
condition. All space allocated to a relation remains associated with
|
|
that relation for reuse only within that relation unless explicitly
|
|
freed (for example, with <command>VACUUM FULL</command>).
|
|
</para>
|
|
|
|
<para>
|
|
This setting does not attempt to guarantee that an error will be
|
|
generated under any particular circumstances. In fact, if the
|
|
correct results can be generated from (for example) a cursor which
|
|
has materialized a result set, no error will be generated even if the
|
|
underlying rows in the referenced table have been vacuumed away.
|
|
Some tables cannot safely be vacuumed early, and so will not be
|
|
affected by this setting, such as system catalogs. For such tables
|
|
this setting will neither reduce bloat nor create a possibility
|
|
of a <quote>snapshot too old</quote> error on scanning.
|
|
</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>
|
|
In <literal>minimal</literal> level, no information is logged for
|
|
permanent relations for the remainder of a transaction that creates or
|
|
rewrites 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>
|
|
But minimal WAL does not contain enough information to reconstruct the
|
|
data from a base backup and the WAL logs, so <literal>replica</literal> or
|
|
higher must be used to enable WAL archiving
|
|
(<xref linkend="guc-archive-mode"/>) and streaming replication.
|
|
Note that changing <varname>wal_level</varname> to
|
|
<literal>minimal</literal> makes any base backups taken before
|
|
unavailable for archive recovery and standby server, which may
|
|
lead to data loss.
|
|
</para>
|
|
<para>
|
|
In <literal>logical</literal> level, the same information is logged as
|
|
with <literal>replica</literal>, plus information needed to allow
|
|
extracting 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>
|
|
The <literal>open_</literal>* options also use <literal>O_DIRECT</literal> if available.
|
|
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> and
|
|
<literal>lz4</literal> (if <productname>PostgreSQL</productname> was
|
|
compiled with <option>--with-lz4</option>). The default value is
|
|
<literal>off</literal>. Only superusers 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 many 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 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 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"/>. 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> and <varname>archive_command</varname> are
|
|
separate variables so that <varname>archive_command</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 ignored unless
|
|
<varname>archive_mode</varname> was enabled at server start.
|
|
If <varname>archive_command</varname> is an empty string (the default) while
|
|
<varname>archive_mode</varname> is enabled, 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-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"/> 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-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>
|
|
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>
|
|
|
|
</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"/>). 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>
|
|
|
|
<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>
|
|
</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>
|
|
On the subscriber side, 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>,
|
|
not <link linkend="catalog-pg-replication-origin">pg_replication_origin</link>)
|
|
will prevent the server from starting.
|
|
</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 log file segments 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>
|
|
|
|
</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>
|
|
|
|
<varlistentry id="guc-vacuum-defer-cleanup-age" xreflabel="vacuum_defer_cleanup_age">
|
|
<term><varname>vacuum_defer_cleanup_age</varname> (<type>integer</type>)
|
|
<indexterm>
|
|
<primary><varname>vacuum_defer_cleanup_age</varname> configuration parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the number of transactions by which <command>VACUUM</command> and
|
|
<acronym>HOT</acronym> updates will defer cleanup of dead row versions. The
|
|
default is zero transactions, meaning that dead row versions can be
|
|
removed as soon as possible, that is, as soon as they are no longer
|
|
visible to any open transaction. You may wish to set this to a
|
|
non-zero value on a primary server that is supporting hot standby
|
|
servers, as described in <xref linkend="hot-standby"/>. This allows
|
|
more time for queries on the standby to complete without incurring
|
|
conflicts due to early cleanup of rows. However, since the value
|
|
is measured in terms of number of write transactions occurring on the
|
|
primary server, it is difficult to predict just how much additional
|
|
grace time will be made available to standby queries.
|
|
This parameter can only be set in the <filename>postgresql.conf</filename>
|
|
file or on the server command line.
|
|
</para>
|
|
<para>
|
|
You should also consider setting <varname>hot_standby_feedback</varname>
|
|
on standby server(s) as an alternative to using this parameter.
|
|
</para>
|
|
<para>
|
|
This does not prevent cleanup of dead rows which have reached the age
|
|
specified by <varname>old_snapshot_threshold</varname>.
|
|
</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).
|
|
Do not specify a database name in the
|
|
<varname>primary_conninfo</varname> string.
|
|
</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-promote-trigger-file" xreflabel="promote_trigger_file">
|
|
<term><varname>promote_trigger_file</varname> (<type>string</type>)
|
|
<indexterm>
|
|
<primary><varname>promote_trigger_file</varname> configuration parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a trigger file whose presence ends recovery in the
|
|
standby. Even if this value is not set, you can still promote
|
|
the standby using <command>pg_ctl promote</command> or calling
|
|
<function>pg_promote()</function>.
|
|
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" 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>
|
|
<para>
|
|
This setting does not override the behavior of
|
|
<varname>old_snapshot_threshold</varname> on the primary; a snapshot on the
|
|
standby which exceeds the primary's age threshold can become invalid,
|
|
resulting in cancellation of transactions on the standby. This is
|
|
because <varname>old_snapshot_threshold</varname> is intended to provide an
|
|
absolute limit on the time which dead rows can contribute to bloat,
|
|
which would otherwise be violated because of the configuration of a
|
|
standby.
|
|
</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
|
|
log 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 amount of times an infrastructure is accessed
|
|
is taken into account.
|
|
</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>
|
|
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>
|
|
|
|
</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.
|
|
</para>
|
|
|
|
<para>
|
|
Note that <varname>wal_receiver_timeout</varname>,
|
|
<varname>wal_receiver_status_interval</varname> and
|
|
<varname>wal_retrieve_retry_interval</varname> configuration parameters
|
|
affect the logical replication workers as well.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry id="guc-max-logical-replication-workers" xreflabel="max_logical_replication_workers">
|
|
<term><varname>max_logical_replication_workers</varname> (<type>int</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
|
|
both 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>
|
|
|
|
</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 a partitioned
|
|
tables 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-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>
|
|
|
|
</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 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 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 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 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 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 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 operations.
|
|
</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>
|
|
|
|
<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 will be
|
|
replaced with question marks (<literal>?</literal>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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>
|
|
<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 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 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 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 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 (backendID/localXID)</entry>
|
|
<entry>no</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>%x</literal></entry>
|
|
<entry>Transaction ID (0 if none is assigned)</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 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 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 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>
|
|
</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 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 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 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 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 as of the following
|
|
set of keys with their values.
|
|
</para>
|
|
|
|
<table>
|
|
<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>string</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>
|
|
<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 will be
|
|
replaced with question marks (<literal>?</literal>). 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 can change this setting.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="runtime-config-statistics">
|
|
<title>Run-time Statistics</title>
|
|
|
|
<sect2 id="runtime-config-statistics-collector">
|
|
<title>Query and Index Statistics Collector</title>
|
|
|
|
<para>
|
|
These parameters control server-wide statistics collection features.
|
|
When statistics collection is enabled, the data that is produced 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 not
|
|
visible to all users, only to superusers and the user owning
|
|
the session being reported on, so it should not represent a
|
|
security risk.
|
|
Only superusers 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 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 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 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 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-temp-directory" xreflabel="stats_temp_directory">
|
|
<term><varname>stats_temp_directory</varname> (<type>string</type>)
|
|
<indexterm>
|
|
<primary><varname>stats_temp_directory</varname> configuration parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets the directory to store temporary statistics data in. This can be
|
|
a path relative to the data directory or an absolute path. The default
|
|
is <filename>pg_stat_tmp</filename>. Pointing this at a RAM-based
|
|
file system will decrease physical I/O requirements and can lead to
|
|
improved performance.
|
|
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-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) and <literal>auto</literal>,
|
|
which lets modules such as <xref linkend="pgstatstatements"/>
|
|
automatically enable it.
|
|
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>
|
|
<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 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 to
|
|
specify 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. Setting this variable requires
|
|
superuser privilege and results in discarding any previously cached
|
|
query plans. Possible values are <literal>origin</literal> (the default),
|
|
<literal>replica</literal> and <literal>local</literal>.
|
|
</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-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 freeze row versions
|
|
while scanning a table.
|
|
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, and further non-essential
|
|
maintenance tasks (such as index vacuuming) are bypassed.
|
|
</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 replace multixact IDs with a newer
|
|
transaction ID or multixact ID while scanning a table. 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>
|
|
|
|
</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 can change this setting, because it affects the
|
|
messages sent to the server log as well as to the client, and
|
|
an improper value might obscure the readability of the server
|
|
logs.
|
|
</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-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 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, 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 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 tracks locks on
|
|
<varname>max_locks_per_transaction</varname> * (<xref
|
|
linkend="guc-max-connections"/> + <xref
|
|
linkend="guc-max-prepared-transactions"/>) objects (e.g., tables);
|
|
hence, no more than this many distinct objects can be locked at
|
|
any one time. This parameter controls the average number of object
|
|
locks allocated for 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 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-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 tracks locks on
|
|
<varname>max_pred_locks_per_transaction</varname> * (<xref
|
|
linkend="guc-max-connections"/> + <xref
|
|
linkend="guc-max-prepared-transactions"/>) objects (e.g., tables);
|
|
hence, no more than this many distinct objects can be locked at
|
|
any one time. This parameter controls the average number of object
|
|
locks allocated for 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 generally been sufficient in testing, 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 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>
|
|
|
|
</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 whole 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-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-lc-collate" xreflabel="lc_collate">
|
|
<term><varname>lc_collate</varname> (<type>string</type>)
|
|
<indexterm>
|
|
<primary><varname>lc_collate</varname> configuration parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Reports the locale in which sorting of textual data is done.
|
|
See <xref linkend="locale"/> for more information.
|
|
This value is determined when a database is created.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="guc-lc-ctype" xreflabel="lc_ctype">
|
|
<term><varname>lc_ctype</varname> (<type>string</type>)
|
|
<indexterm>
|
|
<primary><varname>lc_ctype</varname> configuration parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Reports the locale that determines character classifications.
|
|
See <xref linkend="locale"/> for more information.
|
|
This value is determined when a database is created.
|
|
Ordinarily this will be the same as <varname>lc_collate</varname>,
|
|
but for special applications it might be set differently.
|
|
</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, convert any placeholder values according to
|
|
those definitions, and issue warnings for any unrecognized placeholders
|
|
that begin with its extension name.
|
|
</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 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 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>
|
|
This parameter can only be set by superusers.
|
|
</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-force-parallel-mode" xreflabel="force_parallel_mode">
|
|
<term><varname>force_parallel_mode</varname> (<type>enum</type>)
|
|
<indexterm>
|
|
<primary><varname>force_parallel_mode</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>force_parallel_mode</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-recovery-messages" xreflabel="trace_recovery_messages">
|
|
<term><varname>trace_recovery_messages</varname> (<type>enum</type>)
|
|
<indexterm>
|
|
<primary><varname>trace_recovery_messages</varname> configuration parameter</primary>
|
|
</indexterm>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Enables logging of recovery-related debugging output that otherwise
|
|
would not be logged. This parameter allows the user to override the
|
|
normal setting of <xref linkend="guc-log-min-messages"/>, but only for
|
|
specific messages. This is intended for use in debugging Hot Standby.
|
|
Valid values are <literal>DEBUG5</literal>, <literal>DEBUG4</literal>,
|
|
<literal>DEBUG3</literal>, <literal>DEBUG2</literal>, <literal>DEBUG1</literal>, and
|
|
<literal>LOG</literal>. The default, <literal>LOG</literal>, does not affect
|
|
logging decisions at all. The other values cause recovery-related
|
|
debug messages of that priority or higher to be logged as though they
|
|
had <literal>LOG</literal> priority; for common settings of
|
|
<varname>log_min_messages</varname> this results in unconditionally sending
|
|
them to the server log.
|
|
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-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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>. Only
|
|
superusers 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>, and it can only be changed by a superuser.
|
|
</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>, and it can only be changed
|
|
by a superuser.
|
|
</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>.
|
|
This parameter can only be changed by a superuser.
|
|
</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>
|
|
|
|
</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>
|