diff options
Diffstat (limited to 'doc/src/sgml/config.sgml')
| -rw-r--r-- | doc/src/sgml/config.sgml | 11614 |
1 files changed, 11614 insertions, 0 deletions
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml new file mode 100644 index 0000000..ae8c3c6 --- /dev/null +++ b/doc/src/sgml/config.sgml @@ -0,0 +1,11614 @@ +<!-- 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. + Many parameters can be set this way by any user, but some can + only be set by superusers and users who have been + granted <literal>SET</literal> privilege on that parameter. + The corresponding SQL function is + <function>set_config(setting_name, new_value, is_local)</function> + (see <xref linkend="functions-admin-set"/>). + </para> + </listitem> + </itemizedlist> + + <para> + In addition, the system view <link + linkend="view-pg-settings"><structname>pg_settings</structname></link> can be + used to view and change session-local values: + </para> + + <itemizedlist> + <listitem> + <para> + Querying this view is similar to using <command>SHOW ALL</command> but + provides more detail. It is also more flexible, since it's possible + to specify filter conditions or join against other relations. + </para> + </listitem> + + <listitem> + <para> + Using <command>UPDATE</command> on this view, specifically + updating the <structname>setting</structname> column, is the equivalent + of issuing <command>SET</command> commands. For example, the equivalent of +<programlisting> +SET configuration_parameter TO DEFAULT; +</programlisting> + is: +<programlisting> +UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter'; +</programlisting> + </para> + </listitem> + </itemizedlist> + + </sect2> + + <sect2> + <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. If the list is not empty, the server will start if it + can listen on at least one TCP/IP address. A warning will be + emitted for any TCP/IP address which cannot be opened. + The default value is <systemitem class="systemname">localhost</systemitem>, + which allows only local TCP/IP <quote>loopback</quote> connections to be + made. + </para> + <para> + While client authentication (<xref + linkend="client-authentication"/>) allows fine-grained control + over who can access the server, <varname>listen_addresses</varname> + controls which interfaces accept connection attempts, which + can help prevent repeated malicious connection requests on + insecure network interfaces. This parameter can only be set + at server start. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-port" xreflabel="port"> + <term><varname>port</varname> (<type>integer</type>) + <indexterm> + <primary><varname>port</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The TCP port the server listens on; 5432 by default. Note that the + same port number is used for all IP addresses the server listens on. + This parameter can only be set at server start. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-max-connections" xreflabel="max_connections"> + <term><varname>max_connections</varname> (<type>integer</type>) + <indexterm> + <primary><varname>max_connections</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Determines the maximum number of concurrent connections to the + database server. The default is typically 100 connections, but + might be less if your kernel settings will not support it (as + determined during <application>initdb</application>). This parameter can + only be set at server start. + </para> + + <para> + 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 only). In that case, this value + does not specify a <quote>directory</quote> but a prefix from which + the actual socket name is computed in the same manner as for the + file-system namespace. While the abstract socket name prefix can be + chosen freely, since it is not a file-system location, the convention + is to nonetheless use file-system-like values such as + <literal>@/tmp</literal>. + </para> + + <para> + The default value is normally + <filename>/tmp</filename>, but that can be changed at build time. + On Windows, the default is empty, which means no Unix-domain socket is + created by default. + This parameter can only be set at server start. + </para> + + <para> + In addition to the socket file itself, which is named + <literal>.s.PGSQL.<replaceable>nnnn</replaceable></literal> where + <replaceable>nnnn</replaceable> is the server's port number, an ordinary file + named <literal>.s.PGSQL.<replaceable>nnnn</replaceable>.lock</literal> will be + created in each of the <varname>unix_socket_directories</varname> directories. + Neither file should ever be removed manually. + For sockets in the abstract namespace, no lock file is created. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-unix-socket-group" xreflabel="unix_socket_group"> + <term><varname>unix_socket_group</varname> (<type>string</type>) + <indexterm> + <primary><varname>unix_socket_group</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the owning group of the Unix-domain socket(s). (The owning + user of the sockets is always the user that starts the + server.) In combination with the parameter + <varname>unix_socket_permissions</varname> this can be used as + an additional access control mechanism for Unix-domain connections. + By default this is the empty string, which uses the default + group of the server user. This parameter can only be set at + server start. + </para> + + <para> + This parameter is not supported on Windows. Any setting will be + ignored. Also, sockets in the abstract namespace have no file owner, + so this setting is also ignored in that case. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-unix-socket-permissions" xreflabel="unix_socket_permissions"> + <term><varname>unix_socket_permissions</varname> (<type>integer</type>) + <indexterm> + <primary><varname>unix_socket_permissions</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the access permissions of the Unix-domain socket(s). Unix-domain + sockets use the usual Unix file system permission set. + The parameter value is expected to be a numeric mode + specified in the format accepted by the + <function>chmod</function> and <function>umask</function> + system calls. (To use the customary octal format the number + must start with a <literal>0</literal> (zero).) + </para> + + <para> + The default permissions are <literal>0777</literal>, meaning + anyone can connect. Reasonable alternatives are + <literal>0770</literal> (only user and group, see also + <varname>unix_socket_group</varname>) and <literal>0700</literal> + (only user). (Note that for a Unix-domain socket, only write + permission matters, so there is no point in setting or revoking + read or execute permissions.) + </para> + + <para> + This access control mechanism is independent of the one + described in <xref linkend="client-authentication"/>. + </para> + + <para> + This parameter can only be set at server start. + </para> + + <para> + This parameter is irrelevant on systems, notably Solaris as of Solaris + 10, that ignore socket permissions entirely. There, one can achieve a + similar effect by pointing <varname>unix_socket_directories</varname> to a + directory having search permission limited to the desired audience. + </para> + + <para> + Sockets in the abstract namespace have no file permissions, so this + setting is also ignored in that case. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-bonjour" xreflabel="bonjour"> + <term><varname>bonjour</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>bonjour</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables advertising the server's existence via + <productname>Bonjour</productname>. The default is off. + This parameter can only be set at server start. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-bonjour-name" xreflabel="bonjour_name"> + <term><varname>bonjour_name</varname> (<type>string</type>) + <indexterm> + <primary><varname>bonjour_name</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the <productname>Bonjour</productname> service + name. The computer name is used if this parameter is set to the + empty string <literal>''</literal> (which is the default). This parameter is + ignored if the server was not compiled with + <productname>Bonjour</productname> support. + This parameter can only be set at server start. + </para> + </listitem> + </varlistentry> + + <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 relies on kernel events exposed by Linux, macOS, illumos + and the BSD family of operating systems, and is not currently available + on other systems. + </para> + <para> + If the value is specified without units, it is taken as milliseconds. + The default value is <literal>0</literal>, which disables connection + checks. Without connection checks, the server will detect the loss of + the connection only at the next interaction with the socket, when it + waits for, receives or sends data. + </para> + <para> + For the kernel itself to detect lost TCP connections reliably and within + a known timeframe in all scenarios including network failure, it may + also be necessary to adjust the TCP keepalive settings of the operating + system, or the <xref linkend="guc-tcp-keepalives-idle"/>, + <xref linkend="guc-tcp-keepalives-interval"/> and + <xref linkend="guc-tcp-keepalives-count"/> settings of + <productname>PostgreSQL</productname>. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + + <sect2 id="runtime-config-connection-authentication"> + <title>Authentication</title> + + <variablelist> + <varlistentry id="guc-authentication-timeout" xreflabel="authentication_timeout"> + <term><varname>authentication_timeout</varname> (<type>integer</type>) + <indexterm><primary>timeout</primary><secondary>client authentication</secondary></indexterm> + <indexterm><primary>client authentication</primary><secondary>timeout during</secondary></indexterm> + <indexterm> + <primary><varname>authentication_timeout</varname> configuration parameter</primary> + </indexterm> + </term> + + <listitem> + <para> + Maximum amount of time allowed to complete client authentication. If a + would-be client has not completed the authentication protocol in + this much time, the server closes the connection. This prevents + hung clients from occupying a connection indefinitely. + If this value is specified without units, it is taken as seconds. + The default is one minute (<literal>1m</literal>). + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-password-encryption" xreflabel="password_encryption"> + <term><varname>password_encryption</varname> (<type>enum</type>) + <indexterm> + <primary><varname>password_encryption</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When a password is specified in <xref linkend="sql-createrole"/> or + <xref linkend="sql-alterrole"/>, this parameter determines the + algorithm to use to encrypt the password. Possible values are + <literal>scram-sha-256</literal>, which will encrypt the password with + SCRAM-SHA-256, and <literal>md5</literal>, which stores the password + as an MD5 hash. The default is <literal>scram-sha-256</literal>. + </para> + <para> + Note that older clients might lack support for the SCRAM authentication + mechanism, and hence not work with passwords encrypted with + SCRAM-SHA-256. See <xref linkend="auth-password"/> for more details. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-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 + <acronym>SSL</acronym>. The configuration parameters for controlling + transfer encryption using <acronym>TLS</acronym> protocols are named + <literal>ssl</literal> for historic reasons, even though support for + the <acronym>SSL</acronym> protocol has been deprecated. + <acronym>SSL</acronym> is in this context used interchangeably with + <acronym>TLS</acronym>. + </para> + + <variablelist> + <varlistentry id="guc-ssl" xreflabel="ssl"> + <term><varname>ssl</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>ssl</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables <acronym>SSL</acronym> connections. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + The default is <literal>off</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-ssl-ca-file" xreflabel="ssl_ca_file"> + <term><varname>ssl_ca_file</varname> (<type>string</type>) + <indexterm> + <primary><varname>ssl_ca_file</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the name of the file containing the SSL server certificate + authority (CA). + Relative paths are relative to the data directory. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + The default is empty, meaning no CA file is loaded, + and client certificate verification is not performed. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-ssl-cert-file" xreflabel="ssl_cert_file"> + <term><varname>ssl_cert_file</varname> (<type>string</type>) + <indexterm> + <primary><varname>ssl_cert_file</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the name of the file containing the SSL server certificate. + Relative paths are relative to the data directory. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + The default is <filename>server.crt</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-ssl-crl-file" xreflabel="ssl_crl_file"> + <term><varname>ssl_crl_file</varname> (<type>string</type>) + <indexterm> + <primary><varname>ssl_crl_file</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the name of the file containing the SSL client certificate + revocation list (CRL). + Relative paths are relative to the data directory. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + The default is empty, meaning no CRL file is loaded (unless + <xref linkend="guc-ssl-crl-dir"/> is set). + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-ssl-crl-dir" xreflabel="ssl_crl_dir"> + <term><varname>ssl_crl_dir</varname> (<type>string</type>) + <indexterm> + <primary><varname>ssl_crl_dir</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the name of the directory containing the SSL client + certificate revocation list (CRL). Relative paths are relative to the + data directory. This parameter can only be set in + the <filename>postgresql.conf</filename> file or on the server command + line. The default is empty, meaning no CRLs are used (unless + <xref linkend="guc-ssl-crl-file"/> is set). + </para> + + <para> + The directory needs to be prepared with the + <productname>OpenSSL</productname> command + <literal>openssl rehash</literal> or <literal>c_rehash</literal>. See + its documentation for details. + </para> + + <para> + When using this setting, CRLs in the specified directory are loaded + on-demand at connection time. New CRLs can be added to the directory + and will be used immediately. This is unlike <xref + linkend="guc-ssl-crl-file"/>, which causes the CRL in the file to be + loaded at server start time or when the configuration is reloaded. + Both settings can be used together. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-ssl-key-file" xreflabel="ssl_key_file"> + <term><varname>ssl_key_file</varname> (<type>string</type>) + <indexterm> + <primary><varname>ssl_key_file</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the name of the file containing the SSL server private key. + Relative paths are relative to the data directory. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + The default is <filename>server.key</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-ssl-ciphers" xreflabel="ssl_ciphers"> + <term><varname>ssl_ciphers</varname> (<type>string</type>) + <indexterm> + <primary><varname>ssl_ciphers</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies a list of <acronym>SSL</acronym> cipher suites that are + allowed to be used by SSL connections. See the + <citerefentry><refentrytitle>ciphers</refentrytitle></citerefentry> + manual page in the <productname>OpenSSL</productname> package for the + syntax of this setting and a list of supported values. Only + connections using TLS version 1.2 and lower are affected. There is + currently no setting that controls the cipher choices used by TLS + version 1.3 connections. The default value is + <literal>HIGH:MEDIUM:+3DES:!aNULL</literal>. The default is usually a + reasonable choice unless you have specific security requirements. + </para> + + <para> + This parameter can only be set in the + <filename>postgresql.conf</filename> file or on the server command + line. + </para> + + <para> + Explanation of the default value: + <variablelist> + <varlistentry> + <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 a complex query might perform several sort and hash + operations at the same time, with each operation generally being + allowed to use as much memory as this value specifies before + it starts + to write data into temporary files. Also, several running + sessions could be doing such operations concurrently. + Therefore, the total memory used could be many times the value + of <varname>work_mem</varname>; it is necessary to keep this + fact in mind when choosing the value. Sort operations are used + for <literal>ORDER BY</literal>, <literal>DISTINCT</literal>, + and merge joins. + Hash tables are used in hash joins, hash-based aggregation, memoize + nodes and hash-based processing of <literal>IN</literal> subqueries. + </para> + <para> + Hash-based operations are generally more sensitive to memory + availability than equivalent sort-based operations. The + memory limit for a hash table is computed by multiplying + <varname>work_mem</varname> by + <varname>hash_mem_multiplier</varname>. This makes it + possible for hash-based operations to use an amount of memory + that exceeds the usual <varname>work_mem</varname> base + amount. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-hash-mem-multiplier" xreflabel="hash_mem_multiplier"> + <term><varname>hash_mem_multiplier</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>hash_mem_multiplier</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Used to compute the maximum amount of memory that hash-based + operations can use. The final limit is determined by + multiplying <varname>work_mem</varname> by + <varname>hash_mem_multiplier</varname>. The default value is + 2.0, which makes hash-based operations use twice the usual + <varname>work_mem</varname> base amount. + </para> + <para> + Consider increasing <varname>hash_mem_multiplier</varname> in + environments where spilling by query operations is a regular + occurrence, especially when simply increasing + <varname>work_mem</varname> results in memory pressure (memory + pressure typically takes the form of intermittent out of + memory errors). The default setting of 2.0 is often effective with + mixed workloads. Higher settings in the range of 2.0 - 8.0 or + more may be effective in environments where + <varname>work_mem</varname> has already been increased to 40MB + or more. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-maintenance-work-mem" xreflabel="maintenance_work_mem"> + <term><varname>maintenance_work_mem</varname> (<type>integer</type>) + <indexterm> + <primary><varname>maintenance_work_mem</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the maximum amount of memory to be used by maintenance + operations, such as <command>VACUUM</command>, <command>CREATE + INDEX</command>, and <command>ALTER TABLE ADD FOREIGN KEY</command>. + If this value is specified without units, it is taken as kilobytes. + It defaults + to 64 megabytes (<literal>64MB</literal>). Since only one of these + operations can be executed at a time by a database session, and + an installation normally doesn't have many of them running + concurrently, it's safe to set this value significantly larger + than <varname>work_mem</varname>. Larger settings might improve + performance for vacuuming and for restoring database dumps. + </para> + <para> + Note that when autovacuum runs, up to + <xref linkend="guc-autovacuum-max-workers"/> times this memory + may be allocated, so be careful not to set the default value + too high. It may be useful to control for this by separately + setting <xref linkend="guc-autovacuum-work-mem"/>. + </para> + <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 and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <para> + Setting <varname>max_stack_depth</varname> higher than + the actual kernel limit will mean that a runaway recursive function + can crash an individual backend process. On platforms where + <productname>PostgreSQL</productname> can determine the kernel limit, + the server will not allow this variable to be set to an unsafe + value. However, not all platforms provide the information, + so caution is recommended in selecting a value. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-shared-memory-type" xreflabel="shared_memory_type"> + <term><varname>shared_memory_type</varname> (<type>enum</type>) + <indexterm> + <primary><varname>shared_memory_type</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the shared memory implementation that the server + should use for the main shared memory region that holds + <productname>PostgreSQL</productname>'s shared buffers and other + shared data. Possible values are <literal>mmap</literal> (for + anonymous shared memory allocated using <function>mmap</function>), + <literal>sysv</literal> (for System V shared memory allocated via + <function>shmget</function>) and <literal>windows</literal> (for Windows + shared memory). Not all values are supported on all platforms; the + first supported option is the default for that platform. The use of + the <literal>sysv</literal> option, which is not the default on any + platform, is generally discouraged because it typically requires + non-default kernel settings to allow for large allocations (see <xref + linkend="sysvipc"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-dynamic-shared-memory-type" xreflabel="dynamic_shared_memory_type"> + <term><varname>dynamic_shared_memory_type</varname> (<type>enum</type>) + <indexterm> + <primary><varname>dynamic_shared_memory_type</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the dynamic shared memory implementation that the server + should use. Possible values are <literal>posix</literal> (for POSIX shared + memory allocated using <literal>shm_open</literal>), <literal>sysv</literal> + (for System V shared memory allocated via <literal>shmget</literal>), + <literal>windows</literal> (for Windows shared memory), + and <literal>mmap</literal> (to simulate shared memory using + memory-mapped files stored in the data directory). + Not all values are supported on all platforms; the first supported + option is usually the default for that platform. The use of the + <literal>mmap</literal> option, which is not the default on any platform, + is generally discouraged because the operating system may write + modified pages back to disk repeatedly, increasing system I/O load; + however, it may be useful for debugging, when the + <literal>pg_dynshmem</literal> directory is stored on a RAM disk, or when + other shared memory facilities are not available. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-min-dynamic-shared-memory" xreflabel="min_dynamic_shared_memory"> + <term><varname>min_dynamic_shared_memory</varname> (<type>integer</type>) + <indexterm> + <primary><varname>min_dynamic_shared_memory</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the amount of memory that should be allocated at server + startup for use by parallel queries. When this memory region is + insufficient or exhausted by concurrent queries, new parallel queries + try to allocate extra shared memory temporarily from the operating + system using the method configured with + <varname>dynamic_shared_memory_type</varname>, which may be slower due + to memory management overheads. Memory that is allocated at startup + with <varname>min_dynamic_shared_memory</varname> is affected by + the <varname>huge_pages</varname> setting on operating systems where + that is supported, and may be more likely to benefit from larger pages + on operating systems where that is managed automatically. + The default value is <literal>0</literal> (none). This parameter can + only be set at server start. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + + <sect2 id="runtime-config-resource-disk"> + <title>Disk</title> + + <variablelist> + <varlistentry id="guc-temp-file-limit" xreflabel="temp_file_limit"> + <term><varname>temp_file_limit</varname> (<type>integer</type>) + <indexterm> + <primary><varname>temp_file_limit</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the maximum amount of disk space that a process can use + for temporary files, such as sort and hash temporary files, or the + storage file for a held cursor. A transaction attempting to exceed + this limit will be canceled. + If this value is specified without units, it is taken as kilobytes. + <literal>-1</literal> (the default) means no limit. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + <para> + This setting constrains the total space used at any instant by all + temporary files used by a given <productname>PostgreSQL</productname> process. + It should be noted that disk space used for explicit temporary + tables, as opposed to temporary files used behind-the-scenes in query + execution, does <emphasis>not</emphasis> count against this limit. + </para> + </listitem> + </varlistentry> + + </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> + The <literal>minimal</literal> level generates the least WAL + volume. It logs no row information for permanent relations + in transactions that create or + rewrite them. This can make operations much faster (see + <xref linkend="populate-pitr"/>). Operations that initiate this + optimization include: + <simplelist> + <member><command>ALTER ... SET TABLESPACE</command></member> + <member><command>CLUSTER</command></member> + <member><command>CREATE TABLE</command></member> + <member><command>REFRESH MATERIALIZED VIEW</command> + (without <option>CONCURRENTLY</option>)</member> + <member><command>REINDEX</command></member> + <member><command>TRUNCATE</command></member> + </simplelist> + However, minimal WAL does not contain sufficient information for + point-in-time recovery, so <literal>replica</literal> or + higher must be used to enable continuous archiving + (<xref linkend="guc-archive-mode"/>) and streaming binary replication. + In fact, the server will not even start in this mode if + <varname>max_wal_senders</varname> is non-zero. + Note that changing <varname>wal_level</varname> to + <literal>minimal</literal> makes previous base backups unusable + for point-in-time recovery and standby servers. + </para> + <para> + In <literal>logical</literal> level, the same information is logged as + with <literal>replica</literal>, plus information needed to + extract logical change sets from the WAL. Using a level of + <literal>logical</literal> will increase the WAL volume, particularly if many + tables are configured for <literal>REPLICA IDENTITY FULL</literal> and + many <command>UPDATE</command> and <command>DELETE</command> statements are + executed. + </para> + <para> + In releases prior to 9.6, this parameter also allowed the + values <literal>archive</literal> and <literal>hot_standby</literal>. + These are still accepted but mapped to <literal>replica</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-fsync" xreflabel="fsync"> + <term><varname>fsync</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>fsync</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If this parameter is on, the <productname>PostgreSQL</productname> server + will try to make sure that updates are physically written to + disk, by issuing <function>fsync()</function> system calls or various + equivalent methods (see <xref linkend="guc-wal-sync-method"/>). + This ensures that the database cluster can recover to a + consistent state after an operating system or hardware crash. + </para> + + <para> + While turning off <varname>fsync</varname> is often a performance + benefit, this can result in unrecoverable data corruption in + the event of a power failure or system crash. Thus it + is only advisable to turn off <varname>fsync</varname> if + you can easily recreate your entire database from external + data. + </para> + + <para> + Examples of safe circumstances for turning off + <varname>fsync</varname> include the initial loading of a new + database cluster from a backup file, using a database cluster + for processing a batch of data after which the database + will be thrown away and recreated, + or for a read-only database clone which + gets recreated frequently and is not used for failover. High + quality hardware alone is not a sufficient justification for + turning off <varname>fsync</varname>. + </para> + + <para> + For reliable recovery when changing <varname>fsync</varname> + off to on, it is necessary to force all modified buffers in the + kernel to durable storage. This can be done while the cluster + is shutdown or while <varname>fsync</varname> is on by running <command>initdb + --sync-only</command>, running <command>sync</command>, unmounting the + file system, or rebooting the server. + </para> + + <para> + In many situations, turning off <xref linkend="guc-synchronous-commit"/> + for noncritical transactions can provide much of the potential + performance benefit of turning off <varname>fsync</varname>, without + the attendant risks of data corruption. + </para> + + <para> + <varname>fsync</varname> can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + If you turn this parameter off, also consider turning off + <xref linkend="guc-full-page-writes"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-synchronous-commit" xreflabel="synchronous_commit"> + <term><varname>synchronous_commit</varname> (<type>enum</type>) + <indexterm> + <primary><varname>synchronous_commit</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies how much WAL processing must complete before + the database server returns a <quote>success</quote> + indication to the client. Valid values are + <literal>remote_apply</literal>, <literal>on</literal> + (the default), <literal>remote_write</literal>, + <literal>local</literal>, and <literal>off</literal>. + </para> + + <para> + If <varname>synchronous_standby_names</varname> is empty, + the only meaningful settings are <literal>on</literal> and + <literal>off</literal>; <literal>remote_apply</literal>, + <literal>remote_write</literal> and <literal>local</literal> + all provide the same local synchronization level + as <literal>on</literal>. The local behavior of all + non-<literal>off</literal> modes is to wait for local flush of WAL + to disk. In <literal>off</literal> mode, there is no waiting, + so there can be a delay between when success is reported to the + client and when the transaction is later guaranteed to be safe + against a server crash. (The maximum + delay is three times <xref linkend="guc-wal-writer-delay"/>.) Unlike + <xref linkend="guc-fsync"/>, setting this parameter to <literal>off</literal> + does not create any risk of database inconsistency: an operating + system or database crash might + result in some recent allegedly-committed transactions being lost, but + the database state will be just the same as if those transactions had + been aborted cleanly. So, turning <varname>synchronous_commit</varname> off + can be a useful alternative when performance is more important than + exact certainty about the durability of a transaction. For more + discussion see <xref linkend="wal-async-commit"/>. + </para> + + <para> + If <xref linkend="guc-synchronous-standby-names"/> is non-empty, + <varname>synchronous_commit</varname> also controls whether + transaction commits will wait for their WAL records to be + processed on the standby server(s). + </para> + + <para> + When set to <literal>remote_apply</literal>, commits will wait + until replies from the current synchronous standby(s) indicate they + have received the commit record of the transaction and applied + it, so that it has become visible to queries on the standby(s), + and also written to durable storage on the standbys. This will + cause much larger commit delays than previous settings since + it waits for WAL replay. When set to <literal>on</literal>, + commits wait until replies + from the current synchronous standby(s) indicate they have received + the commit record of the transaction and flushed it to durable storage. This + ensures the transaction will not be lost unless both the primary and + all synchronous standbys suffer corruption of their database storage. + When set to <literal>remote_write</literal>, commits will wait until replies + from the current synchronous standby(s) indicate they have + received the commit record of the transaction and written it to + their file systems. This setting ensures data preservation if a standby instance of + <productname>PostgreSQL</productname> crashes, but not if the standby + suffers an operating-system-level crash because the data has not + necessarily reached durable storage on the standby. + The setting <literal>local</literal> causes commits to wait for + local flush to disk, but not for replication. This is usually not + desirable when synchronous replication is in use, but is provided for + completeness. + </para> + + <para> + This parameter can be changed at any time; the behavior for any + one transaction is determined by the setting in effect when it + commits. It is therefore possible, and useful, to have some + transactions commit synchronously and others asynchronously. + For example, to make a single multistatement transaction commit + asynchronously when the default is the opposite, issue <command>SET + LOCAL synchronous_commit TO OFF</command> within the transaction. + </para> + + <para> + <xref linkend="synchronous-commit-matrix"/> summarizes the + capabilities of the <varname>synchronous_commit</varname> settings. + </para> + + <table id="synchronous-commit-matrix"> + <title>synchronous_commit Modes</title> + <tgroup cols="5"> + <colspec colname="col1" colwidth="1.5*"/> + <colspec colname="col2" colwidth="1*"/> + <colspec colname="col3" colwidth="1*"/> + <colspec colname="col4" colwidth="1*"/> + <colspec colname="col5" colwidth="1*"/> + <thead> + <row> + <entry>synchronous_commit setting</entry> + <entry>local durable commit</entry> + <entry>standby durable commit after PG crash</entry> + <entry>standby durable commit after OS crash</entry> + <entry>standby query consistency</entry> + </row> + </thead> + + <tbody> + + <row> + <entry>remote_apply</entry> + <entry align="center">•</entry> + <entry align="center">•</entry> + <entry align="center">•</entry> + <entry align="center">•</entry> + </row> + + <row> + <entry>on</entry> + <entry align="center">•</entry> + <entry align="center">•</entry> + <entry align="center">•</entry> + <entry align="center"></entry> + </row> + + <row> + <entry>remote_write</entry> + <entry align="center">•</entry> + <entry align="center">•</entry> + <entry align="center"></entry> + <entry align="center"></entry> + </row> + + <row> + <entry>local</entry> + <entry align="center">•</entry> + <entry align="center"></entry> + <entry align="center"></entry> + <entry align="center"></entry> + </row> + + <row> + <entry>off</entry> + <entry align="center"></entry> + <entry align="center"></entry> + <entry align="center"></entry> + <entry align="center"></entry> + </row> + + </tbody> + </tgroup> + </table> + + </listitem> + </varlistentry> + + <varlistentry id="guc-wal-sync-method" xreflabel="wal_sync_method"> + <term><varname>wal_sync_method</varname> (<type>enum</type>) + <indexterm> + <primary><varname>wal_sync_method</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Method used for forcing WAL updates out to disk. + If <varname>fsync</varname> is off then this setting is irrelevant, + since WAL file updates will not be forced out at all. + Possible values are: + </para> + <itemizedlist> + <listitem> + <para> + <literal>open_datasync</literal> (write WAL files with <function>open()</function> option <symbol>O_DSYNC</symbol>) + </para> + </listitem> + <listitem> + <para> + <literal>fdatasync</literal> (call <function>fdatasync()</function> at each commit) + </para> + </listitem> + <listitem> + <para> + <literal>fsync</literal> (call <function>fsync()</function> at each commit) + </para> + </listitem> + <listitem> + <para> + <literal>fsync_writethrough</literal> (call <function>fsync()</function> at each commit, forcing write-through of any disk write cache) + </para> + </listitem> + <listitem> + <para> + <literal>open_sync</literal> (write WAL files with <function>open()</function> option <symbol>O_SYNC</symbol>) + </para> + </listitem> + </itemizedlist> + <para> + 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>, + <literal>lz4</literal> (if <productname>PostgreSQL</productname> + was compiled with <option>--with-lz4</option>) and + <literal>zstd</literal> (if <productname>PostgreSQL</productname> + was compiled with <option>--with-zstd</option>). + The default value is <literal>off</literal>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <para> + Enabling compression can reduce the WAL volume without + increasing the risk of unrecoverable data corruption, + but at the cost of some extra CPU spent on the compression during + WAL logging and on the decompression during WAL replay. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-wal-init-zero" xreflabel="wal_init_zero"> + <term><varname>wal_init_zero</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>wal_init_zero</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If set to <literal>on</literal> (the default), this option causes new + WAL files to be filled with zeroes. On some file systems, this ensures + that space is allocated before we need to write WAL records. However, + <firstterm>Copy-On-Write</firstterm> (COW) file systems may not benefit + from this technique, so the option is given to skip the unnecessary + work. If set to <literal>off</literal>, only the final byte is written + when the file is created so that it has the expected size. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-wal-recycle" xreflabel="wal_recycle"> + <term><varname>wal_recycle</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>wal_recycle</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If set to <literal>on</literal> (the default), this option causes WAL + files to be recycled by renaming them, avoiding the need to create new + ones. On COW file systems, it may be faster to create new ones, so the + option is given to disable this behavior. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-wal-buffers" xreflabel="wal_buffers"> + <term><varname>wal_buffers</varname> (<type>integer</type>) + <indexterm> + <primary><varname>wal_buffers</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The amount of shared memory used for WAL data that has not yet been + written to disk. The default setting of -1 selects a size equal to + 1/32nd (about 3%) of <xref linkend="guc-shared-buffers"/>, but not less + than <literal>64kB</literal> nor more than the size of one WAL + segment, typically <literal>16MB</literal>. This value can be set + manually if the automatic choice is too large or too small, + but any positive value less than <literal>32kB</literal> will be + treated as <literal>32kB</literal>. + If this value is specified without units, it is taken as WAL blocks, + that is <symbol>XLOG_BLCKSZ</symbol> bytes, typically 8kB. + This parameter can only be set at server start. + </para> + + <para> + The contents of the WAL buffers are written out to disk at every + transaction commit, so extremely large values are unlikely to + provide a significant benefit. However, setting this value to at + least a few megabytes can improve write performance on a busy + server where many clients are committing at once. The auto-tuning + selected by the default setting of -1 should give reasonable + results in most cases. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="guc-wal-writer-delay" xreflabel="wal_writer_delay"> + <term><varname>wal_writer_delay</varname> (<type>integer</type>) + <indexterm> + <primary><varname>wal_writer_delay</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies how often the WAL writer flushes WAL, in time terms. + After flushing WAL the writer sleeps for the length of time given + by <varname>wal_writer_delay</varname>, unless woken up sooner + by an asynchronously committing transaction. If the last flush + happened less than <varname>wal_writer_delay</varname> ago and less + than <varname>wal_writer_flush_after</varname> worth of WAL has been + produced since, then WAL is only written to the operating system, not + flushed to disk. + If this value is specified without units, it is taken as milliseconds. + The default value is 200 milliseconds (<literal>200ms</literal>). Note that + on 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 and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + <para> + In <productname>PostgreSQL</productname> releases prior to 9.3, + <varname>commit_delay</varname> behaved differently and was much + less effective: it affected only commits, rather than all WAL flushes, + and waited for the entire configured delay even if the WAL flush + was completed sooner. Beginning in <productname>PostgreSQL</productname> 9.3, + the first process that becomes ready to flush waits for the configured + interval, while subsequent processes wait only until the leader + completes the flush operation. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-commit-siblings" xreflabel="commit_siblings"> + <term><varname>commit_siblings</varname> (<type>integer</type>) + <indexterm> + <primary><varname>commit_siblings</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Minimum number of concurrent open transactions to require + before performing the <varname>commit_delay</varname> delay. A larger + value makes it more probable that at least one other + transaction will become ready to commit during the delay + interval. The default is five transactions. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + <sect2 id="runtime-config-wal-checkpoints"> + <title>Checkpoints</title> + + <variablelist> + <varlistentry id="guc-checkpoint-timeout" xreflabel="checkpoint_timeout"> + <term><varname>checkpoint_timeout</varname> (<type>integer</type>) + <indexterm> + <primary><varname>checkpoint_timeout</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Maximum time between automatic WAL checkpoints. + If this value is specified without units, it is taken as seconds. + The valid range is between 30 seconds and one day. + The default is five minutes (<literal>5min</literal>). + Increasing this parameter can increase the amount of time needed + for crash recovery. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-checkpoint-completion-target" xreflabel="checkpoint_completion_target"> + <term><varname>checkpoint_completion_target</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>checkpoint_completion_target</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the target of checkpoint completion, as a fraction of + total time between checkpoints. The default is 0.9, which spreads the + checkpoint across almost all of the available interval, providing fairly + consistent I/O load while also leaving some time for checkpoint + completion overhead. Reducing this parameter is not recommended because + it causes the checkpoint to complete faster. This results in a higher + rate of I/O during the checkpoint followed by a period of less I/O between + the checkpoint completion and the next scheduled checkpoint. This + parameter can only be set in the <filename>postgresql.conf</filename> file + or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-checkpoint-flush-after" xreflabel="checkpoint_flush_after"> + <term><varname>checkpoint_flush_after</varname> (<type>integer</type>) + <indexterm> + <primary><varname>checkpoint_flush_after</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Whenever more than this amount of data has been + written while performing a checkpoint, attempt to force the + OS to issue these writes to the underlying storage. Doing so will + limit the amount of dirty data in the kernel's page cache, reducing + the likelihood of stalls when an <function>fsync</function> is issued at the end of the + checkpoint, or when the OS writes data back in larger batches in the + background. Often that will result in greatly reduced transaction + latency, but there also are some cases, especially with workloads + that are bigger than <xref linkend="guc-shared-buffers"/>, but smaller + than the OS's page cache, where performance might degrade. This + setting may have no effect on some platforms. + If this value is specified without units, it is taken as blocks, + that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. + The valid range is + between <literal>0</literal>, which disables forced writeback, + and <literal>2MB</literal>. The default is <literal>256kB</literal> on + Linux, <literal>0</literal> elsewhere. (If <symbol>BLCKSZ</symbol> is not + 8kB, the default and maximum values scale proportionally to it.) + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-checkpoint-warning" xreflabel="checkpoint_warning"> + <term><varname>checkpoint_warning</varname> (<type>integer</type>) + <indexterm> + <primary><varname>checkpoint_warning</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Write a message to the server log if checkpoints caused by + the filling of WAL segment files happen closer together + than this amount of time (which suggests that + <varname>max_wal_size</varname> ought to be raised). + If this value is specified without units, it is taken as seconds. + The default is 30 seconds (<literal>30s</literal>). + Zero disables the warning. + No warnings will be generated if <varname>checkpoint_timeout</varname> + is less than <varname>checkpoint_warning</varname>. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-max-wal-size" xreflabel="max_wal_size"> + <term><varname>max_wal_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>max_wal_size</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Maximum size to let the WAL grow during automatic + checkpoints. This is a soft limit; WAL size can exceed + <varname>max_wal_size</varname> under special circumstances, such as + heavy load, a failing <varname>archive_command</varname> or <varname>archive_library</varname>, or a high + <varname>wal_keep_size</varname> setting. + If this value is specified without units, it is taken as megabytes. + The default is 1 GB. + Increasing this parameter can increase the amount of time needed for + crash recovery. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-min-wal-size" xreflabel="min_wal_size"> + <term><varname>min_wal_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>min_wal_size</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + As long as WAL disk usage stays below this setting, old WAL files are + always recycled for future use at a checkpoint, rather than removed. + This can be used to ensure that enough WAL space is reserved to + handle spikes in WAL usage, for example when running large batch + jobs. + If this value is specified without units, it is taken as megabytes. + The default is 80 MB. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + <sect2 id="runtime-config-wal-archiving"> + <title>Archiving</title> + + <variablelist> + <varlistentry id="guc-archive-mode" xreflabel="archive_mode"> + <term><varname>archive_mode</varname> (<type>enum</type>) + <indexterm> + <primary><varname>archive_mode</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When <varname>archive_mode</varname> is enabled, completed WAL segments + are sent to archive storage by setting + <xref linkend="guc-archive-command"/> or + <xref linkend="guc-archive-library"/>. In addition to <literal>off</literal>, + to disable, there are two modes: <literal>on</literal>, and + <literal>always</literal>. During normal operation, there is no + difference between the two modes, but when set to <literal>always</literal> + the WAL archiver is enabled also during archive recovery or standby + mode. In <literal>always</literal> mode, all files restored from the archive + or streamed with streaming replication will be archived (again). See + <xref linkend="continuous-archiving-in-standby"/> for details. + </para> + <para> + <varname>archive_mode</varname> is a separate setting from + <varname>archive_command</varname> and + <varname>archive_library</varname> so that + <varname>archive_command</varname> and + <varname>archive_library</varname> can be changed without leaving + archiving mode. + This parameter can only be set at server start. + <varname>archive_mode</varname> cannot be enabled when + <varname>wal_level</varname> is set to <literal>minimal</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-archive-command" xreflabel="archive_command"> + <term><varname>archive_command</varname> (<type>string</type>) + <indexterm> + <primary><varname>archive_command</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The local shell command to execute to archive a completed WAL file + segment. Any <literal>%p</literal> in the string is + replaced by the path name of the file to archive, and any + <literal>%f</literal> is replaced by only the file name. + (The path name is relative to the working directory of the server, + i.e., the cluster's data directory.) + Use <literal>%%</literal> to embed an actual <literal>%</literal> character in the + command. It is important for the command to return a zero + exit status only if it succeeds. For more information see + <xref linkend="backup-archiving-wal"/>. + </para> + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. It is ignored unless + <varname>archive_mode</varname> was enabled at server start and + <varname>archive_library</varname> is set to an empty string. + If <varname>archive_command</varname> is an empty string (the default) while + <varname>archive_mode</varname> is enabled (and <varname>archive_library</varname> + is set to an empty string), WAL archiving is temporarily + disabled, but the server continues to accumulate WAL segment files in + the expectation that a command will soon be provided. Setting + <varname>archive_command</varname> to a command that does nothing but + return true, e.g., <literal>/bin/true</literal> (<literal>REM</literal> on + Windows), effectively disables + archiving, but also breaks the chain of WAL files needed for + archive recovery, so it should only be used in unusual circumstances. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-archive-library" xreflabel="archive_library"> + <term><varname>archive_library</varname> (<type>string</type>) + <indexterm> + <primary><varname>archive_library</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The library to use for archiving completed WAL file segments. If set to + an empty string (the default), archiving via shell is enabled, and + <xref linkend="guc-archive-command"/> is used. Otherwise, the specified + shared library is used for archiving. The WAL archiver process is + restarted by the postmaster when this parameter changes. For more + information, see <xref linkend="backup-archiving-wal"/> and + <xref linkend="archive-modules"/>. + </para> + <para> + This parameter can only be set in the + <filename>postgresql.conf</filename> file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-archive-timeout" xreflabel="archive_timeout"> + <term><varname>archive_timeout</varname> (<type>integer</type>) + <indexterm> + <primary><varname>archive_timeout</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The <xref linkend="guc-archive-command"/> or <xref linkend="guc-archive-library"/> is only invoked for + completed WAL segments. Hence, if your server generates little WAL + traffic (or has slack periods where it does so), there could be a + long delay between the completion of a transaction and its safe + recording in archive storage. To limit how old unarchived + data can be, you can set <varname>archive_timeout</varname> to force the + server to switch to a new WAL segment file periodically. When this + parameter is greater than zero, the server will switch to a new + segment file whenever this amount of time has elapsed since the last + segment file switch, and there has been any database activity, + including a single checkpoint (checkpoints are skipped if there is + no database activity). Note that archived files that are closed + early due to a forced switch are still the same length as completely + full files. Therefore, it is unwise to use a very short + <varname>archive_timeout</varname> — it will bloat your archive + storage. <varname>archive_timeout</varname> settings of a minute or so are + usually reasonable. You should consider using streaming replication, + instead of archiving, if you want data to be copied off the primary + server more quickly than that. + If this value is specified without units, it is taken as seconds. + This parameter can only be set in the + <filename>postgresql.conf</filename> file or on the server command line. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + + <sect2 id="runtime-config-wal-recovery"> + + <title>Recovery</title> + + <indexterm> + <primary>configuration</primary> + <secondary>of recovery</secondary> + <tertiary>general settings</tertiary> + </indexterm> + + <para> + This section describes the settings that apply to recovery in general, + affecting crash recovery, streaming replication and archive-based + replication. + </para> + + + <variablelist> + <varlistentry id="guc-recovery-prefetch" xreflabel="recovery_prefetch"> + <term><varname>recovery_prefetch</varname> (<type>enum</type>) + <indexterm> + <primary><varname>recovery_prefetch</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Whether to try to prefetch blocks that are referenced in the WAL that + are not yet in the buffer pool, during recovery. Valid values are + <literal>off</literal>, <literal>on</literal> and + <literal>try</literal> (the default). The setting + <literal>try</literal> enables + prefetching only if the operating system provides the + <function>posix_fadvise</function> function, which is currently used + to implement prefetching. Note that some operating systems provide the + function, but it doesn't do anything. + </para> + <para> + Prefetching blocks that will soon be needed can reduce I/O wait times + during recovery with some workloads. + See also the <xref linkend="guc-wal-decode-buffer-size"/> and + <xref linkend="guc-maintenance-io-concurrency"/> settings, which limit + prefetching activity. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-wal-decode-buffer-size" xreflabel="wal_decode_buffer_size"> + <term><varname>wal_decode_buffer_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>wal_decode_buffer_size</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + A limit on how far ahead the server can look in the WAL, to find + blocks to prefetch. If this value is specified without units, it is + taken as bytes. + The default is 512kB. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + + <sect2 id="runtime-config-wal-archive-recovery"> + + <title>Archive Recovery</title> + + <indexterm> + <primary>configuration</primary> + <secondary>of recovery</secondary> + <tertiary>of a standby server</tertiary> + </indexterm> + + <para> + This section describes the settings that apply only for the duration of + the recovery. They must be reset for any subsequent recovery you wish to + perform. + </para> + + <para> + <quote>Recovery</quote> covers using the server as a standby or for + executing a targeted recovery. Typically, standby mode would be used to + provide high availability and/or read scalability, whereas a targeted + recovery is used to recover from data loss. + </para> + + <para> + To start the server in standby mode, create a file called + <filename>standby.signal</filename><indexterm><primary>standby.signal</primary></indexterm> + in the data directory. The server will enter recovery and will not stop + recovery when the end of archived WAL is reached, but will keep trying to + continue recovery by connecting to the sending server as specified by the + <varname>primary_conninfo</varname> setting and/or by fetching new WAL + segments using <varname>restore_command</varname>. For this mode, the + parameters from this section and <xref + linkend="runtime-config-replication-standby"/> are of interest. + Parameters from <xref linkend="runtime-config-wal-recovery-target"/> will + also be applied but are typically not useful in this mode. + </para> + + <para> + To start the server in targeted recovery mode, create a file called + <filename>recovery.signal</filename><indexterm><primary>recovery.signal</primary></indexterm> + in the data directory. If both <filename>standby.signal</filename> and + <filename>recovery.signal</filename> files are created, standby mode + takes precedence. Targeted recovery mode ends when the archived WAL is + fully replayed, or when <varname>recovery_target</varname> is reached. + In this mode, the parameters from both this section and <xref + linkend="runtime-config-wal-recovery-target"/> will be used. + </para> + + <variablelist> + <varlistentry id="guc-restore-command" xreflabel="restore_command"> + <term><varname>restore_command</varname> (<type>string</type>) + <indexterm> + <primary><varname>restore_command</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The local shell command to execute to retrieve an archived segment of + the WAL file series. This parameter is required for archive recovery, + but optional for streaming replication. + Any <literal>%f</literal> in the string is + replaced by the name of the file to retrieve from the archive, + and any <literal>%p</literal> is replaced by the copy destination path name + on the server. + (The path name is relative to the current working directory, + i.e., the cluster's data directory.) + Any <literal>%r</literal> is replaced by the name of the file containing the + last valid restart point. That is the earliest file that must be kept + to allow a restore to be restartable, so this information can be used + to truncate the archive to just the minimum required to support + restarting from the current restore. <literal>%r</literal> is typically only + used by warm-standby configurations + (see <xref linkend="warm-standby"/>). + Write <literal>%%</literal> to embed an actual <literal>%</literal> character. + </para> + + <para> + It is important for the command to return a zero exit status + only if it succeeds. The command <emphasis>will</emphasis> be asked for file + names that are not present in the archive; it must return nonzero + when so asked. Examples: +<programlisting> +restore_command = 'cp /mnt/server/archivedir/%f "%p"' +restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows +</programlisting> + An exception is that if the command was terminated by a signal (other + than <systemitem>SIGTERM</systemitem>, which is used as part of a + database server shutdown) or an error by the shell (such as command + not found), then recovery will abort and the server will not start up. + </para> + + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-archive-cleanup-command" xreflabel="archive_cleanup_command"> + <term><varname>archive_cleanup_command</varname> (<type>string</type>) + <indexterm> + <primary><varname>archive_cleanup_command</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This optional parameter specifies a shell command that will be executed + at every restartpoint. The purpose of + <varname>archive_cleanup_command</varname> is to provide a mechanism for + cleaning up old archived WAL files that are no longer needed by the + standby server. + Any <literal>%r</literal> is replaced by the name of the file containing the + last valid restart point. + That is the earliest file that must be <emphasis>kept</emphasis> to allow a + restore to be restartable, and so all files earlier than <literal>%r</literal> + may be safely removed. + This information can be used to truncate the archive to just the + minimum required to support restart from the current restore. + The <xref linkend="pgarchivecleanup"/> module + is often used in <varname>archive_cleanup_command</varname> for + single-standby configurations, for example: +<programlisting>archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'</programlisting> + Note however that if multiple standby servers are restoring from the + same archive directory, you will need to ensure that you do not delete + WAL files until they are no longer needed by any of the servers. + <varname>archive_cleanup_command</varname> would typically be used in a + warm-standby configuration (see <xref linkend="warm-standby"/>). + Write <literal>%%</literal> to embed an actual <literal>%</literal> character in the + command. + </para> + <para> + If the command returns a nonzero exit status then a warning log + message will be written. An exception is that if the command was + terminated by a signal or an error by the shell (such as command not + found), a fatal error will be raised. + </para> + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-end-command" xreflabel="recovery_end_command"> + <term><varname>recovery_end_command</varname> (<type>string</type>) + <indexterm> + <primary><varname>recovery_end_command</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies a shell command that will be executed once only + at the end of recovery. This parameter is optional. The purpose of the + <varname>recovery_end_command</varname> is to provide a mechanism for cleanup + following replication or recovery. + Any <literal>%r</literal> is replaced by the name of the file containing the + last valid restart point, like in <xref linkend="guc-archive-cleanup-command"/>. + </para> + <para> + If the command returns a nonzero exit status then a warning log + message will be written and the database will proceed to start up + anyway. An exception is that if the command was terminated by a + signal or an error by the shell (such as command not found), the + database will not proceed with startup. + </para> + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect2> + + <sect2 id="runtime-config-wal-recovery-target"> + + <title>Recovery Target</title> + + <para> + By default, recovery will recover to the end of the WAL log. The + following parameters can be used to specify an earlier stopping point. + At most one of <varname>recovery_target</varname>, + <varname>recovery_target_lsn</varname>, <varname>recovery_target_name</varname>, + <varname>recovery_target_time</varname>, or <varname>recovery_target_xid</varname> + can be used; if more than one of these is specified in the configuration + file, an error will be raised. + These parameters can only be set at server start. + </para> + + <variablelist> + <varlistentry id="guc-recovery-target" xreflabel="recovery_target"> + <term><varname>recovery_target</varname><literal> = 'immediate'</literal> + <indexterm> + <primary><varname>recovery_target</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies that recovery should end as soon as a + consistent state is reached, i.e., as early as possible. When restoring + from an online backup, this means the point where taking the backup + ended. + </para> + <para> + Technically, this is a string parameter, but <literal>'immediate'</literal> + is currently the only allowed value. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-name" xreflabel="recovery_target_name"> + <term><varname>recovery_target_name</varname> (<type>string</type>) + <indexterm> + <primary><varname>recovery_target_name</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies the named restore point (created with + <function>pg_create_restore_point()</function>) to which recovery will proceed. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-time" xreflabel="recovery_target_time"> + <term><varname>recovery_target_time</varname> (<type>timestamp</type>) + <indexterm> + <primary><varname>recovery_target_time</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies the time stamp up to which recovery + will proceed. + The precise stopping point is also influenced by + <xref linkend="guc-recovery-target-inclusive"/>. + </para> + + <para> + The value of this parameter is a time stamp in the same format + accepted by the <type>timestamp with time zone</type> data type, + except that you cannot use a time zone abbreviation (unless the + <xref linkend="guc-timezone-abbreviations"/> variable has been set + earlier in the configuration file). Preferred style is to use a + numeric offset from UTC, or you can write a full time zone name, + e.g., <literal>Europe/Helsinki</literal> not <literal>EEST</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-xid" xreflabel="recovery_target_xid"> + <term><varname>recovery_target_xid</varname> (<type>string</type>) + <indexterm> + <primary><varname>recovery_target_xid</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies the transaction ID up to which recovery + will proceed. Keep in mind + that while transaction IDs are assigned sequentially at transaction + start, transactions can complete in a different numeric order. + The transactions that will be recovered are those that committed + before (and optionally including) the specified one. + The precise stopping point is also influenced by + <xref linkend="guc-recovery-target-inclusive"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-lsn" xreflabel="recovery_target_lsn"> + <term><varname>recovery_target_lsn</varname> (<type>pg_lsn</type>) + <indexterm> + <primary><varname>recovery_target_lsn</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies the LSN of the write-ahead log location up + to which recovery will proceed. The precise stopping point is also + influenced by <xref linkend="guc-recovery-target-inclusive"/>. This + parameter is parsed using the system data type + <link linkend="datatype-pg-lsn"><type>pg_lsn</type></link>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + The following options further specify the recovery target, and affect + what happens when the target is reached: + </para> + + <variablelist> + <varlistentry id="guc-recovery-target-inclusive" + xreflabel="recovery_target_inclusive"> + <term><varname>recovery_target_inclusive</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>recovery_target_inclusive</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies whether to stop just after the specified recovery target + (<literal>on</literal>), or just before the recovery target + (<literal>off</literal>). + Applies when <xref linkend="guc-recovery-target-lsn"/>, + <xref linkend="guc-recovery-target-time"/>, or + <xref linkend="guc-recovery-target-xid"/> is specified. + This setting controls whether transactions + having exactly the target WAL location (LSN), commit time, or transaction ID, respectively, will + be included in the recovery. Default is <literal>on</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recovery-target-timeline" + xreflabel="recovery_target_timeline"> + <term><varname>recovery_target_timeline</varname> (<type>string</type>) + <indexterm> + <primary><varname>recovery_target_timeline</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies recovering into a particular timeline. The value can be a + numeric timeline ID or a special value. The value + <literal>current</literal> recovers along the same timeline that was + current when the base backup was taken. The + value <literal>latest</literal> recovers + to the latest timeline found in the archive, which is useful in + a standby server. <literal>latest</literal> is the default. + </para> + + <para> + 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 + <link linkend="storage-hot"><acronym>HOT</acronym> updates</link> + 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 number 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> + WAL records must be kept on the standby until they are ready to be + applied. Therefore, longer delays will result in a greater accumulation + of WAL files, increasing disk space requirements for the standby's + <filename>pg_wal</filename> directory. + </para> + <para> + This parameter is intended for use with streaming replication deployments; + however, if the parameter is specified it will be honored in all cases + except crash recovery. + + <varname>hot_standby_feedback</varname> will be delayed by use of this feature + which could lead to bloat on the primary; use both together with care. + + <warning> + <para> + Synchronous replication is affected by this setting when <varname>synchronous_commit</varname> + is set to <literal>remote_apply</literal>; every <literal>COMMIT</literal> + will need to wait to be applied. + </para> + </warning> + </para> + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + </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>integer</type>) + <indexterm> + <primary><varname>max_logical_replication_workers</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies maximum number of logical replication workers. This includes + 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 partitioned + tables to be performed separately for each partition. If the + <literal>GROUP BY</literal> clause does not include the partition + keys, only partial aggregation can be performed on a per-partition + basis, and finalization must be performed later. Because + partitionwise grouping or aggregation can use significantly more CPU + time and memory during planning, the default is + <literal>off</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-enable-seqscan" xreflabel="enable_seqscan"> + <term><varname>enable_seqscan</varname> (<type>boolean</type>) + <indexterm> + <primary>sequential scan</primary> + </indexterm> + <indexterm> + <primary><varname>enable_seqscan</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables or disables the query planner's use of sequential scan + plan types. It is impossible to suppress sequential scans + entirely, but turning this variable off discourages the planner + from using one if there are other methods available. The + default is <literal>on</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-enable-sort" xreflabel="enable_sort"> + <term><varname>enable_sort</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>enable_sort</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables or disables the query planner's use of explicit sort + steps. It is impossible to suppress explicit sorts entirely, + but turning this variable off discourages the planner from + using one if there are other methods available. The default + is <literal>on</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-enable-tidscan" xreflabel="enable_tidscan"> + <term><varname>enable_tidscan</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>enable_tidscan</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables or disables the query planner's use of <acronym>TID</acronym> + scan plan types. The default is <literal>on</literal>. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + <sect2 id="runtime-config-query-constants"> + <title>Planner Cost Constants</title> + + <para> + The <firstterm>cost</firstterm> variables described in this section are measured + on an arbitrary scale. Only their relative values matter, hence + scaling them all up or down by the same factor will result in no change + in the planner's choices. By default, these cost variables are based on + the cost of sequential page fetches; that is, + <varname>seq_page_cost</varname> is conventionally set to <literal>1.0</literal> + and the other cost variables are set with reference to that. But + you can use a different scale if you prefer, such as actual execution + times in milliseconds on a particular machine. + </para> + + <note> + <para> + Unfortunately, there is no well-defined method for determining ideal + values for the cost variables. They are best treated as averages over + the entire mix of queries that a particular installation will receive. This + means that changing them on the basis of just a few experiments is very + risky. + </para> + </note> + + <variablelist> + + <varlistentry id="guc-seq-page-cost" xreflabel="seq_page_cost"> + <term><varname>seq_page_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>seq_page_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's estimate of the cost of a disk page fetch + that is part of a series of sequential fetches. The default is 1.0. + This value can be overridden for tables and indexes in a particular + tablespace by setting the tablespace parameter of the same name + (see <xref linkend="sql-altertablespace"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-random-page-cost" xreflabel="random_page_cost"> + <term><varname>random_page_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>random_page_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's estimate of the cost of a + non-sequentially-fetched disk page. The default is 4.0. + This value can be overridden for tables and indexes in a particular + tablespace by setting the tablespace parameter of the same name + (see <xref linkend="sql-altertablespace"/>). + </para> + + <para> + Reducing this value relative to <varname>seq_page_cost</varname> + will cause the system to prefer index scans; raising it will + make index scans look relatively more expensive. You can raise + or lower both values together to change the importance of disk I/O + costs relative to CPU costs, which are described by the following + parameters. + </para> + + <para> + Random access to mechanical disk storage is normally much more expensive + than four times sequential access. However, a lower default is used + (4.0) because the majority of random accesses to disk, such as indexed + reads, are assumed to be in cache. The default value can be thought of + as modeling random access as 40 times slower than sequential, while + expecting 90% of random reads to be cached. + </para> + + <para> + If you believe a 90% cache rate is an incorrect assumption + for your workload, you can increase random_page_cost to better + reflect the true cost of random storage reads. Correspondingly, + if your data is likely to be completely in cache, such as when + the database is smaller than the total server memory, decreasing + random_page_cost can be appropriate. Storage that has a low random + read cost relative to sequential, e.g., solid-state drives, might + also be better modeled with a lower value for random_page_cost, + e.g., <literal>1.1</literal>. + </para> + + <tip> + <para> + Although the system will let you set <varname>random_page_cost</varname> to + less than <varname>seq_page_cost</varname>, it is not physically sensible + to do so. However, setting them equal makes sense if the database + is entirely cached in RAM, since in that case there is no penalty + for touching pages out of sequence. Also, in a heavily-cached + database you should lower both values relative to the CPU parameters, + since the cost of fetching a page already in RAM is much smaller + than it would normally be. + </para> + </tip> + </listitem> + </varlistentry> + + <varlistentry id="guc-cpu-tuple-cost" xreflabel="cpu_tuple_cost"> + <term><varname>cpu_tuple_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>cpu_tuple_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's estimate of the cost of processing + each row during a query. + The default is 0.01. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-cpu-index-tuple-cost" xreflabel="cpu_index_tuple_cost"> + <term><varname>cpu_index_tuple_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>cpu_index_tuple_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's estimate of the cost of processing + each index entry during an index scan. + The default is 0.005. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-cpu-operator-cost" xreflabel="cpu_operator_cost"> + <term><varname>cpu_operator_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>cpu_operator_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's estimate of the cost of processing each + operator or function executed during a query. + The default is 0.0025. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-parallel-setup-cost" xreflabel="parallel_setup_cost"> + <term><varname>parallel_setup_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>parallel_setup_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's estimate of the cost of launching parallel worker + processes. + The default is 1000. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-parallel-tuple-cost" xreflabel="parallel_tuple_cost"> + <term><varname>parallel_tuple_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>parallel_tuple_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's estimate of the cost of transferring one tuple + from a parallel worker process to another process. + The default is 0.1. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-min-parallel-table-scan-size" xreflabel="min_parallel_table_scan_size"> + <term><varname>min_parallel_table_scan_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>min_parallel_table_scan_size</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the minimum amount of table data that must be scanned in order + for a parallel scan to be considered. For a parallel sequential scan, + the amount of table data scanned is always equal to the size of the + table, but when indexes are used the amount of table data + scanned will normally be less. + If this value is specified without units, it is taken as blocks, + that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. + The default is 8 megabytes (<literal>8MB</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-min-parallel-index-scan-size" xreflabel="min_parallel_index_scan_size"> + <term><varname>min_parallel_index_scan_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>min_parallel_index_scan_size</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the minimum amount of index data that must be scanned in order + for a parallel scan to be considered. Note that a parallel index scan + typically won't touch the entire index; it is the number of pages + which the planner believes will actually be touched by the scan which + is relevant. This parameter is also used to decide whether a + particular index can participate in a parallel vacuum. See + <xref linkend="sql-vacuum"/>. + If this value is specified without units, it is taken as blocks, + that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. + The default is 512 kilobytes (<literal>512kB</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-effective-cache-size" xreflabel="effective_cache_size"> + <term><varname>effective_cache_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>effective_cache_size</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's assumption about the effective size of the + disk cache that is available to a single query. This is + factored into estimates of the cost of using an index; a + higher value makes it more likely index scans will be used, a + lower value makes it more likely sequential scans will be + used. When setting this parameter you should consider both + <productname>PostgreSQL</productname>'s shared buffers and the + portion of the kernel's disk cache that will be used for + <productname>PostgreSQL</productname> data files, though some + data might exist in both places. Also, take + into account the expected number of concurrent queries on different + tables, since they will have to share the available + space. This parameter has no effect on the size of shared + memory allocated by <productname>PostgreSQL</productname>, nor + does it reserve kernel disk cache; it is used only for estimation + purposes. The system also does not assume data remains in + the disk cache between queries. + If this value is specified without units, it is taken as blocks, + that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. + The default is 4 gigabytes (<literal>4GB</literal>). + (If <symbol>BLCKSZ</symbol> is not 8kB, the default value scales + proportionally to it.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit-above-cost" xreflabel="jit_above_cost"> + <term><varname>jit_above_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>jit_above_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the query cost above which JIT compilation is activated, if + enabled (see <xref linkend="jit"/>). + Performing <acronym>JIT</acronym> costs planning time but can + accelerate query execution. + Setting this to <literal>-1</literal> disables JIT compilation. + The default is <literal>100000</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit-inline-above-cost" xreflabel="jit_inline_above_cost"> + <term><varname>jit_inline_above_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>jit_inline_above_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the query cost above which JIT compilation attempts to inline + functions and operators. Inlining adds planning time, but can + improve execution speed. It is not meaningful to set this to less + than <varname>jit_above_cost</varname>. + Setting this to <literal>-1</literal> disables inlining. + The default is <literal>500000</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit-optimize-above-cost" xreflabel="jit_optimize_above_cost"> + <term><varname>jit_optimize_above_cost</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>jit_optimize_above_cost</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the query cost above which JIT compilation applies expensive + optimizations. Such optimization adds planning time, but can improve + execution speed. It is not meaningful to set this to less + than <varname>jit_above_cost</varname>, and it is unlikely to be + beneficial to set it to more + than <varname>jit_inline_above_cost</varname>. + Setting this to <literal>-1</literal> disables expensive optimizations. + The default is <literal>500000</literal>. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect2> + <sect2 id="runtime-config-query-geqo"> + <title>Genetic Query Optimizer</title> + + <para> + The genetic query optimizer (GEQO) is an algorithm that does query + planning using heuristic searching. This reduces planning time for + complex queries (those joining many relations), at the cost of producing + plans that are sometimes inferior to those found by the normal + exhaustive-search algorithm. + For more information see <xref linkend="geqo"/>. + </para> + + <variablelist> + + <varlistentry id="guc-geqo" xreflabel="geqo"> + <term><varname>geqo</varname> (<type>boolean</type>) + <indexterm> + <primary>genetic query optimization</primary> + </indexterm> + <indexterm> + <primary>GEQO</primary> + <see>genetic query optimization</see> + </indexterm> + <indexterm> + <primary><varname>geqo</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables or disables genetic query optimization. + This is on by default. It is usually best not to turn it off in + production; the <varname>geqo_threshold</varname> variable provides + more granular control of GEQO. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-geqo-threshold" xreflabel="geqo_threshold"> + <term><varname>geqo_threshold</varname> (<type>integer</type>) + <indexterm> + <primary><varname>geqo_threshold</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Use genetic query optimization to plan queries with at least + this many <literal>FROM</literal> items involved. (Note that a + <literal>FULL OUTER JOIN</literal> construct counts as only one <literal>FROM</literal> + item.) The default is 12. For simpler queries it is usually best + to use the regular, exhaustive-search planner, but for queries with + many tables the exhaustive search takes too long, often + longer than the penalty of executing a suboptimal plan. Thus, + a threshold on the size of the query is a convenient way to manage + use of GEQO. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-geqo-effort" xreflabel="geqo_effort"> + <term><varname>geqo_effort</varname> (<type>integer</type>) + <indexterm> + <primary><varname>geqo_effort</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls the trade-off between planning time and query plan + quality in GEQO. This variable must be an integer in the + range from 1 to 10. The default value is five. Larger values + increase the time spent doing query planning, but also + increase the likelihood that an efficient query plan will be + chosen. + </para> + + <para> + <varname>geqo_effort</varname> doesn't actually do anything + directly; it is only used to compute the default values for + the other variables that influence GEQO behavior (described + below). If you prefer, you can set the other parameters by + hand instead. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-geqo-pool-size" xreflabel="geqo_pool_size"> + <term><varname>geqo_pool_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>geqo_pool_size</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls the pool size used by GEQO, that is the + number of individuals in the genetic population. It must be + at least two, and useful values are typically 100 to 1000. If + it is set to zero (the default setting) then a suitable + value is chosen based on <varname>geqo_effort</varname> and + the number of tables in the query. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-geqo-generations" xreflabel="geqo_generations"> + <term><varname>geqo_generations</varname> (<type>integer</type>) + <indexterm> + <primary><varname>geqo_generations</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls the number of generations used by GEQO, that is + the number of iterations of the algorithm. It must + be at least one, and useful values are in the same range as + the pool size. If it is set to zero (the default setting) + then a suitable value is chosen based on + <varname>geqo_pool_size</varname>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-geqo-selection-bias" xreflabel="geqo_selection_bias"> + <term><varname>geqo_selection_bias</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>geqo_selection_bias</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls the selection bias used by GEQO. The selection bias + is the selective pressure within the population. Values can be + from 1.50 to 2.00; the latter is the default. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-geqo-seed" xreflabel="geqo_seed"> + <term><varname>geqo_seed</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>geqo_seed</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls the initial value of the random number generator used + by GEQO to select random paths through the join order search space. + The value can range from zero (the default) to one. Varying the + value changes the set of join paths explored, and may result in a + better or worse best path being found. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + <sect2 id="runtime-config-query-other"> + <title>Other Planner Options</title> + + <variablelist> + + <varlistentry id="guc-default-statistics-target" xreflabel="default_statistics_target"> + <term><varname>default_statistics_target</varname> (<type>integer</type>) + <indexterm> + <primary><varname>default_statistics_target</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the default statistics target for table columns without + a column-specific target set via <command>ALTER TABLE + SET STATISTICS</command>. Larger values increase the time needed to + do <command>ANALYZE</command>, but might improve the quality of the + planner's estimates. The default is 100. For more information + on the use of statistics by the <productname>PostgreSQL</productname> + query planner, refer to <xref linkend="planner-stats"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-constraint-exclusion" xreflabel="constraint_exclusion"> + <term><varname>constraint_exclusion</varname> (<type>enum</type>) + <indexterm> + <primary>constraint exclusion</primary> + </indexterm> + <indexterm> + <primary><varname>constraint_exclusion</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls the query planner's use of table constraints to + optimize queries. + The allowed values of <varname>constraint_exclusion</varname> are + <literal>on</literal> (examine constraints for all tables), + <literal>off</literal> (never examine constraints), and + <literal>partition</literal> (examine constraints only for inheritance + child tables and <literal>UNION ALL</literal> subqueries). + <literal>partition</literal> is the default setting. + It is often used with traditional inheritance trees to improve + performance. + </para> + + <para> + When this parameter allows it for a particular table, the planner + compares query conditions with the table's <literal>CHECK</literal> + constraints, and omits scanning tables for which the conditions + contradict the constraints. For example: + +<programlisting> +CREATE TABLE parent(key integer, ...); +CREATE TABLE child1000(check (key between 1000 and 1999)) INHERITS(parent); +CREATE TABLE child2000(check (key between 2000 and 2999)) INHERITS(parent); +... +SELECT * FROM parent WHERE key = 2400; +</programlisting> + + With constraint exclusion enabled, this <command>SELECT</command> + will not scan <structname>child1000</structname> at all, improving performance. + </para> + + <para> + Currently, constraint exclusion is enabled by default + only for cases that are often used to implement table partitioning via + inheritance trees. Turning it on for all tables imposes extra + planning overhead that is quite noticeable on simple queries, and most + often will yield no benefit for simple queries. If you have no + tables that are partitioned using traditional inheritance, you might + prefer to turn it off entirely. (Note that the equivalent feature for + partitioned tables is controlled by a separate parameter, + <xref linkend="guc-enable-partition-pruning"/>.) + </para> + + <para> + Refer to <xref linkend="ddl-partitioning-constraint-exclusion"/> for + more information on using constraint exclusion to implement + partitioning. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-cursor-tuple-fraction" xreflabel="cursor_tuple_fraction"> + <term><varname>cursor_tuple_fraction</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>cursor_tuple_fraction</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's estimate of the fraction of a cursor's rows that + will be retrieved. The default is 0.1. Smaller values of this + setting bias the planner towards using <quote>fast start</quote> plans + for cursors, which will retrieve the first few rows quickly while + perhaps taking a long time to fetch all rows. Larger values + put more emphasis on the total estimated time. At the maximum + setting of 1.0, cursors are planned exactly like regular queries, + considering only the total estimated time and not how soon the + first rows might be delivered. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-from-collapse-limit" xreflabel="from_collapse_limit"> + <term><varname>from_collapse_limit</varname> (<type>integer</type>) + <indexterm> + <primary><varname>from_collapse_limit</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The planner will merge sub-queries into upper queries if the + resulting <literal>FROM</literal> list would have no more than + this many items. Smaller values reduce planning time but might + yield inferior query plans. The default is eight. + For more information see <xref linkend="explicit-joins"/>. + </para> + + <para> + Setting this value to <xref linkend="guc-geqo-threshold"/> or more + may trigger use of the GEQO planner, resulting in non-optimal + plans. See <xref linkend="runtime-config-query-geqo"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit" xreflabel="jit"> + <term><varname>jit</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>jit</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Determines whether <acronym>JIT</acronym> compilation may be used by + <productname>PostgreSQL</productname>, if available (see <xref + linkend="jit"/>). + The default is <literal>on</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-join-collapse-limit" xreflabel="join_collapse_limit"> + <term><varname>join_collapse_limit</varname> (<type>integer</type>) + <indexterm> + <primary><varname>join_collapse_limit</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The planner will rewrite explicit <literal>JOIN</literal> + constructs (except <literal>FULL JOIN</literal>s) into lists of + <literal>FROM</literal> items whenever a list of no more than this many items + would result. Smaller values reduce planning time but might + yield inferior query plans. + </para> + + <para> + By default, this variable is set the same as + <varname>from_collapse_limit</varname>, which is appropriate + for most uses. Setting it to 1 prevents any reordering of + explicit <literal>JOIN</literal>s. Thus, the explicit join order + specified in the query will be the actual order in which the + relations are joined. Because the query planner does not always choose + the optimal join order, advanced users can elect to + temporarily set this variable to 1, and then specify the join + order they desire explicitly. + For more information see <xref linkend="explicit-joins"/>. + </para> + + <para> + Setting this value to <xref linkend="guc-geqo-threshold"/> or more + may trigger use of the GEQO planner, resulting in non-optimal + plans. See <xref linkend="runtime-config-query-geqo"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-plan-cache_mode" xreflabel="plan_cache_mode"> + <term><varname>plan_cache_mode</varname> (<type>enum</type>) + <indexterm> + <primary><varname>plan_cache_mode</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Prepared statements (either explicitly prepared or implicitly + generated, for example by PL/pgSQL) can be executed using custom or + generic plans. Custom plans are made afresh for each execution + using its specific set of parameter values, while generic plans do + not rely on the parameter values and can be re-used across + executions. Thus, use of a generic plan saves planning time, but if + the ideal plan depends strongly on the parameter values then a + generic plan may be inefficient. The choice between these options + is normally made automatically, but it can be overridden + with <varname>plan_cache_mode</varname>. + The allowed values are <literal>auto</literal> (the default), + <literal>force_custom_plan</literal> and + <literal>force_generic_plan</literal>. + This setting is considered when a cached plan is to be executed, + not when it is prepared. + For more information see <xref linkend="sql-prepare"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-recursive-worktable-factor" xreflabel="recursive_worktable_factor"> + <term><varname>recursive_worktable_factor</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>recursive_worktable_factor</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the planner's estimate of the average size of the working + table of a <link linkend="queries-with-recursive">recursive + query</link>, as a multiple of the estimated size of the initial + non-recursive term of the query. This helps the planner choose + the most appropriate method for joining the working table to the + query's other tables. + The default value is <literal>10.0</literal>. A smaller value + such as <literal>1.0</literal> can be helpful when the recursion + has low <quote>fan-out</quote> from one step to the next, as for + example in shortest-path queries. Graph analytics queries may + benefit from larger-than-default values. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + </sect1> + + <sect1 id="runtime-config-logging"> + <title>Error Reporting and Logging</title> + + <indexterm zone="runtime-config-logging"> + <primary>server log</primary> + </indexterm> + + <sect2 id="runtime-config-logging-where"> + <title>Where to Log</title> + + <indexterm zone="runtime-config-logging-where"> + <primary>where to log</primary> + </indexterm> + + <indexterm> + <primary>current_logfiles</primary> + <secondary>and the log_destination configuration parameter</secondary> + </indexterm> + + <variablelist> + + <varlistentry id="guc-log-destination" xreflabel="log_destination"> + <term><varname>log_destination</varname> (<type>string</type>) + <indexterm> + <primary><varname>log_destination</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + <productname>PostgreSQL</productname> supports several methods + for logging server messages, including + <systemitem>stderr</systemitem>, <systemitem>csvlog</systemitem>, + <systemitem>jsonlog</systemitem>, and + <systemitem>syslog</systemitem>. On Windows, + <systemitem>eventlog</systemitem> is also supported. Set this + parameter to a list of desired log destinations separated by + commas. The default is to log to <systemitem>stderr</systemitem> + only. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + <para> + If <systemitem>csvlog</systemitem> is included in <varname>log_destination</varname>, + log entries are output in <quote>comma separated + value</quote> (<acronym>CSV</acronym>) format, which is convenient for + loading logs into programs. + See <xref linkend="runtime-config-logging-csvlog"/> for details. + <xref linkend="guc-logging-collector"/> must be enabled to generate + CSV-format log output. + </para> + <para> + If <systemitem>jsonlog</systemitem> is included in + <varname>log_destination</varname>, log entries are output in + <acronym>JSON</acronym> format, which is convenient for loading logs + into programs. + See <xref linkend="runtime-config-logging-jsonlog"/> for details. + <xref linkend="guc-logging-collector"/> must be enabled to generate + JSON-format log output. + </para> + <para> + When either <systemitem>stderr</systemitem>, + <systemitem>csvlog</systemitem> or <systemitem>jsonlog</systemitem> are + included, the file <filename>current_logfiles</filename> is created to + record the location of the log file(s) currently in use by the logging + collector and the associated logging destination. This provides a + convenient way to find the logs currently in use by the instance. Here + is an example of this file's content: +<programlisting> +stderr log/postgresql.log +csvlog log/postgresql.csv +jsonlog log/postgresql.json +</programlisting> + + <filename>current_logfiles</filename> is recreated when a new log file + is created as an effect of rotation, and + when <varname>log_destination</varname> is reloaded. It is removed when + none of <systemitem>stderr</systemitem>, + <systemitem>csvlog</systemitem> or <systemitem>jsonlog</systemitem> are + included in <varname>log_destination</varname>, and when the logging + collector is disabled. + </para> + + <note> + <para> + On most Unix systems, you will need to alter the configuration of + your system's <application>syslog</application> daemon in order + to make use of the <systemitem>syslog</systemitem> option for + <varname>log_destination</varname>. <productname>PostgreSQL</productname> + can log to <application>syslog</application> facilities + <literal>LOCAL0</literal> through <literal>LOCAL7</literal> (see <xref + linkend="guc-syslog-facility"/>), but the default + <application>syslog</application> configuration on most platforms + will discard all such messages. You will need to add something like: +<programlisting> +local0.* /var/log/postgresql +</programlisting> + to the <application>syslog</application> daemon's configuration file + to make it work. + </para> + <para> + On Windows, when you use the <literal>eventlog</literal> + option for <varname>log_destination</varname>, you should + register an event source and its library with the operating + system so that the Windows Event Viewer can display event + log messages cleanly. + See <xref linkend="event-log-registration"/> for details. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="guc-logging-collector" xreflabel="logging_collector"> + <term><varname>logging_collector</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>logging_collector</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter enables the <firstterm>logging collector</firstterm>, which + is a background process that captures log messages + sent to <systemitem>stderr</systemitem> and redirects them into log files. + This approach is often more useful than + logging to <application>syslog</application>, since some types of messages + might not appear in <application>syslog</application> output. (One common + example is dynamic-linker failure messages; another is error messages + produced by scripts such as <varname>archive_command</varname>.) + This parameter can only be set at server start. + </para> + + <note> + <para> + It is possible to log to <systemitem>stderr</systemitem> without using the + logging collector; the log messages will just go to wherever the + server's <systemitem>stderr</systemitem> is directed. However, that method is + only suitable for low log volumes, since it provides no convenient + way to rotate log files. Also, on some platforms not using the + logging collector can result in lost or garbled log output, because + multiple processes writing concurrently to the same log file can + overwrite each other's output. + </para> + </note> + + <note> + <para> + The logging collector is designed to never lose messages. This means + that in case of extremely high load, server processes could be + blocked while trying to send additional log messages when the + collector has fallen behind. In contrast, <application>syslog</application> + prefers to drop messages if it cannot write them, which means it + may fail to log some messages in such cases but it will not block + the rest of the system. + </para> + </note> + + </listitem> + </varlistentry> + + <varlistentry id="guc-log-directory" xreflabel="log_directory"> + <term><varname>log_directory</varname> (<type>string</type>) + <indexterm> + <primary><varname>log_directory</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When <varname>logging_collector</varname> is enabled, + this parameter determines the directory in which log files will be created. + It can be specified as an absolute path, or relative to the + cluster data directory. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + The default is <literal>log</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-filename" xreflabel="log_filename"> + <term><varname>log_filename</varname> (<type>string</type>) + <indexterm> + <primary><varname>log_filename</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When <varname>logging_collector</varname> is enabled, + this parameter sets the file names of the created log files. The value + is treated as a <function>strftime</function> pattern, + so <literal>%</literal>-escapes can be used to specify time-varying + file names. (Note that if there are + any time-zone-dependent <literal>%</literal>-escapes, the computation + is done in the zone specified + by <xref linkend="guc-log-timezone"/>.) + The supported <literal>%</literal>-escapes are similar to those + listed in the Open Group's <ulink + url="https://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html">strftime + </ulink> specification. + Note that the system's <function>strftime</function> is not used + directly, so platform-specific (nonstandard) extensions do not work. + The default is <literal>postgresql-%Y-%m-%d_%H%M%S.log</literal>. + </para> + <para> + If you specify a file name without escapes, you should plan to + use a log rotation utility to avoid eventually filling the + entire disk. In releases prior to 8.4, if + no <literal>%</literal> escapes were + present, <productname>PostgreSQL</productname> would append + the epoch of the new log file's creation time, but this is no + longer the case. + </para> + <para> + If CSV-format output is enabled in <varname>log_destination</varname>, + <literal>.csv</literal> will be appended to the timestamped + log file name to create the file name for CSV-format output. + (If <varname>log_filename</varname> ends in <literal>.log</literal>, the suffix is + replaced instead.) + </para> + <para> + If JSON-format output is enabled in <varname>log_destination</varname>, + <literal>.json</literal> will be appended to the timestamped + log file name to create the file name for JSON-format output. + (If <varname>log_filename</varname> ends in <literal>.log</literal>, the suffix is + replaced instead.) + </para> + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-file-mode" xreflabel="log_file_mode"> + <term><varname>log_file_mode</varname> (<type>integer</type>) + <indexterm> + <primary><varname>log_file_mode</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + On Unix systems this parameter sets the permissions for log files + when <varname>logging_collector</varname> is enabled. (On Microsoft + Windows this parameter is ignored.) + The parameter value is expected to be a numeric mode + specified in the format accepted by the + <function>chmod</function> and <function>umask</function> + system calls. (To use the customary octal format the number + must start with a <literal>0</literal> (zero).) + </para> + <para> + The default permissions are <literal>0600</literal>, meaning only the + server owner can read or write the log files. The other commonly + useful setting is <literal>0640</literal>, allowing members of the owner's + group to read the files. Note however that to make use of such a + setting, you'll need to alter <xref linkend="guc-log-directory"/> to + store the files somewhere outside the cluster data directory. In + any case, it's unwise to make the log files world-readable, since + they might contain sensitive data. + </para> + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-rotation-age" xreflabel="log_rotation_age"> + <term><varname>log_rotation_age</varname> (<type>integer</type>) + <indexterm> + <primary><varname>log_rotation_age</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When <varname>logging_collector</varname> is enabled, + this parameter determines the maximum amount of time to use an + individual log file, after which a new log file will be created. + If this value is specified without units, it is taken as minutes. + The default is 24 hours. + Set to zero to disable time-based creation of new log files. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-rotation-size" xreflabel="log_rotation_size"> + <term><varname>log_rotation_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>log_rotation_size</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When <varname>logging_collector</varname> is enabled, + this parameter determines the maximum size of an individual log file. + After this amount of data has been emitted into a log file, + a new log file will be created. + If this value is specified without units, it is taken as kilobytes. + The default is 10 megabytes. + Set to zero to disable size-based creation of new log files. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-truncate-on-rotation" xreflabel="log_truncate_on_rotation"> + <term><varname>log_truncate_on_rotation</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_truncate_on_rotation</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When <varname>logging_collector</varname> is enabled, + this parameter will cause <productname>PostgreSQL</productname> to truncate (overwrite), + rather than append to, any existing log file of the same name. + However, truncation will occur only when a new file is being opened + due to time-based rotation, not during server startup or size-based + rotation. When off, pre-existing files will be appended to in + all cases. For example, using this setting in combination with + a <varname>log_filename</varname> like <literal>postgresql-%H.log</literal> + would result in generating twenty-four hourly log files and then + cyclically overwriting them. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + <para> + Example: To keep 7 days of logs, one log file per day named + <literal>server_log.Mon</literal>, <literal>server_log.Tue</literal>, + etc., and automatically overwrite last week's log with this week's log, + set <varname>log_filename</varname> to <literal>server_log.%a</literal>, + <varname>log_truncate_on_rotation</varname> to <literal>on</literal>, and + <varname>log_rotation_age</varname> to <literal>1440</literal>. + </para> + <para> + Example: To keep 24 hours of logs, one log file per hour, but + also rotate sooner if the log file size exceeds 1GB, set + <varname>log_filename</varname> to <literal>server_log.%H%M</literal>, + <varname>log_truncate_on_rotation</varname> to <literal>on</literal>, + <varname>log_rotation_age</varname> to <literal>60</literal>, and + <varname>log_rotation_size</varname> to <literal>1000000</literal>. + Including <literal>%M</literal> in <varname>log_filename</varname> allows + any size-driven rotations that might occur to select a file name + different from the hour's initial file name. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-syslog-facility" xreflabel="syslog_facility"> + <term><varname>syslog_facility</varname> (<type>enum</type>) + <indexterm> + <primary><varname>syslog_facility</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When logging to <application>syslog</application> is enabled, this parameter + determines the <application>syslog</application> + <quote>facility</quote> to be used. You can choose + from <literal>LOCAL0</literal>, <literal>LOCAL1</literal>, + <literal>LOCAL2</literal>, <literal>LOCAL3</literal>, <literal>LOCAL4</literal>, + <literal>LOCAL5</literal>, <literal>LOCAL6</literal>, <literal>LOCAL7</literal>; + the default is <literal>LOCAL0</literal>. See also the + documentation of your system's + <application>syslog</application> daemon. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-syslog-ident" xreflabel="syslog_ident"> + <term><varname>syslog_ident</varname> (<type>string</type>) + <indexterm> + <primary><varname>syslog_ident</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When logging to <application>syslog</application> is enabled, this parameter + determines the program name used to identify + <productname>PostgreSQL</productname> messages in + <application>syslog</application> logs. The default is + <literal>postgres</literal>. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-syslog-sequence-numbers" xreflabel="syslog_sequence_numbers"> + <term><varname>syslog_sequence_numbers</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>syslog_sequence_numbers</varname> configuration parameter</primary> + </indexterm> + </term> + + <listitem> + <para> + When logging to <application>syslog</application> and this is on (the + default), then each message will be prefixed by an increasing + sequence number (such as <literal>[2]</literal>). This circumvents + the <quote>--- last message repeated N times ---</quote> suppression + that many syslog implementations perform by default. In more modern + syslog implementations, repeated message suppression can be configured + (for example, <literal>$RepeatedMsgReduction</literal> + in <productname>rsyslog</productname>), so this might not be + necessary. Also, you could turn this off if you actually want to + suppress repeated messages. + </para> + + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-syslog-split-messages" xreflabel="syslog_split_messages"> + <term><varname>syslog_split_messages</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>syslog_split_messages</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When logging to <application>syslog</application> is enabled, this parameter + determines how messages are delivered to syslog. When on (the + default), messages are split by lines, and long lines are split so + that they will fit into 1024 bytes, which is a typical size limit for + traditional syslog implementations. When off, PostgreSQL server log + messages are delivered to the syslog service as is, and it is up to + the syslog service to cope with the potentially bulky messages. + </para> + + <para> + If syslog is ultimately logging to a text file, then the effect will + be the same either way, and it is best to leave the setting on, since + most syslog implementations either cannot handle large messages or + would need to be specially configured to handle them. But if syslog + is ultimately writing into some other medium, it might be necessary or + more useful to keep messages logically together. + </para> + + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-event-source" xreflabel="event_source"> + <term><varname>event_source</varname> (<type>string</type>) + <indexterm> + <primary><varname>event_source</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When logging to <application>event log</application> is enabled, this parameter + determines the program name used to identify + <productname>PostgreSQL</productname> messages in + the log. The default is <literal>PostgreSQL</literal>. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + <sect2 id="runtime-config-logging-when"> + <title>When to Log</title> + + <variablelist> + + <varlistentry id="guc-log-min-messages" xreflabel="log_min_messages"> + <term><varname>log_min_messages</varname> (<type>enum</type>) + <indexterm> + <primary><varname>log_min_messages</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls which <link linkend="runtime-config-severity-levels">message + levels</link> are written to the server log. + Valid values are <literal>DEBUG5</literal>, <literal>DEBUG4</literal>, + <literal>DEBUG3</literal>, <literal>DEBUG2</literal>, <literal>DEBUG1</literal>, + <literal>INFO</literal>, <literal>NOTICE</literal>, <literal>WARNING</literal>, + <literal>ERROR</literal>, <literal>LOG</literal>, <literal>FATAL</literal>, and + <literal>PANIC</literal>. Each level includes all the levels that + follow it. The later the level, the fewer messages are sent + to the log. The default is <literal>WARNING</literal>. Note that + <literal>LOG</literal> has a different rank here than in + <xref linkend="guc-client-min-messages"/>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-min-error-statement" xreflabel="log_min_error_statement"> + <term><varname>log_min_error_statement</varname> (<type>enum</type>) + <indexterm> + <primary><varname>log_min_error_statement</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls which SQL statements that cause an error + condition are recorded in the server log. The current + SQL statement is included in the log entry for any message of + the specified + <link linkend="runtime-config-severity-levels">severity</link> + or higher. + Valid values are <literal>DEBUG5</literal>, + <literal>DEBUG4</literal>, <literal>DEBUG3</literal>, + <literal>DEBUG2</literal>, <literal>DEBUG1</literal>, + <literal>INFO</literal>, <literal>NOTICE</literal>, + <literal>WARNING</literal>, <literal>ERROR</literal>, + <literal>LOG</literal>, + <literal>FATAL</literal>, and <literal>PANIC</literal>. + The default is <literal>ERROR</literal>, which means statements + causing errors, log messages, fatal errors, or panics will be logged. + To effectively turn off logging of failing statements, + set this parameter to <literal>PANIC</literal>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-min-duration-statement" xreflabel="log_min_duration_statement"> + <term><varname>log_min_duration_statement</varname> (<type>integer</type>) + <indexterm> + <primary><varname>log_min_duration_statement</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Causes the duration of each completed statement to be logged + if the statement ran for at least the specified amount of time. + For example, if you set it to <literal>250ms</literal> + then all SQL statements that run 250ms or longer will be + logged. Enabling this parameter can be helpful in tracking down + unoptimized queries in your applications. + If this value is specified without units, it is taken as milliseconds. + Setting this to zero prints all statement durations. + <literal>-1</literal> (the default) disables logging statement + durations. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <para> + This overrides <xref linkend="guc-log-min-duration-sample"/>, + meaning that queries with duration exceeding this setting are not + subject to sampling and are always logged. + </para> + + <para> + For clients using extended query protocol, durations of the Parse, + Bind, and Execute steps are logged independently. + </para> + + <note> + <para> + When using this option together with + <xref linkend="guc-log-statement"/>, + the text of statements that are logged because of + <varname>log_statement</varname> will not be repeated in the + duration log message. + If you are not using <application>syslog</application>, it is recommended + that you log the PID or session ID using + <xref linkend="guc-log-line-prefix"/> + so that you can link the statement message to the later + duration message using the process ID or session ID. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-min-duration-sample" xreflabel="log_min_duration_sample"> + <term><varname>log_min_duration_sample</varname> (<type>integer</type>) + <indexterm> + <primary><varname>log_min_duration_sample</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Allows sampling the duration of completed statements that ran for + at least the specified amount of time. This produces the same + kind of log entries as + <xref linkend="guc-log-min-duration-statement"/>, but only for a + subset of the executed statements, with sample rate controlled by + <xref linkend="guc-log-statement-sample-rate"/>. + For example, if you set it to <literal>100ms</literal> then all + SQL statements that run 100ms or longer will be considered for + sampling. Enabling this parameter can be helpful when the + traffic is too high to log all queries. + If this value is specified without units, it is taken as milliseconds. + Setting this to zero samples all statement durations. + <literal>-1</literal> (the default) disables sampling statement + durations. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <para> + This setting has lower priority + than <varname>log_min_duration_statement</varname>, meaning that + statements with durations + exceeding <varname>log_min_duration_statement</varname> are not + subject to sampling and are always logged. + </para> + + <para> + Other notes for <varname>log_min_duration_statement</varname> + apply also to this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-statement-sample-rate" xreflabel="log_statement_sample_rate"> + <term><varname>log_statement_sample_rate</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>log_statement_sample_rate</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Determines the fraction of statements with duration exceeding + <xref linkend="guc-log-min-duration-sample"/> that will be logged. + Sampling is stochastic, for example <literal>0.5</literal> means + there is statistically one chance in two that any given statement + will be logged. + The default is <literal>1.0</literal>, meaning to log all sampled + statements. + Setting this to zero disables sampled statement-duration logging, + the same as setting + <varname>log_min_duration_sample</varname> to + <literal>-1</literal>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-transaction-sample-rate" xreflabel="log_transaction_sample_rate"> + <term><varname>log_transaction_sample_rate</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>log_transaction_sample_rate</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the fraction of transactions whose statements are all logged, + in addition to statements logged for other reasons. It applies to + each new transaction regardless of its statements' durations. + Sampling is stochastic, for example <literal>0.1</literal> means + there is statistically one chance in ten that any given transaction + will be logged. + <varname>log_transaction_sample_rate</varname> can be helpful to + construct a sample of transactions. + The default is <literal>0</literal>, meaning not to log + statements from any additional transactions. Setting this + to <literal>1</literal> logs all statements of all transactions. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + <note> + <para> + Like all statement-logging options, this option can add significant + overhead. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-startup-progress-interval" xreflabel="log_startup_progress_interval"> + <term><varname>log_startup_progress_interval</varname> (<type>integer</type>) + <indexterm> + <primary><varname>log_startup_progress_interval</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the amount of time after which the startup process will log + a message about a long-running operation that is still in progress, + as well as the interval between further progress messages for that + operation. The default is 10 seconds. A setting of <literal>0</literal> + disables the feature. If this value is specified without units, + it is taken as milliseconds. This setting is applied separately to + each operation. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + + <para> + For example, if syncing the data directory takes 25 seconds and + thereafter resetting unlogged relations takes 8 seconds, and if this + setting has the default value of 10 seconds, then a messages will be + logged for syncing the data directory after it has been in progress + for 10 seconds and again after it has been in progress for 20 seconds, + but nothing will be logged for resetting unlogged relations. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + <xref linkend="runtime-config-severity-levels"/> explains the message + severity levels used by <productname>PostgreSQL</productname>. If logging output + is sent to <systemitem>syslog</systemitem> or Windows' + <systemitem>eventlog</systemitem>, the severity levels are translated + as shown in the table. + </para> + + <table id="runtime-config-severity-levels"> + <title>Message Severity Levels</title> + <tgroup cols="4"> + <colspec colname="col1" colwidth="1*"/> + <colspec colname="col2" colwidth="2*"/> + <colspec colname="col3" colwidth="1*"/> + <colspec colname="col4" colwidth="1*"/> + <thead> + <row> + <entry>Severity</entry> + <entry>Usage</entry> + <entry><systemitem>syslog</systemitem></entry> + <entry><systemitem>eventlog</systemitem></entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>DEBUG1 .. DEBUG5</literal></entry> + <entry>Provides successively-more-detailed information for use by + developers.</entry> + <entry><literal>DEBUG</literal></entry> + <entry><literal>INFORMATION</literal></entry> + </row> + + <row> + <entry><literal>INFO</literal></entry> + <entry>Provides information implicitly requested by the user, + e.g., output from <command>VACUUM VERBOSE</command>.</entry> + <entry><literal>INFO</literal></entry> + <entry><literal>INFORMATION</literal></entry> + </row> + + <row> + <entry><literal>NOTICE</literal></entry> + <entry>Provides information that might be helpful to users, e.g., + notice of truncation of long identifiers.</entry> + <entry><literal>NOTICE</literal></entry> + <entry><literal>INFORMATION</literal></entry> + </row> + + <row> + <entry><literal>WARNING</literal></entry> + <entry>Provides warnings of likely problems, e.g., <command>COMMIT</command> + outside a transaction block.</entry> + <entry><literal>NOTICE</literal></entry> + <entry><literal>WARNING</literal></entry> + </row> + + <row> + <entry><literal>ERROR</literal></entry> + <entry>Reports an error that caused the current command to + abort.</entry> + <entry><literal>WARNING</literal></entry> + <entry><literal>ERROR</literal></entry> + </row> + + <row> + <entry><literal>LOG</literal></entry> + <entry>Reports information of interest to administrators, e.g., + checkpoint activity.</entry> + <entry><literal>INFO</literal></entry> + <entry><literal>INFORMATION</literal></entry> + </row> + + <row> + <entry><literal>FATAL</literal></entry> + <entry>Reports an error that caused the current session to + abort.</entry> + <entry><literal>ERR</literal></entry> + <entry><literal>ERROR</literal></entry> + </row> + + <row> + <entry><literal>PANIC</literal></entry> + <entry>Reports an error that caused all database sessions to abort.</entry> + <entry><literal>CRIT</literal></entry> + <entry><literal>ERROR</literal></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + <sect2 id="runtime-config-logging-what"> + <title>What to Log</title> + + <note> + <para> + What you choose to log can have security implications; see + <xref linkend="logfile-maintenance"/>. + </para> + </note> + + <variablelist> + + <varlistentry id="guc-application-name" xreflabel="application_name"> + <term><varname>application_name</varname> (<type>string</type>) + <indexterm> + <primary><varname>application_name</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The <varname>application_name</varname> can be any string of less than + <symbol>NAMEDATALEN</symbol> characters (64 characters in a standard build). + It is typically set by an application upon connection to the server. + The name will be displayed in the <structname>pg_stat_activity</structname> view + and included in CSV log entries. It can also be included in regular + log entries via the <xref linkend="guc-log-line-prefix"/> parameter. + Only printable ASCII characters may be used in the + <varname>application_name</varname> value. Other characters 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 and users with the appropriate <literal>SET</literal> + privilege can change this parameter at session start, + and it cannot be changed at all within a session. + The default is <literal>off</literal>. + </para> + + <note> + <para> + Some client programs, like <application>psql</application>, attempt + to connect twice while determining if a password is required, so + duplicate <quote>connection received</quote> messages do not + necessarily indicate a problem. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-disconnections" xreflabel="log_disconnections"> + <term><varname>log_disconnections</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_disconnections</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Causes session terminations to be logged. The log output + provides information similar to <varname>log_connections</varname>, + plus the duration of the session. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this parameter at session start, + and it cannot be changed at all within a session. + The default is <literal>off</literal>. + </para> + </listitem> + </varlistentry> + + + <varlistentry id="guc-log-duration" xreflabel="log_duration"> + <term><varname>log_duration</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_duration</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Causes the duration of every completed statement to be logged. + The default is <literal>off</literal>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <para> + For clients using extended query protocol, durations of the Parse, + Bind, and Execute steps are logged independently. + </para> + + <note> + <para> + The difference between enabling <varname>log_duration</varname> and setting + <xref linkend="guc-log-min-duration-statement"/> to zero is that + exceeding <varname>log_min_duration_statement</varname> forces the text of + the query to be logged, but this option doesn't. Thus, if + <varname>log_duration</varname> is <literal>on</literal> and + <varname>log_min_duration_statement</varname> has a positive value, all + durations are logged but the query text is included only for + statements exceeding the threshold. This behavior can be useful for + gathering statistics in high-load installations. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-error-verbosity" xreflabel="log_error_verbosity"> + <term><varname>log_error_verbosity</varname> (<type>enum</type>) + <indexterm> + <primary><varname>log_error_verbosity</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls the amount of detail written in the server log for each + message that is logged. Valid values are <literal>TERSE</literal>, + <literal>DEFAULT</literal>, and <literal>VERBOSE</literal>, each adding more + fields to displayed messages. <literal>TERSE</literal> excludes + the logging of <literal>DETAIL</literal>, <literal>HINT</literal>, + <literal>QUERY</literal>, and <literal>CONTEXT</literal> error information. + <literal>VERBOSE</literal> output includes the <symbol>SQLSTATE</symbol> error + code (see also <xref linkend="errcodes-appendix"/>) and the source code file name, function name, + and line number that generated the error. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-hostname" xreflabel="log_hostname"> + <term><varname>log_hostname</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_hostname</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + By default, connection log messages only show the IP address of the + connecting host. Turning this parameter on causes logging of the + host name as well. Note that depending on your host name resolution + setup this might impose a non-negligible performance penalty. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-line-prefix" xreflabel="log_line_prefix"> + <term><varname>log_line_prefix</varname> (<type>string</type>) + <indexterm> + <primary><varname>log_line_prefix</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This is a <function>printf</function>-style string that is output at the + beginning of each log line. + <literal>%</literal> characters begin <quote>escape sequences</quote> + that are replaced with status information as outlined below. + Unrecognized escapes are ignored. Other + characters are copied straight to the log line. Some escapes are + only recognized by session processes, and will be treated as empty by + background processes such as the main server process. Status + information may be aligned either left or right by specifying a + numeric literal after the % and before the option. A negative + value will cause the status information to be padded on the + right with spaces to give it a minimum width, whereas a positive + value will pad on the left. Padding can be useful to aid human + readability in log files. + </para> + + <para> + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. The default is + <literal>'%m [%p] '</literal> which logs a time stamp and the process ID. + </para> + + <informaltable> + <tgroup cols="3"> + <thead> + <row> + <entry>Escape</entry> + <entry>Effect</entry> + <entry>Session only</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>%a</literal></entry> + <entry>Application name</entry> + <entry>yes</entry> + </row> + <row> + <entry><literal>%u</literal></entry> + <entry>User name</entry> + <entry>yes</entry> + </row> + <row> + <entry><literal>%d</literal></entry> + <entry>Database name</entry> + <entry>yes</entry> + </row> + <row> + <entry><literal>%r</literal></entry> + <entry>Remote host name or IP address, and remote port</entry> + <entry>yes</entry> + </row> + <row> + <entry><literal>%h</literal></entry> + <entry>Remote host name or IP address</entry> + <entry>yes</entry> + </row> + <row> + <entry><literal>%b</literal></entry> + <entry>Backend type</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%p</literal></entry> + <entry>Process ID</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%P</literal></entry> + <entry>Process ID of the parallel group leader, if this process + is a parallel query worker</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%t</literal></entry> + <entry>Time stamp without milliseconds</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%m</literal></entry> + <entry>Time stamp with milliseconds</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%n</literal></entry> + <entry>Time stamp with milliseconds (as a Unix epoch)</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%i</literal></entry> + <entry>Command tag: type of session's current command</entry> + <entry>yes</entry> + </row> + <row> + <entry><literal>%e</literal></entry> + <entry>SQLSTATE error code</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%c</literal></entry> + <entry>Session ID: see below</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%l</literal></entry> + <entry>Number of the log line for each session or process, starting at 1</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%s</literal></entry> + <entry>Process start time stamp</entry> + <entry>no</entry> + </row> + <row> + <entry><literal>%v</literal></entry> + <entry>Virtual transaction ID (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 and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-recovery-conflict-waits" xreflabel="log_recovery_conflict_waits"> + <term><varname>log_recovery_conflict_waits</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_recovery_conflict_waits</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls whether a log message is produced when the startup process + waits longer than <varname>deadlock_timeout</varname> + for recovery conflicts. This is useful in determining if recovery + conflicts prevent the recovery from applying WAL. + </para> + + <para> + The default is <literal>off</literal>. This parameter can only be set + in the <filename>postgresql.conf</filename> file or on the server + command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-parameter-max-length" xreflabel="log_parameter_max_length"> + <term><varname>log_parameter_max_length</varname> (<type>integer</type>) + <indexterm> + <primary><varname>log_parameter_max_length</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If greater than zero, each bind parameter value logged with a + non-error statement-logging message is trimmed to this many bytes. + Zero disables logging of bind parameters for non-error statement logs. + <literal>-1</literal> (the default) allows bind parameters to be + logged in full. + If this value is specified without units, it is taken as bytes. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <para> + This setting only affects log messages printed as a result of + <xref linkend="guc-log-statement"/>, + <xref linkend="guc-log-duration"/>, and related settings. Non-zero + values of this setting add some overhead, particularly if parameters + are sent in binary form, since then conversion to text is required. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-parameter-max-length-on-error" xreflabel="log_parameter_max_length_on_error"> + <term><varname>log_parameter_max_length_on_error</varname> (<type>integer</type>) + <indexterm> + <primary><varname>log_parameter_max_length_on_error</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If greater than zero, each bind parameter value reported in error + messages is trimmed to this many bytes. + Zero (the default) disables including bind parameters in error + messages. + <literal>-1</literal> allows bind parameters to be printed in full. + If this value is specified without units, it is taken as bytes. + </para> + + <para> + Non-zero values of this setting add overhead, as + <productname>PostgreSQL</productname> will need to store textual + representations of parameter values in memory at the start of each + statement, whether or not an error eventually occurs. The overhead + is greater when bind parameters are sent in binary form than when + they are sent as text, since the former case requires data + conversion while the latter only requires copying the string. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-statement" xreflabel="log_statement"> + <term><varname>log_statement</varname> (<type>enum</type>) + <indexterm> + <primary><varname>log_statement</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls which SQL statements are logged. Valid values are + <literal>none</literal> (off), <literal>ddl</literal>, <literal>mod</literal>, and + <literal>all</literal> (all statements). <literal>ddl</literal> logs all data definition + statements, such as <command>CREATE</command>, <command>ALTER</command>, and + <command>DROP</command> statements. <literal>mod</literal> logs all + <literal>ddl</literal> statements, plus data-modifying statements + such as <command>INSERT</command>, + <command>UPDATE</command>, <command>DELETE</command>, <command>TRUNCATE</command>, + and <command>COPY FROM</command>. + <command>PREPARE</command>, <command>EXECUTE</command>, and + <command>EXPLAIN ANALYZE</command> statements are also logged if their + contained command is of an appropriate type. For clients using + extended query protocol, logging occurs when an Execute message + is received, and values of the Bind parameters are included + (with any embedded single-quote marks doubled). + </para> + + <para> + The default is <literal>none</literal>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <note> + <para> + Statements that contain simple syntax errors are not logged + even by the <varname>log_statement</varname> = <literal>all</literal> setting, + because the log message is emitted only after basic parsing has + been done to determine the statement type. In the case of extended + query protocol, this setting likewise does not log statements that + fail before the Execute phase (i.e., during parse analysis or + planning). Set <varname>log_min_error_statement</varname> to + <literal>ERROR</literal> (or lower) to log such statements. + </para> + <para> + Logged statements might reveal sensitive data and even contain + plaintext passwords. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-replication-commands" xreflabel="log_replication_commands"> + <term><varname>log_replication_commands</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_replication_commands</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Causes each replication command to be logged in the server log. + See <xref linkend="protocol-replication"/> for more information about + replication command. The default value is <literal>off</literal>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-temp-files" xreflabel="log_temp_files"> + <term><varname>log_temp_files</varname> (<type>integer</type>) + <indexterm> + <primary><varname>log_temp_files</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls logging of temporary file names and sizes. + Temporary files can be + created for sorts, hashes, and temporary query results. + If enabled by this setting, a log entry is emitted for each + temporary file when it is deleted. + A value of zero logs all temporary file information, while positive + values log only files whose size is greater than or equal to + the specified amount of data. + If this value is specified without units, it is taken as kilobytes. + The default setting is -1, which disables such logging. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-timezone" xreflabel="log_timezone"> + <term><varname>log_timezone</varname> (<type>string</type>) + <indexterm> + <primary><varname>log_timezone</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the time zone used for timestamps written in the server log. + Unlike <xref linkend="guc-timezone"/>, this value is cluster-wide, + so that all sessions will report timestamps consistently. + The built-in default is <literal>GMT</literal>, but that is typically + overridden in <filename>postgresql.conf</filename>; <application>initdb</application> + will install a setting there corresponding to its system environment. + See <xref linkend="datatype-timezones"/> for more information. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + <sect2 id="runtime-config-logging-csvlog"> + <title>Using CSV-Format Log Output</title> + + <para> + Including <literal>csvlog</literal> in the <varname>log_destination</varname> list + provides a convenient way to import log files into a database table. + This option emits log lines in comma-separated-values + (<acronym>CSV</acronym>) format, + with these columns: + time stamp with milliseconds, + user name, + database name, + process ID, + client host:port number, + session ID, + per-session line number, + command tag, + session start time, + virtual transaction ID, + regular transaction ID, + error severity, + SQLSTATE code, + error message, + error message detail, + hint, + internal query that led to the error (if any), + character count of the error position therein, + error context, + user query that led to the error (if any and enabled by + <varname>log_min_error_statement</varname>), + character count of the error position therein, + location of the error in the PostgreSQL source code + (if <varname>log_error_verbosity</varname> is set to <literal>verbose</literal>), + application name, backend type, process ID of parallel group leader, + and query id. + Here is a sample table definition for storing CSV-format log output: + +<programlisting> +CREATE TABLE postgres_log +( + log_time timestamp(3) with time zone, + user_name text, + database_name text, + process_id integer, + connection_from text, + session_id text, + session_line_num bigint, + command_tag text, + session_start_time timestamp with time zone, + virtual_transaction_id text, + transaction_id bigint, + error_severity text, + sql_state_code text, + message text, + detail text, + hint text, + internal_query text, + internal_query_pos integer, + context text, + query text, + query_pos integer, + location text, + application_name text, + backend_type text, + leader_pid integer, + query_id bigint, + PRIMARY KEY (session_id, session_line_num) +); +</programlisting> + </para> + + <para> + To import a log file into this table, use the <command>COPY FROM</command> + command: + +<programlisting> +COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; +</programlisting> + It is also possible to access the file as a foreign table, using + the supplied <xref linkend="file-fdw"/> module. + </para> + + <para> + There are a few things you need to do to simplify importing CSV log + files: + + <orderedlist> + <listitem> + <para> + Set <varname>log_filename</varname> and + <varname>log_rotation_age</varname> to provide a consistent, + predictable naming scheme for your log files. This lets you + predict what the file name will be and know when an individual log + file is complete and therefore ready to be imported. + </para> + </listitem> + + <listitem> + <para> + Set <varname>log_rotation_size</varname> to 0 to disable + size-based log rotation, as it makes the log file name difficult + to predict. + </para> + </listitem> + + <listitem> + <para> + Set <varname>log_truncate_on_rotation</varname> to <literal>on</literal> so + that old log data isn't mixed with the new in the same file. + </para> + </listitem> + + <listitem> + <para> + The table definition above includes a primary key specification. + This is useful to protect against accidentally importing the same + information twice. The <command>COPY</command> command commits all of the + data it imports at one time, so any error will cause the entire + import to fail. If you import a partial log file and later import + the file again when it is complete, the primary key violation will + cause the import to fail. Wait until the log is complete and + closed before importing. This procedure will also protect against + accidentally importing a partial line that hasn't been completely + written, which would also cause <command>COPY</command> to fail. + </para> + </listitem> + </orderedlist> + </para> + </sect2> + <sect2 id="runtime-config-logging-jsonlog"> + <title>Using JSON-Format Log Output</title> + + <para> + Including <literal>jsonlog</literal> in the + <varname>log_destination</varname> list provides a convenient way to + import log files into many different programs. This option emits log + lines in <acronym>JSON</acronym> format. + </para> + + <para> + String fields with null values are excluded from output. + Additional fields may be added in the future. User applications that + process <literal>jsonlog</literal> output should ignore unknown fields. + </para> + + <para> + Each log line is serialized as a JSON object with the set of keys and + their associated values shown in <xref + linkend="runtime-config-logging-jsonlog-keys-values"/>. + </para> + + <table id="runtime-config-logging-jsonlog-keys-values"> + <title>Keys and Values of JSON Log Entries</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Key name</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>timestamp</literal></entry> + <entry>string</entry> + <entry>Time stamp with milliseconds</entry> + </row> + <row> + <entry><literal>user</literal></entry> + <entry>string</entry> + <entry>User name</entry> + </row> + <row> + <entry><literal>dbname</literal></entry> + <entry>string</entry> + <entry>Database name</entry> + </row> + <row> + <entry><literal>pid</literal></entry> + <entry>number</entry> + <entry>Process ID</entry> + </row> + <row> + <entry><literal>remote_host</literal></entry> + <entry>string</entry> + <entry>Client host</entry> + </row> + <row> + <entry><literal>remote_port</literal></entry> + <entry>number</entry> + <entry>Client port</entry> + </row> + <row> + <entry><literal>session_id</literal></entry> + <entry>string</entry> + <entry>Session ID</entry> + </row> + <row> + <entry><literal>line_num</literal></entry> + <entry>number</entry> + <entry>Per-session line number</entry> + </row> + <row> + <entry><literal>ps</literal></entry> + <entry>string</entry> + <entry>Current ps display</entry> + </row> + <row> + <entry><literal>session_start</literal></entry> + <entry>string</entry> + <entry>Session start time</entry> + </row> + <row> + <entry><literal>vxid</literal></entry> + <entry>string</entry> + <entry>Virtual transaction ID</entry> + </row> + <row> + <entry><literal>txid</literal></entry> + <entry>string</entry> + <entry>Regular transaction ID</entry> + </row> + <row> + <entry><literal>error_severity</literal></entry> + <entry>string</entry> + <entry>Error severity</entry> + </row> + <row> + <entry><literal>state_code</literal></entry> + <entry>string</entry> + <entry>SQLSTATE code</entry> + </row> + <row> + <entry><literal>message</literal></entry> + <entry>string</entry> + <entry>Error message</entry> + </row> + <row> + <entry><literal>detail</literal></entry> + <entry>string</entry> + <entry>Error message detail</entry> + </row> + <row> + <entry><literal>hint</literal></entry> + <entry>string</entry> + <entry>Error message hint</entry> + </row> + <row> + <entry><literal>internal_query</literal></entry> + <entry>string</entry> + <entry>Internal query that led to the error</entry> + </row> + <row> + <entry><literal>internal_position</literal></entry> + <entry>number</entry> + <entry>Cursor index into internal query</entry> + </row> + <row> + <entry><literal>context</literal></entry> + <entry>string</entry> + <entry>Error context</entry> + </row> + <row> + <entry><literal>statement</literal></entry> + <entry>string</entry> + <entry>Client-supplied query string</entry> + </row> + <row> + <entry><literal>cursor_position</literal></entry> + <entry>number</entry> + <entry>Cursor index into query string</entry> + </row> + <row> + <entry><literal>func_name</literal></entry> + <entry>string</entry> + <entry>Error location function name</entry> + </row> + <row> + <entry><literal>file_name</literal></entry> + <entry>string</entry> + <entry>File name of error location</entry> + </row> + <row> + <entry><literal>file_line_num</literal></entry> + <entry>number</entry> + <entry>File line number of the error location</entry> + </row> + <row> + <entry><literal>application_name</literal></entry> + <entry>string</entry> + <entry>Client application name</entry> + </row> + <row> + <entry><literal>backend_type</literal></entry> + <entry>string</entry> + <entry>Type of backend</entry> + </row> + <row> + <entry><literal>leader_pid</literal></entry> + <entry>number</entry> + <entry>Process ID of leader for active parallel workers</entry> + </row> + <row> + <entry><literal>query_id</literal></entry> + <entry>number</entry> + <entry>Query ID</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2> + <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 and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> + + <sect1 id="runtime-config-statistics"> + <title>Run-time Statistics</title> + + <sect2 id="runtime-config-cumulative-statistics"> + <title>Cumulative Query and Index Statistics</title> + + <para> + These parameters control the server-wide cumulative statistics system. + When enabled, the data that is collected can be accessed via the + <structname>pg_stat</structname> and <structname>pg_statio</structname> + family of system views. Refer to <xref linkend="monitoring"/> for more + information. + </para> + + <variablelist> + + <varlistentry id="guc-track-activities" xreflabel="track_activities"> + <term><varname>track_activities</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>track_activities</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables the collection of information on the currently + executing command of each session, along with its identifier and the + time when that command began execution. This parameter is on by + default. Note that even when enabled, this information is only + visible to superusers, roles with privileges of the + <literal>pg_read_all_stats</literal> role and the user owning the + sessions being reported on (including sessions belonging to a role they + have the privileges of), so it should not represent a security risk. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-track-activity-query-size" xreflabel="track_activity_query_size"> + <term><varname>track_activity_query_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>track_activity_query_size</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the amount of memory reserved to store the text of the + currently executing command for each active session, for the + <structname>pg_stat_activity</structname>.<structfield>query</structfield> field. + If this value is specified without units, it is taken as bytes. + The default value is 1024 bytes. + This parameter can only be set at server start. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-track-counts" xreflabel="track_counts"> + <term><varname>track_counts</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>track_counts</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables collection of statistics on database activity. + This parameter is on by default, because the autovacuum + daemon needs the collected information. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-track-io-timing" xreflabel="track_io_timing"> + <term><varname>track_io_timing</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>track_io_timing</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables timing of database I/O calls. This parameter is off by + default, as it will repeatedly query the operating system for + the current time, which may cause significant overhead on some + platforms. You can use the <xref linkend="pgtesttiming"/> tool to + measure the overhead of timing on your system. + I/O timing information is + displayed in <link linkend="monitoring-pg-stat-database-view"> + <structname>pg_stat_database</structname></link>, in the output of + <xref linkend="sql-explain"/> when the <literal>BUFFERS</literal> option + is used, in the output of <xref linkend="sql-vacuum"/> when + the <literal>VERBOSE</literal> option is used, by autovacuum + for auto-vacuums and auto-analyzes, when <xref + linkend="guc-log-autovacuum-min-duration"/> is set and by + <xref linkend="pgstatstatements"/>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-track-wal-io-timing" xreflabel="track_wal_io_timing"> + <term><varname>track_wal_io_timing</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>track_wal_io_timing</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables timing of WAL I/O calls. This parameter is off by default, + as it will repeatedly query the operating system for the current time, + which may cause significant overhead on some platforms. + You can use the <application>pg_test_timing</application> tool to + measure the overhead of timing on your system. + I/O timing information is + displayed in <link linkend="monitoring-pg-stat-wal-view"> + <structname>pg_stat_wal</structname></link>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-track-functions" xreflabel="track_functions"> + <term><varname>track_functions</varname> (<type>enum</type>) + <indexterm> + <primary><varname>track_functions</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables tracking of function call counts and time used. Specify + <literal>pl</literal> to track only procedural-language functions, + <literal>all</literal> to also track SQL and C language functions. + The default is <literal>none</literal>, which disables function + statistics tracking. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <note> + <para> + SQL-language functions that are simple enough to be <quote>inlined</quote> + into the calling query will not be tracked, regardless of this + setting. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="guc-stats-fetch-consistency" xreflabel="stats_fetch_consistency"> + <term><varname>stats_fetch_consistency</varname> (<type>enum</type>) + <indexterm> + <primary><varname>stats_fetch_consistency</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Determines the behavior when cumulative statistics are accessed + multiple times within a transaction. When set to + <literal>none</literal>, each access re-fetches counters from shared + memory. When set to <literal>cache</literal>, the first access to + statistics for an object caches those statistics until the end of the + transaction unless <function>pg_stat_clear_snapshot()</function> is + called. When set to <literal>snapshot</literal>, the first statistics + access caches all statistics accessible in the current database, until + the end of the transaction unless + <function>pg_stat_clear_snapshot()</function> is called. Changing this + parameter in a transaction discards the statistics snapshot. + The default is <literal>cache</literal>. + </para> + <note> + <para> + <literal>none</literal> is most suitable for monitoring systems. If + values are only accessed once, it is the most + efficient. <literal>cache</literal> ensures repeat accesses yield the + same values, which is important for queries involving + e.g. self-joins. <literal>snapshot</literal> can be useful when + interactively inspecting statistics, but has higher overhead, + particularly if many database objects exist. + </para> + </note> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + + <sect2 id="runtime-config-statistics-monitor"> + <title>Statistics Monitoring</title> + <variablelist> + + <varlistentry id="guc-compute-query-id" xreflabel="compute_query_id"> + <term><varname>compute_query_id</varname> (<type>enum</type>) + <indexterm> + <primary><varname>compute_query_id</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables in-core computation of a query identifier. + Query identifiers can be displayed in the <link + linkend="monitoring-pg-stat-activity-view"><structname>pg_stat_activity</structname></link> + view, using <command>EXPLAIN</command>, or emitted in the log if + configured via the <xref linkend="guc-log-line-prefix"/> parameter. + The <xref linkend="pgstatstatements"/> extension also requires a query + identifier to be computed. Note that an external module can + alternatively be used if the in-core query identifier computation + method is not acceptable. In this case, in-core computation + must be always disabled. + Valid values are <literal>off</literal> (always disabled), + <literal>on</literal> (always enabled), <literal>auto</literal>, + which lets modules such as <xref linkend="pgstatstatements"/> + automatically enable it, and <literal>regress</literal> which + has the same effect as <literal>auto</literal>, except that the + query identifier is not shown in the <literal>EXPLAIN</literal> output + in order to facilitate automated regression testing. + The default is <literal>auto</literal>. + </para> + <note> + <para> + To ensure that only one query identifier is calculated and + displayed, extensions that calculate query identifiers should + throw an error if a query identifier has already been computed. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>log_statement_stats</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_statement_stats</varname> configuration parameter</primary> + </indexterm> + </term> + <term><varname>log_parser_stats</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_parser_stats</varname> configuration parameter</primary> + </indexterm> + </term> + <term><varname>log_planner_stats</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_planner_stats</varname> configuration parameter</primary> + </indexterm> + </term> + <term><varname>log_executor_stats</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_executor_stats</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + For each query, output performance statistics of the respective + module to the server log. This is a crude profiling + instrument, similar to the Unix <function>getrusage()</function> operating + system facility. <varname>log_statement_stats</varname> reports total + statement statistics, while the others report per-module statistics. + <varname>log_statement_stats</varname> cannot be enabled together with + any of the per-module options. All of these options are disabled by + default. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change these settings. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect2> + </sect1> + + <sect1 id="runtime-config-autovacuum"> + <title>Automatic Vacuuming</title> + + <indexterm> + <primary>autovacuum</primary> + <secondary>configuration parameters</secondary> + </indexterm> + + <para> + These settings control the behavior of the <firstterm>autovacuum</firstterm> + feature. Refer to <xref linkend="autovacuum"/> for more information. + Note that many of these settings can be overridden on a per-table + basis; see <xref linkend="sql-createtable-storage-parameters"/>. + </para> + + <variablelist> + + <varlistentry id="guc-autovacuum" xreflabel="autovacuum"> + <term><varname>autovacuum</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>autovacuum</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls whether the server should run the + autovacuum launcher daemon. This is on by default; however, + <xref linkend="guc-track-counts"/> must also be enabled for + autovacuum to work. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line; however, autovacuuming can be + disabled for individual tables by changing table storage parameters. + </para> + <para> + Note that even when this parameter is disabled, the system + will launch autovacuum processes if necessary to + prevent transaction ID wraparound. See <xref + linkend="vacuum-for-wraparound"/> for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-max-workers" xreflabel="autovacuum_max_workers"> + <term><varname>autovacuum_max_workers</varname> (<type>integer</type>) + <indexterm> + <primary><varname>autovacuum_max_workers</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the maximum number of autovacuum processes (other than the + autovacuum launcher) that may be running at any one time. The default + is three. This parameter can only be set at server start. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-naptime" xreflabel="autovacuum_naptime"> + <term><varname>autovacuum_naptime</varname> (<type>integer</type>) + <indexterm> + <primary><varname>autovacuum_naptime</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies the minimum delay between autovacuum runs on any given + database. In each round the daemon examines the + database and issues <command>VACUUM</command> and <command>ANALYZE</command> commands + as needed for tables in that database. + If this value is specified without units, it is taken as seconds. + The default is one minute (<literal>1min</literal>). + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-vacuum-threshold" xreflabel="autovacuum_vacuum_threshold"> + <term><varname>autovacuum_vacuum_threshold</varname> (<type>integer</type>) + <indexterm> + <primary><varname>autovacuum_vacuum_threshold</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies the minimum number of updated or deleted tuples needed + to trigger a <command>VACUUM</command> in any one table. + The default is 50 tuples. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line; + but the setting can be overridden for individual tables by + changing table storage parameters. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-vacuum-insert-threshold" xreflabel="autovacuum_vacuum_insert_threshold"> + <term><varname>autovacuum_vacuum_insert_threshold</varname> (<type>integer</type>) + <indexterm> + <primary><varname>autovacuum_vacuum_insert_threshold</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies the number of inserted tuples needed to trigger a + <command>VACUUM</command> in any one table. + The default is 1000 tuples. If -1 is specified, autovacuum will not + trigger a <command>VACUUM</command> operation on any tables based on + the number of inserts. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line; + but the setting can be overridden for individual tables by + changing table storage parameters. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-analyze-threshold" xreflabel="autovacuum_analyze_threshold"> + <term><varname>autovacuum_analyze_threshold</varname> (<type>integer</type>) + <indexterm> + <primary><varname>autovacuum_analyze_threshold</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies the minimum number of inserted, updated or deleted tuples + needed to trigger an <command>ANALYZE</command> in any one table. + The default is 50 tuples. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line; + but the setting can be overridden for individual tables by + changing table storage parameters. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-vacuum-scale-factor" xreflabel="autovacuum_vacuum_scale_factor"> + <term><varname>autovacuum_vacuum_scale_factor</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>autovacuum_vacuum_scale_factor</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies a fraction of the table size to add to + <varname>autovacuum_vacuum_threshold</varname> + when deciding whether to trigger a <command>VACUUM</command>. + The default is 0.2 (20% of table size). + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line; + but the setting can be overridden for individual tables by + changing table storage parameters. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-vacuum-insert-scale-factor" xreflabel="autovacuum_vacuum_insert_scale_factor"> + <term><varname>autovacuum_vacuum_insert_scale_factor</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>autovacuum_vacuum_insert_scale_factor</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies a fraction of the table size to add to + <varname>autovacuum_vacuum_insert_threshold</varname> + when deciding whether to trigger a <command>VACUUM</command>. + The default is 0.2 (20% of table size). + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line; + but the setting can be overridden for individual tables by + changing table storage parameters. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-analyze-scale-factor" xreflabel="autovacuum_analyze_scale_factor"> + <term><varname>autovacuum_analyze_scale_factor</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>autovacuum_analyze_scale_factor</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies a fraction of the table size to add to + <varname>autovacuum_analyze_threshold</varname> + when deciding whether to trigger an <command>ANALYZE</command>. + The default is 0.1 (10% of table size). + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line; + but the setting can be overridden for individual tables by + changing table storage parameters. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-freeze-max-age" xreflabel="autovacuum_freeze_max_age"> + <term><varname>autovacuum_freeze_max_age</varname> (<type>integer</type>) + <indexterm> + <primary><varname>autovacuum_freeze_max_age</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies the maximum age (in transactions) that a table's + <structname>pg_class</structname>.<structfield>relfrozenxid</structfield> field can + attain before a <command>VACUUM</command> operation is forced + to prevent transaction ID wraparound within the table. + Note that the system will launch autovacuum processes to + prevent wraparound even when autovacuum is otherwise disabled. + </para> + + <para> + Vacuum also allows removal of old files from the + <filename>pg_xact</filename> subdirectory, which is why the default + is a relatively low 200 million transactions. + This parameter can only be set at server start, but the setting + can be reduced for individual tables by + changing table storage parameters. + For more information see <xref linkend="vacuum-for-wraparound"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-multixact-freeze-max-age" xreflabel="autovacuum_multixact_freeze_max_age"> + <term><varname>autovacuum_multixact_freeze_max_age</varname> (<type>integer</type>) + <indexterm> + <primary><varname>autovacuum_multixact_freeze_max_age</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies the maximum age (in multixacts) that a table's + <structname>pg_class</structname>.<structfield>relminmxid</structfield> field can + attain before a <command>VACUUM</command> operation is forced to + prevent multixact ID wraparound within the table. + Note that the system will launch autovacuum processes to + prevent wraparound even when autovacuum is otherwise disabled. + </para> + + <para> + Vacuuming multixacts also allows removal of old files from the + <filename>pg_multixact/members</filename> and <filename>pg_multixact/offsets</filename> + subdirectories, which is why the default is a relatively low + 400 million multixacts. + This parameter can only be set at server start, but the setting can + be reduced for individual tables by changing table storage parameters. + For more information see <xref linkend="vacuum-for-multixact-wraparound"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-vacuum-cost-delay" xreflabel="autovacuum_vacuum_cost_delay"> + <term><varname>autovacuum_vacuum_cost_delay</varname> (<type>floating point</type>) + <indexterm> + <primary><varname>autovacuum_vacuum_cost_delay</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies the cost delay value that will be used in automatic + <command>VACUUM</command> operations. If -1 is specified, the regular + <xref linkend="guc-vacuum-cost-delay"/> value will be used. + If this value is specified without units, it is taken as milliseconds. + The default value is 2 milliseconds. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line; + but the setting can be overridden for individual tables by + changing table storage parameters. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-autovacuum-vacuum-cost-limit" xreflabel="autovacuum_vacuum_cost_limit"> + <term><varname>autovacuum_vacuum_cost_limit</varname> (<type>integer</type>) + <indexterm> + <primary><varname>autovacuum_vacuum_cost_limit</varname></primary> + <secondary>configuration parameter</secondary> + </indexterm> + </term> + <listitem> + <para> + Specifies the cost limit value that will be used in automatic + <command>VACUUM</command> operations. If -1 is specified (which is the + default), the regular + <xref linkend="guc-vacuum-cost-limit"/> value will be used. Note that + the value is distributed proportionally among the running autovacuum + workers, if there is more than one, so that the sum of the limits for + each worker does not exceed the value of this variable. + This parameter can only be set in the <filename>postgresql.conf</filename> + file or on the server command line; + but the setting can be overridden for individual tables by + changing table storage parameters. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect1> + + <sect1 id="runtime-config-client"> + <title>Client Connection Defaults</title> + + <sect2 id="runtime-config-client-statement"> + <title>Statement Behavior</title> + <variablelist> + + <varlistentry id="guc-client-min-messages" xreflabel="client_min_messages"> + <term><varname>client_min_messages</varname> (<type>enum</type>) + <indexterm> + <primary><varname>client_min_messages</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls which + <link linkend="runtime-config-severity-levels">message levels</link> + are sent to the client. + Valid values are <literal>DEBUG5</literal>, + <literal>DEBUG4</literal>, <literal>DEBUG3</literal>, <literal>DEBUG2</literal>, + <literal>DEBUG1</literal>, <literal>LOG</literal>, <literal>NOTICE</literal>, + <literal>WARNING</literal>, and <literal>ERROR</literal>. + Each level includes all the levels that follow it. The later the level, + the fewer messages are sent. The default is + <literal>NOTICE</literal>. Note that <literal>LOG</literal> has a different + rank here than in <xref linkend="guc-log-min-messages"/>. + </para> + <para> + <literal>INFO</literal> level messages are always sent to the client. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-search-path" xreflabel="search_path"> + <term><varname>search_path</varname> (<type>string</type>) + <indexterm> + <primary><varname>search_path</varname> configuration parameter</primary> + </indexterm> + <indexterm><primary>path</primary><secondary>for schemas</secondary></indexterm> + </term> + <listitem> + <para> + This variable specifies the order in which schemas are searched + when an object (table, data type, function, etc.) is referenced by a + simple name with no schema specified. When there are objects of + identical names in different schemas, the one found first + in the search path is used. An object that is not in any of the + schemas in the search path can only be referenced by specifying + its containing schema with a qualified (dotted) name. + </para> + + <para> + The value for <varname>search_path</varname> must be a comma-separated + list of schema names. Any name that is not an existing schema, or is + a schema for which the user does not have <literal>USAGE</literal> + permission, is silently ignored. + </para> + + <para> + If one of the list items is the special name + <literal>$user</literal>, then the schema having the name returned by + <function>CURRENT_USER</function> is substituted, if there is such a schema + and the user has <literal>USAGE</literal> permission for it. + (If not, <literal>$user</literal> is ignored.) + </para> + + <para> + The system catalog schema, <literal>pg_catalog</literal>, is always + searched, whether it is mentioned in the path or not. If it is + mentioned in the path then it will be searched in the specified + order. If <literal>pg_catalog</literal> is not in the path then it will + be searched <emphasis>before</emphasis> searching any of the path items. + </para> + + <!-- To further split hairs, funcname('foo') does not use the temporary + schema, even when it considers typname='funcname'. This paragraph + refers to function names in a loose sense, "pg_proc.proname or + func_name grammar production". --> + <para> + Likewise, the current session's temporary-table schema, + <literal>pg_temp_<replaceable>nnn</replaceable></literal>, is always searched if it + exists. It can be explicitly listed in the path by using the + alias <literal>pg_temp</literal><indexterm><primary>pg_temp</primary></indexterm>. If it is not listed in the path then + it is searched first (even before <literal>pg_catalog</literal>). However, + the temporary schema is only searched for relation (table, view, + sequence, etc.) and data type names. It is never searched for + function or operator names. + </para> + + <para> + When objects are created without specifying a particular target + schema, they will be placed in the first valid schema named in + <varname>search_path</varname>. An error is reported if the search + path is empty. + </para> + + <para> + The default value for this parameter is + <literal>"$user", public</literal>. + This setting supports shared use of a database (where no users + have private schemas, and all share use of <literal>public</literal>), + private per-user schemas, and combinations of these. Other + effects can be obtained by altering the default search path + setting, either globally or per-user. + </para> + + <para> + For more information on schema handling, see + <xref linkend="ddl-schemas"/>. In particular, the default + configuration is suitable only when the database has a single user or + a few mutually-trusting users. + </para> + + <para> + The current effective value of the search path can be examined + via the <acronym>SQL</acronym> function + <function>current_schemas</function> + (see <xref linkend="functions-info"/>). + This is not quite the same as + examining the value of <varname>search_path</varname>, since + <function>current_schemas</function> shows how the items + appearing in <varname>search_path</varname> were resolved. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="guc-row-security" xreflabel="row_security"> + <term><varname>row_security</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>row_security</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This variable controls whether to raise an error in lieu of applying a + row security policy. When set to <literal>on</literal>, policies apply + normally. When set to <literal>off</literal>, queries fail which would + otherwise apply at least one policy. The default is <literal>on</literal>. + Change to <literal>off</literal> where limited row visibility could cause + incorrect results; for example, <application>pg_dump</application> makes that + change by default. This variable has no effect on roles which bypass + every row security policy, to wit, superusers and roles with + the <literal>BYPASSRLS</literal> attribute. + </para> + + <para> + For more information on row security policies, + see <xref linkend="sql-createpolicy"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-default-table-access-method" xreflabel="default_table_access_method"> + <term><varname>default_table_access_method</varname> (<type>string</type>) + <indexterm> + <primary><varname>default_table_access_method</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies the default table access method to use when + creating tables or materialized views if the <command>CREATE</command> + command does not explicitly specify an access method, or when + <command>SELECT ... INTO</command> is used, which does not allow + specifying a table access method. The default is <literal>heap</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-default-tablespace" xreflabel="default_tablespace"> + <term><varname>default_tablespace</varname> (<type>string</type>) + <indexterm> + <primary><varname>default_tablespace</varname> configuration parameter</primary> + </indexterm> + <indexterm><primary>tablespace</primary><secondary>default</secondary></indexterm> + </term> + <listitem> + <para> + This variable specifies the default tablespace in which to create + objects (tables and indexes) when a <command>CREATE</command> command does + not explicitly specify a tablespace. + </para> + + <para> + The value is either the name of a tablespace, or an empty string + to specify using the default tablespace of the current database. + If the value does not match the name of any existing tablespace, + <productname>PostgreSQL</productname> will automatically use the default + tablespace of the current database. If a nondefault tablespace + is specified, the user must have <literal>CREATE</literal> privilege + for it, or creation attempts will fail. + </para> + + <para> + This variable is not used for temporary tables; for them, + <xref linkend="guc-temp-tablespaces"/> is consulted instead. + </para> + + <para> + This variable is also not used when creating databases. + By default, a new database inherits its tablespace setting from + the template database it is copied from. + </para> + + <para> + If this parameter is set to a value other than the empty string + when a partitioned table is created, the partitioned table's + tablespace will be set to that value, which will be used as + the default tablespace for partitions created in the future, + even if <varname>default_tablespace</varname> has changed since then. + </para> + + <para> + For more information on tablespaces, + see <xref linkend="manage-ag-tablespaces"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-default-toast-compression" xreflabel="default_toast_compression"> + <term><varname>default_toast_compression</varname> (<type>enum</type>) + <indexterm> + <primary><varname>default_toast_compression</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This variable sets the default + <link linkend="storage-toast">TOAST</link> + compression method for values of compressible columns. + (This can be overridden for individual columns by setting + the <literal>COMPRESSION</literal> column option in + <command>CREATE TABLE</command> or + <command>ALTER TABLE</command>.) + The supported compression methods are <literal>pglz</literal> and + (if <productname>PostgreSQL</productname> was compiled with + <option>--with-lz4</option>) <literal>lz4</literal>. + The default is <literal>pglz</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-temp-tablespaces" xreflabel="temp_tablespaces"> + <term><varname>temp_tablespaces</varname> (<type>string</type>) + <indexterm> + <primary><varname>temp_tablespaces</varname> configuration parameter</primary> + </indexterm> + <indexterm><primary>tablespace</primary><secondary>temporary</secondary></indexterm> + </term> + <listitem> + <para> + This variable specifies tablespaces in which to create temporary + objects (temp tables and indexes on temp tables) when a + <command>CREATE</command> command does not explicitly specify a tablespace. + Temporary files for purposes such as sorting large data sets + are also created in these tablespaces. + </para> + + <para> + The value is a list of names of tablespaces. When there is more than + one name in the list, <productname>PostgreSQL</productname> chooses a random + member of the list each time a temporary object is to be created; + except that within a transaction, successively created temporary + objects are placed in successive tablespaces from the list. + If the selected element of the list is an empty string, + <productname>PostgreSQL</productname> will automatically use the default + tablespace of the current database instead. + </para> + + <para> + When <varname>temp_tablespaces</varname> is set interactively, specifying a + nonexistent tablespace is an error, as is specifying a tablespace for + which the user does not have <literal>CREATE</literal> privilege. However, + when using a previously set value, nonexistent tablespaces are + ignored, as are tablespaces for which the user lacks + <literal>CREATE</literal> privilege. In particular, this rule applies when + using a value set in <filename>postgresql.conf</filename>. + </para> + + <para> + The default value is an empty string, which results in all temporary + objects being created in the default tablespace of the current + database. + </para> + + <para> + See also <xref linkend="guc-default-tablespace"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-check-function-bodies" xreflabel="check_function_bodies"> + <term><varname>check_function_bodies</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>check_function_bodies</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter is normally on. When set to <literal>off</literal>, it + disables validation of the routine body string during <xref + linkend="sql-createfunction"/> and <xref + linkend="sql-createprocedure"/>. Disabling validation avoids side + effects of the validation process, in particular preventing false + positives due to problems such as forward references. + Set this parameter + to <literal>off</literal> before loading functions on behalf of other + users; <application>pg_dump</application> does so automatically. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-default-transaction-isolation" xreflabel="default_transaction_isolation"> + <term><varname>default_transaction_isolation</varname> (<type>enum</type>) + <indexterm> + <primary>transaction isolation level</primary> + <secondary>setting default</secondary> + </indexterm> + <indexterm> + <primary><varname>default_transaction_isolation</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Each SQL transaction has an isolation level, which can be + either <quote>read uncommitted</quote>, <quote>read + committed</quote>, <quote>repeatable read</quote>, or + <quote>serializable</quote>. This parameter controls the + default isolation level of each new transaction. The default + is <quote>read committed</quote>. + </para> + + <para> + Consult <xref linkend="mvcc"/> and <xref + linkend="sql-set-transaction"/> for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-default-transaction-read-only" xreflabel="default_transaction_read_only"> + <term><varname>default_transaction_read_only</varname> (<type>boolean</type>) + <indexterm> + <primary>read-only transaction</primary> + <secondary>setting default</secondary> + </indexterm> + <indexterm> + <primary><varname>default_transaction_read_only</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + A read-only SQL transaction cannot alter non-temporary tables. + This parameter controls the default read-only status of each new + transaction. The default is <literal>off</literal> (read/write). + </para> + + <para> + Consult <xref linkend="sql-set-transaction"/> for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-default-transaction-deferrable" xreflabel="default_transaction_deferrable"> + <term><varname>default_transaction_deferrable</varname> (<type>boolean</type>) + <indexterm> + <primary>deferrable transaction</primary> + <secondary>setting default</secondary> + </indexterm> + <indexterm> + <primary><varname>default_transaction_deferrable</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When running at the <literal>serializable</literal> isolation level, + a deferrable read-only SQL transaction may be delayed before + it is allowed to proceed. However, once it begins executing + it does not incur any of the overhead required to ensure + serializability; so serialization code will have no reason to + force it to abort because of concurrent updates, making this + option suitable for long-running read-only transactions. + </para> + + <para> + This parameter controls the default deferrable status of each + new transaction. It currently has no effect on read-write + transactions or those operating at isolation levels lower + than <literal>serializable</literal>. The default is <literal>off</literal>. + </para> + + <para> + Consult <xref linkend="sql-set-transaction"/> for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-transaction-isolation" xreflabel="transaction_isolation"> + <term><varname>transaction_isolation</varname> (<type>enum</type>) + <indexterm> + <primary>transaction isolation level</primary> + </indexterm> + <indexterm> + <primary><varname>transaction_isolation</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter reflects the current transaction's isolation level. + At the beginning of each transaction, it is set to the current value + of <xref linkend="guc-default-transaction-isolation"/>. + Any subsequent attempt to change it is equivalent to a <xref + linkend="sql-set-transaction"/> command. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-transaction-read-only" xreflabel="transaction_read_only"> + <term><varname>transaction_read_only</varname> (<type>boolean</type>) + <indexterm> + <primary>read-only transaction</primary> + </indexterm> + <indexterm> + <primary><varname>transaction_read_only</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter reflects the current transaction's read-only status. + At the beginning of each transaction, it is set to the current value + of <xref linkend="guc-default-transaction-read-only"/>. + Any subsequent attempt to change it is equivalent to a <xref + linkend="sql-set-transaction"/> command. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-transaction-deferrable" xreflabel="transaction_deferrable"> + <term><varname>transaction_deferrable</varname> (<type>boolean</type>) + <indexterm> + <primary>deferrable transaction</primary> + </indexterm> + <indexterm> + <primary><varname>transaction_deferrable</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter reflects the current transaction's deferrability status. + At the beginning of each transaction, it is set to the current value + of <xref linkend="guc-default-transaction-deferrable"/>. + Any subsequent attempt to change it is equivalent to a <xref + linkend="sql-set-transaction"/> command. + </para> + </listitem> + </varlistentry> + + + <varlistentry id="guc-session-replication-role" xreflabel="session_replication_role"> + <term><varname>session_replication_role</varname> (<type>enum</type>) + <indexterm> + <primary><varname>session_replication_role</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Controls firing of replication-related triggers and rules for the + current session. + Possible values are <literal>origin</literal> (the default), + <literal>replica</literal> and <literal>local</literal>. + Setting this parameter results in discarding any previously cached + query plans. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <para> + The intended use of this setting is that logical replication systems + set it to <literal>replica</literal> when they are applying replicated + changes. The effect of that will be that triggers and rules (that + have not been altered from their default configuration) will not fire + on the replica. See the <link linkend="sql-altertable"><command>ALTER TABLE</command></link> clauses + <literal>ENABLE TRIGGER</literal> and <literal>ENABLE RULE</literal> + for more information. + </para> + + <para> + PostgreSQL treats the settings <literal>origin</literal> and + <literal>local</literal> the same internally. Third-party replication + systems may use these two values for their internal purposes, for + example using <literal>local</literal> to designate a session whose + changes should not be replicated. + </para> + + <para> + Since foreign keys are implemented as triggers, setting this parameter + to <literal>replica</literal> also disables all foreign key checks, + which can leave data in an inconsistent state if improperly used. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-statement-timeout" xreflabel="statement_timeout"> + <term><varname>statement_timeout</varname> (<type>integer</type>) + <indexterm> + <primary><varname>statement_timeout</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Abort any statement that takes more than the specified amount of time. + If <varname>log_min_error_statement</varname> is set + to <literal>ERROR</literal> or lower, the statement that timed out + will also be logged. + If this value is specified without units, it is taken as milliseconds. + A value of zero (the default) disables the timeout. + </para> + + <para> + The timeout is measured from the time a command arrives at the + server until it is completed by the server. If multiple SQL + statements appear in a single simple-Query message, the timeout + is applied to each statement separately. + (<productname>PostgreSQL</productname> versions before 13 usually + treated the timeout as applying to the whole query string.) + In extended query protocol, the timeout starts running when any + query-related message (Parse, Bind, Execute, Describe) arrives, and + it is canceled by completion of an Execute or Sync message. + </para> + + <para> + Setting <varname>statement_timeout</varname> in + <filename>postgresql.conf</filename> is not recommended because it would + affect all sessions. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-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 and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-lc-monetary" xreflabel="lc_monetary"> + <term><varname>lc_monetary</varname> (<type>string</type>) + <indexterm> + <primary><varname>lc_monetary</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the locale to use for formatting monetary amounts, for + example with the <function>to_char</function> family of + functions. Acceptable values are system-dependent; see <xref + linkend="locale"/> for more information. If this variable is + set to the empty string (which is the default) then the value + is inherited from the execution environment of the server in a + system-dependent way. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-lc-numeric" xreflabel="lc_numeric"> + <term><varname>lc_numeric</varname> (<type>string</type>) + <indexterm> + <primary><varname>lc_numeric</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the locale to use for formatting numbers, for example + with the <function>to_char</function> family of + functions. Acceptable values are system-dependent; see <xref + linkend="locale"/> for more information. If this variable is + set to the empty string (which is the default) then the value + is inherited from the execution environment of the server in a + system-dependent way. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-lc-time" xreflabel="lc_time"> + <term><varname>lc_time</varname> (<type>string</type>) + <indexterm> + <primary><varname>lc_time</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the locale to use for formatting dates and times, for example + with the <function>to_char</function> family of + functions. Acceptable values are system-dependent; see <xref + linkend="locale"/> for more information. If this variable is + set to the empty string (which is the default) then the value + is inherited from the execution environment of the server in a + system-dependent way. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-default-text-search-config" xreflabel="default_text_search_config"> + <term><varname>default_text_search_config</varname> (<type>string</type>) + <indexterm> + <primary><varname>default_text_search_config</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Selects the text search configuration that is used by those variants + of the text search functions that do not have an explicit argument + specifying the configuration. + See <xref linkend="textsearch"/> for further information. + The built-in default is <literal>pg_catalog.simple</literal>, but + <application>initdb</application> will initialize the + configuration file with a setting that corresponds to the + chosen <varname>lc_ctype</varname> locale, if a configuration + matching that locale can be identified. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect2> + + <sect2 id="runtime-config-client-preload"> + <title>Shared Library Preloading</title> + + <para> + Several settings are available for preloading shared libraries into the + server, in order to load additional functionality or achieve performance + benefits. For example, a setting of + <literal>'$libdir/mylib'</literal> would cause + <literal>mylib.so</literal> (or on some platforms, + <literal>mylib.sl</literal>) to be preloaded from the installation's standard + library directory. The differences between the settings are when they + take effect and what privileges are required to change them. + </para> + + <para> + <productname>PostgreSQL</productname> procedural language libraries can + be preloaded in this way, typically by using the + syntax <literal>'$libdir/plXXX'</literal> where + <literal>XXX</literal> is <literal>pgsql</literal>, <literal>perl</literal>, + <literal>tcl</literal>, or <literal>python</literal>. + </para> + + <para> + Only shared libraries specifically intended to be used with PostgreSQL + can be loaded this way. Every PostgreSQL-supported library has + a <quote>magic block</quote> that is checked to guarantee compatibility. For + this reason, non-PostgreSQL libraries cannot be loaded in this way. You + might be able to use operating-system facilities such + as <envar>LD_PRELOAD</envar> for that. + </para> + + <para> + In general, refer to the documentation of a specific module for the + recommended way to load that module. + </para> + + <variablelist> + <varlistentry id="guc-local-preload-libraries" xreflabel="local_preload_libraries"> + <term><varname>local_preload_libraries</varname> (<type>string</type>) + <indexterm> + <primary><varname>local_preload_libraries</varname> configuration parameter</primary> + </indexterm> + <indexterm> + <primary><filename>$libdir/plugins</filename></primary> + </indexterm> + </term> + <listitem> + <para> + This variable specifies one or more shared libraries that are to be + preloaded at connection start. + It contains a comma-separated list of library names, where each name + is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> command. + Whitespace between entries is ignored; surround a library name with + double quotes if you need to include whitespace or commas in the name. + The parameter value only takes effect at the start of the connection. + Subsequent changes have no effect. If a specified library is not + found, the connection attempt will fail. + </para> + + <para> + This option can be set by any user. Because of that, the libraries + that can be loaded are restricted to those appearing in the + <filename>plugins</filename> subdirectory of the installation's + standard library directory. (It is the database administrator's + responsibility to ensure that only <quote>safe</quote> libraries + are installed there.) Entries in <varname>local_preload_libraries</varname> + can specify this directory explicitly, for example + <literal>$libdir/plugins/mylib</literal>, or just specify + the library name — <literal>mylib</literal> would have + the same effect as <literal>$libdir/plugins/mylib</literal>. + </para> + + <para> + The intent of this feature is to allow unprivileged users to load + debugging or performance-measurement libraries into specific sessions + without requiring an explicit <command>LOAD</command> command. To that end, + it would be typical to set this parameter using + the <envar>PGOPTIONS</envar> environment variable on the client or by + using + <command>ALTER ROLE SET</command>. + </para> + + <para> + However, unless a module is specifically designed to be used in this way by + non-superusers, this is usually not the right setting to use. Look + at <xref linkend="guc-session-preload-libraries"/> instead. + </para> + </listitem> + </varlistentry> + + + <varlistentry id="guc-session-preload-libraries" xreflabel="session_preload_libraries"> + <term><varname>session_preload_libraries</varname> (<type>string</type>) + <indexterm> + <primary><varname>session_preload_libraries</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This variable specifies one or more shared libraries that are to be + preloaded at connection start. + It contains a comma-separated list of library names, where each name + is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> command. + Whitespace between entries is ignored; surround a library name with + double quotes if you need to include whitespace or commas in the name. + The parameter value only takes effect at the start of the connection. + Subsequent changes have no effect. If a specified library is not + found, the connection attempt will fail. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <para> + The intent of this feature is to allow debugging or + performance-measurement libraries to be loaded into specific sessions + without an explicit + <command>LOAD</command> command being given. For + example, <xref linkend="auto-explain"/> could be enabled for all + sessions under a given user name by setting this parameter + with <command>ALTER ROLE SET</command>. Also, this parameter can be changed + without restarting the server (but changes only take effect when a new + session is started), so it is easier to add new modules this way, even + if they should apply to all sessions. + </para> + + <para> + Unlike <xref linkend="guc-shared-preload-libraries"/>, there is no large + performance advantage to loading a library at session start rather than + when it is first used. There is some advantage, however, when + connection pooling is used. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-shared-preload-libraries" xreflabel="shared_preload_libraries"> + <term><varname>shared_preload_libraries</varname> (<type>string</type>) + <indexterm> + <primary><varname>shared_preload_libraries</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This variable specifies one or more shared libraries to be preloaded at + server start. + It contains a comma-separated list of library names, where each name + is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> command. + Whitespace between entries is ignored; surround a library name with + double quotes if you need to include whitespace or commas in the name. + This parameter can only be set at server start. If a specified + library is not found, the server will fail to start. + </para> + + <para> + Some libraries need to perform certain operations that can only take + place at postmaster start, such as allocating shared memory, reserving + light-weight locks, or starting background workers. Those libraries + must be loaded at server start through this parameter. See the + documentation of each library for details. + </para> + + <para> + Other libraries can also be preloaded. By preloading a shared library, + the library startup time is avoided when the library is first used. + However, the time to start each new server process might increase + slightly, even if that process never uses the library. So this + parameter is recommended only for libraries that will be used in most + sessions. Also, changing this parameter requires a server restart, so + this is not the right setting to use for short-term debugging tasks, + say. Use <xref linkend="guc-session-preload-libraries"/> for that + instead. + </para> + + <note> + <para> + On Windows hosts, preloading a library at server start will not reduce + the time required to start each new server process; each server process + will re-load all preload libraries. However, <varname>shared_preload_libraries + </varname> is still useful on Windows hosts for libraries that need to + perform operations at postmaster start time. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit-provider" xreflabel="jit_provider"> + <term><varname>jit_provider</varname> (<type>string</type>) + <indexterm> + <primary><varname>jit_provider</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This variable is the name of the JIT provider library to be used + (see <xref linkend="jit-pluggable"/>). + The default is <literal>llvmjit</literal>. + This parameter can only be set at server start. + </para> + + <para> + If set to a non-existent library, <acronym>JIT</acronym> will not be + available, but no error will be raised. This allows JIT support to be + installed separately from the main + <productname>PostgreSQL</productname> package. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + + <sect2 id="runtime-config-client-other"> + <title>Other Defaults</title> + + <variablelist> + + <varlistentry id="guc-dynamic-library-path" xreflabel="dynamic_library_path"> + <term><varname>dynamic_library_path</varname> (<type>string</type>) + <indexterm> + <primary><varname>dynamic_library_path</varname> configuration parameter</primary> + </indexterm> + <indexterm><primary>dynamic loading</primary></indexterm> + </term> + <listitem> + <para> + If a dynamically loadable module needs to be opened and the + file name specified in the <command>CREATE FUNCTION</command> or + <command>LOAD</command> command + does not have a directory component (i.e., the + name does not contain a slash), the system will search this + path for the required file. + </para> + + <para> + The value for <varname>dynamic_library_path</varname> must be a + list of absolute directory paths separated by colons (or semi-colons + on Windows). If a list element starts + with the special string <literal>$libdir</literal>, the + compiled-in <productname>PostgreSQL</productname> package + library directory is substituted for <literal>$libdir</literal>; this + is where the modules provided by the standard + <productname>PostgreSQL</productname> distribution are installed. + (Use <literal>pg_config --pkglibdir</literal> to find out the name of + this directory.) For example: +<programlisting> +dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' +</programlisting> + or, in a Windows environment: +<programlisting> +dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' +</programlisting> + </para> + + <para> + The default value for this parameter is + <literal>'$libdir'</literal>. If the value is set to an empty + string, the automatic path search is turned off. + </para> + + <para> + This parameter can be changed at run time by superusers and users + with the appropriate <literal>SET</literal> privilege, but a + setting done that way will only persist until the end of the + client connection, so this method should be reserved for + development purposes. The recommended way to set this parameter + is in the <filename>postgresql.conf</filename> configuration + file. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-gin-fuzzy-search-limit" xreflabel="gin_fuzzy_search_limit"> + <term><varname>gin_fuzzy_search_limit</varname> (<type>integer</type>) + <indexterm> + <primary><varname>gin_fuzzy_search_limit</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Soft upper limit of the size of the set returned by GIN index scans. For more + information see <xref linkend="gin-tips"/>. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + </sect1> + + <sect1 id="runtime-config-locks"> + <title>Lock Management</title> + + <variablelist> + + <varlistentry id="guc-deadlock-timeout" xreflabel="deadlock_timeout"> + <term><varname>deadlock_timeout</varname> (<type>integer</type>) + <indexterm> + <primary>deadlock</primary> + <secondary>timeout during</secondary> + </indexterm> + <indexterm> + <primary>timeout</primary> + <secondary>deadlock</secondary> + </indexterm> + <indexterm> + <primary><varname>deadlock_timeout</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This is the amount of time to wait on a lock + before checking to see if there is a deadlock condition. The + check for deadlock is relatively expensive, so the server doesn't run + it every time it waits for a lock. We optimistically assume + that deadlocks are not common in production applications and + just wait on the lock for a while before checking for a + deadlock. Increasing this value reduces the amount of time + wasted in needless deadlock checks, but slows down reporting of + real deadlock errors. + If this value is specified without units, it is taken as milliseconds. + The default is one second (<literal>1s</literal>), + which is probably about the smallest value you would want in + practice. On a heavily loaded server you might want to raise it. + Ideally the setting should exceed your typical transaction time, + so as to improve the odds that a lock will be released before + the waiter decides to check for deadlock. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + + <para> + When <xref linkend="guc-log-lock-waits"/> is set, + this parameter also determines the amount of time to wait before + a log message is issued about the lock wait. If you are trying + to investigate locking delays you might want to set a shorter than + normal <varname>deadlock_timeout</varname>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-max-locks-per-transaction" xreflabel="max_locks_per_transaction"> + <term><varname>max_locks_per_transaction</varname> (<type>integer</type>) + <indexterm> + <primary><varname>max_locks_per_transaction</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + The shared lock table 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 and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + <para> + Setting this variable does not disable all security checks related to + large objects — only those for which the default behavior has + changed in <productname>PostgreSQL</productname> 9.0. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-quote-all-identifiers" xreflabel="quote-all-identifiers"> + <term><varname>quote_all_identifiers</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>quote_all_identifiers</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When the database generates SQL, force all identifiers to be quoted, + even if they are not (currently) keywords. This will affect the + output of <command>EXPLAIN</command> as well as the results of functions + like <function>pg_get_viewdef</function>. See also the + <option>--quote-all-identifiers</option> option of + <xref linkend="app-pgdump"/> and <xref linkend="app-pg-dumpall"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-standard-conforming-strings" xreflabel="standard_conforming_strings"> + <term><varname>standard_conforming_strings</varname> (<type>boolean</type>) + <indexterm><primary>strings</primary><secondary>standard conforming</secondary></indexterm> + <indexterm> + <primary><varname>standard_conforming_strings</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This controls whether ordinary string literals + (<literal>'...'</literal>) treat backslashes literally, as specified in + the SQL standard. + Beginning in <productname>PostgreSQL</productname> 9.1, the default is + <literal>on</literal> (prior releases defaulted to <literal>off</literal>). + Applications can check this + parameter to determine how string literals will be processed. + The presence of this parameter can also be taken as an indication + that the escape string syntax (<literal>E'...'</literal>) is supported. + Escape string syntax (<xref linkend="sql-syntax-strings-escape"/>) + should be used if an application desires + backslashes to be treated as escape characters. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-synchronize-seqscans" xreflabel="synchronize_seqscans"> + <term><varname>synchronize_seqscans</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>synchronize_seqscans</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This allows sequential scans of large tables to synchronize with each + other, so that concurrent scans read the same block at about the + same time and hence share the I/O workload. When this is enabled, + a scan might start in the middle of the table and then <quote>wrap + around</quote> the end to cover all rows, so as to synchronize with the + activity of scans already in progress. This can result in + unpredictable changes in the row ordering returned by queries that + have no <literal>ORDER BY</literal> clause. Setting this parameter to + <literal>off</literal> ensures the pre-8.3 behavior in which a sequential + scan always starts from the beginning of the table. The default + is <literal>on</literal>. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + + <sect2 id="runtime-config-compatible-clients"> + <title>Platform and Client Compatibility</title> + <variablelist> + + <varlistentry id="guc-transform-null-equals" xreflabel="transform_null_equals"> + <term><varname>transform_null_equals</varname> (<type>boolean</type>) + <indexterm><primary>IS NULL</primary></indexterm> + <indexterm> + <primary><varname>transform_null_equals</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When on, expressions of the form <literal><replaceable>expr</replaceable> = + NULL</literal> (or <literal>NULL = + <replaceable>expr</replaceable></literal>) are treated as + <literal><replaceable>expr</replaceable> IS NULL</literal>, that is, they + return true if <replaceable>expr</replaceable> evaluates to the null value, + and false otherwise. The correct SQL-spec-compliant behavior of + <literal><replaceable>expr</replaceable> = NULL</literal> is to always + return null (unknown). Therefore this parameter defaults to + <literal>off</literal>. + </para> + + <para> + However, filtered forms in <productname>Microsoft + Access</productname> generate queries that appear to use + <literal><replaceable>expr</replaceable> = NULL</literal> to test for + null values, so if you use that interface to access the database you + might want to turn this option on. Since expressions of the + form <literal><replaceable>expr</replaceable> = NULL</literal> always + return the null value (using the SQL standard interpretation), they are not + very useful and do not appear often in normal applications so + this option does little harm in practice. But new users are + frequently confused about the semantics of expressions + involving null values, so this option is off by default. + </para> + + <para> + Note that this option only affects the exact form <literal>= NULL</literal>, + not other comparison operators or other expressions + that are computationally equivalent to some expression + involving the equals operator (such as <literal>IN</literal>). + Thus, this option is not a general fix for bad programming. + </para> + + <para> + Refer to <xref linkend="functions-comparison"/> for related information. + </para> + </listitem> + </varlistentry> + + </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 and convert any placeholder values according to + those definitions. If there are any unrecognized placeholders + that begin with its extension name, warnings are issued and those + placeholders are removed. + </para> + </sect1> + + <sect1 id="runtime-config-developer"> + <title>Developer Options</title> + + <para> + The following parameters are intended for developer testing, and + should never be used on a production database. However, some of + them can be used to assist with the recovery of severely damaged + databases. As such, they have been excluded from the sample + <filename>postgresql.conf</filename> file. Note that many of these + parameters require special source compilation flags to work at all. + </para> + + <variablelist> + <varlistentry id="guc-allow-in-place-tablespaces" xreflabel="allow_in_place_tablespaces"> + <term><varname>allow_in_place_tablespaces</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>allow_in_place_tablespaces</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Allows tablespaces to be created as directories inside + <filename>pg_tblspc</filename>, when an empty location string + is provided to the <command>CREATE TABLESPACE</command> command. This + is intended to allow testing replication scenarios where primary and + standby servers are running on the same machine. Such directories + are likely to confuse backup tools that expect to find only symbolic + links in that location. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-allow-system-table-mods" xreflabel="allow_system_table_mods"> + <term><varname>allow_system_table_mods</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>allow_system_table_mods</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Allows modification of the structure of system tables as well as + certain other risky actions on system tables. This is otherwise not + allowed even for superusers. Ill-advised use of this setting can + cause irretrievable data loss or seriously corrupt the database + system. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-backtrace-functions" xreflabel="backtrace_functions"> + <term><varname>backtrace_functions</varname> (<type>string</type>) + <indexterm> + <primary><varname>backtrace_functions</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter contains a comma-separated list of C function names. + If an error is raised and the name of the internal C function where + the error happens matches a value in the list, then a backtrace is + written to the server log together with the error message. This can + be used to debug specific areas of the source code. + </para> + + <para> + Backtrace support is not available on all platforms, and the quality + of the backtraces depends on compilation options. + </para> + + <para> + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-debug-discard-caches" xreflabel="debug_discard_caches"> + <term><varname>debug_discard_caches</varname> (<type>integer</type>) + <indexterm> + <primary><varname>debug_discard_caches</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When set to <literal>1</literal>, each system catalog cache entry is + invalidated at the first possible opportunity, whether or not + anything that would render it invalid really occurred. Caching of + system catalogs is effectively disabled as a result, so the server + will run extremely slowly. Higher values run the cache invalidation + recursively, which is even slower and only useful for testing + the caching logic itself. The default value of <literal>0</literal> + selects normal catalog caching behavior. + </para> + + <para> + This parameter can be very helpful when trying to trigger + hard-to-reproduce bugs involving concurrent catalog changes, but it + is otherwise rarely needed. See the source code files + <filename>inval.c</filename> and + <filename>pg_config_manual.h</filename> for details. + </para> + + <para> + This parameter is supported when + <symbol>DISCARD_CACHES_ENABLED</symbol> was defined at compile time + (which happens automatically when using the + <application>configure</application> option + <option>--enable-cassert</option>). In production builds, its value + will always be <literal>0</literal> and attempts to set it to another + value will raise an error. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-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 id="guc-trace-locks" xreflabel="trace_locks"> + <term><varname>trace_locks</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>trace_locks</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If on, emit information about lock usage. Information dumped + includes the type of lock operation, the type of lock and the unique + identifier of the object being locked or unlocked. Also included + are bit masks for the lock types already granted on this object as + well as for the lock types awaited on this object. For each lock + type a count of the number of granted locks and waiting locks is + also dumped as well as the totals. An example of the log file output + is shown here: +<screen> +LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) + grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 + wait(0) type(AccessShareLock) +LOG: GrantLock: lock(0xb7acd844) id(24688,24696,0,0,0,1) + grantMask(2) req(1,0,0,0,0,0,0)=1 grant(1,0,0,0,0,0,0)=1 + wait(0) type(AccessShareLock) +LOG: UnGrantLock: updated: lock(0xb7acd844) id(24688,24696,0,0,0,1) + grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 + wait(0) type(AccessShareLock) +LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) + grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 + wait(0) type(INVALID) +</screen> + Details of the structure being dumped may be found in + <filename>src/include/storage/lock.h</filename>. + </para> + <para> + This parameter is only available if the <symbol>LOCK_DEBUG</symbol> + macro was defined when <productname>PostgreSQL</productname> was + compiled. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-trace-lwlocks" xreflabel="trace_lwlocks"> + <term><varname>trace_lwlocks</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>trace_lwlocks</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If on, emit information about lightweight lock usage. Lightweight + locks are intended primarily to provide mutual exclusion of access + to shared-memory data structures. + </para> + <para> + This parameter is only available if the <symbol>LOCK_DEBUG</symbol> + macro was defined when <productname>PostgreSQL</productname> was + compiled. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-trace-userlocks" xreflabel="trace_userlocks"> + <term><varname>trace_userlocks</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>trace_userlocks</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If on, emit information about user lock usage. Output is the same + as for <symbol>trace_locks</symbol>, only for advisory locks. + </para> + <para> + This parameter is only available if the <symbol>LOCK_DEBUG</symbol> + macro was defined when <productname>PostgreSQL</productname> was + compiled. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-trace-lock-oidmin" xreflabel="trace_lock_oidmin"> + <term><varname>trace_lock_oidmin</varname> (<type>integer</type>) + <indexterm> + <primary><varname>trace_lock_oidmin</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If set, do not trace locks for tables below this OID (used to avoid + output on system tables). + </para> + <para> + This parameter is only available if the <symbol>LOCK_DEBUG</symbol> + macro was defined when <productname>PostgreSQL</productname> was + compiled. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-trace-lock-table" xreflabel="trace_lock_table"> + <term><varname>trace_lock_table</varname> (<type>integer</type>) + <indexterm> + <primary><varname>trace_lock_table</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Unconditionally trace locks on this table (OID). + </para> + <para> + This parameter is only available if the <symbol>LOCK_DEBUG</symbol> + macro was defined when <productname>PostgreSQL</productname> was + compiled. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-debug-deadlocks" xreflabel="debug_deadlocks"> + <term><varname>debug_deadlocks</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>debug_deadlocks</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If set, dumps information about all current locks when a + deadlock timeout occurs. + </para> + <para> + This parameter is only available if the <symbol>LOCK_DEBUG</symbol> + macro was defined when <productname>PostgreSQL</productname> was + compiled. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-log-btree-build-stats" xreflabel="log_btree_build_stats"> + <term><varname>log_btree_build_stats</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>log_btree_build_stats</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If set, logs system resource usage statistics (memory and CPU) on + various B-tree operations. + </para> + <para> + This parameter is only available if the <symbol>BTREE_BUILD_STATS</symbol> + macro was defined when <productname>PostgreSQL</productname> was + compiled. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-wal-consistency-checking" xreflabel="wal_consistency_checking"> + <term><varname>wal_consistency_checking</varname> (<type>string</type>) + <indexterm> + <primary><varname>wal_consistency_checking</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter is intended to be used to check for bugs in the WAL + redo routines. When enabled, full-page images of any buffers modified + in conjunction with the WAL record are added to the record. + If the record is subsequently replayed, the system will first apply + each record and then test whether the buffers modified by the record + match the stored images. In certain cases (such as hint bits), minor + variations are acceptable, and will be ignored. Any unexpected + differences will result in a fatal error, terminating recovery. + </para> + + <para> + The default value of this setting is the empty string, which disables + the feature. It can be set to <literal>all</literal> to check all + records, or to a comma-separated list of resource managers to check + only records originating from those resource managers. Currently, + the supported resource managers are <literal>heap</literal>, + <literal>heap2</literal>, <literal>btree</literal>, <literal>hash</literal>, + <literal>gin</literal>, <literal>gist</literal>, <literal>sequence</literal>, + <literal>spgist</literal>, <literal>brin</literal>, and <literal>generic</literal>. + Extensions may define additional resource managers. Only superusers and users with + the appropriate <literal>SET</literal> privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-wal-debug" xreflabel="wal_debug"> + <term><varname>wal_debug</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>wal_debug</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If on, emit WAL-related debugging output. This parameter is + only available if the <symbol>WAL_DEBUG</symbol> macro was + defined when <productname>PostgreSQL</productname> was + compiled. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-ignore-checksum-failure" xreflabel="ignore_checksum_failure"> + <term><varname>ignore_checksum_failure</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>ignore_checksum_failure</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Only has effect if <xref linkend="app-initdb-data-checksums"/> are enabled. + </para> + <para> + Detection of a checksum failure during a read normally causes + <productname>PostgreSQL</productname> to report an error, aborting the current + transaction. Setting <varname>ignore_checksum_failure</varname> to on causes + the system to ignore the failure (but still report a warning), and + continue processing. This behavior may <emphasis>cause crashes, propagate + or hide corruption, or other serious problems</emphasis>. However, it may allow + you to get past the error and retrieve undamaged tuples that might still be + present in the table if the block header is still sane. If the header is + corrupt an error will be reported even if this option is enabled. The + default setting is <literal>off</literal>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-zero-damaged-pages" xreflabel="zero_damaged_pages"> + <term><varname>zero_damaged_pages</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>zero_damaged_pages</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Detection of a damaged page header normally causes + <productname>PostgreSQL</productname> to report an error, aborting the current + transaction. Setting <varname>zero_damaged_pages</varname> to on causes + the system to instead report a warning, zero out the damaged + page in memory, and continue processing. This behavior <emphasis>will destroy data</emphasis>, + namely all the rows on the damaged page. However, it does allow you to get + past the error and retrieve rows from any undamaged pages that might + be present in the table. It is useful for recovering data if + corruption has occurred due to a hardware or software error. You should + generally not set this on until you have given up hope of recovering + data from the damaged pages of a table. Zeroed-out pages are not + forced to disk so it is recommended to recreate the table or + the index before turning this parameter off again. The + default setting is <literal>off</literal>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-ignore-invalid-pages" xreflabel="ignore_invalid_pages"> + <term><varname>ignore_invalid_pages</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>ignore_invalid_pages</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If set to <literal>off</literal> (the default), detection of + WAL records having references to invalid pages during + recovery causes <productname>PostgreSQL</productname> to + raise a PANIC-level error, aborting the recovery. Setting + <varname>ignore_invalid_pages</varname> to <literal>on</literal> + causes the system to ignore invalid page references in WAL records + (but still report a warning), and continue the recovery. + This behavior may <emphasis>cause crashes, data loss, + propagate or hide corruption, or other serious problems</emphasis>. + However, it may allow you to get past the PANIC-level error, + to finish the recovery, and to cause the server to start up. + The parameter can only be set at server start. It only has effect + during recovery or in standby mode. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit-debugging-support" xreflabel="jit_debugging_support"> + <term><varname>jit_debugging_support</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>jit_debugging_support</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If LLVM has the required functionality, register generated functions + with <productname>GDB</productname>. This makes debugging easier. + The default setting is <literal>off</literal>. + This parameter can only be set at server start. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit-dump-bitcode" xreflabel="jit_dump_bitcode"> + <term><varname>jit_dump_bitcode</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>jit_dump_bitcode</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Writes the generated <productname>LLVM</productname> IR out to the + file system, inside <xref linkend="guc-data-directory"/>. This is only + useful for working on the internals of the JIT implementation. + The default setting is <literal>off</literal>. + Only superusers and users with the appropriate <literal>SET</literal> + privilege can change this setting. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit-expressions" xreflabel="jit_expressions"> + <term><varname>jit_expressions</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>jit_expressions</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Determines whether expressions are JIT compiled, when JIT compilation + is activated (see <xref linkend="jit-decision"/>). The default is + <literal>on</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit-profiling-support" xreflabel="jit_profiling_support"> + <term><varname>jit_profiling_support</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>jit_profiling_support</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + If LLVM has the required functionality, emit the data needed to allow + <productname>perf</productname> to profile functions generated by JIT. + This writes out files to <filename>~/.debug/jit/</filename>; the + user is responsible for performing cleanup when desired. + The default setting is <literal>off</literal>. + This parameter can only be set at server start. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-jit-tuple-deforming" xreflabel="jit_tuple_deforming"> + <term><varname>jit_tuple_deforming</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>jit_tuple_deforming</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Determines whether tuple deforming is JIT compiled, when JIT + compilation is activated (see <xref linkend="jit-decision"/>). + The default is <literal>on</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-remove-temp-files-after-crash" xreflabel="remove_temp_files_after_crash"> + <term><varname>remove_temp_files_after_crash</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>remove_temp_files_after_crash</varname> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + When set to <literal>on</literal>, which is the default, + <productname>PostgreSQL</productname> will automatically remove + temporary files after a backend crash. If disabled, the files will be + retained and may be used for debugging, for example. Repeated crashes + may however result in accumulation of useless files. This parameter + can only be set in the <filename>postgresql.conf</filename> file or on + the server command line. + </para> + </listitem> + </varlistentry> + + </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> |