From 9813fc1bae21e4027a72d88fcb0528922150d457 Mon Sep 17 00:00:00 2001
From: Neil Conway <neilc@samurai.com>
Date: Mon, 12 Sep 2005 22:11:38 +0000
Subject: [PATCH] Make the documentation of GUC variables a separate chapter,
rather than a section of the "Server Run-time Environment" chapter. Also,
move the SGML for the new chapter to a separate file and fix the resulting
fallout.
---
doc/src/sgml/config.sgml | 4238 ++++++++++++++++++++++++++++++++++++
doc/src/sgml/filelist.sgml | 3 +-
doc/src/sgml/postgres.sgml | 3 +-
doc/src/sgml/runtime.sgml | 4220 +----------------------------------
4 files changed, 4243 insertions(+), 4221 deletions(-)
create mode 100644 doc/src/sgml/config.sgml
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
new file mode 100644
index 00000000000..de5e71eb42a
--- /dev/null
+++ b/doc/src/sgml/config.sgml
@@ -0,0 +1,4238 @@
+<!--
+$PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.13 2005/09/12 22:11:38 neilc Exp $
+-->
+<chapter Id="runtime-config">
+ <title>Run-time 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 set configuration chapters. The subsequent sections
+ discuss each parameter in detail.
+ </para>
+
+ <sect1 id="config-setting">
+ <title>Setting Parameters</title>
+
+ <para>
+ All parameter names are case-insensitive. Every parameter takes a
+ value of one of four types: boolean, integer, floating point,
+ or string. Boolean values may be written as <literal>ON</literal>,
+ <literal>OFF</literal>, <literal>TRUE</literal>,
+ <literal>FALSE</literal>, <literal>YES</literal>,
+ <literal>NO</literal>, <literal>1</literal>, <literal>0</literal>
+ (all case-insensitive) or any unambiguous prefix of these.
+ </para>
+
+ <para>
+ One way to set these parameters is to edit the file
+ <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
+ which is normally kept in the data directory. (<command>initdb</>
+ installs a default copy there.) 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'
+</programlisting>
+ One parameter is specified per line. The equal sign between name and
+ value is optional. Whitespace is insignificant and blank lines are
+ ignored. Hash marks (<literal>#</literal>) introduce comments
+ anywhere. Parameter values that are not simple identifiers or
+ numbers must be single-quoted.
+ </para>
+
+ <para>
+ <indexterm>
+ <primary>SIGHUP</primary>
+ </indexterm>
+ The configuration file is reread whenever the
+ <command>postmaster</command> process receives a
+ <systemitem>SIGHUP</> signal (which is most easily sent by means
+ of <literal>pg_ctl reload</>). The <command>postmaster</command>
+ also propagates this signal to all currently running server
+ processes so that existing sessions also get the new
+ value. 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.
+ </para>
+
+ <para>
+ A second way to set these configuration parameters is to give them
+ as a command line option to the <command>postmaster</command>, such as:
+<programlisting>
+postmaster -c log_connections=yes -c log_destination='syslog'
+</programlisting>
+ Command-line options override any conflicting settings in
+ <filename>postgresql.conf</filename>. Note that this means you won't
+ be able to change the value on-the-fly by editing
+ <filename>postgresql.conf</filename>, so while the command-line
+ method may be convenient, it can cost you flexibility later.
+ </para>
+
+ <para>
+ Occasionally it is useful to give a command line option to
+ one particular session only. The environment variable
+ <envar>PGOPTIONS</envar> can be used for this purpose on the
+ client side:
+<programlisting>
+env PGOPTIONS='-c geqo=off' psql
+</programlisting>
+ (This works for any <application>libpq</>-based client application, not
+ just <application>psql</application>.) Note that this won't work for
+ parameters that are fixed when the server is started or that must be
+ specified in <filename>postgresql.conf</filename>.
+ </para>
+
+ <para>
+ Furthermore, it is possible to assign a set of option settings to
+ a user or a database. Whenever a session is started, the default
+ settings for the user and database involved are loaded. The
+ commands <xref linkend="sql-alteruser" endterm="sql-alteruser-title">
+ and <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">,
+ respectively, are used to configure these settings. Per-database
+ settings override anything received from the
+ <command>postmaster</command> command-line or the configuration
+ file, and in turn are overridden by per-user settings; both are
+ overridden by per-session options.
+ </para>
+
+ <para>
+ Some parameters can be changed in individual <acronym>SQL</acronym>
+ sessions with the <xref linkend="SQL-SET" endterm="SQL-SET-title">
+ command, for example:
+<screen>
+SET ENABLE_SEQSCAN TO OFF;
+</screen>
+ If <command>SET</> is allowed, it overrides all other sources of
+ values for the parameter. Some parameters cannot be changed via
+ <command>SET</command>: for example, if they control behavior that
+ cannot reasonably be changed without restarting
+ <productname>PostgreSQL</productname>. Also, some parameters can
+ be modified via <command>SET</command> or <command>ALTER</> by superusers,
+ but not by ordinary users.
+ </para>
+
+ <para>
+ The <xref linkend="SQL-SHOW" endterm="SQL-SHOW-title">
+ command allows inspection of the current values of all parameters.
+ </para>
+
+ <para>
+ The virtual table <structname>pg_settings</structname>
+ (described in <xref linkend="view-pg-settings">) also allows
+ displaying and updating session run-time parameters. It is equivalent
+ to <command>SHOW</> and <command>SET</>, but can be more convenient
+ to use because it can be joined with other tables, or selected from using
+ any desired selection condition.
+ </para>
+ </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 options 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>)</term>
+ <indexterm>
+ <primary><varname>data_directory</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the directory to use for data storage.
+ This option 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>)</term>
+ <indexterm>
+ <primary><varname>config_file</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the main server configuration file
+ (customarily called <filename>postgresql.conf</>).
+ This option can only be set on the postmaster command line.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-hba-file" xreflabel="hba_file">
+ <term><varname>hba_file</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>hba_file</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the configuration file for host-based authentication
+ (customarily called <filename>pg_hba.conf</>).
+ This option 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>)</term>
+ <indexterm>
+ <primary><varname>ident_file</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the configuration file for
+ <application>ident</> authentication
+ (customarily called <filename>pg_ident.conf</>).
+ This option can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-external-pid-file" xreflabel="external_pid_file">
+ <term><varname>external_pid_file</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>external_pid_file</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the name of an additional process-id (PID) file that the
+ <application>postmaster</> should create for use by server
+ administration programs.
+ This option can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ In a default installation, none of the above options 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 postmaster's <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</> option 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</> 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 options <varname>config_file</>,
+ <varname>hba_file</> and/or <varname>ident_file</>.
+ <varname>config_file</> can only be specified on the
+ <command>postmaster</command> command line, but the others can be
+ set within the main configuration file. If all three options plus
+ <varname>data_directory</> are explicitly set, then it is not necessary
+ to specify <option>-D</option> or <envar>PGDATA</envar>.
+ </para>
+
+ <para>
+ When setting any of these options, a relative path will be interpreted
+ with respect to the directory in which the <command>postmaster</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>)</term>
+ <indexterm>
+ <primary><varname>listen_addresses</> configuration parameter</primary>
+ </indexterm>
+ <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>*</>
+ corresponds to all available IP interfaces.
+ If the list is empty, the server does not listen on any IP interface
+ at all, in which case only Unix-domain sockets can be used to connect
+ to it.
+ The default value is <systemitem class="systemname">localhost</>,
+ which allows only local <quote>loopback</> connections to be made.
+ 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>)</term>
+ <indexterm>
+ <primary><varname>port</> configuration parameter</primary>
+ </indexterm>
+ <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>)</term>
+ <indexterm>
+ <primary><varname>max_connections</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Determines the maximum number of concurrent connections to the
+ database server. The default is typically 100, but may be less
+ if your kernel settings will not support it (as determined
+ during <application>initdb</>). This parameter can only be
+ set at server start.
+ </para>
+
+ <para>
+ Increasing this parameter may cause <productname>PostgreSQL</>
+ to request more <systemitem class="osname">System V</> shared
+ memory or semaphores than your operating system's default configuration
+ allows. See <xref linkend="sysvipc"> for information on how to
+ adjust those parameters, if necessary.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-superuser-reserved-connections"
+ xreflabel="superuser_reserved_connections">
+ <term><varname>superuser_reserved_connections</varname>
+ (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>superuser_reserved_connections</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Determines the number of connection <quote>slots</quote> that
+ are reserved for connections by <productname>PostgreSQL</>
+ 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</> minus
+ <varname>superuser_reserved_connections</varname>, new
+ connections will be accepted only for superusers.
+ </para>
+
+ <para>
+ The default value is 2. The value must be less than the value of
+ <varname>max_connections</varname>. This parameter can only be
+ set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-unix-socket-directory" xreflabel="unix_socket_directory">
+ <term><varname>unix_socket_directory</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>unix_socket_directory</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the directory of the Unix-domain socket on which the
+ server is to listen for
+ connections from client applications. The default is normally
+ <filename>/tmp</filename>, but can be changed at build time.
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-unix-socket-group" xreflabel="unix_socket_group">
+ <term><varname>unix_socket_group</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>unix_socket_group</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the owning group of the Unix-domain socket. (The owning
+ user of the socket is always the user that starts the
+ server.) In combination with the option
+ <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 for the current user. This option can only be set at
+ server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-unix-socket-permissions" xreflabel="unix_socket_permissions">
+ <term><varname>unix_socket_permissions</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>unix_socket_permissions</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the access permissions of the Unix-domain socket. Unix-domain
+ sockets use the usual Unix file system permission set.
+ The option value is expected to be a numeric mode
+ specification in the form 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 and 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 option 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>)</term>
+ <indexterm>
+ <primary><varname>bonjour_name</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the <productname>Bonjour</productname> broadcast
+ name. By default, the computer name is used, specified as an
+ empty string ''. This option is ignored if the server was not
+ compiled with <productname>Bonjour</productname> support. This
+ option 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>)</term>
+ <indexterm>
+ <primary><varname>tcp_keepalives_idle</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ On systems that support the TCP_KEEPIDLE socket option, specifies the
+ number of seconds between sending keepalives on an otherwise idle
+ connection. A value of 0 uses the system default. If TCP_KEEPIDLE is
+ not supported, this parameter must be 0. This option is ignored for
+ connections made via a Unix-domain socket.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-tcp-keepalives-interval" xreflabel="tcp_keepalives_interval">
+ <term><varname>tcp_keepalives_interval</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>tcp_keepalives_interval</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ On systems that support the TCP_KEEPINTVL socket option, specifies how
+ long, in seconds, to wait for a response to a keepalive before
+ retransmitting. A value of 0 uses the system default. If TCP_KEEPINTVL
+ is not supported, this parameter must be 0. This option is ignored
+ for connections made via a Unix-domain socket.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-tcp-keepalives-count" xreflabel="tcp_keepalives_count">
+ <term><varname>tcp_keepalives_count</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>tcp_keepalives_count</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ On systems that support the TCP_KEEPCNT socket option, specifies how
+ many keepalives may be lost before the connection is considered dead.
+ A value of 0 uses the system default. If TCP_KEEPINTVL is not
+ supported, this parameter must be 0.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+ <sect2 id="runtime-config-connection-security">
+ <title>Security and Authentication</title>
+
+ <variablelist>
+ <varlistentry id="guc-authentication-timeout" xreflabel="authentication_timeout">
+ <term><varname>authentication_timeout</varname> (<type>integer</type>)</term>
+ <indexterm><primary>timeout</><secondary>client authentication</></indexterm>
+ <indexterm><primary>client authentication</><secondary>timeout during</></indexterm>
+ <indexterm>
+ <primary><varname>authentication_timeout</> configuration parameter</primary>
+ </indexterm>
+
+ <listitem>
+ <para>
+ Maximum time to complete client authentication, in seconds. If a
+ would-be client has not completed the authentication protocol in
+ this much time, the server breaks the connection. This prevents
+ hung clients from occupying a connection indefinitely. This
+ option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file. The default is 60.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-ssl" xreflabel="ssl">
+ <term><varname>ssl</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>ssl</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables <acronym>SSL</> connections. Please read
+ <xref linkend="ssl-tcp"> before using this. The default
+ is <literal>off</>. This parameter can only be set at server
+ start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-password-encryption" xreflabel="password_encryption">
+ <term><varname>password_encryption</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>password_encryption</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When a password is specified in <xref
+ linkend="sql-createuser" endterm="sql-createuser-title"> or
+ <xref linkend="sql-alteruser" endterm="sql-alteruser-title">
+ without writing either <literal>ENCRYPTED</> or
+ <literal>UNENCRYPTED</>, this option determines whether the
+ password is to be encrypted. The default is <literal>on</>
+ (encrypt the password).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-krb-server-keyfile" xreflabel="krb_server_keyfile">
+ <term><varname>krb_server_keyfile</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>krb_server_keyfile</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the location of the Kerberos server key file. See
+ <xref linkend="kerberos-auth"> for details. This parameter
+ can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-krb-srvname" xreflabel="krb_srvname">
+ <term><varname>krb_srvname</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>krb_srvname</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the Kerberos service name. See <xref linkend="kerberos-auth">
+ for details. This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-krb-server-hostname" xreflabel="krb_server_hostname">
+ <term><varname>krb_server_hostname</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>krb_server_hostname</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the hostname part of the service principal.
+ This, combined with <varname>krb_srvname</>, is used to generate
+ the complete service principal, i.e.
+ <varname>krb_server_hostname</><literal>/</><varname>krb_server_hostname</><literal>@</>REALM.
+ </para>
+ <para>
+ If not set, the default is to allow any service principal matching an entry
+ in the keytab. See <xref linkend="kerberos-auth"> for details.
+ This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-krb-caseins-users" xreflabel="krb_caseins_users">
+ <term><varname>krb_caseins_users</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>krb_caseins_users</varname> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets if Kerberos usernames should be treated case-insensitively.
+ The default is <literal>off</> (case sensitive). This parameter
+ can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-db-user-namespace" xreflabel="db_user_namespace">
+ <term><varname>db_user_namespace</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>db_user_namespace</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ This enables per-database user names. It is off by default.
+ </para>
+
+ <para>
+ If this is on, you should create users as <literal>username@dbname</>.
+ When <literal>username</> is passed by a connecting client,
+ <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>@</> within the SQL environment, you will need to
+ quote the user name.
+ </para>
+
+ <para>
+ With this option enabled, you can still create ordinary global
+ users. Simply append <literal>@</> when specifying the user
+ name in the client. The <literal>@</> will be stripped off
+ before the user name is looked up by the server.
+ </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>
+ </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>)</term>
+ <indexterm>
+ <primary><varname>shared_buffers</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the number of shared memory buffers used by the database
+ server. The default is typically 1000, but may be less if your
+ kernel settings will not support it (as determined during
+ <application>initdb</>). Each buffer is 8192 bytes, unless a
+ different value of <symbol>BLCKSZ</symbol> was chosen when building
+ the server. This setting must be at least 16, as well as at
+ least twice the value of <xref linkend="guc-max-connections">;
+ however, settings significantly higher than the minimum are
+ usually needed for good performance. Values of a few thousand
+ are recommended for production installations. This option can
+ only be set at server start.
+ </para>
+
+ <para>
+ Increasing this parameter may cause <productname>PostgreSQL</>
+ to request more <systemitem class="osname">System V</> shared
+ memory than your operating system's default configuration
+ allows. See <xref linkend="sysvipc"> for information on how to
+ adjust those parameters, if necessary.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-temp-buffers" xreflabel="temp_buffers">
+ <term><varname>temp_buffers</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>temp_buffers</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the maximum number of temporary buffers used by each database
+ session. These are session-local buffers used only for access
+ to temporary tables. The default is 1000. The setting can
+ be changed within individual sessions, but only up until the
+ first use of temporary tables within a 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</>. The cost of setting a large
+ value in sessions that do not actually need a lot of temporary
+ buffers is only a buffer descriptor, or about 64 bytes, per
+ increment in <varname>temp_buffers</>. 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>)</term>
+ <indexterm>
+ <primary><varname>max_prepared_transactions</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the maximum number of transactions that can be in the
+ <quote>prepared</> state simultaneously (see <xref
+ linkend="sql-prepare-transaction"
+ endterm="sql-prepare-transaction-title">).
+ Setting this parameter to zero disables the prepared-transaction
+ feature.
+ The default is 5.
+ This option can only be set at server start.
+ </para>
+
+ <para>
+ If you are not using prepared transactions, this parameter may as
+ well be set to zero. If you are using them, you will probably
+ want <varname>max_prepared_transactions</varname> to be at least
+ as large as <xref linkend="guc-max-connections">, to avoid unwanted
+ failures at the prepare step.
+ </para>
+
+ <para>
+ Increasing this parameter may cause <productname>PostgreSQL</>
+ to request more <systemitem class="osname">System V</> shared
+ memory than your operating system's default configuration
+ allows. See <xref linkend="sysvipc"> for information on how to
+ adjust those parameters, if necessary.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-work-mem" xreflabel="work_mem">
+ <term><varname>work_mem</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>work_mem</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the amount of memory to be used by internal sort operations
+ and hash tables before switching to temporary disk files. The value is
+ specified in kilobytes, and defaults to 1024 kilobytes (1 MB).
+ Note that for a complex query, several sort or hash operations might be
+ running in parallel; each one will be allowed to use as much memory
+ as this value specifies before it starts to put data into temporary
+ files. Also, several running sessions could be doing such operations
+ concurrently. So 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>DISTINCT</>, and
+ merge joins.
+ Hash tables are used in hash joins, hash-based aggregation, and
+ hash-based processing of <literal>IN</> subqueries.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-maintenance-work-mem" xreflabel="maintenance_work_mem">
+ <term><varname>maintenance_work_mem</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>maintenance_work_mem</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the maximum amount of memory to be used in maintenance
+ operations, such as <command>VACUUM</command>, <command>CREATE
+ INDEX</>, and <command>ALTER TABLE ADD FOREIGN KEY</>.
+ The value is specified in kilobytes, and defaults to 16384 kilobytes
+ (16 MB). Since only one of these operations can be executed at
+ a time by a database session, and an installation normally doesn't
+ have very many of them happening concurrently, it's safe to set this
+ value significantly larger than <varname>work_mem</varname>. Larger
+ settings may improve performance for vacuuming and for restoring
+ database dumps.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-max-stack-depth" xreflabel="max_stack_depth">
+ <term><varname>max_stack_depth</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>max_stack_depth</> configuration parameter</primary>
+ </indexterm>
+ <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</> 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
+ such as expression evaluation. Setting the parameter higher than
+ the actual kernel limit will mean that a runaway recursive function
+ can crash an individual backend process. The default setting is
+ 2048 KB (two megabytes), which is conservatively small and unlikely
+ to risk crashes. However, it may be too small to allow execution
+ of complex functions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+ <sect2 id="runtime-config-resource-fsm">
+ <title>Free Space Map</title>
+
+ <indexterm>
+ <primary>free space map</primary>
+ </indexterm>
+
+ <para>
+ These parameters control the size of the shared <firstterm>free space
+ map</>, which tracks the locations of unused space in the database.
+ An undersized free space map may cause the database to consume
+ increasing amounts of disk space over time, because free space that
+ is not in the map cannot be re-used; instead <productname>PostgreSQL</>
+ will request more disk space from the operating system when it needs
+ to store new data.
+ The last few lines displayed by a database-wide <command>VACUUM VERBOSE</>
+ command can help in determining if the current settings are adequate.
+ A <literal>NOTICE</> message is also printed during such an operation
+ if the current settings are too low.
+ </para>
+
+ <para>
+ Increasing these parameters may cause <productname>PostgreSQL</>
+ to request more <systemitem class="osname">System V</> shared
+ memory than your operating system's default configuration
+ allows. See <xref linkend="sysvipc"> for information on how to
+ adjust those parameters, if necessary.
+ </para>
+
+ <variablelist>
+ <varlistentry id="guc-max-fsm-pages" xreflabel="max_fsm_pages">
+ <term><varname>max_fsm_pages</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>max_fsm_pages</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the maximum number of disk pages for which free space will
+ be tracked in the shared free-space map. Six bytes of shared memory
+ are consumed for each page slot. This setting must be more than
+ 16 * <varname>max_fsm_relations</varname>. The default is 20000.
+ This option can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-max-fsm-relations" xreflabel="max_fsm_relations">
+ <term><varname>max_fsm_relations</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>max_fsm_relations</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the maximum number of relations (tables and indexes) for which
+ free space will be tracked in the shared free-space map. Roughly
+ seventy bytes of shared memory are consumed for each slot.
+ The default is 1000.
+ This option can only be set at server start.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>max_files_per_process</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the maximum number of simultaneously open files allowed to each
+ server subprocess. The default is 1000. 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 really support when a large number of processes all try to open
+ that many files. If you find yourself seeing <quote>Too many open
+ files</> failures, try reducing this setting.
+ This option can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-preload-libraries" xreflabel="preload_libraries">
+ <term><varname>preload_libraries</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>preload_libraries</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ This variable specifies one or more shared libraries that are
+ to be preloaded at server start. A parameterless
+ initialization function can optionally be called for each
+ library. To specify that, add a colon and the name of the
+ initialization function after the library name. For example
+ <literal>'$libdir/mylib:mylib_init'</literal> would cause
+ <literal>mylib</> to be preloaded and <literal>mylib_init</>
+ to be executed. If more than one library is to be loaded,
+ separate their names with commas.
+ </para>
+
+ <para>
+ If a specified library or initialization function is not found,
+ the server will fail to start.
+ </para>
+
+ <para>
+ <productname>PostgreSQL</productname> procedural language
+ libraries may be preloaded in this way, typically by using the
+ syntax <literal>'$libdir/plXXX:plXXX_init'</literal> where
+ <literal>XXX</literal> is <literal>pgsql</>, <literal>perl</>,
+ <literal>tcl</>, or <literal>python</>.
+ </para>
+
+ <para>
+ By preloading a shared library (and initializing it if
+ applicable), the library startup time is avoided when the
+ library is first used. However, the time to start each new
+ server process may increase slightly, even if that process never
+ uses the library. So this option is recommended only for
+ libraries that will be used in most sessions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+
+ <sect2 id="runtime-config-resource-vacuum-cost">
+ <title id="runtime-config-resource-vacuum-cost-title">
+ Cost-Based Vacuum Delay
+ </title>
+
+ <para>
+ During the execution of <xref linkend="sql-vacuum"
+ endterm="sql-vacuum-title"> and <xref linkend="sql-analyze"
+ endterm="sql-analyze-title"> 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 while (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 in which it is not very
+ 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. 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>integer</type>)</term>
+ <indexterm>
+ <primary><varname>vacuum_cost_delay</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ The length of time, in milliseconds, that the process will sleep
+ when the cost limit has been exceeded.
+ The default value is 0, which disables the cost-based vacuum
+ delay feature. Positive values enable cost-based vacuuming.
+ Note that on many systems, the effective resolution
+ of sleep delays is 10 milliseconds; setting
+ <varname>vacuum_cost_delay</varname> to a value that is
+ not a multiple of 10 may have the same results as setting it
+ to the next higher multiple of 10.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>vacuum_cost_page_hit</> configuration parameter</primary>
+ </indexterm>
+ <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 1.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>vacuum_cost_page_miss</> configuration parameter</primary>
+ </indexterm>
+ <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 10.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>vacuum_cost_page_dirty</> configuration parameter</primary>
+ </indexterm>
+ <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>)</term>
+ <indexterm>
+ <primary><varname>vacuum_cost_limit</> configuration parameter</primary>
+ </indexterm>
+ <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>
+ Beginning in <productname>PostgreSQL</> 8.0, there is a separate server
+ process called the <firstterm>background writer</>, whose sole function
+ is to issue writes of <quote>dirty</> shared buffers. The intent is
+ that server processes handling user queries should seldom or never have
+ to wait for a write to occur, because the background writer will do it.
+ This arrangement also reduces the performance penalty associated with
+ checkpoints. The background writer will continuously trickle out dirty
+ pages to disk, so that only a few pages will need to be forced out when
+ checkpoint time arrives, instead of the storm of dirty-buffer writes that
+ formerly occurred at each checkpoint. However there is a net overall
+ increase in I/O load, because where a repeatedly-dirtied page might
+ before have been written only once per checkpoint interval, the
+ background writer might write it several times in the same interval.
+ In most situations a continuous low load is preferable to periodic
+ spikes, but 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>)</term>
+ <indexterm>
+ <primary><varname>bgwriter_delay</> configuration parameter</primary>
+ </indexterm>
+ <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 <varname>bgwriter_delay</>
+ milliseconds, and repeats. The default value is 200. Note
+ that on many systems, the effective resolution of sleep
+ delays is 10 milliseconds; setting <varname>bgwriter_delay</>
+ to a value that is not a multiple of 10 may have the same
+ results as setting it to the next higher multiple of 10.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-bgwriter-lru-percent" xreflabel="bgwriter_lru_percent">
+ <term><varname>bgwriter_lru_percent</varname> (<type>floating point</type>)</term>
+ <indexterm>
+ <primary><varname>bgwriter_lru_percent</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ To reduce the probability that server processes will need to issue
+ their own writes, the background writer tries to write buffers that
+ are likely to be recycled soon. In each round, it examines up to
+ <varname>bgwriter_lru_percent</> of the buffers that are nearest to
+ being recycled, and writes any that are dirty.
+ The default value is 1.0 (this is a percentage of the total number
+ of shared buffers).
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-bgwriter-lru-maxpages" xreflabel="bgwriter_lru_maxpages">
+ <term><varname>bgwriter_lru_maxpages</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>bgwriter_lru_maxpages</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ In each round, no more than this many buffers will be written
+ as a result of scanning soon-to-be-recycled buffers.
+ The default value is 5.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-bgwriter-all-percent" xreflabel="bgwriter_all_percent">
+ <term><varname>bgwriter_all_percent</varname> (<type>floating point</type>)</term>
+ <indexterm>
+ <primary><varname>bgwriter_all_percent</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ To reduce the amount of work that will be needed at checkpoint time,
+ the background writer also does a circular scan through the entire
+ buffer pool, writing buffers that are found to be dirty.
+ In each round, it examines up to
+ <varname>bgwriter_all_percent</> of the buffers for this purpose.
+ The default value is 0.333 (this is a percentage of the total number
+ of shared buffers). With the default <varname>bgwriter_delay</>
+ setting, this will allow the entire shared buffer pool to be scanned
+ about once per minute.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-bgwriter-all-maxpages" xreflabel="bgwriter_all_maxpages">
+ <term><varname>bgwriter_all_maxpages</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>bgwriter_all_maxpages</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ In each round, no more than this many buffers will be written
+ as a result of the scan of the entire buffer pool. (If this
+ limit is reached, the scan stops, and resumes at the next buffer
+ during the next round.)
+ The default value is 5.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Smaller values of <varname>bgwriter_all_percent</varname> and
+ <varname>bgwriter_all_maxpages</varname> reduce the extra I/O load
+ caused by the background writer, but leave more work to be done
+ at checkpoint time. To reduce load spikes at checkpoints,
+ increase these two values.
+ Similarly, smaller values of <varname>bgwriter_lru_percent</varname> and
+ <varname>bgwriter_lru_maxpages</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.
+ To disable background writing entirely,
+ set both <varname>maxpages</varname> values and/or both
+ <varname>percent</varname> values to zero.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="runtime-config-wal">
+ <title>Write Ahead Log</title>
+
+ <para>
+ See also <xref linkend="wal-configuration"> for details on WAL
+ tuning.
+ </para>
+
+ <sect2 id="runtime-config-wal-settings">
+ <title>Settings</title>
+ <variablelist>
+
+ <varlistentry id="guc-fsync" xreflabel="fsync">
+ <indexterm>
+ <primary><varname>fsync</> configuration parameter</primary>
+ </indexterm>
+ <term><varname>fsync</varname> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ If this option is on, the <productname>PostgreSQL</> server
+ will use the <function>fsync()</> system call in several places
+ to make sure that updates are physically written to disk. This
+ insures that a database cluster will recover to a
+ consistent state after an operating system or hardware crash.
+ </para>
+
+ <para>
+ However, using <function>fsync()</function> results in a
+ performance penalty: when a transaction is committed,
+ <productname>PostgreSQL</productname> must wait for the
+ operating system to flush the write-ahead log to disk. When
+ <varname>fsync</varname> is disabled, the operating system is
+ allowed to do its best in buffering, ordering, and delaying
+ writes. This can result in significantly improved performance.
+ However, if the system crashes, the results of the last few
+ committed transactions may be lost in part or whole. In the
+ worst case, unrecoverable data corruption may occur.
+ (Crashes of the database server itself are <emphasis>not</>
+ a risk factor here. Only an operating-system-level crash
+ creates a risk of corruption.)
+ </para>
+
+ <para>
+ Due to the risks involved, there is no universally correct
+ setting for <varname>fsync</varname>. Some administrators
+ always disable <varname>fsync</varname>, while others only
+ turn it off for bulk loads, where there is a clear restart
+ point if something goes wrong, whereas some administrators
+ always leave <varname>fsync</varname> enabled. The default is
+ to enable <varname>fsync</varname>, for maximum reliability.
+ If you trust your operating system, your hardware, and your
+ utility company (or your battery backup), you can consider
+ disabling <varname>fsync</varname>.
+ </para>
+
+ <para>
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file. If this option
+ is <literal>off</>, consider also turning off
+ <varname>guc-full-page-writes</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-wal-sync-method" xreflabel="wal_sync_method">
+ <term><varname>wal_sync_method</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>wal_sync_method</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Method used for forcing WAL updates out to disk. Possible
+ values are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>open_datasync</> (write WAL files with <function>open()</> option <symbol>O_DSYNC</>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fdatasync</> (call <function>fdatasync()</> at each commit),
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fsync</> (call <function>fsync()</> at each commit)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fsync_writethrough</> (force write-through of any disk write cache)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>open_sync</> (write WAL files with <function>open()</> option <symbol>O_SYNC</>)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Not all of these choices are available on all platforms.
+ The top-most supported option is used as the default.
+ If <varname>fsync</varname> is off then this setting is irrelevant.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-full-page-writes" xreflabel="full_page_writes">
+ <indexterm>
+ <primary><varname>full_page_writes</> configuration parameter</primary>
+ </indexterm>
+ <term><varname>full_page_writes</varname> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ A page write in process during an operating system crash might
+ be only partially written to disk, leading to an on-disk page
+ that contains a mix of old and new data. During recovery, the
+ row changes stored in WAL are not enough to completely restore
+ the page.
+ </para>
+
+ <para>
+ When this option is on, the <productname>PostgreSQL</> server
+ writes full pages to WAL when they are first modified after a
+ checkpoint so full recovery is possible. Turning this option off
+ might lead to a corrupt system after an operating system crash
+ or power failure because uncorrected partial pages might contain
+ inconsistent or corrupt data. The risks are less but similar to
+ <varname>fsync</>.
+ </para>
+
+ <para>
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file. The default is
+ <literal>on</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-wal-buffers" xreflabel="wal_buffers">
+ <term><varname>wal_buffers</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>wal_buffers</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Number of disk-page buffers allocated in shared memory for WAL data.
+ The default is 8. The setting need only be large enough to hold
+ the amount of WAL data generated by one typical transaction, since
+ the data is flushed to disk at every transaction commit.
+ This option can only be set at server start.
+ </para>
+
+ <para>
+ Increasing this parameter may cause <productname>PostgreSQL</>
+ to request more <systemitem class="osname">System V</> shared
+ memory than your operating system's default configuration
+ allows. See <xref linkend="sysvipc"> for information on how to
+ adjust those parameters, if necessary.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-commit-delay" xreflabel="commit_delay">
+ <term><varname>commit_delay</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>commit_delay</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Time delay between writing a commit record to the WAL buffer
+ and flushing the buffer out to disk, in microseconds. A
+ nonzero delay can allow multiple transactions to be committed
+ with only one <function>fsync()</function> system call, if
+ system load is high enough that additional transactions become
+ ready to commit within the given interval. But the delay is
+ just wasted if no other transactions become ready to
+ commit. Therefore, the delay is only performed if at least
+ <varname>commit_siblings</varname> other transactions are
+ active at the instant that a server process has written its
+ commit record. The default is zero (no delay).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-commit-siblings" xreflabel="commit_siblings">
+ <term><varname>commit_siblings</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>commit_siblings</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Minimum number of concurrent open transactions to require
+ before performing the <varname>commit_delay</> 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+ <sect2 id="runtime-config-wal-checkpoints">
+ <title>Checkpoints</title>
+
+ <variablelist>
+ <varlistentry id="guc-checkpoint-segments" xreflabel="checkpoint_segments">
+ <term><varname>checkpoint_segments</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>checkpoint_segments</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Maximum distance between automatic WAL checkpoints, in log
+ file segments (each segment is normally 16 megabytes). The
+ default is three. This option can only be set at server start
+ or in the <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-checkpoint-timeout" xreflabel="checkpoint_timeout">
+ <term><varname>checkpoint_timeout</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>checkpoint_timeout</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Maximum time between automatic WAL checkpoints, in
+ seconds. The default is 300 seconds. This option can only be
+ set at server start or in the <filename>postgresql.conf</>
+ file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-checkpoint-warning" xreflabel="checkpoint_warning">
+ <term><varname>checkpoint_warning</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>checkpoint_warning</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Write a message to the server log if checkpoints caused by
+ the filling of checkpoint segment files happen closer together
+ than this many seconds. The default is 30 seconds.
+ Zero turns off the warning.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+ <sect2 id="runtime-config-wal-archiving">
+ <title>Archiving</title>
+
+ <variablelist>
+ <varlistentry id="guc-archive-command" xreflabel="archive_command">
+ <term><varname>archive_command</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>archive_command</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ The shell command to execute to archive a completed segment of
+ the WAL file series. If this is an empty string (the default),
+ WAL archiving is disabled. Any <literal>%p</> in the string is
+ replaced by the absolute path of the file to archive, and any
+ <literal>%f</> is replaced by the file name only. Use
+ <literal>%%</> to embed an actual <literal>%</> character in the
+ command. For more information see <xref
+ linkend="backup-archiving-wal">. This option can only be set at
+ server start or in the <filename>postgresql.conf</filename>
+ file.
+ </para>
+ <para>
+ It is important for the command to return a zero exit status if
+ and only if it succeeds. Examples:
+<programlisting>
+archive_command = 'cp "%p" /mnt/server/archivedir/"%f"'
+archive_command = 'copy "%p" /mnt/server/archivedir/"%f"' # Windows
+</programlisting>
+ </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 temporary solution may be found by using one
+ of these configuration parameters to force the optimizer to
+ choose a different plan. Turning one of these settings off
+ permanently is seldom a good idea, however.
+ Better ways to improve the quality of the
+ plans chosen by the optimizer include adjusting the <xref
+ linkend="runtime-config-query-constants"
+ endterm="runtime-config-query-constants-title">, running <xref
+ linkend="sql-analyze" endterm="sql-analyze-title"> more
+ frequently, 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-bitmapscan" xreflabel="enable_bitmapscan">
+ <term><varname>enable_bitmapscan</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary>bitmap scan</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>enable_bitmapscan</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of bitmap-scan plan
+ types. The default is <literal>on</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-enable-hashagg" xreflabel="enable_hashagg">
+ <term><varname>enable_hashagg</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>enable_hashagg</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of hashed
+ aggregation plan types. The default is <literal>on</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-enable-hashjoin" xreflabel="enable_hashjoin">
+ <term><varname>enable_hashjoin</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>enable_hashjoin</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of hash-join plan
+ types. The default is <literal>on</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-enable-indexscan" xreflabel="enable_indexscan">
+ <term><varname>enable_indexscan</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary>index scan</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>enable_indexscan</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of index-scan plan
+ types. The default is <literal>on</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-enable-mergejoin" xreflabel="enable_mergejoin">
+ <term><varname>enable_mergejoin</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>enable_mergejoin</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of merge-join plan
+ types. The default is <literal>on</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-enable-nestloop" xreflabel="enable_nestloop">
+ <term><varname>enable_nestloop</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>enable_nestloop</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of nested-loop join
+ plans. It's not possible 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</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-enable-seqscan" xreflabel="enable_seqscan">
+ <term><varname>enable_seqscan</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary>sequential scan</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>enable_seqscan</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of sequential scan
+ plan types. It's not possible 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</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-enable-sort" xreflabel="enable_sort">
+ <term><varname>enable_sort</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>enable_sort</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of explicit sort
+ steps. It's not possible 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</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-enable-tidscan" xreflabel="enable_tidscan">
+ <term><varname>enable_tidscan</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>enable_tidscan</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of <acronym>TID</>
+ scan plan types. The default is <literal>on</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+ <sect2 id="runtime-config-query-constants">
+ <title id="runtime-config-query-constants-title">
+ Planner Cost Constants
+ </title>
+
+ <note>
+ <para>
+ Unfortunately, there is no well-defined method for determining
+ ideal values for the family of <quote>cost</quote> variables that
+ appear below. You are encouraged to experiment and share
+ your findings.
+ </para>
+ </note>
+
+ <variablelist>
+
+ <varlistentry id="guc-effective-cache-size" xreflabel="effective_cache_size">
+ <term><varname>effective_cache_size</varname> (<type>floating point</type>)</term>
+ <indexterm>
+ <primary><varname>effective_cache_size</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the planner's assumption about the effective size of the
+ disk cache that is available to a single index scan. 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. Also, take into
+ account the expected number of concurrent queries using different
+ indexes, since they will have to share the available space.
+ This parameter has no effect on the size of shared memory
+ allocated by PostgreSQL, nor does it reserve kernel disk cache;
+ it is used only for estimation purposes.
+ The value is measured in disk pages, which are
+ normally 8192 bytes each. The default is 1000.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-random-page-cost" xreflabel="random_page_cost">
+ <term><varname>random_page_cost</varname> (<type>floating point</type>)</term>
+ <indexterm>
+ <primary><varname>random_page_cost</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the planner's estimate of the cost of a
+ nonsequentially fetched disk page. This is measured as a
+ multiple of the cost of a sequential page fetch. A higher
+ value makes it more likely a sequential scan will be used, a
+ lower value makes it more likely an index scan will be
+ used. The default is four.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-cpu-tuple-cost" xreflabel="cpu_tuple_cost">
+ <term><varname>cpu_tuple_cost</varname> (<type>floating point</type>)</term>
+ <indexterm>
+ <primary><varname>cpu_tuple_cost</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the planner's estimate of the cost of processing
+ each row during a query. This is measured as a fraction of
+ the cost of a sequential page fetch. 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>)</term>
+ <indexterm>
+ <primary><varname>cpu_index_tuple_cost</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the planner's estimate of the cost of processing
+ each index row during an index scan. This is measured as a
+ fraction of the cost of a sequential page fetch. The default
+ is 0.001.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-cpu-operator-cost" xreflabel="cpu_operator_cost">
+ <term><varname>cpu_operator_cost</varname> (<type>floating point</type>)</term>
+ <indexterm>
+ <primary><varname>cpu_operator_cost</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the planner's estimate of the cost of processing each
+ operator in a <literal>WHERE</> clause. This is measured as a fraction of
+ the cost of a sequential page fetch. The default is 0.0025.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+ <sect2 id="runtime-config-query-geqo">
+ <title>Genetic Query Optimizer</title>
+
+ <variablelist>
+
+ <varlistentry id="guc-geqo" xreflabel="geqo">
+ <indexterm>
+ <primary>genetic query optimization</primary>
+ </indexterm>
+ <indexterm>
+ <primary>GEQO</primary>
+ <see>genetic query optimization</see>
+ </indexterm>
+ <indexterm>
+ <primary><varname>geqo</> configuration parameter</primary>
+ </indexterm>
+ <term><varname>geqo</varname> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Enables or disables genetic query optimization, which is an
+ algorithm that attempts to do query planning without
+ exhaustive searching. This is on by default. The
+ <varname>geqo_threshold</varname> variable provides a more
+ granular way to disable GEQO for certain classes of queries.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-geqo-threshold" xreflabel="geqo_threshold">
+ <term><varname>geqo_threshold</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>geqo_threshold</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Use genetic query optimization to plan queries with at least
+ this many <literal>FROM</> items involved. (Note that an outer
+ <literal>JOIN</> construct counts as only one <literal>FROM</>
+ item.) The default is 12. For simpler queries it is usually best
+ to use the deterministic, exhaustive planner, but for queries with
+ many tables the deterministic planner takes too long.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-geqo-effort" xreflabel="geqo_effort">
+ <term><varname>geqo_effort</varname>
+ (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>geqo_effort</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls the trade off between planning time and query plan
+ efficiency in GEQO. This variable must be an integer in the
+ range from 1 to 10. The default value is 5. 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>)</term>
+ <indexterm>
+ <primary><varname>geqo_pool_size</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls the pool size used by GEQO. The pool size 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
+ default 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>)</term>
+ <indexterm>
+ <primary><varname>geqo_generations</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls the number of generations used by GEQO. Generations
+ specifies 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 default 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>)</term>
+ <indexterm>
+ <primary><varname>geqo_selection_bias</> configuration parameter</primary>
+ </indexterm>
+ <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>
+
+ </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>)</term>
+ <indexterm>
+ <primary><varname>default_statistics_target</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the default statistics target for table columns that have
+ not had a column-specific target set via <command>ALTER TABLE
+ SET STATISTICS</>. Larger values increase the time needed to
+ do <command>ANALYZE</>, but may improve the quality of the
+ planner's estimates. The default is 10. For more information
+ on the use of statistics by the <productname>PostgreSQL</>
+ 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>boolean</type>)</term>
+ <indexterm>
+ <primary>constraint exclusion</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>constraint_exclusion</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of table constraints to
+ limit table access. The default is <literal>off</>.
+ </para>
+
+ <para>
+ When this parameter is <literal>on</>, the planner compares query
+ conditions with table CHECK constraints, and omits scanning tables
+ where the conditions contradict the constraints. (Presently
+ this is done only for child tables of inheritance scans.) 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 SELECT will not scan
+ <structname>child1000</> at all. This can improve performance when
+ inheritance is used to build partitioned tables.
+ </para>
+
+ <para>
+ Currently, <varname>constraint_exclusion</> defaults to
+ <literal>off</>, because it risks incorrect results if
+ query plans are cached --- if a table constraint is changed or dropped,
+ the previously generated plan might now be wrong, and there is no
+ built-in mechanism to force re-planning. (This deficiency will
+ probably be addressed in a future
+ <productname>PostgreSQL</productname> release.) Another reason
+ for keeping it off is that the constraint checks are relatively
+ expensive, and in many circumstances will yield no savings.
+ It is recommended to turn this on only if you are actually using
+ partitioned tables designed to take advantage of the feature.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-from-collapse-limit" xreflabel="from_collapse_limit">
+ <term><varname>from_collapse_limit</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>from_collapse_limit</> configuration parameter</primary>
+ </indexterm>
+ <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 may
+ yield inferior query plans. The default is 8. It is usually
+ wise to keep this less than <xref linkend="guc-geqo-threshold">.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-join-collapse-limit" xreflabel="join_collapse_limit">
+ <term><varname>join_collapse_limit</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>join_collapse_limit</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ The planner will rewrite explicit inner <literal>JOIN</>
+ constructs into lists of <literal>FROM</> items whenever a
+ list of no more than this many items in total would
+ result. Prior to <productname>PostgreSQL</> 7.4, joins
+ specified via the <literal>JOIN</literal> construct would
+ never be reordered by the query planner. The query planner has
+ subsequently been improved so that inner joins written in this
+ form can be reordered; this configuration parameter controls
+ the extent to which this reordering is performed.
+ <note>
+ <para>
+ At present, the order of outer joins specified via the
+ <literal>JOIN</> construct is never adjusted by the query
+ planner; therefore, <varname>join_collapse_limit</> has no
+ effect on this behavior. The planner may be improved to
+ reorder some classes of outer joins in a future release of
+ <productname>PostgreSQL</productname>.
+ </para>
+ </note>
+ </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
+ inner <literal>JOIN</>s. Thus, the explicit join order
+ specified in the query will be the actual order in which the
+ relations are joined. The query planner does not always choose
+ the optimal join order; advanced users may elect to
+ temporarily set this variable to 1, and then specify the join
+ order they desire explicitly. Another consequence of setting
+ this variable to 1 is that the query planner will behave more
+ like the <productname>PostgreSQL</productname> 7.3 query
+ planner, which some users might find useful for backward
+ compatibility reasons.
+ </para>
+
+ <para>
+ Setting this variable to a value between 1 and
+ <varname>from_collapse_limit</varname> might be useful to
+ trade off planning time against the quality of the chosen plan
+ (higher values produce better plans).
+ </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>
+
+ <variablelist>
+
+ <varlistentry id="guc-log-destination" xreflabel="log_destination">
+ <term><varname>log_destination</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>log_destination</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> supports several methods
+ for logging server messages, including
+ <systemitem>stderr</systemitem> and
+ <systemitem>syslog</systemitem>. On Windows,
+ <systemitem>eventlog</systemitem> is also supported. Set this
+ option to a list of desired log destinations separated by
+ commas. The default is to log to <systemitem>stderr</systemitem>
+ only.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-redirect-stderr" xreflabel="redirect_stderr">
+ <term><varname>redirect_stderr</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>redirect_stderr</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ This option allows messages sent to <application>stderr</> to be
+ captured and redirected into log files.
+ This option, in combination with logging to <application>stderr</>,
+ is often more useful than
+ logging to <application>syslog</>, since some types of messages
+ may not appear in <application>syslog</> output (a common example
+ is dynamic-linker failure messages).
+ This option can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-directory" xreflabel="log_directory">
+ <term><varname>log_directory</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>log_directory</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When <varname>redirect_stderr</> is enabled, this option
+ determines the directory in which log files will be created.
+ It may be specified as an absolute path, or relative to the
+ cluster data directory.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-filename" xreflabel="log_filename">
+ <term><varname>log_filename</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>log_filename</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When <varname>redirect_stderr</varname> is enabled, this option
+ sets the file names of the created log files. The value
+ is treated as a <systemitem>strftime</systemitem> pattern,
+ so <literal>%</literal>-escapes
+ can be used to specify time-varying file names.
+ If no <literal>%</literal>-escapes are present,
+ <productname>PostgreSQL</productname> will
+ append the epoch of the new log file's open time. For example,
+ if <varname>log_filename</varname> were <literal>server_log</literal>, then the
+ chosen file name would be <literal>server_log.1093827753</literal>
+ for a log starting at Sun Aug 29 19:02:33 2004 MST.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-rotation-age" xreflabel="log_rotation_age">
+ <term><varname>log_rotation_age</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>log_rotation_age</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When <varname>redirect_stderr</varname> is enabled, this option
+ determines the maximum lifetime of an individual log file.
+ After this many minutes have elapsed, a new log file will
+ be created. Set to zero to disable time-based creation of
+ new log files.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-rotation-size" xreflabel="log_rotation_size">
+ <term><varname>log_rotation_size</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>log_rotation_size</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When <varname>redirect_stderr</varname> is enabled, this option
+ determines the maximum size of an individual log file.
+ After this many kilobytes have been emitted into a log file,
+ a new log file will be created. Set to zero to disable size-based
+ creation of new log files.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>log_truncate_on_rotation</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When <varname>redirect_stderr</varname> is enabled, this option 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 option 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 option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+ </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</> in <varname>log_filename</varname> allows
+ any size-driven rotations that may occur to select a filename
+ different from the hour's initial filename.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-syslog-facility" xreflabel="syslog_facility">
+ <term><varname>syslog_facility</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>syslog_facility</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When logging to <application>syslog</> is enabled, this option
+ determines the <application>syslog</application>
+ <quote>facility</quote> to be used. You may choose
+ from <literal>LOCAL0</>, <literal>LOCAL1</>,
+ <literal>LOCAL2</>, <literal>LOCAL3</>, <literal>LOCAL4</>,
+ <literal>LOCAL5</>, <literal>LOCAL6</>, <literal>LOCAL7</>;
+ the default is <literal>LOCAL0</>. See also the
+ documentation of your system's
+ <application>syslog</application> daemon.
+ This option can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-syslog-ident" xreflabel="syslog_ident">
+ <term><varname>syslog_ident</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>syslog_identity</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When logging to <application>syslog</> is enabled, this option
+ determines the program name used to identify
+ <productname>PostgreSQL</productname> messages in
+ <application>syslog</application> logs. The default is
+ <literal>postgres</literal>.
+ This option can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+ <sect2 id="runtime-config-logging-when">
+ <title>When To Log</title>
+
+ <variablelist>
+
+ <varlistentry id="guc-client-min-messages" xreflabel="client_min_messages">
+ <term><varname>client_min_messages</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>client_min_messages</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls which message levels are sent to the client.
+ Valid values are <literal>DEBUG5</>,
+ <literal>DEBUG4</>, <literal>DEBUG3</>, <literal>DEBUG2</>,
+ <literal>DEBUG1</>, <literal>LOG</>, <literal>NOTICE</>,
+ <literal>WARNING</>, and <literal>ERROR</>. Each level
+ includes all the levels that follow it. The later the level,
+ the fewer messages are sent. The default is
+ <literal>NOTICE</>. Note that <literal>LOG</> has a different
+ rank here than in <varname>log_min_messages</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-min-messages" xreflabel="log_min_messages">
+ <term><varname>log_min_messages</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>log_min_messages</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls which message levels are written to the server log.
+ Valid values are <literal>DEBUG5</>, <literal>DEBUG4</>,
+ <literal>DEBUG3</>, <literal>DEBUG2</>, <literal>DEBUG1</>,
+ <literal>INFO</>, <literal>NOTICE</>, <literal>WARNING</>,
+ <literal>ERROR</>, <literal>LOG</>, <literal>FATAL</>, and
+ <literal>PANIC</>. 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>NOTICE</>. Note that
+ <literal>LOG</> has a different rank here than in
+ <varname>client_min_messages</>.
+ Only superusers can change this setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-error-verbosity" xreflabel="log_error_verbosity">
+ <term><varname>log_error_verbosity</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>log_error_verbosity</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls the amount of detail written in the server log for each
+ message that is logged. Valid values are <literal>TERSE</>,
+ <literal>DEFAULT</>, and <literal>VERBOSE</>, each adding more
+ fields to displayed messages.
+ Only superusers can change this setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-min-error-statement" xreflabel="log_min_error_statement">
+ <term><varname>log_min_error_statement</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>log_min_error_statement</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls whether or not the SQL statement that causes an error
+ condition will also be recorded in the server log. All SQL
+ statements that cause an error of the specified level or
+ higher are logged. The default is
+ <literal>PANIC</literal> (effectively turning this feature
+ off for normal use). 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>FATAL</literal>, and <literal>PANIC</literal>. For
+ example, if you set this to <literal>ERROR</literal> then all
+ SQL statements causing errors, fatal errors, or panics will be
+ logged. Enabling this option can be helpful in tracking down
+ the source of any errors that appear in the server log.
+ Only superusers can change this setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-min-duration-statement" xreflabel="log_min_duration_statement">
+ <term><varname>log_min_duration_statement</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>log_min_duration_statement</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Logs the statement and its duration on a single log line if its
+ duration is greater than or equal to the specified number of
+ milliseconds. Setting this to zero will print all statements
+ and their durations. Minus-one (the default) disables the
+ feature. For example, if you set it to <literal>250</literal>
+ then all SQL statements that run 250ms or longer will be
+ logged. Enabling this option can be useful in tracking down
+ unoptimized queries in your applications. This setting is
+ independent of <varname>log_statement</varname> and
+ <varname>log_duration</varname>. Only superusers can change
+ this setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-silent-mode" xreflabel="silent_mode">
+ <term><varname>silent_mode</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>silent_mode</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Runs the server silently. If this option is set, the server
+ will automatically run in background and any controlling
+ terminals are disassociated (same effect as
+ <command>postmaster</>'s <option>-S</option> option).
+ The server's standard output and standard error are redirected
+ to <literal>/dev/null</>, so any messages sent to them will be lost.
+ Unless <application>syslog</> logging is selected or
+ <varname>redirect_stderr</> is enabled, using this option
+ is discouraged because it makes it impossible to see error messages.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ Here is a list of the various message severity levels used in
+ these settings:
+ <variablelist>
+ <varlistentry>
+ <term><literal>DEBUG[1-5]</literal></term>
+ <listitem>
+ <para>
+ Provides information for use by developers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>INFO</literal></term>
+ <listitem>
+ <para>
+ Provides information implicitly requested by the user,
+ e.g., during <command>VACUUM VERBOSE</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>NOTICE</literal></term>
+ <listitem>
+ <para>
+ Provides information that may be helpful to users, e.g.,
+ truncation of long identifiers and the creation of indexes as part
+ of primary keys.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>WARNING</literal></term>
+ <listitem>
+ <para>
+ Provides warnings to the user, e.g., <command>COMMIT</>
+ outside a transaction block.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>ERROR</literal></term>
+ <listitem>
+ <para>
+ Reports an error that caused the current command to abort.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>LOG</literal></term>
+ <listitem>
+ <para>
+ Reports information of interest to administrators, e.g.,
+ checkpoint activity.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>FATAL</literal></term>
+ <listitem>
+ <para>
+ Reports an error that caused the current session to abort.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PANIC</literal></term>
+ <listitem>
+ <para>
+ Reports an error that caused all sessions to abort.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ </sect2>
+ <sect2 id="runtime-config-logging-what">
+ <title>What To Log</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><varname>debug_print_parse</varname> (<type>boolean</type>)</term>
+ <term><varname>debug_print_rewritten</varname> (<type>boolean</type>)</term>
+ <term><varname>debug_print_plan</varname> (<type>boolean</type>)</term>
+ <term><varname>debug_pretty_print</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>debug_print_parse</> configuration parameter</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>debug_print_rewritten</> configuration parameter</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>debug_print_plan</> configuration parameter</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>debug_pretty_print</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ These options enable various debugging output to be emitted.
+ For each executed query, they print
+ the resulting parse tree, the query rewriter output, or the
+ execution plan. <varname>debug_pretty_print</varname> indents
+ these displays to produce a more readable but much longer
+ output format. <varname>client_min_messages</varname> or
+ <varname>log_min_messages</varname> must be
+ <literal>DEBUG1</literal> or lower to actually send this output
+ to the client or the server log, respectively.
+ These options are off by default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-connections" xreflabel="log_connections">
+ <term><varname>log_connections</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>log_connections</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ This outputs a line to the server log detailing each successful
+ connection. This is off by default, although it is probably very
+ useful. This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-disconnections" xreflabel="log_disconnections">
+ <term><varname>log_disconnections</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>log_disconnections</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ This outputs a line in the server log similar to
+ <varname>log_connections</varname> but at session termination,
+ and includes the duration of the session. This is off by
+ default. This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry id="guc-log-duration" xreflabel="log_duration">
+ <term><varname>log_duration</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>log_duration</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Causes the duration of every completed statement which satisfies
+ <varname>log_statement</> to be logged. When using this option,
+ if you are not using <application>syslog</>, it is recommended
+ that you log the PID or session ID using <varname>log_line_prefix</>
+ so that you can link the statement to the
+ duration using the process ID or session ID. The default is
+ <literal>off</>. Only superusers can change this setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-line-prefix" xreflabel="log_line_prefix">
+ <term><varname>log_line_prefix</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>log_line_prefix</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ This is a <function>printf</>-style string that is output at the
+ beginning of each log line. The default is an empty string.
+ Each recognized escape is replaced as outlined
+ below - anything else that looks like an escape is ignored. Other
+ characters are copied straight to the log line. Some escapes are
+ only recognised by session processes, and do not apply to
+ background processes such as the postmaster. <application>Syslog</>
+ produces its own
+ time stamp and process ID information, so you probably do not want to
+ use those escapes if you are using <application>syslog</>.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Escape</entry>
+ <entry>Effect</entry>
+ <entry>Session only</entry>
+ </row>
+ </thead>
+ <tbody>
+ <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 Hostname or IP address</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry><literal>%p</literal></entry>
+ <entry>Process ID</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry><literal>%t</literal></entry>
+ <entry>Time stamp (no 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>%i</literal></entry>
+ <entry>Command tag: This is the command that generated the log line.</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry><literal>%c</literal></entry>
+ <entry>Session ID: A unique identifier for each session.
+ It is 2 4-byte hexadecimal numbers (without leading zeros)
+ separated by a dot. The numbers
+ are the session start time and the process ID, so this can also
+ be used as a space saving way of printing these items.</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry><literal>%l</literal></entry>
+ <entry>Number of the log line for each process, starting at 1</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry><literal>%s</literal></entry>
+ <entry>Session start time stamp</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry><literal>%x</literal></entry>
+ <entry>Transaction ID</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry><literal>%q</literal></entry>
+ <entry>Does not produce any 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>%%</literal></entry>
+ <entry>Literal <literal>%</></entry>
+ <entry>no</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-statement" xreflabel="log_statement">
+ <term><varname>log_statement</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>log_statement</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls which SQL statements are logged. Valid values are
+ <literal>none</>, <literal>ddl</>, <literal>mod</>, and
+ <literal>all</>. <literal>ddl</> logs all data definition
+ commands like <literal>CREATE</>, <literal>ALTER</>, and
+ <literal>DROP</> commands. <literal>mod</> logs all
+ <literal>ddl</> statements, plus <literal>INSERT</>,
+ <literal>UPDATE</>, <literal>DELETE</>, <literal>TRUNCATE</>,
+ and <literal>COPY FROM</>. <literal>PREPARE</> and
+ <literal>EXPLAIN ANALYZE</> statements are also logged if their
+ contained command is of an appropriate type.
+ </para>
+ <para>
+ The default is <literal>none</>. Only superusers can change this
+ setting.
+ </para>
+
+ <note>
+ <para>
+ The <command>EXECUTE</command> statement is not considered a
+ <literal>ddl</> or <literal>mod</> statement. When it is logged,
+ only the name of the prepared statement is reported, not the
+ actual prepared statement.
+ </para>
+
+ <para>
+ When a function is defined in the
+ <application>PL/pgSQL</application>server-side language, any queries
+ executed by the function will only be logged the first time that the
+ function is invoked in a particular session. This is because
+ <application>PL/pgSQL</application> keeps a cache of the
+ query plans produced for the SQL statements in the function.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-log-hostname" xreflabel="log_hostname">
+ <term><varname>log_hostname</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>log_hostname</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ By default, connection log messages only show the IP address of the
+ connecting host. Turning on this option 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
+ option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+ </sect1>
+
+ <sect1 id="runtime-config-statistics">
+ <title>Runtime Statistics</title>
+
+ <sect2 id="runtime-config-statistics-monitor">
+ <title>Statistics Monitoring</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><varname>log_statement_stats</varname> (<type>boolean</type>)</term>
+ <term><varname>log_parser_stats</varname> (<type>boolean</type>)</term>
+ <term><varname>log_planner_stats</varname> (<type>boolean</type>)</term>
+ <term><varname>log_executor_stats</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>log_statement_stats</> configuration parameter</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>log_parser_stats</> configuration parameter</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>log_planner_stats</> configuration parameter</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>log_executor_stats</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ For each query, write performance statistics of the respective
+ module to the server log. This is a crude profiling
+ instrument. <varname>log_statement_stats</varname> reports total
+ statement statistics, while the others report per-module statistics.
+ <varname>log_statement_stats</varname> cannot be enabled together with
+ any of the per-module options. All of these options are disabled by
+ default. Only superusers can change these settings.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+ <sect2 id="runtime-config-statistics-collector">
+ <title>Query and Index Statistics Collector</title>
+ <variablelist>
+
+ <varlistentry id="guc-stats-start-collector" xreflabel="stats_start_collector">
+ <term><varname>stats_start_collector</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>stats_start_collector</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls whether the server should start the
+ statistics-collection subprocess. This is on by default, but
+ may be turned off if you know you have no interest in
+ collecting statistics. This option can only be set at server
+ start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-stats-command-string" xreflabel="stats_command_string">
+ <term><varname>stats_command_string</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>stats_command_string</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables the collection of statistics on the currently
+ executing command of each session, along with the time at
+ which that command began execution. This option is off by
+ default. Note that even when enabled, this information is not
+ visible to all users, only to superusers and the user owning
+ the session being reported on; so it should not represent a
+ security risk. This data can be accessed via the
+ <structname>pg_stat_activity</structname> system view; refer
+ to <xref linkend="monitoring"> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-stats-block-level" xreflabel="stats_block_level">
+ <term><varname>stats_block_level</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>stats_block_level</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables the collection of block-level statistics on database
+ activity. This option is disabled by default. If this option
+ is enabled, the data that is produced can be accessed via the
+ <structname>pg_stat</structname> and
+ <structname>pg_statio</structname> family of system views;
+ refer to <xref linkend="monitoring"> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-stats-row-level" xreflabel="stats_row_level">
+ <term><varname>stats_row_level</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>stats_row_level</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Enables the collection of row-level statistics on database
+ activity. This option is disabled by default. If this option
+ is enabled, the data that is produced can be accessed via the
+ <structname>pg_stat</structname> and
+ <structname>pg_statio</structname> family of system views;
+ refer to <xref linkend="monitoring"> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-stats-reset-on-server-start" xreflabel="stats_reset_on_server_start">
+ <term><varname>stats_reset_on_server_start</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>stats_reset_on_server_start</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ If on, collected statistics are zeroed out whenever the server
+ is restarted. If off, statistics are accumulated across server
+ restarts. The default is <literal>off</>. This option can only
+ be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+ </sect1>
+
+ <sect1 id="runtime-config-autovacuum">
+ <title>Automatic Vacuuming</title>
+
+ <para>
+ Beginning in <productname>PostgreSQL</> 8.1, there is an optional server
+ process called the <firstterm>autovacuum daemon</>, whose purpose is
+ to automate the issuance of periodic <command>VACUUM</> and
+ <command>ANALYZE</> commands. When enabled, the autovacuum daemon
+ runs periodically and checks for tables that have had a large number
+ of updated or deleted tuples. This check uses the row-level statistics
+ collection facility; therefore, the autovacuum daemon cannot be used
+ unless <xref linkend="guc-stats-start-collector"> and
+ <xref linkend="guc-stats-row-level"> are set TRUE. Also, it's
+ important to allow a slot for the autovacuum process when choosing
+ the value of <xref linkend="guc-superuser-reserved-connections">.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="guc-autovacuum" xreflabel="autovacuum">
+ <term><varname>autovacuum</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>autovacuum</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Controls whether the server should start the
+ autovacuum subprocess. This is off by default.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-autovacuum-naptime" xreflabel="autovacuum_naptime">
+ <term><varname>autovacuum_naptime</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>autovacuum_naptime</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the delay between activity rounds for the autovacuum
+ subprocess. In each round the subprocess examines one database
+ and issues <command>VACUUM</> and <command>ANALYZE</> commands
+ as needed for tables in that database. The delay is measured
+ in seconds, and the default is 60.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-autovacuum-vacuum-threshold" xreflabel="autovacuum_vacuum_threshold">
+ <term><varname>autovacuum_vacuum_threshold</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>autovacuum_vacuum_threshold</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the minimum number of updated or deleted tuples needed
+ to trigger a <command>VACUUM</> in any one table.
+ The default is 1000.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-autovacuum-analyze-threshold" xreflabel="autovacuum_analyze_threshold">
+ <term><varname>autovacuum_analyze_threshold</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>autovacuum_analyze_threshold</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the minimum number of inserted, updated or deleted tuples
+ needed to trigger an <command>ANALYZE</> in any one table.
+ The default is 500.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>autovacuum_vacuum_scale_factor</> configuration parameter</primary>
+ </indexterm>
+ <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</>.
+ The default is 0.4.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>autovacuum_analyze_scale_factor</> configuration parameter</primary>
+ </indexterm>
+ <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</>.
+ The default is 0.2.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-autovacuum-vacuum-cost-delay" xreflabel="autovacuum_vacuum_cost_delay">
+ <term><varname>autovacuum_vacuum_cost_delay</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>autovacuum_vacuum_cost_delay</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the cost delay value that will be used in automatic
+ <command>VACUUM</> operations. If -1 is specified (which is the
+ default), the regular
+ <xref linkend="guc-vacuum-cost-delay"> value will be used.
+ This setting can be overridden for individual tables by entries in
+ <structname>pg_autovacuum</>.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>autovacuum_vacuum_cost_limit</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the cost limit value that will be used in automatic
+ <command>VACUUM</> operations. If -1 is specified (which is the
+ default), the regular
+ <xref linkend="guc-vacuum-cost-limit"> value will be used.
+ This setting can be overridden for individual tables by entries in
+ <structname>pg_autovacuum</>.
+ </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-search-path" xreflabel="search_path">
+ <term><varname>search_path</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>search_path</> configuration parameter</primary>
+ </indexterm>
+ <indexterm><primary>path</><secondary>for schemas</></>
+ <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 component. 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> has to be a comma-separated
+ list of schema names. If one of the list items is
+ the special value <literal>$user</literal>, then the schema
+ having the name returned by <function>SESSION_USER</> is substituted, if there
+ is such a schema. (If not, <literal>$user</literal> is ignored.)
+ </para>
+
+ <para>
+ The system catalog schema, <literal>pg_catalog</>, 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</> is not in the path then it will
+ be searched <emphasis>before</> searching any of the path items.
+ It should also be noted that the temporary-table schema,
+ <literal>pg_temp_<replaceable>nnn</></>, is implicitly searched before any of
+ these.
+ </para>
+
+ <para>
+ When objects are created without specifying a particular target
+ schema, they will be placed in the first schema listed
+ in the search path. An error is reported if the search path is
+ empty.
+ </para>
+
+ <para>
+ The default value for this parameter is
+ <literal>'$user, public'</literal> (where the second part will be
+ ignored if there is no schema named <literal>public</>).
+ This supports shared use of a database (where no users
+ have private schemas, and all share use of <literal>public</>),
+ 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>
+ The current effective value of the search path can be examined
+ via the <acronym>SQL</acronym> function
+ <function>current_schemas()</>. This is not quite the same as
+ examining the value of <varname>search_path</varname>, since
+ <function>current_schemas()</> shows how the requests
+ appearing in <varname>search_path</varname> were resolved.
+ </para>
+
+ <para>
+ For more information on schema handling, see <xref linkend="ddl-schemas">.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-default-tablespace" xreflabel="default_tablespace">
+ <term><varname>default_tablespace</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>default_tablespace</> configuration parameter</primary>
+ </indexterm>
+ <indexterm><primary>tablespace</><secondary>default</></>
+ <listitem>
+ <para>
+ This variable specifies the default tablespace in which to create
+ objects (tables and indexes) when a <command>CREATE</> 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</> will automatically use the default
+ tablespace of the current database.
+ </para>
+
+ <para>
+ For more information on tablespaces,
+ see <xref linkend="manage-ag-tablespaces">.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-check-function-bodies" xreflabel="check_function_bodies">
+ <term><varname>check_function_bodies</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>check_function_bodies</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ This parameter is normally on. When set to <literal>off</>, it
+ disables validation of the function body string during <xref
+ linkend="sql-createfunction"
+ endterm="sql-createfunction-title">. Disabling validation is
+ occasionally useful to avoid problems such as forward references
+ when restoring function definitions from a dump.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-default-transaction-isolation" xreflabel="default_transaction_isolation">
+ <indexterm>
+ <primary>transaction isolation level</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>default_transaction_isolation</> configuration parameter</primary>
+ </indexterm>
+ <term><varname>default_transaction_isolation</varname> (<type>string</type>)</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"
+ endterm="sql-set-transaction-title"> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-default-transaction-read-only" xreflabel="default_transaction_read_only">
+ <indexterm>
+ <primary>read-only transaction</primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>default_transaction_read_only</> configuration parameter</primary>
+ </indexterm>
+
+ <term><varname>default_transaction_read_only</varname> (<type>boolean</type>)</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</> (read/write).
+ </para>
+
+ <para>
+ Consult <xref linkend="sql-set-transaction"
+ endterm="sql-set-transaction-title"> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-statement-timeout" xreflabel="statement_timeout">
+ <term><varname>statement_timeout</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>statement_timeout</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Abort any statement that takes over the specified number of
+ milliseconds. A value of zero (the default) turns off the limitation.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>DateStyle</> configuration parameter</primary>
+ </indexterm>
+ <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>Postgres</>, <literal>SQL</>, or <literal>German</>)
+ and the input/output specification for year/month/day ordering
+ (<literal>DMY</>, <literal>MDY</>, or <literal>YMD</>). These
+ can be set separately or together. The keywords <literal>Euro</>
+ and <literal>European</> are synonyms for <literal>DMY</>; the
+ keywords <literal>US</>, <literal>NonEuro</>, and
+ <literal>NonEuropean</> are synonyms for <literal>MDY</>. See
+ <xref linkend="datatype-datetime"> for more information. The
+ default is <literal>ISO, MDY</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-timezone" xreflabel="timezone">
+ <term><varname>timezone</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>timezone</> configuration parameter</primary>
+ </indexterm>
+ <indexterm><primary>time zone</></>
+ <listitem>
+ <para>
+ Sets the time zone for displaying and interpreting time
+ stamps. The default is 'unknown', which means to use whatever
+ the system environment specifies as the time zone. See <xref
+ linkend="datatype-datetime"> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-australian-timezones" xreflabel="australian_timezones">
+ <term><varname>australian_timezones</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>australian_timezones</> configuration parameter</primary>
+ </indexterm>
+ <indexterm><primary>time zone</><secondary>Australian</></>
+ <listitem>
+ <para>
+ If set to on, <literal>ACST</literal>,
+ <literal>CST</literal>, <literal>EST</literal>, and
+ <literal>SAT</literal> are interpreted as Australian time
+ zones rather than as North/South American time zones and
+ Saturday. The default is <literal>off</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-extra-float-digits" xreflabel="extra_float_digits">
+ <indexterm>
+ <primary>significant digits</primary>
+ </indexterm>
+ <indexterm>
+ <primary>floating-point</primary>
+ <secondary>display</secondary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>extra_float_digits</> configuration parameter</primary>
+ </indexterm>
+
+ <term><varname>extra_float_digits</varname> (<type>integer</type>)</term>
+ <listitem>
+ <para>
+ This parameter adjusts the number of digits displayed for
+ floating-point values, including <type>float4</>, <type>float8</>,
+ and geometric data types. The parameter value is added to the
+ standard number of digits (<literal>FLT_DIG</> or <literal>DBL_DIG</>
+ as appropriate). The value can be set as high as 2, to include
+ partially-significant digits; this is especially useful for dumping
+ float data that needs to be restored exactly. Or it can be set
+ negative to suppress unwanted digits.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-client-encoding" xreflabel="client_encoding">
+ <term><varname>client_encoding</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>client_encoding</> configuration parameter</primary>
+ </indexterm>
+ <indexterm><primary>character set</></>
+ <listitem>
+ <para>
+ Sets the client-side encoding (character set).
+ The default is to use the database encoding.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-lc-messages" xreflabel="lc_messages">
+ <term><varname>lc_messages</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>lc_messages</> configuration parameter</primary>
+ </indexterm>
+ <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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-lc-monetary" xreflabel="lc_monetary">
+ <term><varname>lc_monetary</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>lc_monetary</> configuration parameter</primary>
+ </indexterm>
+ <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>)</term>
+ <indexterm>
+ <primary><varname>lc_numeric</> configuration parameter</primary>
+ </indexterm>
+ <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>)</term>
+ <indexterm>
+ <primary><varname>lc_time</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Sets the locale to use for formatting date and time values.
+ (Currently, this setting does nothing, but it may in the
+ future.) 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>
+
+ </variablelist>
+
+ </sect2>
+ <sect2 id="runtime-config-client-other">
+ <title>Other Defaults</title>
+
+ <variablelist>
+
+ <varlistentry id="guc-explain-pretty-print" xreflabel="explain_pretty_print">
+ <term><varname>explain_pretty_print</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>explain_pretty_print</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Determines whether <command>EXPLAIN VERBOSE</> uses the
+ indented or non-indented format for displaying detailed
+ query-tree dumps. The default is <literal>on</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-dynamic-library-path" xreflabel="dynamic_library_path">
+ <term><varname>dynamic_library_path</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>dynamic_library_path</> configuration parameter</primary>
+ </indexterm>
+ <indexterm><primary>dynamic loading</></>
+ <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> has to be a
+ list of absolute directory paths separated by colons (or semi-colons
+ on Windows). If a list element starts
+ with the special string <literal>$libdir</literal>, the
+ compiled-in <productname>PostgreSQL</productname> package
+ library directory is substituted for <literal>$libdir</literal>. This
+ is where the modules provided by the standard
+ <productname>PostgreSQL</productname> distribution are installed.
+ (Use <literal>pg_config --pkglibdir</literal> to find out the name of
+ this directory.) For example:
+<programlisting>
+dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
+</programlisting>
+ or, in a Windows environment:
+<programlisting>
+dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
+</programlisting>
+ </para>
+
+ <para>
+ The default value for this parameter is
+ <literal>'$libdir'</literal>. If the value is set to an empty
+ string, the automatic path search is turned off.
+ </para>
+
+ <para>
+ This parameter can be changed at run time by superusers, but a
+ setting done that way will only persist until the end of the
+ client connection, so this method should be reserved for
+ development purposes. The recommended way to set this parameter
+ is in the <filename>postgresql.conf</filename> configuration
+ file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+ </sect1>
+
+ <sect1 id="runtime-config-locks">
+ <title>Lock Management</title>
+
+ <variablelist>
+
+ <varlistentry id="guc-deadlock-timeout" xreflabel="deadlock_timeout">
+ <indexterm>
+ <primary>deadlock</primary>
+ <secondary>timeout during</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>timeout</primary>
+ <secondary>deadlock</secondary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>deadlock_timeout</> configuration parameter</primary>
+ </indexterm>
+
+ <term><varname>deadlock_timeout</varname> (<type>integer</type>)</term>
+ <listitem>
+ <para>
+ This is the amount of time, in milliseconds, to wait on a lock
+ before checking to see if there is a deadlock condition. The
+ check for deadlock is relatively slow, 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 starting the check for a
+ deadlock. Increasing this value reduces the amount of time
+ wasted in needless deadlock checks, but slows down reporting of
+ real deadlock errors. The default is 1000 (i.e., one second),
+ 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.
+ </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>)</term>
+ <indexterm>
+ <primary><varname>max_locks_per_transaction</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ The shared lock table is created with room to describe locks on
+ <varname>max_locks_per_transaction</varname> *
+ (<xref linkend="guc-max-connections"> +
+ <xref linkend="guc-max-prepared-transactions">) objects;
+ hence, no more than this many distinct objects can
+ be locked at any one time. (Thus, this parameter's name may be
+ confusing: it is not a hard limit on the number of locks taken
+ by any one transaction, but rather a maximum average value.)
+ The default, 64, has historically
+ proven sufficient, but you might need to raise this value if you
+ have clients that touch many different tables in a single
+ transaction. This option can only be set at server start.
+ </para>
+
+ <para>
+ Increasing this parameter may cause <productname>PostgreSQL</>
+ to request more <systemitem class="osname">System V</> shared
+ memory than your operating system's default configuration
+ allows. See <xref linkend="sysvipc"> for information on how to
+ adjust those parameters, if necessary.
+ </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-add-missing-from" xreflabel="add_missing_from">
+ <term><varname>add_missing_from</varname> (<type>boolean</type>)</term>
+ <indexterm><primary>FROM</><secondary>missing</></>
+ <indexterm>
+ <primary><varname>add_missing_from</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When on, tables that are referenced by a query will be
+ automatically added to the <literal>FROM</> clause if not
+ already present. This behavior does not comply with the SQL
+ standard and many people dislike it because it can mask mistakes
+ (such as referencing a table where you should have referenced
+ its alias). The default is <literal>off</>. This variable can be
+ enabled for compatibility with releases of
+ <productname>PostgreSQL</> prior to 8.1, where this behavior was
+ allowed by default.
+ </para>
+
+ <para>
+ Note that even when this variable is enabled, a warning
+ message will be emitted for each implicit <literal>FROM</>
+ entry referenced by a query. Users are encouraged to update
+ their applications to not rely on this behavior, by adding all
+ tables referenced by a query to the query's <literal>FROM</>
+ clause (or its <literal>USING</> clause in the case of
+ <command>DELETE</>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-regex-flavor" xreflabel="regex_flavor">
+ <term><varname>regex_flavor</varname> (<type>string</type>)</term>
+ <indexterm><primary>regular expressions</></>
+ <indexterm>
+ <primary><varname>regex_flavor</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ The regular expression <quote>flavor</> can be set to
+ <literal>advanced</>, <literal>extended</>, or <literal>basic</>.
+ The default is <literal>advanced</>. The <literal>extended</>
+ setting may be useful for exact backwards compatibility with
+ pre-7.4 releases of <productname>PostgreSQL</>. See
+ <xref linkend="posix-syntax-details"> for details.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-sql-inheritance" xreflabel="sql_inheritance">
+ <term><varname>sql_inheritance</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>sql_inheritance</> configuration parameter</primary>
+ </indexterm>
+ <indexterm><primary>inheritance</></>
+ <listitem>
+ <para>
+ This controls the inheritance semantics, in particular whether
+ subtables are included by various commands by default. They were
+ not included in versions prior to 7.1. If you need the old
+ behavior you can set this variable to <literal>off</>, but in
+ the long run you are encouraged to change your applications to
+ use the <literal>ONLY</literal> key word to exclude subtables.
+ See <xref linkend="ddl-inherit"> for more information about
+ inheritance.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-default-with-oids" xreflabel="default_with_oids">
+ <term><varname>default_with_oids</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>default_with_oids</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ This controls whether <command>CREATE TABLE</command> and
+ <command>CREATE TABLE AS</command> include an OID column in
+ newly-created tables, if neither <literal>WITH OIDS</literal>
+ nor <literal>WITHOUT OIDS</literal> is specified. It also
+ determines whether OIDs will be included in tables created by
+ <command>SELECT INTO</command>. In <productname>PostgreSQL</>
+ 8.1 <varname>default_with_oids</> is disabled by default; in
+ prior versions of PostgreSQL, it was on by default.
+ </para>
+
+ <para>
+ The use of OIDs in user tables is considered deprecated, so
+ most installations should leave this variable disabled.
+ Applications that require OIDs for a particular table should
+ specify <literal>WITH OIDS</literal> when creating the
+ table. This variable can be enabled for compatibility with old
+ applications that do not follow this behavior.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-escape-string-warning" xreflabel="escape_string_warning">
+ <term><varname>escape_string_warning</varname> (<type>boolean</type>)</term>
+ <indexterm><primary>strings</><secondary>escape</></>
+ <indexterm>
+ <primary><varname>escape_string_warning</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When on, a warning is issued if a backslash (<literal>\</>)
+ appears in an ordinary string literal (<literal>'...'</>
+ syntax). The default is <literal>off</>.
+ </para>
+ <para>
+ Escape string syntax (<literal>E'...'</>) should be used for
+ escapes, because in future versions of
+ <productname>PostgreSQL</productname> ordinary strings will have
+ the standard-conforming behavior of treating backslashes
+ literally.
+ </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>)</term>
+ <indexterm><primary>IS NULL</></>
+ <indexterm>
+ <primary><varname>transform_null_equals</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ When on, expressions of the form <literal><replaceable>expr</> =
+ NULL</literal> (or <literal>NULL =
+ <replaceable>expr</></literal>) are treated as
+ <literal><replaceable>expr</> IS NULL</literal>, that is, they
+ return true if <replaceable>expr</> evaluates to the null value,
+ and false otherwise. The correct SQL-spec-compliant behavior of
+ <literal><replaceable>expr</> = NULL</literal> is to always
+ return null (unknown). Therefore this option defaults to
+ <literal>off</>.
+ </para>
+
+ <para>
+ However, filtered forms in <productname>Microsoft
+ Access</productname> generate queries that appear to use
+ <literal><replaceable>expr</> = 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</> = NULL</literal> always
+ return the null value (using the correct 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 not on by default.
+ </para>
+
+ <para>
+ Note that this option only affects the exact form <literal>= NULL</>,
+ 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-preset">
+ <title>Preset Options</title>
+
+ <para>
+ The following <quote>parameters</> are read-only, and are determined
+ when <productname>PostgreSQL</productname> is compiled or when it is
+ installed. As such, they have been excluded from the sample
+ <filename>postgresql.conf</> file. These options report
+ various aspects of <productname>PostgreSQL</productname> behavior
+ that may be of interest to certain applications, particularly
+ administrative front-ends.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="guc-block-size" xreflabel="block_size">
+ <term><varname>block_size</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>block_size</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Reports the size of a disk block. It is determined by the value
+ of <literal>BLCKSZ</> 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-integer-datetimes" xreflabel="integer_datetimes">
+ <term><varname>integer_datetimes</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>integer_datetimes</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Reports whether <productname>PostgreSQL</productname> was built
+ with support for 64-bit-integer dates and times. It is set by
+ configuring with <literal>--enable-integer-datetimes</literal>
+ when building <productname>PostgreSQL</productname>. The
+ default value is <literal>off</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-lc-collate" xreflabel="lc_collate">
+ <term><varname>lc_collate</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>lc_collate</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Reports the locale in which sorting of textual data is done.
+ See <xref linkend="locale"> for more information.
+ The value is determined when the database cluster is initialized.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-lc-ctype" xreflabel="lc_ctype">
+ <term><varname>lc_ctype</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>lc_ctype</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Reports the locale that determines character classifications.
+ See <xref linkend="locale"> for more information.
+ The value is determined when the database cluster is initialized.
+ 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>)</term>
+ <indexterm>
+ <primary><varname>max_function_args</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Reports the maximum number of function arguments. It is determined by
+ the value of <literal>FUNC_MAX_ARGS</> when building the server. The
+ default value is 100.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-max-identifier-length" xreflabel="max_identifier_length">
+ <term><varname>max_identifier_length</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>max_identifier_length</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Reports the maximum identifier length. It is determined as one
+ less than the value of <literal>NAMEDATALEN</> when building
+ the server. The default value of <literal>NAMEDATALEN</> is
+ 64; therefore the default
+ <varname>max_identifier_length</varname> is 63.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-max-index-keys" xreflabel="max_index_keys">
+ <term><varname>max_index_keys</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>max_index_keys</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Reports the maximum number of index keys. It is determined by
+ the value of <literal>INDEX_MAX_KEYS</> when building the server. The
+ default value is 32.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-server-encoding" xreflabel="server_encoding">
+ <term><varname>server_encoding</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>server_encoding</> configuration parameter</primary>
+ </indexterm>
+ <indexterm><primary>character set</></>
+ <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>)</term>
+ <indexterm>
+ <primary><varname>server_version</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Reports the version number of the server. It is determined by the
+ value of <literal>PG_VERSION</> when building the server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-standard-conforming-strings" xreflabel="standard_conforming_strings">
+ <term><varname>standard_conforming_strings</varname> (<type>boolean</type>)</term>
+ <indexterm><primary>strings</><secondary>escape</></>
+ <indexterm>
+ <primary><varname>standard_conforming_strings</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Reports whether ordinary string literals
+ (<literal>'...'</>) treat backslashes literally, as specified in
+ the SQL standard. The value is currently always <literal>off</>,
+ indicating that backslashes are treated as escapes. It is planned
+ that this will change to <literal>on</> in a future
+ <productname>PostgreSQL</productname> release when string literal
+ syntax changes to meet the standard. Applications may 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'...'</>) is supported.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect1>
+
+ <sect1 id="runtime-config-custom">
+ <title>Customized Options</title>
+
+ <para>
+ This feature was designed to allow options not normally known to
+ <productname>PostgreSQL</productname> to be added by add-on modules
+ (such as procedural languages). This allows add-on modules to be
+ configured in the standard ways.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="guc-custom-variable-classes" xreflabel="custom_variable_classes">
+ <term><varname>custom_variable_classes</varname> (<type>string</type>)</term>
+ <indexterm>
+ <primary><varname>custom_variable_classes</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ This variable specifies one or several class names to be used for
+ custom variables, in the form of a comma-separated list. A custom
+ variable is a variable not normally known
+ to <productname>PostgreSQL</productname> proper but used by some
+ add-on module. Such variables must have names consisting of a class
+ name, a dot, and a variable name. <varname>custom_variable_classes</>
+ specifies all the class names in use in a particular installation.
+ This option can only be set at server start or in the
+ <filename>postgresql.conf</filename> configuration file.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The difficulty with setting custom variables in
+ <filename>postgresql.conf</> is that the file must be read before add-on
+ modules have been loaded, and so custom variables would ordinarily be
+ rejected as unknown. When <varname>custom_variable_classes</> is set,
+ the server will accept definitions of arbitrary variables within each
+ specified class. These variables will be treated as placeholders and
+ will have no function until the module that defines them is loaded. When a
+ module for a specific class is loaded, it will add the proper variable
+ definitions for its class name, convert any placeholder
+ values according to those definitions, and issue warnings for any
+ placeholders of its class that remain (which presumably would be
+ misspelled configuration variables).
+ </para>
+
+ <para>
+ Here is an example of what <filename>postgresql.conf</> might contain
+ when using custom variables:
+
+<programlisting>
+custom_variable_classes = 'plr,plperl'
+plr.path = '/usr/lib/R'
+plperl.use_strict = true
+plruby.use_strict = true # generates error: unknown class name
+</programlisting>
+ </para>
+ </sect1>
+
+ <sect1 id="runtime-config-developer">
+ <title>Developer Options</title>
+
+ <para>
+ The following options are intended for work on the
+ <productname>PostgreSQL</productname> source, and in some cases
+ to assist with recovery of severely damaged databases. There
+ should be no reason to use them in a production database setup.
+ As such, they have been excluded from the sample
+ <filename>postgresql.conf</> file. Note that many of these
+ options require special source compilation flags to work at all.
+ </para>
+
+ <variablelist>
+ <varlistentry id="guc-debug-assertions" xreflabel="debug_assertions">
+ <term><varname>debug_assertions</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>debug_assertions</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Turns on various assertion checks. This is a debugging aid. If
+ you are experiencing strange problems or crashes you might want
+ to turn this on, as it might expose programming mistakes. To use
+ this option, the macro <symbol>USE_ASSERT_CHECKING</symbol>
+ must be defined when <productname>PostgreSQL</productname> is
+ built (accomplished by the <command>configure</command> option
+ <option>--enable-cassert</option>). Note that
+ <varname>debug_assertions</varname> defaults to <literal>on</>
+ if <productname>PostgreSQL</productname> has been built with
+ assertions enabled.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-pre-auth-delay" xreflabel="pre_auth_delay">
+ <term><varname>pre_auth_delay</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>pre_auth_delay</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ If nonzero, a delay of this many seconds occurs just after a new
+ server process is forked, before it conducts the authentication
+ process. This is intended to give an opportunity to attach to the
+ server process with a debugger to trace down misbehavior in
+ authentication.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-trace-notify" xreflabel="trace_notify">
+ <term><varname>trace_notify</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>trace_notify</> configuration parameter</primary>
+ </indexterm>
+ <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 log, respectively.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>trace_locks</varname> (<type>boolean</type>)</term>
+ <term><varname>trace_lwlocks</varname> (<type>boolean</type>)</term>
+ <term><varname>trace_userlocks</varname> (<type>boolean</type>)</term>
+ <term><varname>trace_lock_oidmin</varname> (<type>boolean</type>)</term>
+ <term><varname>trace_lock_table</varname> (<type>boolean</type>)</term>
+ <term><varname>debug_deadlocks</varname> (<type>boolean</type>)</term>
+ <term><varname>log_btree_build_stats</varname> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Various other code tracing and debugging options.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-wal-debug" xreflabel="wal_debug">
+ <term><varname>wal_debug</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>wal_debug</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ If on, emit WAL-related debugging output. This option is
+ only available if the <symbol>WAL_DEBUG</symbol> macro was
+ defined when <productname>PostgreSQL</productname> was
+ compiled.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-zero-damaged-pages" xreflabel="zero_damaged_pages">
+ <term><varname>zero_damaged_pages</varname> (<type>boolean</type>)</term>
+ <indexterm>
+ <primary><varname>zero_damaged_pages</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Detection of a damaged page header normally causes
+ <productname>PostgreSQL</> to report an error, aborting the current
+ command. Setting <varname>zero_damaged_pages</> to on causes
+ the system to instead report a warning, zero out the damaged page,
+ and continue processing. This behavior <emphasis>will destroy data</>,
+ namely all the rows on the damaged page. But it allows you to get
+ past the error and retrieve rows from any undamaged pages that may
+ be present in the table. So it is useful for recovering data if
+ corruption has occurred due to hardware or software error. You should
+ generally not set this on until you have given up hope of recovering
+ data from the damaged page(s) of a table. The
+ default setting is <literal>off</>, and it can only be changed
+ by a superuser.
+ </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">.
+ </para>
+
+ <table id="runtime-config-short-table">
+ <title>Short option key</title>
+ <tgroup cols="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></></entry>
+ </row>
+ <row>
+ <entry><option>-d <replaceable>x</replaceable></option></entry>
+ <entry><literal>log_min_messages = DEBUG<replaceable>x</replaceable></></entry>
+ </row>
+ <row>
+ <entry><option>-F</option></entry>
+ <entry><literal>fsync = off</></entry>
+ </row>
+ <row>
+ <entry><option>-h <replaceable>x</replaceable></option></entry>
+ <entry><literal>listen_addresses = <replaceable>x</replaceable></></entry>
+ </row>
+ <row>
+ <entry><option>-i</option></entry>
+ <entry><literal>listen_addresses = '*'</></entry>
+ </row>
+ <row>
+ <entry><option>-k <replaceable>x</replaceable></option></entry>
+ <entry><literal>unix_socket_directory = <replaceable>x</replaceable></></entry>
+ </row>
+ <row>
+ <entry><option>-l</option></entry>
+ <entry><literal>ssl = on</></entry>
+ </row>
+ <row>
+ <entry><option>-N <replaceable>x</replaceable></option></entry>
+ <entry><literal>max_connections = <replaceable>x</replaceable></></entry>
+ </row>
+ <row>
+ <entry><option>-p <replaceable>x</replaceable></option></entry>
+ <entry><literal>port = <replaceable>x</replaceable></></entry>
+ </row>
+
+ <row>
+ <entry>
+ <option>-fb</option>, <option>-fh</option>, <option>-fi</option>,
+ <option>-fm</option>, <option>-fn</option>,
+ <option>-fs</option>, <option>-ft</option><footnote
+ id="fn.runtime-config-short">
+ <para>
+ For historical reasons, these options must be passed to
+ the individual server process via the <option>-o</option>
+ <command>postmaster</command> option, for example,
+<screen>
+$ <userinput>postmaster -o '-S 1024 -s'</userinput>
+</screen>
+ or via <envar>PGOPTIONS</envar> from the client side, as
+ explained above.
+ </para>
+ </footnote>
+ </entry>
+ <entry>
+ <literal>enable_bitmapscan = off</>,
+ <literal>enable_hashjoin = off</>,
+ <literal>enable_indexscan = off</>,
+ <literal>enable_mergejoin = off</>,
+ <literal>enable_nestloop = off</>,
+ <literal>enable_seqscan = off</>,
+ <literal>enable_tidscan = off</>
+ </entry>
+ </row>
+
+ <row>
+ <entry><option>-s</option><footnoteref linkend="fn.runtime-config-short"></entry>
+ <entry><literal>log_statement_stats = on</></entry>
+ </row>
+
+ <row>
+ <entry><option>-S <replaceable>x</replaceable></option><footnoteref linkend="fn.runtime-config-short">
+ </entry>
+ <entry><literal>work_mem = <replaceable>x</replaceable></></entry>
+ </row>
+
+ <row>
+ <entry><option>-tpa</option>, <option>-tpl</option>, <option>-te</option><footnoteref linkend="fn.runtime-config-short"></entry>
+ <entry><literal>log_parser_stats = on</>,
+ <literal>log_planner_stats = on</>,
+ <literal>log_executor_stats = on</></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </sect1>
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode:sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:("/usr/lib/sgml/catalog")
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 88487ee9388..3b1cd740057 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.43 2005/02/27 00:49:28 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.44 2005/09/12 22:11:38 neilc Exp $ -->
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
@@ -41,6 +41,7 @@
<!entity monitoring SYSTEM "monitoring.sgml">
<!entity regress SYSTEM "regress.sgml">
<!entity runtime SYSTEM "runtime.sgml">
+<!entity config SYSTEM "config.sgml">
<!entity user-manag SYSTEM "user-manag.sgml">
<!entity wal SYSTEM "wal.sgml">
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 6fa0e28191b..8099f72dd8b 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.75 2005/02/27 00:49:28 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.76 2005/09/12 22:11:38 neilc Exp $
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
@@ -146,6 +146,7 @@ $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.75 2005/02/27 00:49:28 momjian
&installation;
&installw;
&runtime;
+ &config;
&user-manag;
&manage-ag;
&client-auth;
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 5af562a6635..3a8745df909 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.352 2005/08/30 15:48:28 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.353 2005/09/12 22:11:38 neilc Exp $
-->
<chapter Id="runtime">
@@ -451,4224 +451,6 @@ psql: could not connect to server: No such file or directory
</sect2>
</sect1>
- <sect1 id="runtime-config">
- <title>Run-time Configuration</title>
-
- <indexterm>
- <primary>configuration</primary>
- <secondary>of the server</secondary>
- </indexterm>
-
- <para>
- There are a lot of configuration parameters that affect the
- behavior of the database system. In this subsection, we describe
- how to set configuration parameters; the following subsections
- discuss each parameter in detail.
- </para>
-
- <para>
- All parameter names are case-insensitive. Every parameter takes a
- value of one of four types: boolean, integer, floating point,
- or string. Boolean values may be written as <literal>ON</literal>,
- <literal>OFF</literal>, <literal>TRUE</literal>,
- <literal>FALSE</literal>, <literal>YES</literal>,
- <literal>NO</literal>, <literal>1</literal>, <literal>0</literal>
- (all case-insensitive) or any unambiguous prefix of these.
- </para>
-
- <para>
- One way to set these parameters is to edit the file
- <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
- which is normally kept in the data directory. (<command>initdb</>
- installs a default copy there.) 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'
-</programlisting>
- One parameter is specified per line. The equal sign between name and
- value is optional. Whitespace is insignificant and blank lines are
- ignored. Hash marks (<literal>#</literal>) introduce comments
- anywhere. Parameter values that are not simple identifiers or
- numbers must be single-quoted.
- </para>
-
- <para>
- <indexterm>
- <primary>SIGHUP</primary>
- </indexterm>
- The configuration file is reread whenever the
- <command>postmaster</command> process receives a
- <systemitem>SIGHUP</> signal (which is most easily sent by means
- of <literal>pg_ctl reload</>). The <command>postmaster</command>
- also propagates this signal to all currently running server
- processes so that existing sessions also get the new
- value. 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.
- </para>
-
- <para>
- A second way to set these configuration parameters is to give them
- as a command line option to the <command>postmaster</command>, such as:
-<programlisting>
-postmaster -c log_connections=yes -c log_destination='syslog'
-</programlisting>
- Command-line options override any conflicting settings in
- <filename>postgresql.conf</filename>. Note that this means you won't
- be able to change the value on-the-fly by editing
- <filename>postgresql.conf</filename>, so while the command-line
- method may be convenient, it can cost you flexibility later.
- </para>
-
- <para>
- Occasionally it is useful to give a command line option to
- one particular session only. The environment variable
- <envar>PGOPTIONS</envar> can be used for this purpose on the
- client side:
-<programlisting>
-env PGOPTIONS='-c geqo=off' psql
-</programlisting>
- (This works for any <application>libpq</>-based client application, not
- just <application>psql</application>.) Note that this won't work for
- parameters that are fixed when the server is started or that must be
- specified in <filename>postgresql.conf</filename>.
- </para>
-
- <para>
- Furthermore, it is possible to assign a set of option settings to
- a user or a database. Whenever a session is started, the default
- settings for the user and database involved are loaded. The
- commands <xref linkend="sql-alteruser" endterm="sql-alteruser-title">
- and <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">,
- respectively, are used to configure these settings. Per-database
- settings override anything received from the
- <command>postmaster</command> command-line or the configuration
- file, and in turn are overridden by per-user settings; both are
- overridden by per-session options.
- </para>
-
- <para>
- Some parameters can be changed in individual <acronym>SQL</acronym>
- sessions with the <xref linkend="SQL-SET" endterm="SQL-SET-title">
- command, for example:
-<screen>
-SET ENABLE_SEQSCAN TO OFF;
-</screen>
- If <command>SET</> is allowed, it overrides all other sources of
- values for the parameter. Some parameters cannot be changed via
- <command>SET</command>: for example, if they control behavior that
- cannot reasonably be changed without restarting
- <productname>PostgreSQL</productname>. Also, some parameters can
- be modified via <command>SET</command> or <command>ALTER</> by superusers,
- but not by ordinary users.
- </para>
-
- <para>
- The <xref linkend="SQL-SHOW" endterm="SQL-SHOW-title">
- command allows inspection of the current values of all parameters.
- </para>
-
- <para>
- The virtual table <structname>pg_settings</structname>
- (described in <xref linkend="view-pg-settings">) also allows
- displaying and updating session run-time parameters. It is equivalent
- to <command>SHOW</> and <command>SET</>, but can be more convenient
- to use because it can be joined with other tables, or selected from using
- any desired selection condition.
- </para>
-
- <sect2 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 options described
- in this subsection 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>)</term>
- <indexterm>
- <primary><varname>data_directory</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the directory to use for data storage.
- This option 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>)</term>
- <indexterm>
- <primary><varname>config_file</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the main server configuration file
- (customarily called <filename>postgresql.conf</>).
- This option can only be set on the postmaster command line.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-hba-file" xreflabel="hba_file">
- <term><varname>hba_file</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>hba_file</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the configuration file for host-based authentication
- (customarily called <filename>pg_hba.conf</>).
- This option 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>)</term>
- <indexterm>
- <primary><varname>ident_file</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the configuration file for
- <application>ident</> authentication
- (customarily called <filename>pg_ident.conf</>).
- This option can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-external-pid-file" xreflabel="external_pid_file">
- <term><varname>external_pid_file</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>external_pid_file</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the name of an additional process-id (PID) file that the
- <application>postmaster</> should create for use by server
- administration programs.
- This option can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- In a default installation, none of the above options 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 postmaster's <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</> option 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</> 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 options <varname>config_file</>,
- <varname>hba_file</> and/or <varname>ident_file</>.
- <varname>config_file</> can only be specified on the
- <command>postmaster</command> command line, but the others can be
- set within the main configuration file. If all three options plus
- <varname>data_directory</> are explicitly set, then it is not necessary
- to specify <option>-D</option> or <envar>PGDATA</envar>.
- </para>
-
- <para>
- When setting any of these options, a relative path will be interpreted
- with respect to the directory in which the <command>postmaster</command>
- is started.
- </para>
- </sect2>
-
- <sect2 id="runtime-config-connection">
- <title>Connections and Authentication</title>
-
- <sect3 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>)</term>
- <indexterm>
- <primary><varname>listen_addresses</> configuration parameter</primary>
- </indexterm>
- <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>*</>
- corresponds to all available IP interfaces.
- If the list is empty, the server does not listen on any IP interface
- at all, in which case only Unix-domain sockets can be used to connect
- to it.
- The default value is <systemitem class="systemname">localhost</>,
- which allows only local <quote>loopback</> connections to be made.
- 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>)</term>
- <indexterm>
- <primary><varname>port</> configuration parameter</primary>
- </indexterm>
- <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>)</term>
- <indexterm>
- <primary><varname>max_connections</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Determines the maximum number of concurrent connections to the
- database server. The default is typically 100, but may be less
- if your kernel settings will not support it (as determined
- during <application>initdb</>). This parameter can only be
- set at server start.
- </para>
-
- <para>
- Increasing this parameter may cause <productname>PostgreSQL</>
- to request more <systemitem class="osname">System V</> shared
- memory or semaphores than your operating system's default configuration
- allows. See <xref linkend="sysvipc"> for information on how to
- adjust those parameters, if necessary.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-superuser-reserved-connections"
- xreflabel="superuser_reserved_connections">
- <term><varname>superuser_reserved_connections</varname>
- (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>superuser_reserved_connections</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Determines the number of connection <quote>slots</quote> that
- are reserved for connections by <productname>PostgreSQL</>
- 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</> minus
- <varname>superuser_reserved_connections</varname>, new
- connections will be accepted only for superusers.
- </para>
-
- <para>
- The default value is 2. The value must be less than the value of
- <varname>max_connections</varname>. This parameter can only be
- set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-unix-socket-directory" xreflabel="unix_socket_directory">
- <term><varname>unix_socket_directory</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>unix_socket_directory</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the directory of the Unix-domain socket on which the
- server is to listen for
- connections from client applications. The default is normally
- <filename>/tmp</filename>, but can be changed at build time.
- This parameter can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-unix-socket-group" xreflabel="unix_socket_group">
- <term><varname>unix_socket_group</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>unix_socket_group</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the owning group of the Unix-domain socket. (The owning
- user of the socket is always the user that starts the
- server.) In combination with the option
- <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 for the current user. This option can only be set at
- server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-unix-socket-permissions" xreflabel="unix_socket_permissions">
- <term><varname>unix_socket_permissions</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>unix_socket_permissions</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the access permissions of the Unix-domain socket. Unix-domain
- sockets use the usual Unix file system permission set.
- The option value is expected to be a numeric mode
- specification in the form 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 and 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 option 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>)</term>
- <indexterm>
- <primary><varname>bonjour_name</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the <productname>Bonjour</productname> broadcast
- name. By default, the computer name is used, specified as an
- empty string ''. This option is ignored if the server was not
- compiled with <productname>Bonjour</productname> support. This
- option 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>)</term>
- <indexterm>
- <primary><varname>tcp_keepalives_idle</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- On systems that support the TCP_KEEPIDLE socket option, specifies the
- number of seconds between sending keepalives on an otherwise idle
- connection. A value of 0 uses the system default. If TCP_KEEPIDLE is
- not supported, this parameter must be 0. This option is ignored for
- connections made via a Unix-domain socket.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-tcp-keepalives-interval" xreflabel="tcp_keepalives_interval">
- <term><varname>tcp_keepalives_interval</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>tcp_keepalives_interval</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- On systems that support the TCP_KEEPINTVL socket option, specifies how
- long, in seconds, to wait for a response to a keepalive before
- retransmitting. A value of 0 uses the system default. If TCP_KEEPINTVL
- is not supported, this parameter must be 0. This option is ignored
- for connections made via a Unix-domain socket.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-tcp-keepalives-count" xreflabel="tcp_keepalives_count">
- <term><varname>tcp_keepalives_count</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>tcp_keepalives_count</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- On systems that support the TCP_KEEPCNT socket option, specifies how
- many keepalives may be lost before the connection is considered dead.
- A value of 0 uses the system default. If TCP_KEEPINTVL is not
- supported, this parameter must be 0.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- <sect3 id="runtime-config-connection-security">
- <title>Security and Authentication</title>
-
- <variablelist>
- <varlistentry id="guc-authentication-timeout" xreflabel="authentication_timeout">
- <term><varname>authentication_timeout</varname> (<type>integer</type>)</term>
- <indexterm><primary>timeout</><secondary>client authentication</></indexterm>
- <indexterm><primary>client authentication</><secondary>timeout during</></indexterm>
- <indexterm>
- <primary><varname>authentication_timeout</> configuration parameter</primary>
- </indexterm>
-
- <listitem>
- <para>
- Maximum time to complete client authentication, in seconds. If a
- would-be client has not completed the authentication protocol in
- this much time, the server breaks the connection. This prevents
- hung clients from occupying a connection indefinitely. This
- option can only be set at server start or in the
- <filename>postgresql.conf</filename> file. The default is 60.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-ssl" xreflabel="ssl">
- <term><varname>ssl</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>ssl</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables <acronym>SSL</> connections. Please read
- <xref linkend="ssl-tcp"> before using this. The default
- is <literal>off</>. This parameter can only be set at server
- start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-password-encryption" xreflabel="password_encryption">
- <term><varname>password_encryption</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>password_encryption</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When a password is specified in <xref
- linkend="sql-createuser" endterm="sql-createuser-title"> or
- <xref linkend="sql-alteruser" endterm="sql-alteruser-title">
- without writing either <literal>ENCRYPTED</> or
- <literal>UNENCRYPTED</>, this option determines whether the
- password is to be encrypted. The default is <literal>on</>
- (encrypt the password).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-krb-server-keyfile" xreflabel="krb_server_keyfile">
- <term><varname>krb_server_keyfile</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>krb_server_keyfile</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the location of the Kerberos server key file. See
- <xref linkend="kerberos-auth"> for details. This parameter
- can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-krb-srvname" xreflabel="krb_srvname">
- <term><varname>krb_srvname</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>krb_srvname</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the Kerberos service name. See <xref linkend="kerberos-auth">
- for details. This parameter can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-krb-server-hostname" xreflabel="krb_server_hostname">
- <term><varname>krb_server_hostname</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>krb_server_hostname</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the hostname part of the service principal.
- This, combined with <varname>krb_srvname</>, is used to generate
- the complete service principal, i.e.
- <varname>krb_server_hostname</><literal>/</><varname>krb_server_hostname</><literal>@</>REALM.
- </para>
- <para>
- If not set, the default is to allow any service principal matching an entry
- in the keytab. See <xref linkend="kerberos-auth"> for details.
- This parameter can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-krb-caseins-users" xreflabel="krb_caseins_users">
- <term><varname>krb_caseins_users</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>krb_caseins_users</varname> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets if Kerberos usernames should be treated case-insensitively.
- The default is <literal>off</> (case sensitive). This parameter
- can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-db-user-namespace" xreflabel="db_user_namespace">
- <term><varname>db_user_namespace</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>db_user_namespace</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- This enables per-database user names. It is off by default.
- </para>
-
- <para>
- If this is on, you should create users as <literal>username@dbname</>.
- When <literal>username</> is passed by a connecting client,
- <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>@</> within the SQL environment, you will need to
- quote the user name.
- </para>
-
- <para>
- With this option enabled, you can still create ordinary global
- users. Simply append <literal>@</> when specifying the user
- name in the client. The <literal>@</> will be stripped off
- before the user name is looked up by the server.
- </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>
- </sect3>
- </sect2>
-
- <sect2 id="runtime-config-resource">
- <title>Resource Consumption</title>
-
- <sect3 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>)</term>
- <indexterm>
- <primary><varname>shared_buffers</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the number of shared memory buffers used by the database
- server. The default is typically 1000, but may be less if your
- kernel settings will not support it (as determined during
- <application>initdb</>). Each buffer is 8192 bytes, unless a
- different value of <symbol>BLCKSZ</symbol> was chosen when building
- the server. This setting must be at least 16, as well as at
- least twice the value of <xref linkend="guc-max-connections">;
- however, settings significantly higher than the minimum are
- usually needed for good performance. Values of a few thousand
- are recommended for production installations. This option can
- only be set at server start.
- </para>
-
- <para>
- Increasing this parameter may cause <productname>PostgreSQL</>
- to request more <systemitem class="osname">System V</> shared
- memory than your operating system's default configuration
- allows. See <xref linkend="sysvipc"> for information on how to
- adjust those parameters, if necessary.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-temp-buffers" xreflabel="temp_buffers">
- <term><varname>temp_buffers</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>temp_buffers</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the maximum number of temporary buffers used by each database
- session. These are session-local buffers used only for access
- to temporary tables. The default is 1000. The setting can
- be changed within individual sessions, but only up until the
- first use of temporary tables within a 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</>. The cost of setting a large
- value in sessions that do not actually need a lot of temporary
- buffers is only a buffer descriptor, or about 64 bytes, per
- increment in <varname>temp_buffers</>. 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>)</term>
- <indexterm>
- <primary><varname>max_prepared_transactions</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the maximum number of transactions that can be in the
- <quote>prepared</> state simultaneously (see <xref
- linkend="sql-prepare-transaction"
- endterm="sql-prepare-transaction-title">).
- Setting this parameter to zero disables the prepared-transaction
- feature.
- The default is 5.
- This option can only be set at server start.
- </para>
-
- <para>
- If you are not using prepared transactions, this parameter may as
- well be set to zero. If you are using them, you will probably
- want <varname>max_prepared_transactions</varname> to be at least
- as large as <xref linkend="guc-max-connections">, to avoid unwanted
- failures at the prepare step.
- </para>
-
- <para>
- Increasing this parameter may cause <productname>PostgreSQL</>
- to request more <systemitem class="osname">System V</> shared
- memory than your operating system's default configuration
- allows. See <xref linkend="sysvipc"> for information on how to
- adjust those parameters, if necessary.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-work-mem" xreflabel="work_mem">
- <term><varname>work_mem</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>work_mem</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the amount of memory to be used by internal sort operations
- and hash tables before switching to temporary disk files. The value is
- specified in kilobytes, and defaults to 1024 kilobytes (1 MB).
- Note that for a complex query, several sort or hash operations might be
- running in parallel; each one will be allowed to use as much memory
- as this value specifies before it starts to put data into temporary
- files. Also, several running sessions could be doing such operations
- concurrently. So 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>DISTINCT</>, and
- merge joins.
- Hash tables are used in hash joins, hash-based aggregation, and
- hash-based processing of <literal>IN</> subqueries.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-maintenance-work-mem" xreflabel="maintenance_work_mem">
- <term><varname>maintenance_work_mem</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>maintenance_work_mem</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the maximum amount of memory to be used in maintenance
- operations, such as <command>VACUUM</command>, <command>CREATE
- INDEX</>, and <command>ALTER TABLE ADD FOREIGN KEY</>.
- The value is specified in kilobytes, and defaults to 16384 kilobytes
- (16 MB). Since only one of these operations can be executed at
- a time by a database session, and an installation normally doesn't
- have very many of them happening concurrently, it's safe to set this
- value significantly larger than <varname>work_mem</varname>. Larger
- settings may improve performance for vacuuming and for restoring
- database dumps.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-max-stack-depth" xreflabel="max_stack_depth">
- <term><varname>max_stack_depth</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>max_stack_depth</> configuration parameter</primary>
- </indexterm>
- <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</> 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
- such as expression evaluation. Setting the parameter higher than
- the actual kernel limit will mean that a runaway recursive function
- can crash an individual backend process. The default setting is
- 2048 KB (two megabytes), which is conservatively small and unlikely
- to risk crashes. However, it may be too small to allow execution
- of complex functions.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- <sect3 id="runtime-config-resource-fsm">
- <title>Free Space Map</title>
-
- <indexterm>
- <primary>free space map</primary>
- </indexterm>
-
- <para>
- These parameters control the size of the shared <firstterm>free space
- map</>, which tracks the locations of unused space in the database.
- An undersized free space map may cause the database to consume
- increasing amounts of disk space over time, because free space that
- is not in the map cannot be re-used; instead <productname>PostgreSQL</>
- will request more disk space from the operating system when it needs
- to store new data.
- The last few lines displayed by a database-wide <command>VACUUM VERBOSE</>
- command can help in determining if the current settings are adequate.
- A <literal>NOTICE</> message is also printed during such an operation
- if the current settings are too low.
- </para>
-
- <para>
- Increasing these parameters may cause <productname>PostgreSQL</>
- to request more <systemitem class="osname">System V</> shared
- memory than your operating system's default configuration
- allows. See <xref linkend="sysvipc"> for information on how to
- adjust those parameters, if necessary.
- </para>
-
- <variablelist>
- <varlistentry id="guc-max-fsm-pages" xreflabel="max_fsm_pages">
- <term><varname>max_fsm_pages</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>max_fsm_pages</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the maximum number of disk pages for which free space will
- be tracked in the shared free-space map. Six bytes of shared memory
- are consumed for each page slot. This setting must be more than
- 16 * <varname>max_fsm_relations</varname>. The default is 20000.
- This option can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-max-fsm-relations" xreflabel="max_fsm_relations">
- <term><varname>max_fsm_relations</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>max_fsm_relations</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the maximum number of relations (tables and indexes) for which
- free space will be tracked in the shared free-space map. Roughly
- seventy bytes of shared memory are consumed for each slot.
- The default is 1000.
- This option can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- <sect3 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>)</term>
- <indexterm>
- <primary><varname>max_files_per_process</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the maximum number of simultaneously open files allowed to each
- server subprocess. The default is 1000. 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 really support when a large number of processes all try to open
- that many files. If you find yourself seeing <quote>Too many open
- files</> failures, try reducing this setting.
- This option can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-preload-libraries" xreflabel="preload_libraries">
- <term><varname>preload_libraries</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>preload_libraries</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- This variable specifies one or more shared libraries that are
- to be preloaded at server start. A parameterless
- initialization function can optionally be called for each
- library. To specify that, add a colon and the name of the
- initialization function after the library name. For example
- <literal>'$libdir/mylib:mylib_init'</literal> would cause
- <literal>mylib</> to be preloaded and <literal>mylib_init</>
- to be executed. If more than one library is to be loaded,
- separate their names with commas.
- </para>
-
- <para>
- If a specified library or initialization function is not found,
- the server will fail to start.
- </para>
-
- <para>
- <productname>PostgreSQL</productname> procedural language
- libraries may be preloaded in this way, typically by using the
- syntax <literal>'$libdir/plXXX:plXXX_init'</literal> where
- <literal>XXX</literal> is <literal>pgsql</>, <literal>perl</>,
- <literal>tcl</>, or <literal>python</>.
- </para>
-
- <para>
- By preloading a shared library (and initializing it if
- applicable), the library startup time is avoided when the
- library is first used. However, the time to start each new
- server process may increase slightly, even if that process never
- uses the library. So this option is recommended only for
- libraries that will be used in most sessions.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
-
- <sect3 id="runtime-config-resource-vacuum-cost">
- <title id="runtime-config-resource-vacuum-cost-title">
- Cost-Based Vacuum Delay
- </title>
-
- <para>
- During the execution of <xref linkend="sql-vacuum"
- endterm="sql-vacuum-title"> and <xref linkend="sql-analyze"
- endterm="sql-analyze-title"> 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 while (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 in which it is not very
- 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. 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>integer</type>)</term>
- <indexterm>
- <primary><varname>vacuum_cost_delay</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- The length of time, in milliseconds, that the process will sleep
- when the cost limit has been exceeded.
- The default value is 0, which disables the cost-based vacuum
- delay feature. Positive values enable cost-based vacuuming.
- Note that on many systems, the effective resolution
- of sleep delays is 10 milliseconds; setting
- <varname>vacuum_cost_delay</varname> to a value that is
- not a multiple of 10 may have the same results as setting it
- to the next higher multiple of 10.
- </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>)</term>
- <indexterm>
- <primary><varname>vacuum_cost_page_hit</> configuration parameter</primary>
- </indexterm>
- <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 1.
- </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>)</term>
- <indexterm>
- <primary><varname>vacuum_cost_page_miss</> configuration parameter</primary>
- </indexterm>
- <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 10.
- </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>)</term>
- <indexterm>
- <primary><varname>vacuum_cost_page_dirty</> configuration parameter</primary>
- </indexterm>
- <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>)</term>
- <indexterm>
- <primary><varname>vacuum_cost_limit</> configuration parameter</primary>
- </indexterm>
- <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>
-
- </sect3>
-
- <sect3 id="runtime-config-resource-background-writer">
- <title>Background Writer</title>
-
- <para>
- Beginning in <productname>PostgreSQL</> 8.0, there is a separate server
- process called the <firstterm>background writer</>, whose sole function
- is to issue writes of <quote>dirty</> shared buffers. The intent is
- that server processes handling user queries should seldom or never have
- to wait for a write to occur, because the background writer will do it.
- This arrangement also reduces the performance penalty associated with
- checkpoints. The background writer will continuously trickle out dirty
- pages to disk, so that only a few pages will need to be forced out when
- checkpoint time arrives, instead of the storm of dirty-buffer writes that
- formerly occurred at each checkpoint. However there is a net overall
- increase in I/O load, because where a repeatedly-dirtied page might
- before have been written only once per checkpoint interval, the
- background writer might write it several times in the same interval.
- In most situations a continuous low load is preferable to periodic
- spikes, but the parameters discussed in this section 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>)</term>
- <indexterm>
- <primary><varname>bgwriter_delay</> configuration parameter</primary>
- </indexterm>
- <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 <varname>bgwriter_delay</>
- milliseconds, and repeats. The default value is 200. Note
- that on many systems, the effective resolution of sleep
- delays is 10 milliseconds; setting <varname>bgwriter_delay</>
- to a value that is not a multiple of 10 may have the same
- results as setting it to the next higher multiple of 10.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-bgwriter-lru-percent" xreflabel="bgwriter_lru_percent">
- <term><varname>bgwriter_lru_percent</varname> (<type>floating point</type>)</term>
- <indexterm>
- <primary><varname>bgwriter_lru_percent</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- To reduce the probability that server processes will need to issue
- their own writes, the background writer tries to write buffers that
- are likely to be recycled soon. In each round, it examines up to
- <varname>bgwriter_lru_percent</> of the buffers that are nearest to
- being recycled, and writes any that are dirty.
- The default value is 1.0 (this is a percentage of the total number
- of shared buffers).
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-bgwriter-lru-maxpages" xreflabel="bgwriter_lru_maxpages">
- <term><varname>bgwriter_lru_maxpages</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>bgwriter_lru_maxpages</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- In each round, no more than this many buffers will be written
- as a result of scanning soon-to-be-recycled buffers.
- The default value is 5.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-bgwriter-all-percent" xreflabel="bgwriter_all_percent">
- <term><varname>bgwriter_all_percent</varname> (<type>floating point</type>)</term>
- <indexterm>
- <primary><varname>bgwriter_all_percent</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- To reduce the amount of work that will be needed at checkpoint time,
- the background writer also does a circular scan through the entire
- buffer pool, writing buffers that are found to be dirty.
- In each round, it examines up to
- <varname>bgwriter_all_percent</> of the buffers for this purpose.
- The default value is 0.333 (this is a percentage of the total number
- of shared buffers). With the default <varname>bgwriter_delay</>
- setting, this will allow the entire shared buffer pool to be scanned
- about once per minute.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-bgwriter-all-maxpages" xreflabel="bgwriter_all_maxpages">
- <term><varname>bgwriter_all_maxpages</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>bgwriter_all_maxpages</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- In each round, no more than this many buffers will be written
- as a result of the scan of the entire buffer pool. (If this
- limit is reached, the scan stops, and resumes at the next buffer
- during the next round.)
- The default value is 5.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Smaller values of <varname>bgwriter_all_percent</varname> and
- <varname>bgwriter_all_maxpages</varname> reduce the extra I/O load
- caused by the background writer, but leave more work to be done
- at checkpoint time. To reduce load spikes at checkpoints,
- increase these two values.
- Similarly, smaller values of <varname>bgwriter_lru_percent</varname> and
- <varname>bgwriter_lru_maxpages</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.
- To disable background writing entirely,
- set both <varname>maxpages</varname> values and/or both
- <varname>percent</varname> values to zero.
- </para>
- </sect3>
-
- </sect2>
-
- <sect2 id="runtime-config-wal">
- <title>Write Ahead Log</title>
-
- <para>
- See also <xref linkend="wal-configuration"> for details on WAL
- tuning.
- </para>
-
- <sect3 id="runtime-config-wal-settings">
- <title>Settings</title>
- <variablelist>
-
- <varlistentry id="guc-fsync" xreflabel="fsync">
- <indexterm>
- <primary><varname>fsync</> configuration parameter</primary>
- </indexterm>
- <term><varname>fsync</varname> (<type>boolean</type>)</term>
- <listitem>
- <para>
- If this option is on, the <productname>PostgreSQL</> server
- will use the <function>fsync()</> system call in several places
- to make sure that updates are physically written to disk. This
- insures that a database cluster will recover to a
- consistent state after an operating system or hardware crash.
- </para>
-
- <para>
- However, using <function>fsync()</function> results in a
- performance penalty: when a transaction is committed,
- <productname>PostgreSQL</productname> must wait for the
- operating system to flush the write-ahead log to disk. When
- <varname>fsync</varname> is disabled, the operating system is
- allowed to do its best in buffering, ordering, and delaying
- writes. This can result in significantly improved performance.
- However, if the system crashes, the results of the last few
- committed transactions may be lost in part or whole. In the
- worst case, unrecoverable data corruption may occur.
- (Crashes of the database server itself are <emphasis>not</>
- a risk factor here. Only an operating-system-level crash
- creates a risk of corruption.)
- </para>
-
- <para>
- Due to the risks involved, there is no universally correct
- setting for <varname>fsync</varname>. Some administrators
- always disable <varname>fsync</varname>, while others only
- turn it off for bulk loads, where there is a clear restart
- point if something goes wrong, whereas some administrators
- always leave <varname>fsync</varname> enabled. The default is
- to enable <varname>fsync</varname>, for maximum reliability.
- If you trust your operating system, your hardware, and your
- utility company (or your battery backup), you can consider
- disabling <varname>fsync</varname>.
- </para>
-
- <para>
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file. If this option
- is <literal>off</>, consider also turning off
- <varname>guc-full-page-writes</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-wal-sync-method" xreflabel="wal_sync_method">
- <term><varname>wal_sync_method</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>wal_sync_method</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Method used for forcing WAL updates out to disk. Possible
- values are:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>open_datasync</> (write WAL files with <function>open()</> option <symbol>O_DSYNC</>)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fdatasync</> (call <function>fdatasync()</> at each commit),
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fsync</> (call <function>fsync()</> at each commit)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fsync_writethrough</> (force write-through of any disk write cache)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>open_sync</> (write WAL files with <function>open()</> option <symbol>O_SYNC</>)
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Not all of these choices are available on all platforms.
- The top-most supported option is used as the default.
- If <varname>fsync</varname> is off then this setting is irrelevant.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-full-page-writes" xreflabel="full_page_writes">
- <indexterm>
- <primary><varname>full_page_writes</> configuration parameter</primary>
- </indexterm>
- <term><varname>full_page_writes</varname> (<type>boolean</type>)</term>
- <listitem>
- <para>
- A page write in process during an operating system crash might
- be only partially written to disk, leading to an on-disk page
- that contains a mix of old and new data. During recovery, the
- row changes stored in WAL are not enough to completely restore
- the page.
- </para>
-
- <para>
- When this option is on, the <productname>PostgreSQL</> server
- writes full pages to WAL when they are first modified after a
- checkpoint so full recovery is possible. Turning this option off
- might lead to a corrupt system after an operating system crash
- or power failure because uncorrected partial pages might contain
- inconsistent or corrupt data. The risks are less but similar to
- <varname>fsync</>.
- </para>
-
- <para>
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file. The default is
- <literal>on</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-wal-buffers" xreflabel="wal_buffers">
- <term><varname>wal_buffers</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>wal_buffers</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Number of disk-page buffers allocated in shared memory for WAL data.
- The default is 8. The setting need only be large enough to hold
- the amount of WAL data generated by one typical transaction, since
- the data is flushed to disk at every transaction commit.
- This option can only be set at server start.
- </para>
-
- <para>
- Increasing this parameter may cause <productname>PostgreSQL</>
- to request more <systemitem class="osname">System V</> shared
- memory than your operating system's default configuration
- allows. See <xref linkend="sysvipc"> for information on how to
- adjust those parameters, if necessary.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-commit-delay" xreflabel="commit_delay">
- <term><varname>commit_delay</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>commit_delay</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Time delay between writing a commit record to the WAL buffer
- and flushing the buffer out to disk, in microseconds. A
- nonzero delay can allow multiple transactions to be committed
- with only one <function>fsync()</function> system call, if
- system load is high enough that additional transactions become
- ready to commit within the given interval. But the delay is
- just wasted if no other transactions become ready to
- commit. Therefore, the delay is only performed if at least
- <varname>commit_siblings</varname> other transactions are
- active at the instant that a server process has written its
- commit record. The default is zero (no delay).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-commit-siblings" xreflabel="commit_siblings">
- <term><varname>commit_siblings</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>commit_siblings</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Minimum number of concurrent open transactions to require
- before performing the <varname>commit_delay</> 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.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- <sect3 id="runtime-config-wal-checkpoints">
- <title>Checkpoints</title>
-
- <variablelist>
- <varlistentry id="guc-checkpoint-segments" xreflabel="checkpoint_segments">
- <term><varname>checkpoint_segments</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>checkpoint_segments</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Maximum distance between automatic WAL checkpoints, in log
- file segments (each segment is normally 16 megabytes). The
- default is three. This option can only be set at server start
- or in the <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-checkpoint-timeout" xreflabel="checkpoint_timeout">
- <term><varname>checkpoint_timeout</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>checkpoint_timeout</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Maximum time between automatic WAL checkpoints, in
- seconds. The default is 300 seconds. This option can only be
- set at server start or in the <filename>postgresql.conf</>
- file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-checkpoint-warning" xreflabel="checkpoint_warning">
- <term><varname>checkpoint_warning</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>checkpoint_warning</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Write a message to the server log if checkpoints caused by
- the filling of checkpoint segment files happen closer together
- than this many seconds. The default is 30 seconds.
- Zero turns off the warning.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- <sect3 id="runtime-config-wal-archiving">
- <title>Archiving</title>
-
- <variablelist>
- <varlistentry id="guc-archive-command" xreflabel="archive_command">
- <term><varname>archive_command</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>archive_command</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- The shell command to execute to archive a completed segment of
- the WAL file series. If this is an empty string (the default),
- WAL archiving is disabled. Any <literal>%p</> in the string is
- replaced by the absolute path of the file to archive, and any
- <literal>%f</> is replaced by the file name only. Use
- <literal>%%</> to embed an actual <literal>%</> character in the
- command. For more information see <xref
- linkend="backup-archiving-wal">. This option can only be set at
- server start or in the <filename>postgresql.conf</filename>
- file.
- </para>
- <para>
- It is important for the command to return a zero exit status if
- and only if it succeeds. Examples:
-<programlisting>
-archive_command = 'cp "%p" /mnt/server/archivedir/"%f"'
-archive_command = 'copy "%p" /mnt/server/archivedir/"%f"' # Windows
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- </sect2>
-
- <sect2 id="runtime-config-query">
- <title>Query Planning</title>
-
- <sect3 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 temporary solution may be found by using one
- of these configuration parameters to force the optimizer to
- choose a different plan. Turning one of these settings off
- permanently is seldom a good idea, however.
- Better ways to improve the quality of the
- plans chosen by the optimizer include adjusting the <xref
- linkend="runtime-config-query-constants"
- endterm="runtime-config-query-constants-title">, running <xref
- linkend="sql-analyze" endterm="sql-analyze-title"> more
- frequently, 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-bitmapscan" xreflabel="enable_bitmapscan">
- <term><varname>enable_bitmapscan</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary>bitmap scan</primary>
- </indexterm>
- <indexterm>
- <primary><varname>enable_bitmapscan</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of bitmap-scan plan
- types. The default is <literal>on</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-enable-hashagg" xreflabel="enable_hashagg">
- <term><varname>enable_hashagg</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>enable_hashagg</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of hashed
- aggregation plan types. The default is <literal>on</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-enable-hashjoin" xreflabel="enable_hashjoin">
- <term><varname>enable_hashjoin</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>enable_hashjoin</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of hash-join plan
- types. The default is <literal>on</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-enable-indexscan" xreflabel="enable_indexscan">
- <term><varname>enable_indexscan</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary>index scan</primary>
- </indexterm>
- <indexterm>
- <primary><varname>enable_indexscan</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of index-scan plan
- types. The default is <literal>on</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-enable-mergejoin" xreflabel="enable_mergejoin">
- <term><varname>enable_mergejoin</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>enable_mergejoin</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of merge-join plan
- types. The default is <literal>on</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-enable-nestloop" xreflabel="enable_nestloop">
- <term><varname>enable_nestloop</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>enable_nestloop</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of nested-loop join
- plans. It's not possible 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</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-enable-seqscan" xreflabel="enable_seqscan">
- <term><varname>enable_seqscan</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary>sequential scan</primary>
- </indexterm>
- <indexterm>
- <primary><varname>enable_seqscan</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of sequential scan
- plan types. It's not possible 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</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-enable-sort" xreflabel="enable_sort">
- <term><varname>enable_sort</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>enable_sort</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of explicit sort
- steps. It's not possible 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</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-enable-tidscan" xreflabel="enable_tidscan">
- <term><varname>enable_tidscan</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>enable_tidscan</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of <acronym>TID</>
- scan plan types. The default is <literal>on</>.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- <sect3 id="runtime-config-query-constants">
- <title id="runtime-config-query-constants-title">
- Planner Cost Constants
- </title>
-
- <note>
- <para>
- Unfortunately, there is no well-defined method for determining
- ideal values for the family of <quote>cost</quote> variables that
- appear below. You are encouraged to experiment and share
- your findings.
- </para>
- </note>
-
- <variablelist>
-
- <varlistentry id="guc-effective-cache-size" xreflabel="effective_cache_size">
- <term><varname>effective_cache_size</varname> (<type>floating point</type>)</term>
- <indexterm>
- <primary><varname>effective_cache_size</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the planner's assumption about the effective size of the
- disk cache that is available to a single index scan. 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. Also, take into
- account the expected number of concurrent queries using different
- indexes, since they will have to share the available space.
- This parameter has no effect on the size of shared memory
- allocated by PostgreSQL, nor does it reserve kernel disk cache;
- it is used only for estimation purposes.
- The value is measured in disk pages, which are
- normally 8192 bytes each. The default is 1000.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-random-page-cost" xreflabel="random_page_cost">
- <term><varname>random_page_cost</varname> (<type>floating point</type>)</term>
- <indexterm>
- <primary><varname>random_page_cost</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the planner's estimate of the cost of a
- nonsequentially fetched disk page. This is measured as a
- multiple of the cost of a sequential page fetch. A higher
- value makes it more likely a sequential scan will be used, a
- lower value makes it more likely an index scan will be
- used. The default is four.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-cpu-tuple-cost" xreflabel="cpu_tuple_cost">
- <term><varname>cpu_tuple_cost</varname> (<type>floating point</type>)</term>
- <indexterm>
- <primary><varname>cpu_tuple_cost</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the planner's estimate of the cost of processing
- each row during a query. This is measured as a fraction of
- the cost of a sequential page fetch. 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>)</term>
- <indexterm>
- <primary><varname>cpu_index_tuple_cost</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the planner's estimate of the cost of processing
- each index row during an index scan. This is measured as a
- fraction of the cost of a sequential page fetch. The default
- is 0.001.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-cpu-operator-cost" xreflabel="cpu_operator_cost">
- <term><varname>cpu_operator_cost</varname> (<type>floating point</type>)</term>
- <indexterm>
- <primary><varname>cpu_operator_cost</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the planner's estimate of the cost of processing each
- operator in a <literal>WHERE</> clause. This is measured as a fraction of
- the cost of a sequential page fetch. The default is 0.0025.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </sect3>
- <sect3 id="runtime-config-query-geqo">
- <title>Genetic Query Optimizer</title>
-
- <variablelist>
-
- <varlistentry id="guc-geqo" xreflabel="geqo">
- <indexterm>
- <primary>genetic query optimization</primary>
- </indexterm>
- <indexterm>
- <primary>GEQO</primary>
- <see>genetic query optimization</see>
- </indexterm>
- <indexterm>
- <primary><varname>geqo</> configuration parameter</primary>
- </indexterm>
- <term><varname>geqo</varname> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Enables or disables genetic query optimization, which is an
- algorithm that attempts to do query planning without
- exhaustive searching. This is on by default. The
- <varname>geqo_threshold</varname> variable provides a more
- granular way to disable GEQO for certain classes of queries.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-geqo-threshold" xreflabel="geqo_threshold">
- <term><varname>geqo_threshold</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>geqo_threshold</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Use genetic query optimization to plan queries with at least
- this many <literal>FROM</> items involved. (Note that an outer
- <literal>JOIN</> construct counts as only one <literal>FROM</>
- item.) The default is 12. For simpler queries it is usually best
- to use the deterministic, exhaustive planner, but for queries with
- many tables the deterministic planner takes too long.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-geqo-effort" xreflabel="geqo_effort">
- <term><varname>geqo_effort</varname>
- (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>geqo_effort</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls the trade off between planning time and query plan
- efficiency in GEQO. This variable must be an integer in the
- range from 1 to 10. The default value is 5. 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>)</term>
- <indexterm>
- <primary><varname>geqo_pool_size</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls the pool size used by GEQO. The pool size 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
- default 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>)</term>
- <indexterm>
- <primary><varname>geqo_generations</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls the number of generations used by GEQO. Generations
- specifies 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 default 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>)</term>
- <indexterm>
- <primary><varname>geqo_selection_bias</> configuration parameter</primary>
- </indexterm>
- <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>
-
- </variablelist>
- </sect3>
- <sect3 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>)</term>
- <indexterm>
- <primary><varname>default_statistics_target</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the default statistics target for table columns that have
- not had a column-specific target set via <command>ALTER TABLE
- SET STATISTICS</>. Larger values increase the time needed to
- do <command>ANALYZE</>, but may improve the quality of the
- planner's estimates. The default is 10. For more information
- on the use of statistics by the <productname>PostgreSQL</>
- 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>boolean</type>)</term>
- <indexterm>
- <primary>constraint exclusion</primary>
- </indexterm>
- <indexterm>
- <primary><varname>constraint_exclusion</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables or disables the query planner's use of table constraints to
- limit table access. The default is <literal>off</>.
- </para>
-
- <para>
- When this parameter is <literal>on</>, the planner compares query
- conditions with table CHECK constraints, and omits scanning tables
- where the conditions contradict the constraints. (Presently
- this is done only for child tables of inheritance scans.) 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 SELECT will not scan
- <structname>child1000</> at all. This can improve performance when
- inheritance is used to build partitioned tables.
- </para>
-
- <para>
- Currently, <varname>constraint_exclusion</> defaults to
- <literal>off</>, because it risks incorrect results if
- query plans are cached --- if a table constraint is changed or dropped,
- the previously generated plan might now be wrong, and there is no
- built-in mechanism to force re-planning. (This deficiency will
- probably be addressed in a future
- <productname>PostgreSQL</productname> release.) Another reason
- for keeping it off is that the constraint checks are relatively
- expensive, and in many circumstances will yield no savings.
- It is recommended to turn this on only if you are actually using
- partitioned tables designed to take advantage of the feature.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-from-collapse-limit" xreflabel="from_collapse_limit">
- <term><varname>from_collapse_limit</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>from_collapse_limit</> configuration parameter</primary>
- </indexterm>
- <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 may
- yield inferior query plans. The default is 8. It is usually
- wise to keep this less than <xref linkend="guc-geqo-threshold">.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-join-collapse-limit" xreflabel="join_collapse_limit">
- <term><varname>join_collapse_limit</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>join_collapse_limit</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- The planner will rewrite explicit inner <literal>JOIN</>
- constructs into lists of <literal>FROM</> items whenever a
- list of no more than this many items in total would
- result. Prior to <productname>PostgreSQL</> 7.4, joins
- specified via the <literal>JOIN</literal> construct would
- never be reordered by the query planner. The query planner has
- subsequently been improved so that inner joins written in this
- form can be reordered; this configuration parameter controls
- the extent to which this reordering is performed.
- <note>
- <para>
- At present, the order of outer joins specified via the
- <literal>JOIN</> construct is never adjusted by the query
- planner; therefore, <varname>join_collapse_limit</> has no
- effect on this behavior. The planner may be improved to
- reorder some classes of outer joins in a future release of
- <productname>PostgreSQL</productname>.
- </para>
- </note>
- </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
- inner <literal>JOIN</>s. Thus, the explicit join order
- specified in the query will be the actual order in which the
- relations are joined. The query planner does not always choose
- the optimal join order; advanced users may elect to
- temporarily set this variable to 1, and then specify the join
- order they desire explicitly. Another consequence of setting
- this variable to 1 is that the query planner will behave more
- like the <productname>PostgreSQL</productname> 7.3 query
- planner, which some users might find useful for backward
- compatibility reasons.
- </para>
-
- <para>
- Setting this variable to a value between 1 and
- <varname>from_collapse_limit</varname> might be useful to
- trade off planning time against the quality of the chosen plan
- (higher values produce better plans).
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- </sect2>
-
- <sect2 id="runtime-config-logging">
- <title>Error Reporting and Logging</title>
-
- <indexterm zone="runtime-config-logging">
- <primary>server log</primary>
- </indexterm>
-
- <sect3 id="runtime-config-logging-where">
- <title>Where to log</title>
-
- <indexterm zone="runtime-config-logging-where">
- <primary>where to log</primary>
- </indexterm>
-
- <variablelist>
-
- <varlistentry id="guc-log-destination" xreflabel="log_destination">
- <term><varname>log_destination</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>log_destination</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- <productname>PostgreSQL</productname> supports several methods
- for logging server messages, including
- <systemitem>stderr</systemitem> and
- <systemitem>syslog</systemitem>. On Windows,
- <systemitem>eventlog</systemitem> is also supported. Set this
- option to a list of desired log destinations separated by
- commas. The default is to log to <systemitem>stderr</systemitem>
- only.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-redirect-stderr" xreflabel="redirect_stderr">
- <term><varname>redirect_stderr</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>redirect_stderr</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- This option allows messages sent to <application>stderr</> to be
- captured and redirected into log files.
- This option, in combination with logging to <application>stderr</>,
- is often more useful than
- logging to <application>syslog</>, since some types of messages
- may not appear in <application>syslog</> output (a common example
- is dynamic-linker failure messages).
- This option can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-directory" xreflabel="log_directory">
- <term><varname>log_directory</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>log_directory</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When <varname>redirect_stderr</> is enabled, this option
- determines the directory in which log files will be created.
- It may be specified as an absolute path, or relative to the
- cluster data directory.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-filename" xreflabel="log_filename">
- <term><varname>log_filename</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>log_filename</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When <varname>redirect_stderr</varname> is enabled, this option
- sets the file names of the created log files. The value
- is treated as a <systemitem>strftime</systemitem> pattern,
- so <literal>%</literal>-escapes
- can be used to specify time-varying file names.
- If no <literal>%</literal>-escapes are present,
- <productname>PostgreSQL</productname> will
- append the epoch of the new log file's open time. For example,
- if <varname>log_filename</varname> were <literal>server_log</literal>, then the
- chosen file name would be <literal>server_log.1093827753</literal>
- for a log starting at Sun Aug 29 19:02:33 2004 MST.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-rotation-age" xreflabel="log_rotation_age">
- <term><varname>log_rotation_age</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>log_rotation_age</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When <varname>redirect_stderr</varname> is enabled, this option
- determines the maximum lifetime of an individual log file.
- After this many minutes have elapsed, a new log file will
- be created. Set to zero to disable time-based creation of
- new log files.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-rotation-size" xreflabel="log_rotation_size">
- <term><varname>log_rotation_size</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>log_rotation_size</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When <varname>redirect_stderr</varname> is enabled, this option
- determines the maximum size of an individual log file.
- After this many kilobytes have been emitted into a log file,
- a new log file will be created. Set to zero to disable size-based
- creation of new log files.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
- </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>)</term>
- <indexterm>
- <primary><varname>log_truncate_on_rotation</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When <varname>redirect_stderr</varname> is enabled, this option 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 option 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 option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
- </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</> in <varname>log_filename</varname> allows
- any size-driven rotations that may occur to select a filename
- different from the hour's initial filename.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-syslog-facility" xreflabel="syslog_facility">
- <term><varname>syslog_facility</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>syslog_facility</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When logging to <application>syslog</> is enabled, this option
- determines the <application>syslog</application>
- <quote>facility</quote> to be used. You may choose
- from <literal>LOCAL0</>, <literal>LOCAL1</>,
- <literal>LOCAL2</>, <literal>LOCAL3</>, <literal>LOCAL4</>,
- <literal>LOCAL5</>, <literal>LOCAL6</>, <literal>LOCAL7</>;
- the default is <literal>LOCAL0</>. See also the
- documentation of your system's
- <application>syslog</application> daemon.
- This option can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-syslog-ident" xreflabel="syslog_ident">
- <term><varname>syslog_ident</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>syslog_identity</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When logging to <application>syslog</> is enabled, this option
- determines the program name used to identify
- <productname>PostgreSQL</productname> messages in
- <application>syslog</application> logs. The default is
- <literal>postgres</literal>.
- This option can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- <sect3 id="runtime-config-logging-when">
- <title>When To Log</title>
-
- <variablelist>
-
- <varlistentry id="guc-client-min-messages" xreflabel="client_min_messages">
- <term><varname>client_min_messages</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>client_min_messages</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls which message levels are sent to the client.
- Valid values are <literal>DEBUG5</>,
- <literal>DEBUG4</>, <literal>DEBUG3</>, <literal>DEBUG2</>,
- <literal>DEBUG1</>, <literal>LOG</>, <literal>NOTICE</>,
- <literal>WARNING</>, and <literal>ERROR</>. Each level
- includes all the levels that follow it. The later the level,
- the fewer messages are sent. The default is
- <literal>NOTICE</>. Note that <literal>LOG</> has a different
- rank here than in <varname>log_min_messages</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-min-messages" xreflabel="log_min_messages">
- <term><varname>log_min_messages</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>log_min_messages</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls which message levels are written to the server log.
- Valid values are <literal>DEBUG5</>, <literal>DEBUG4</>,
- <literal>DEBUG3</>, <literal>DEBUG2</>, <literal>DEBUG1</>,
- <literal>INFO</>, <literal>NOTICE</>, <literal>WARNING</>,
- <literal>ERROR</>, <literal>LOG</>, <literal>FATAL</>, and
- <literal>PANIC</>. 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>NOTICE</>. Note that
- <literal>LOG</> has a different rank here than in
- <varname>client_min_messages</>.
- Only superusers can change this setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-error-verbosity" xreflabel="log_error_verbosity">
- <term><varname>log_error_verbosity</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>log_error_verbosity</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls the amount of detail written in the server log for each
- message that is logged. Valid values are <literal>TERSE</>,
- <literal>DEFAULT</>, and <literal>VERBOSE</>, each adding more
- fields to displayed messages.
- Only superusers can change this setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-min-error-statement" xreflabel="log_min_error_statement">
- <term><varname>log_min_error_statement</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>log_min_error_statement</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls whether or not the SQL statement that causes an error
- condition will also be recorded in the server log. All SQL
- statements that cause an error of the specified level or
- higher are logged. The default is
- <literal>PANIC</literal> (effectively turning this feature
- off for normal use). 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>FATAL</literal>, and <literal>PANIC</literal>. For
- example, if you set this to <literal>ERROR</literal> then all
- SQL statements causing errors, fatal errors, or panics will be
- logged. Enabling this option can be helpful in tracking down
- the source of any errors that appear in the server log.
- Only superusers can change this setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-min-duration-statement" xreflabel="log_min_duration_statement">
- <term><varname>log_min_duration_statement</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>log_min_duration_statement</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Logs the statement and its duration on a single log line if its
- duration is greater than or equal to the specified number of
- milliseconds. Setting this to zero will print all statements
- and their durations. Minus-one (the default) disables the
- feature. For example, if you set it to <literal>250</literal>
- then all SQL statements that run 250ms or longer will be
- logged. Enabling this option can be useful in tracking down
- unoptimized queries in your applications. This setting is
- independent of <varname>log_statement</varname> and
- <varname>log_duration</varname>. Only superusers can change
- this setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-silent-mode" xreflabel="silent_mode">
- <term><varname>silent_mode</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>silent_mode</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Runs the server silently. If this option is set, the server
- will automatically run in background and any controlling
- terminals are disassociated (same effect as
- <command>postmaster</>'s <option>-S</option> option).
- The server's standard output and standard error are redirected
- to <literal>/dev/null</>, so any messages sent to them will be lost.
- Unless <application>syslog</> logging is selected or
- <varname>redirect_stderr</> is enabled, using this option
- is discouraged because it makes it impossible to see error messages.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>
- Here is a list of the various message severity levels used in
- these settings:
- <variablelist>
- <varlistentry>
- <term><literal>DEBUG[1-5]</literal></term>
- <listitem>
- <para>
- Provides information for use by developers.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>INFO</literal></term>
- <listitem>
- <para>
- Provides information implicitly requested by the user,
- e.g., during <command>VACUUM VERBOSE</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>NOTICE</literal></term>
- <listitem>
- <para>
- Provides information that may be helpful to users, e.g.,
- truncation of long identifiers and the creation of indexes as part
- of primary keys.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>WARNING</literal></term>
- <listitem>
- <para>
- Provides warnings to the user, e.g., <command>COMMIT</>
- outside a transaction block.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>ERROR</literal></term>
- <listitem>
- <para>
- Reports an error that caused the current command to abort.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>LOG</literal></term>
- <listitem>
- <para>
- Reports information of interest to administrators, e.g.,
- checkpoint activity.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>FATAL</literal></term>
- <listitem>
- <para>
- Reports an error that caused the current session to abort.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>PANIC</literal></term>
- <listitem>
- <para>
- Reports an error that caused all sessions to abort.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- </sect3>
- <sect3 id="runtime-config-logging-what">
- <title>What To Log</title>
-
- <variablelist>
-
- <varlistentry>
- <term><varname>debug_print_parse</varname> (<type>boolean</type>)</term>
- <term><varname>debug_print_rewritten</varname> (<type>boolean</type>)</term>
- <term><varname>debug_print_plan</varname> (<type>boolean</type>)</term>
- <term><varname>debug_pretty_print</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>debug_print_parse</> configuration parameter</primary>
- </indexterm>
- <indexterm>
- <primary><varname>debug_print_rewritten</> configuration parameter</primary>
- </indexterm>
- <indexterm>
- <primary><varname>debug_print_plan</> configuration parameter</primary>
- </indexterm>
- <indexterm>
- <primary><varname>debug_pretty_print</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- These options enable various debugging output to be emitted.
- For each executed query, they print
- the resulting parse tree, the query rewriter output, or the
- execution plan. <varname>debug_pretty_print</varname> indents
- these displays to produce a more readable but much longer
- output format. <varname>client_min_messages</varname> or
- <varname>log_min_messages</varname> must be
- <literal>DEBUG1</literal> or lower to actually send this output
- to the client or the server log, respectively.
- These options are off by default.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-connections" xreflabel="log_connections">
- <term><varname>log_connections</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>log_connections</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- This outputs a line to the server log detailing each successful
- connection. This is off by default, although it is probably very
- useful. This option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-disconnections" xreflabel="log_disconnections">
- <term><varname>log_disconnections</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>log_disconnections</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- This outputs a line in the server log similar to
- <varname>log_connections</varname> but at session termination,
- and includes the duration of the session. This is off by
- default. This option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
- </para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry id="guc-log-duration" xreflabel="log_duration">
- <term><varname>log_duration</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>log_duration</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Causes the duration of every completed statement which satisfies
- <varname>log_statement</> to be logged. When using this option,
- if you are not using <application>syslog</>, it is recommended
- that you log the PID or session ID using <varname>log_line_prefix</>
- so that you can link the statement to the
- duration using the process ID or session ID. The default is
- <literal>off</>. Only superusers can change this setting.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-line-prefix" xreflabel="log_line_prefix">
- <term><varname>log_line_prefix</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>log_line_prefix</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- This is a <function>printf</>-style string that is output at the
- beginning of each log line. The default is an empty string.
- Each recognized escape is replaced as outlined
- below - anything else that looks like an escape is ignored. Other
- characters are copied straight to the log line. Some escapes are
- only recognised by session processes, and do not apply to
- background processes such as the postmaster. <application>Syslog</>
- produces its own
- time stamp and process ID information, so you probably do not want to
- use those escapes if you are using <application>syslog</>.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
-
- <informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Escape</entry>
- <entry>Effect</entry>
- <entry>Session only</entry>
- </row>
- </thead>
- <tbody>
- <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 Hostname or IP address</entry>
- <entry>yes</entry>
- </row>
- <row>
- <entry><literal>%p</literal></entry>
- <entry>Process ID</entry>
- <entry>no</entry>
- </row>
- <row>
- <entry><literal>%t</literal></entry>
- <entry>Time stamp (no 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>%i</literal></entry>
- <entry>Command tag: This is the command that generated the log line.</entry>
- <entry>yes</entry>
- </row>
- <row>
- <entry><literal>%c</literal></entry>
- <entry>Session ID: A unique identifier for each session.
- It is 2 4-byte hexadecimal numbers (without leading zeros)
- separated by a dot. The numbers
- are the session start time and the process ID, so this can also
- be used as a space saving way of printing these items.</entry>
- <entry>yes</entry>
- </row>
- <row>
- <entry><literal>%l</literal></entry>
- <entry>Number of the log line for each process, starting at 1</entry>
- <entry>no</entry>
- </row>
- <row>
- <entry><literal>%s</literal></entry>
- <entry>Session start time stamp</entry>
- <entry>yes</entry>
- </row>
- <row>
- <entry><literal>%x</literal></entry>
- <entry>Transaction ID</entry>
- <entry>yes</entry>
- </row>
- <row>
- <entry><literal>%q</literal></entry>
- <entry>Does not produce any 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>%%</literal></entry>
- <entry>Literal <literal>%</></entry>
- <entry>no</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-statement" xreflabel="log_statement">
- <term><varname>log_statement</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>log_statement</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls which SQL statements are logged. Valid values are
- <literal>none</>, <literal>ddl</>, <literal>mod</>, and
- <literal>all</>. <literal>ddl</> logs all data definition
- commands like <literal>CREATE</>, <literal>ALTER</>, and
- <literal>DROP</> commands. <literal>mod</> logs all
- <literal>ddl</> statements, plus <literal>INSERT</>,
- <literal>UPDATE</>, <literal>DELETE</>, <literal>TRUNCATE</>,
- and <literal>COPY FROM</>. <literal>PREPARE</> and
- <literal>EXPLAIN ANALYZE</> statements are also logged if their
- contained command is of an appropriate type.
- </para>
- <para>
- The default is <literal>none</>. Only superusers can change this
- setting.
- </para>
-
- <note>
- <para>
- The <command>EXECUTE</command> statement is not considered a
- <literal>ddl</> or <literal>mod</> statement. When it is logged,
- only the name of the prepared statement is reported, not the
- actual prepared statement.
- </para>
-
- <para>
- When a function is defined in the
- <application>PL/pgSQL</application>server-side language, any queries
- executed by the function will only be logged the first time that the
- function is invoked in a particular session. This is because
- <application>PL/pgSQL</application> keeps a cache of the
- query plans produced for the SQL statements in the function.
- </para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-log-hostname" xreflabel="log_hostname">
- <term><varname>log_hostname</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>log_hostname</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- By default, connection log messages only show the IP address of the
- connecting host. Turning on this option 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
- option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- </sect2>
-
- <sect2 id="runtime-config-statistics">
- <title>Runtime Statistics</title>
-
- <sect3 id="runtime-config-statistics-monitor">
- <title>Statistics Monitoring</title>
- <variablelist>
-
- <varlistentry>
- <term><varname>log_statement_stats</varname> (<type>boolean</type>)</term>
- <term><varname>log_parser_stats</varname> (<type>boolean</type>)</term>
- <term><varname>log_planner_stats</varname> (<type>boolean</type>)</term>
- <term><varname>log_executor_stats</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>log_statement_stats</> configuration parameter</primary>
- </indexterm>
- <indexterm>
- <primary><varname>log_parser_stats</> configuration parameter</primary>
- </indexterm>
- <indexterm>
- <primary><varname>log_planner_stats</> configuration parameter</primary>
- </indexterm>
- <indexterm>
- <primary><varname>log_executor_stats</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- For each query, write performance statistics of the respective
- module to the server log. This is a crude profiling
- instrument. <varname>log_statement_stats</varname> reports total
- statement statistics, while the others report per-module statistics.
- <varname>log_statement_stats</varname> cannot be enabled together with
- any of the per-module options. All of these options are disabled by
- default. Only superusers can change these settings.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </sect3>
- <sect3 id="runtime-config-statistics-collector">
- <title>Query and Index Statistics Collector</title>
- <variablelist>
-
- <varlistentry id="guc-stats-start-collector" xreflabel="stats_start_collector">
- <term><varname>stats_start_collector</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>stats_start_collector</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls whether the server should start the
- statistics-collection subprocess. This is on by default, but
- may be turned off if you know you have no interest in
- collecting statistics. This option can only be set at server
- start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-stats-command-string" xreflabel="stats_command_string">
- <term><varname>stats_command_string</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>stats_command_string</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables the collection of statistics on the currently
- executing command of each session, along with the time at
- which that command began execution. This option is off by
- default. Note that even when enabled, this information is not
- visible to all users, only to superusers and the user owning
- the session being reported on; so it should not represent a
- security risk. This data can be accessed via the
- <structname>pg_stat_activity</structname> system view; refer
- to <xref linkend="monitoring"> for more information.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-stats-block-level" xreflabel="stats_block_level">
- <term><varname>stats_block_level</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>stats_block_level</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables the collection of block-level statistics on database
- activity. This option is disabled by default. If this option
- is enabled, the data that is produced can be accessed via the
- <structname>pg_stat</structname> and
- <structname>pg_statio</structname> family of system views;
- refer to <xref linkend="monitoring"> for more information.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-stats-row-level" xreflabel="stats_row_level">
- <term><varname>stats_row_level</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>stats_row_level</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Enables the collection of row-level statistics on database
- activity. This option is disabled by default. If this option
- is enabled, the data that is produced can be accessed via the
- <structname>pg_stat</structname> and
- <structname>pg_statio</structname> family of system views;
- refer to <xref linkend="monitoring"> for more information.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-stats-reset-on-server-start" xreflabel="stats_reset_on_server_start">
- <term><varname>stats_reset_on_server_start</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>stats_reset_on_server_start</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- If on, collected statistics are zeroed out whenever the server
- is restarted. If off, statistics are accumulated across server
- restarts. The default is <literal>off</>. This option can only
- be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- </sect2>
-
- <sect2 id="runtime-config-autovacuum">
- <title>Automatic Vacuuming</title>
-
- <para>
- Beginning in <productname>PostgreSQL</> 8.1, there is an optional server
- process called the <firstterm>autovacuum daemon</>, whose purpose is
- to automate the issuance of periodic <command>VACUUM</> and
- <command>ANALYZE</> commands. When enabled, the autovacuum daemon
- runs periodically and checks for tables that have had a large number
- of updated or deleted tuples. This check uses the row-level statistics
- collection facility; therefore, the autovacuum daemon cannot be used
- unless <xref linkend="guc-stats-start-collector"> and
- <xref linkend="guc-stats-row-level"> are set TRUE. Also, it's
- important to allow a slot for the autovacuum process when choosing
- the value of <xref linkend="guc-superuser-reserved-connections">.
- </para>
-
- <variablelist>
-
- <varlistentry id="guc-autovacuum" xreflabel="autovacuum">
- <term><varname>autovacuum</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>autovacuum</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Controls whether the server should start the
- autovacuum subprocess. This is off by default.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-autovacuum-naptime" xreflabel="autovacuum_naptime">
- <term><varname>autovacuum_naptime</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>autovacuum_naptime</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the delay between activity rounds for the autovacuum
- subprocess. In each round the subprocess examines one database
- and issues <command>VACUUM</> and <command>ANALYZE</> commands
- as needed for tables in that database. The delay is measured
- in seconds, and the default is 60.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-autovacuum-vacuum-threshold" xreflabel="autovacuum_vacuum_threshold">
- <term><varname>autovacuum_vacuum_threshold</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>autovacuum_vacuum_threshold</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the minimum number of updated or deleted tuples needed
- to trigger a <command>VACUUM</> in any one table.
- The default is 1000.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-autovacuum-analyze-threshold" xreflabel="autovacuum_analyze_threshold">
- <term><varname>autovacuum_analyze_threshold</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>autovacuum_analyze_threshold</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the minimum number of inserted, updated or deleted tuples
- needed to trigger an <command>ANALYZE</> in any one table.
- The default is 500.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </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>)</term>
- <indexterm>
- <primary><varname>autovacuum_vacuum_scale_factor</> configuration parameter</primary>
- </indexterm>
- <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</>.
- The default is 0.4.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </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>)</term>
- <indexterm>
- <primary><varname>autovacuum_analyze_scale_factor</> configuration parameter</primary>
- </indexterm>
- <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</>.
- The default is 0.2.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-autovacuum-vacuum-cost-delay" xreflabel="autovacuum_vacuum_cost_delay">
- <term><varname>autovacuum_vacuum_cost_delay</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>autovacuum_vacuum_cost_delay</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the cost delay value that will be used in automatic
- <command>VACUUM</> operations. If -1 is specified (which is the
- default), the regular
- <xref linkend="guc-vacuum-cost-delay"> value will be used.
- This setting can be overridden for individual tables by entries in
- <structname>pg_autovacuum</>.
- </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>)</term>
- <indexterm>
- <primary><varname>autovacuum_vacuum_cost_limit</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Specifies the cost limit value that will be used in automatic
- <command>VACUUM</> operations. If -1 is specified (which is the
- default), the regular
- <xref linkend="guc-vacuum-cost-limit"> value will be used.
- This setting can be overridden for individual tables by entries in
- <structname>pg_autovacuum</>.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect2>
-
- <sect2 id="runtime-config-client">
- <title>Client Connection Defaults</title>
-
- <sect3 id="runtime-config-client-statement">
- <title>Statement Behavior</title>
- <variablelist>
-
- <varlistentry id="guc-search-path" xreflabel="search_path">
- <term><varname>search_path</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>search_path</> configuration parameter</primary>
- </indexterm>
- <indexterm><primary>path</><secondary>for schemas</></>
- <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 component. 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> has to be a comma-separated
- list of schema names. If one of the list items is
- the special value <literal>$user</literal>, then the schema
- having the name returned by <function>SESSION_USER</> is substituted, if there
- is such a schema. (If not, <literal>$user</literal> is ignored.)
- </para>
-
- <para>
- The system catalog schema, <literal>pg_catalog</>, 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</> is not in the path then it will
- be searched <emphasis>before</> searching any of the path items.
- It should also be noted that the temporary-table schema,
- <literal>pg_temp_<replaceable>nnn</></>, is implicitly searched before any of
- these.
- </para>
-
- <para>
- When objects are created without specifying a particular target
- schema, they will be placed in the first schema listed
- in the search path. An error is reported if the search path is
- empty.
- </para>
-
- <para>
- The default value for this parameter is
- <literal>'$user, public'</literal> (where the second part will be
- ignored if there is no schema named <literal>public</>).
- This supports shared use of a database (where no users
- have private schemas, and all share use of <literal>public</>),
- 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>
- The current effective value of the search path can be examined
- via the <acronym>SQL</acronym> function
- <function>current_schemas()</>. This is not quite the same as
- examining the value of <varname>search_path</varname>, since
- <function>current_schemas()</> shows how the requests
- appearing in <varname>search_path</varname> were resolved.
- </para>
-
- <para>
- For more information on schema handling, see <xref linkend="ddl-schemas">.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-default-tablespace" xreflabel="default_tablespace">
- <term><varname>default_tablespace</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>default_tablespace</> configuration parameter</primary>
- </indexterm>
- <indexterm><primary>tablespace</><secondary>default</></>
- <listitem>
- <para>
- This variable specifies the default tablespace in which to create
- objects (tables and indexes) when a <command>CREATE</> 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</> will automatically use the default
- tablespace of the current database.
- </para>
-
- <para>
- For more information on tablespaces,
- see <xref linkend="manage-ag-tablespaces">.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-check-function-bodies" xreflabel="check_function_bodies">
- <term><varname>check_function_bodies</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>check_function_bodies</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- This parameter is normally on. When set to <literal>off</>, it
- disables validation of the function body string during <xref
- linkend="sql-createfunction"
- endterm="sql-createfunction-title">. Disabling validation is
- occasionally useful to avoid problems such as forward references
- when restoring function definitions from a dump.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-default-transaction-isolation" xreflabel="default_transaction_isolation">
- <indexterm>
- <primary>transaction isolation level</primary>
- </indexterm>
- <indexterm>
- <primary><varname>default_transaction_isolation</> configuration parameter</primary>
- </indexterm>
- <term><varname>default_transaction_isolation</varname> (<type>string</type>)</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"
- endterm="sql-set-transaction-title"> for more information.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-default-transaction-read-only" xreflabel="default_transaction_read_only">
- <indexterm>
- <primary>read-only transaction</primary>
- </indexterm>
- <indexterm>
- <primary><varname>default_transaction_read_only</> configuration parameter</primary>
- </indexterm>
-
- <term><varname>default_transaction_read_only</varname> (<type>boolean</type>)</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</> (read/write).
- </para>
-
- <para>
- Consult <xref linkend="sql-set-transaction"
- endterm="sql-set-transaction-title"> for more information.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-statement-timeout" xreflabel="statement_timeout">
- <term><varname>statement_timeout</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>statement_timeout</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Abort any statement that takes over the specified number of
- milliseconds. A value of zero (the default) turns off the limitation.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- <sect3 id="runtime-config-client-format">
- <title>Locale and Formatting</title>
-
- <variablelist>
-
- <varlistentry id="guc-datestyle" xreflabel="DateStyle">
- <term><varname>DateStyle</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>DateStyle</> configuration parameter</primary>
- </indexterm>
- <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>Postgres</>, <literal>SQL</>, or <literal>German</>)
- and the input/output specification for year/month/day ordering
- (<literal>DMY</>, <literal>MDY</>, or <literal>YMD</>). These
- can be set separately or together. The keywords <literal>Euro</>
- and <literal>European</> are synonyms for <literal>DMY</>; the
- keywords <literal>US</>, <literal>NonEuro</>, and
- <literal>NonEuropean</> are synonyms for <literal>MDY</>. See
- <xref linkend="datatype-datetime"> for more information. The
- default is <literal>ISO, MDY</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-timezone" xreflabel="timezone">
- <term><varname>timezone</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>timezone</> configuration parameter</primary>
- </indexterm>
- <indexterm><primary>time zone</></>
- <listitem>
- <para>
- Sets the time zone for displaying and interpreting time
- stamps. The default is 'unknown', which means to use whatever
- the system environment specifies as the time zone. See <xref
- linkend="datatype-datetime"> for more information.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-australian-timezones" xreflabel="australian_timezones">
- <term><varname>australian_timezones</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>australian_timezones</> configuration parameter</primary>
- </indexterm>
- <indexterm><primary>time zone</><secondary>Australian</></>
- <listitem>
- <para>
- If set to on, <literal>ACST</literal>,
- <literal>CST</literal>, <literal>EST</literal>, and
- <literal>SAT</literal> are interpreted as Australian time
- zones rather than as North/South American time zones and
- Saturday. The default is <literal>off</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-extra-float-digits" xreflabel="extra_float_digits">
- <indexterm>
- <primary>significant digits</primary>
- </indexterm>
- <indexterm>
- <primary>floating-point</primary>
- <secondary>display</secondary>
- </indexterm>
- <indexterm>
- <primary><varname>extra_float_digits</> configuration parameter</primary>
- </indexterm>
-
- <term><varname>extra_float_digits</varname> (<type>integer</type>)</term>
- <listitem>
- <para>
- This parameter adjusts the number of digits displayed for
- floating-point values, including <type>float4</>, <type>float8</>,
- and geometric data types. The parameter value is added to the
- standard number of digits (<literal>FLT_DIG</> or <literal>DBL_DIG</>
- as appropriate). The value can be set as high as 2, to include
- partially-significant digits; this is especially useful for dumping
- float data that needs to be restored exactly. Or it can be set
- negative to suppress unwanted digits.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-client-encoding" xreflabel="client_encoding">
- <term><varname>client_encoding</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>client_encoding</> configuration parameter</primary>
- </indexterm>
- <indexterm><primary>character set</></>
- <listitem>
- <para>
- Sets the client-side encoding (character set).
- The default is to use the database encoding.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-lc-messages" xreflabel="lc_messages">
- <term><varname>lc_messages</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>lc_messages</> configuration parameter</primary>
- </indexterm>
- <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>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-lc-monetary" xreflabel="lc_monetary">
- <term><varname>lc_monetary</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>lc_monetary</> configuration parameter</primary>
- </indexterm>
- <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>)</term>
- <indexterm>
- <primary><varname>lc_numeric</> configuration parameter</primary>
- </indexterm>
- <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>)</term>
- <indexterm>
- <primary><varname>lc_time</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Sets the locale to use for formatting date and time values.
- (Currently, this setting does nothing, but it may in the
- future.) 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>
-
- </variablelist>
-
- </sect3>
- <sect3 id="runtime-config-client-other">
- <title>Other Defaults</title>
-
- <variablelist>
-
- <varlistentry id="guc-explain-pretty-print" xreflabel="explain_pretty_print">
- <term><varname>explain_pretty_print</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>explain_pretty_print</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Determines whether <command>EXPLAIN VERBOSE</> uses the
- indented or non-indented format for displaying detailed
- query-tree dumps. The default is <literal>on</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-dynamic-library-path" xreflabel="dynamic_library_path">
- <term><varname>dynamic_library_path</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>dynamic_library_path</> configuration parameter</primary>
- </indexterm>
- <indexterm><primary>dynamic loading</></>
- <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> has to be a
- list of absolute directory paths separated by colons (or semi-colons
- on Windows). If a list element starts
- with the special string <literal>$libdir</literal>, the
- compiled-in <productname>PostgreSQL</productname> package
- library directory is substituted for <literal>$libdir</literal>. This
- is where the modules provided by the standard
- <productname>PostgreSQL</productname> distribution are installed.
- (Use <literal>pg_config --pkglibdir</literal> to find out the name of
- this directory.) For example:
-<programlisting>
-dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
-</programlisting>
- or, in a Windows environment:
-<programlisting>
-dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
-</programlisting>
- </para>
-
- <para>
- The default value for this parameter is
- <literal>'$libdir'</literal>. If the value is set to an empty
- string, the automatic path search is turned off.
- </para>
-
- <para>
- This parameter can be changed at run time by superusers, but a
- setting done that way will only persist until the end of the
- client connection, so this method should be reserved for
- development purposes. The recommended way to set this parameter
- is in the <filename>postgresql.conf</filename> configuration
- file.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- </sect2>
-
- <sect2 id="runtime-config-locks">
- <title>Lock Management</title>
-
- <variablelist>
-
- <varlistentry id="guc-deadlock-timeout" xreflabel="deadlock_timeout">
- <indexterm>
- <primary>deadlock</primary>
- <secondary>timeout during</secondary>
- </indexterm>
- <indexterm>
- <primary>timeout</primary>
- <secondary>deadlock</secondary>
- </indexterm>
- <indexterm>
- <primary><varname>deadlock_timeout</> configuration parameter</primary>
- </indexterm>
-
- <term><varname>deadlock_timeout</varname> (<type>integer</type>)</term>
- <listitem>
- <para>
- This is the amount of time, in milliseconds, to wait on a lock
- before checking to see if there is a deadlock condition. The
- check for deadlock is relatively slow, 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 starting the check for a
- deadlock. Increasing this value reduces the amount of time
- wasted in needless deadlock checks, but slows down reporting of
- real deadlock errors. The default is 1000 (i.e., one second),
- 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.
- </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>)</term>
- <indexterm>
- <primary><varname>max_locks_per_transaction</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- The shared lock table is created with room to describe locks on
- <varname>max_locks_per_transaction</varname> *
- (<xref linkend="guc-max-connections"> +
- <xref linkend="guc-max-prepared-transactions">) objects;
- hence, no more than this many distinct objects can
- be locked at any one time. (Thus, this parameter's name may be
- confusing: it is not a hard limit on the number of locks taken
- by any one transaction, but rather a maximum average value.)
- The default, 64, has historically
- proven sufficient, but you might need to raise this value if you
- have clients that touch many different tables in a single
- transaction. This option can only be set at server start.
- </para>
-
- <para>
- Increasing this parameter may cause <productname>PostgreSQL</>
- to request more <systemitem class="osname">System V</> shared
- memory than your operating system's default configuration
- allows. See <xref linkend="sysvipc"> for information on how to
- adjust those parameters, if necessary.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect2>
-
- <sect2 id="runtime-config-compatible">
- <title>Version and Platform Compatibility</title>
-
- <sect3 id="runtime-config-compatible-version">
- <title>Previous PostgreSQL Versions</title>
- <variablelist>
-
- <varlistentry id="guc-add-missing-from" xreflabel="add_missing_from">
- <term><varname>add_missing_from</varname> (<type>boolean</type>)</term>
- <indexterm><primary>FROM</><secondary>missing</></>
- <indexterm>
- <primary><varname>add_missing_from</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When on, tables that are referenced by a query will be
- automatically added to the <literal>FROM</> clause if not
- already present. This behavior does not comply with the SQL
- standard and many people dislike it because it can mask mistakes
- (such as referencing a table where you should have referenced
- its alias). The default is <literal>off</>. This variable can be
- enabled for compatibility with releases of
- <productname>PostgreSQL</> prior to 8.1, where this behavior was
- allowed by default.
- </para>
-
- <para>
- Note that even when this variable is enabled, a warning
- message will be emitted for each implicit <literal>FROM</>
- entry referenced by a query. Users are encouraged to update
- their applications to not rely on this behavior, by adding all
- tables referenced by a query to the query's <literal>FROM</>
- clause (or its <literal>USING</> clause in the case of
- <command>DELETE</>).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-regex-flavor" xreflabel="regex_flavor">
- <term><varname>regex_flavor</varname> (<type>string</type>)</term>
- <indexterm><primary>regular expressions</></>
- <indexterm>
- <primary><varname>regex_flavor</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- The regular expression <quote>flavor</> can be set to
- <literal>advanced</>, <literal>extended</>, or <literal>basic</>.
- The default is <literal>advanced</>. The <literal>extended</>
- setting may be useful for exact backwards compatibility with
- pre-7.4 releases of <productname>PostgreSQL</>. See
- <xref linkend="posix-syntax-details"> for details.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-sql-inheritance" xreflabel="sql_inheritance">
- <term><varname>sql_inheritance</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>sql_inheritance</> configuration parameter</primary>
- </indexterm>
- <indexterm><primary>inheritance</></>
- <listitem>
- <para>
- This controls the inheritance semantics, in particular whether
- subtables are included by various commands by default. They were
- not included in versions prior to 7.1. If you need the old
- behavior you can set this variable to <literal>off</>, but in
- the long run you are encouraged to change your applications to
- use the <literal>ONLY</literal> key word to exclude subtables.
- See <xref linkend="ddl-inherit"> for more information about
- inheritance.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-default-with-oids" xreflabel="default_with_oids">
- <term><varname>default_with_oids</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>default_with_oids</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- This controls whether <command>CREATE TABLE</command> and
- <command>CREATE TABLE AS</command> include an OID column in
- newly-created tables, if neither <literal>WITH OIDS</literal>
- nor <literal>WITHOUT OIDS</literal> is specified. It also
- determines whether OIDs will be included in tables created by
- <command>SELECT INTO</command>. In <productname>PostgreSQL</>
- 8.1 <varname>default_with_oids</> is disabled by default; in
- prior versions of PostgreSQL, it was on by default.
- </para>
-
- <para>
- The use of OIDs in user tables is considered deprecated, so
- most installations should leave this variable disabled.
- Applications that require OIDs for a particular table should
- specify <literal>WITH OIDS</literal> when creating the
- table. This variable can be enabled for compatibility with old
- applications that do not follow this behavior.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-escape-string-warning" xreflabel="escape_string_warning">
- <term><varname>escape_string_warning</varname> (<type>boolean</type>)</term>
- <indexterm><primary>strings</><secondary>escape</></>
- <indexterm>
- <primary><varname>escape_string_warning</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When on, a warning is issued if a backslash (<literal>\</>)
- appears in an ordinary string literal (<literal>'...'</>
- syntax). The default is <literal>off</>.
- </para>
- <para>
- Escape string syntax (<literal>E'...'</>) should be used for
- escapes, because in future versions of
- <productname>PostgreSQL</productname> ordinary strings will have
- the standard-conforming behavior of treating backslashes
- literally.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect3>
- <sect3 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>)</term>
- <indexterm><primary>IS NULL</></>
- <indexterm>
- <primary><varname>transform_null_equals</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- When on, expressions of the form <literal><replaceable>expr</> =
- NULL</literal> (or <literal>NULL =
- <replaceable>expr</></literal>) are treated as
- <literal><replaceable>expr</> IS NULL</literal>, that is, they
- return true if <replaceable>expr</> evaluates to the null value,
- and false otherwise. The correct SQL-spec-compliant behavior of
- <literal><replaceable>expr</> = NULL</literal> is to always
- return null (unknown). Therefore this option defaults to
- <literal>off</>.
- </para>
-
- <para>
- However, filtered forms in <productname>Microsoft
- Access</productname> generate queries that appear to use
- <literal><replaceable>expr</> = 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</> = NULL</literal> always
- return the null value (using the correct 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 not on by default.
- </para>
-
- <para>
- Note that this option only affects the exact form <literal>= NULL</>,
- 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>
- </sect3>
- </sect2>
-
- <sect2 id="runtime-config-preset">
- <title>Preset Options</title>
-
- <para>
- The following <quote>parameters</> are read-only, and are determined
- when <productname>PostgreSQL</productname> is compiled or when it is
- installed. As such, they have been excluded from the sample
- <filename>postgresql.conf</> file. These options report
- various aspects of <productname>PostgreSQL</productname> behavior
- that may be of interest to certain applications, particularly
- administrative front-ends.
- </para>
-
- <variablelist>
-
- <varlistentry id="guc-block-size" xreflabel="block_size">
- <term><varname>block_size</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>block_size</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Reports the size of a disk block. It is determined by the value
- of <literal>BLCKSZ</> 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-integer-datetimes" xreflabel="integer_datetimes">
- <term><varname>integer_datetimes</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>integer_datetimes</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Reports whether <productname>PostgreSQL</productname> was built
- with support for 64-bit-integer dates and times. It is set by
- configuring with <literal>--enable-integer-datetimes</literal>
- when building <productname>PostgreSQL</productname>. The
- default value is <literal>off</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-lc-collate" xreflabel="lc_collate">
- <term><varname>lc_collate</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>lc_collate</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Reports the locale in which sorting of textual data is done.
- See <xref linkend="locale"> for more information.
- The value is determined when the database cluster is initialized.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-lc-ctype" xreflabel="lc_ctype">
- <term><varname>lc_ctype</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>lc_ctype</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Reports the locale that determines character classifications.
- See <xref linkend="locale"> for more information.
- The value is determined when the database cluster is initialized.
- 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>)</term>
- <indexterm>
- <primary><varname>max_function_args</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Reports the maximum number of function arguments. It is determined by
- the value of <literal>FUNC_MAX_ARGS</> when building the server. The
- default value is 100.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-max-identifier-length" xreflabel="max_identifier_length">
- <term><varname>max_identifier_length</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>max_identifier_length</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Reports the maximum identifier length. It is determined as one
- less than the value of <literal>NAMEDATALEN</> when building
- the server. The default value of <literal>NAMEDATALEN</> is
- 64; therefore the default
- <varname>max_identifier_length</varname> is 63.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-max-index-keys" xreflabel="max_index_keys">
- <term><varname>max_index_keys</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>max_index_keys</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Reports the maximum number of index keys. It is determined by
- the value of <literal>INDEX_MAX_KEYS</> when building the server. The
- default value is 32.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-server-encoding" xreflabel="server_encoding">
- <term><varname>server_encoding</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>server_encoding</> configuration parameter</primary>
- </indexterm>
- <indexterm><primary>character set</></>
- <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>)</term>
- <indexterm>
- <primary><varname>server_version</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Reports the version number of the server. It is determined by the
- value of <literal>PG_VERSION</> when building the server.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-standard-conforming-strings" xreflabel="standard_conforming_strings">
- <term><varname>standard_conforming_strings</varname> (<type>boolean</type>)</term>
- <indexterm><primary>strings</><secondary>escape</></>
- <indexterm>
- <primary><varname>standard_conforming_strings</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Reports whether ordinary string literals
- (<literal>'...'</>) treat backslashes literally, as specified in
- the SQL standard. The value is currently always <literal>off</>,
- indicating that backslashes are treated as escapes. It is planned
- that this will change to <literal>on</> in a future
- <productname>PostgreSQL</productname> release when string literal
- syntax changes to meet the standard. Applications may 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'...'</>) is supported.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect2>
-
- <sect2 id="runtime-config-custom">
- <title>Customized Options</title>
-
- <para>
- This feature was designed to allow options not normally known to
- <productname>PostgreSQL</productname> to be added by add-on modules
- (such as procedural languages). This allows add-on modules to be
- configured in the standard ways.
- </para>
-
- <variablelist>
-
- <varlistentry id="guc-custom-variable-classes" xreflabel="custom_variable_classes">
- <term><varname>custom_variable_classes</varname> (<type>string</type>)</term>
- <indexterm>
- <primary><varname>custom_variable_classes</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- This variable specifies one or several class names to be used for
- custom variables, in the form of a comma-separated list. A custom
- variable is a variable not normally known
- to <productname>PostgreSQL</productname> proper but used by some
- add-on module. Such variables must have names consisting of a class
- name, a dot, and a variable name. <varname>custom_variable_classes</>
- specifies all the class names in use in a particular installation.
- This option can only be set at server start or in the
- <filename>postgresql.conf</filename> configuration file.
- </para>
-
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- The difficulty with setting custom variables in
- <filename>postgresql.conf</> is that the file must be read before add-on
- modules have been loaded, and so custom variables would ordinarily be
- rejected as unknown. When <varname>custom_variable_classes</> is set,
- the server will accept definitions of arbitrary variables within each
- specified class. These variables will be treated as placeholders and
- will have no function until the module that defines them is loaded. When a
- module for a specific class is loaded, it will add the proper variable
- definitions for its class name, convert any placeholder
- values according to those definitions, and issue warnings for any
- placeholders of its class that remain (which presumably would be
- misspelled configuration variables).
- </para>
-
- <para>
- Here is an example of what <filename>postgresql.conf</> might contain
- when using custom variables:
-
-<programlisting>
-custom_variable_classes = 'plr,plperl'
-plr.path = '/usr/lib/R'
-plperl.use_strict = true
-plruby.use_strict = true # generates error: unknown class name
-</programlisting>
- </para>
- </sect2>
-
- <sect2 id="runtime-config-developer">
- <title>Developer Options</title>
-
- <para>
- The following options are intended for work on the
- <productname>PostgreSQL</productname> source, and in some cases
- to assist with recovery of severely damaged databases. There
- should be no reason to use them in a production database setup.
- As such, they have been excluded from the sample
- <filename>postgresql.conf</> file. Note that many of these
- options require special source compilation flags to work at all.
- </para>
-
- <variablelist>
- <varlistentry id="guc-debug-assertions" xreflabel="debug_assertions">
- <term><varname>debug_assertions</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>debug_assertions</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Turns on various assertion checks. This is a debugging aid. If
- you are experiencing strange problems or crashes you might want
- to turn this on, as it might expose programming mistakes. To use
- this option, the macro <symbol>USE_ASSERT_CHECKING</symbol>
- must be defined when <productname>PostgreSQL</productname> is
- built (accomplished by the <command>configure</command> option
- <option>--enable-cassert</option>). Note that
- <varname>debug_assertions</varname> defaults to <literal>on</>
- if <productname>PostgreSQL</productname> has been built with
- assertions enabled.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-pre-auth-delay" xreflabel="pre_auth_delay">
- <term><varname>pre_auth_delay</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>pre_auth_delay</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- If nonzero, a delay of this many seconds occurs just after a new
- server process is forked, before it conducts the authentication
- process. This is intended to give an opportunity to attach to the
- server process with a debugger to trace down misbehavior in
- authentication.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-trace-notify" xreflabel="trace_notify">
- <term><varname>trace_notify</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>trace_notify</> configuration parameter</primary>
- </indexterm>
- <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 log, respectively.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>trace_locks</varname> (<type>boolean</type>)</term>
- <term><varname>trace_lwlocks</varname> (<type>boolean</type>)</term>
- <term><varname>trace_userlocks</varname> (<type>boolean</type>)</term>
- <term><varname>trace_lock_oidmin</varname> (<type>boolean</type>)</term>
- <term><varname>trace_lock_table</varname> (<type>boolean</type>)</term>
- <term><varname>debug_deadlocks</varname> (<type>boolean</type>)</term>
- <term><varname>log_btree_build_stats</varname> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Various other code tracing and debugging options.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-wal-debug" xreflabel="wal_debug">
- <term><varname>wal_debug</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>wal_debug</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- If on, emit WAL-related debugging output. This option is
- only available if the <symbol>WAL_DEBUG</symbol> macro was
- defined when <productname>PostgreSQL</productname> was
- compiled.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-zero-damaged-pages" xreflabel="zero_damaged_pages">
- <term><varname>zero_damaged_pages</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>zero_damaged_pages</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Detection of a damaged page header normally causes
- <productname>PostgreSQL</> to report an error, aborting the current
- command. Setting <varname>zero_damaged_pages</> to on causes
- the system to instead report a warning, zero out the damaged page,
- and continue processing. This behavior <emphasis>will destroy data</>,
- namely all the rows on the damaged page. But it allows you to get
- past the error and retrieve rows from any undamaged pages that may
- be present in the table. So it is useful for recovering data if
- corruption has occurred due to hardware or software error. You should
- generally not set this on until you have given up hope of recovering
- data from the damaged page(s) of a table. The
- default setting is <literal>off</>, and it can only be changed
- by a superuser.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- <sect2 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">.
- </para>
-
- <table id="runtime-config-short-table">
- <title>Short option key</title>
- <tgroup cols="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></></entry>
- </row>
- <row>
- <entry><option>-d <replaceable>x</replaceable></option></entry>
- <entry><literal>log_min_messages = DEBUG<replaceable>x</replaceable></></entry>
- </row>
- <row>
- <entry><option>-F</option></entry>
- <entry><literal>fsync = off</></entry>
- </row>
- <row>
- <entry><option>-h <replaceable>x</replaceable></option></entry>
- <entry><literal>listen_addresses = <replaceable>x</replaceable></></entry>
- </row>
- <row>
- <entry><option>-i</option></entry>
- <entry><literal>listen_addresses = '*'</></entry>
- </row>
- <row>
- <entry><option>-k <replaceable>x</replaceable></option></entry>
- <entry><literal>unix_socket_directory = <replaceable>x</replaceable></></entry>
- </row>
- <row>
- <entry><option>-l</option></entry>
- <entry><literal>ssl = on</></entry>
- </row>
- <row>
- <entry><option>-N <replaceable>x</replaceable></option></entry>
- <entry><literal>max_connections = <replaceable>x</replaceable></></entry>
- </row>
- <row>
- <entry><option>-p <replaceable>x</replaceable></option></entry>
- <entry><literal>port = <replaceable>x</replaceable></></entry>
- </row>
-
- <row>
- <entry>
- <option>-fb</option>, <option>-fh</option>, <option>-fi</option>,
- <option>-fm</option>, <option>-fn</option>,
- <option>-fs</option>, <option>-ft</option><footnote
- id="fn.runtime-config-short">
- <para>
- For historical reasons, these options must be passed to
- the individual server process via the <option>-o</option>
- <command>postmaster</command> option, for example,
-<screen>
-$ <userinput>postmaster -o '-S 1024 -s'</userinput>
-</screen>
- or via <envar>PGOPTIONS</envar> from the client side, as
- explained above.
- </para>
- </footnote>
- </entry>
- <entry>
- <literal>enable_bitmapscan = off</>,
- <literal>enable_hashjoin = off</>,
- <literal>enable_indexscan = off</>,
- <literal>enable_mergejoin = off</>,
- <literal>enable_nestloop = off</>,
- <literal>enable_seqscan = off</>,
- <literal>enable_tidscan = off</>
- </entry>
- </row>
-
- <row>
- <entry><option>-s</option><footnoteref linkend="fn.runtime-config-short"></entry>
- <entry><literal>log_statement_stats = on</></entry>
- </row>
-
- <row>
- <entry><option>-S <replaceable>x</replaceable></option><footnoteref linkend="fn.runtime-config-short">
- </entry>
- <entry><literal>work_mem = <replaceable>x</replaceable></></entry>
- </row>
-
- <row>
- <entry><option>-tpa</option>, <option>-tpl</option>, <option>-te</option><footnoteref linkend="fn.runtime-config-short"></entry>
- <entry><literal>log_parser_stats = on</>,
- <literal>log_planner_stats = on</>,
- <literal>log_executor_stats = on</></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </sect2>
- </sect1>
-
-
<sect1 id="kernel-resources">
<title>Managing Kernel Resources</title>
--
GitLab