-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.271 2010/04/28 16:10:39 heikki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.272 2010/04/29 21:36:18 tgl Exp $ -->
<chapter Id="runtime-config">
<title>Server Configuration</title>
<sect2 id="runtime-config-wal-settings">
<title>Settings</title>
<variablelist>
-
+
<varlistentry id="guc-wal-level" xreflabel="wal_level">
<term><varname>wal_level</varname> (<type>enum</type>)</term>
<indexterm>
<para>
<varname>wal_level</> determines how much information is written
to the WAL. The default value is <literal>minimal</>, which writes
- only minimal information needed to recover from a crash or immediate
+ only the information needed to recover from a crash or immediate
shutdown. <literal>archive</> adds logging required for WAL archiving,
and <literal>hot_standby</> further adds information required to run
read-only queries on a standby server.
the status of running transactions from the WAL. To enable read-only
queries on a standby server, <varname>wal_level</> must be set to
<literal>hot_standby</> on the primary. It is thought that there is
- little measurable difference in performance from using
- <literal>hot_standby</> level over <literal>archive</>, so feedback
+ little measurable difference in performance between using
+ <literal>hot_standby</> and <literal>archive</> levels, so feedback
is welcome if any production impacts are noticeable.
</para>
</listitem>
</para>
</listitem>
</varlistentry>
-
+
</variablelist>
</sect2>
servers (i.e., the maximum number of simultaneously running WAL sender
processes). The default is zero. This parameter can only be set at
server start. <varname>wal_level</> must be set to <literal>archive</>
- or <literal>hot_standby</> to allow connections from standby
- connections.
+ or <literal>hot_standby</> to allow connections from standby servers.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies the delay between activity rounds for the WAL sender.
- In each round the WAL sender sends any WAL accumulated since last
+ In each round the WAL sender sends any WAL accumulated since the last
round to the standby server. It then sleeps for
<varname>wal_sender_delay</> milliseconds, and repeats. The default
value is 200 milliseconds (<literal>200ms</>).
</indexterm>
<listitem>
<para>
- Specifies the number of log file segments kept in <filename>pg_xlog</>
- directory, in case a standby server needs to fetch them via streaming
+ Specifies the number of past log file segments kept in the
+ <filename>pg_xlog</>
+ directory, in case a standby server needs to fetch them for streaming
replication. Each segment is normally 16 megabytes. If a standby
- server connected to the primary falls behind more than
+ server connected to the primary falls behind by more than
<varname>wal_keep_segments</> segments, the primary might remove
- a WAL segment still needed by the standby and the replication
- connection will be terminated.
+ a WAL segment still needed by the standby, in which case the
+ replication connection will be terminated.
+ </para>
+ <para>
This sets only the minimum number of segments retained for standby
purposes; the system might need to retain more segments for WAL
archival or to recover from a checkpoint. If <varname>wal_keep_segments</>
<variablelist>
- <varlistentry id="recovery-connections" xreflabel="recovery_connections">
- <term><varname>recovery_connections</varname> (<type>boolean</type>)</term>
+ <varlistentry id="guc-hot-standby" xreflabel="hot_standby">
+ <term><varname>hot_standby</varname> (<type>boolean</type>)</term>
<indexterm>
- <primary><varname>recovery_connections</> configuration parameter</primary>
+ <primary><varname>hot_standby</> configuration parameter</primary>
</indexterm>
<listitem>
<para>
Specifies whether or not you can connect and run queries during
- recovery, for <xref linkend="hot-standby">. The default value is
- <literal>on</literal>.
+ recovery, as described in <xref linkend="hot-standby">.
+ The default value is <literal>off</literal>.
This parameter can only be set at server start. It only has effect
during archive recovery or in standby mode.
</para>
</listitem>
</varlistentry>
- <varlistentry id="max-standby-delay" xreflabel="max_standby_delay">
- <term><varname>max_standby_delay</varname> (<type>string</type>)</term>
+ <varlistentry id="guc-max-standby-delay" xreflabel="max_standby_delay">
+ <term><varname>max_standby_delay</varname> (<type>integer</type>)</term>
<indexterm>
<primary><varname>max_standby_delay</> configuration parameter</primary>
</indexterm>
<listitem>
<para>
- When server acts as a standby, this parameter specifies a wait policy
+ When Hot Standby is active, this parameter specifies a wait policy
for applying WAL entries that conflict with active queries.
If a conflict should occur the server will delay up to this number
of seconds before it cancels conflicting queries, as
described in <xref linkend="hot-standby-conflict">.
Typically, this parameter is used only during replication.
+ The value is specified in seconds, and -1 causes the standby to wait
+ forever for a conflicting query to complete.
The default is 30 seconds.
This parameter can only be set in the <filename>postgresql.conf</>
file or on the server command line.
</para>
<para>
- A high value makes query cancel less likely, and -1
- causes the standby to wait forever for a conflicting query to
- complete. Increasing this parameter might delay master server
+ A high value makes query cancel less likely.
+ Increasing this parameter or setting it to -1 might delay master server
changes from appearing on the standby.
</para>
<para>
query ends, there is a finite time required to apply backlogged
WAL logs. If a second long-running query appears before the
WAL has caught up, the snapshot taken by the second query will
- allow significantly less than <varname>max_standby_delay</>
+ allow significantly less than <varname>max_standby_delay</> seconds
before query cancellation is possible.
</para>
</listitem>
-<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.64 2010/04/28 16:10:40 heikki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.65 2010/04/29 21:36:18 tgl Exp $ -->
<chapter id="high-availability">
<title>High Availability, Load Balancing, and Replication</title>
<para>
Hot Standby is the term used to describe the ability to connect to
- the server and run queries while the server is in archive recovery. This
+ the server and run read-only queries while the server is in archive
+ recovery. This
is useful for both log shipping replication and for restoring a backup
to an exact state with great precision.
The term Hot Standby also refers to the ability of the server to move
<para>
Running queries in recovery mode is similar to normal query operation,
- though there are a several usage and administrative differences
+ though there are several usage and administrative differences
noted below.
</para>
<title>Administrator's Overview</title>
<para>
- If there is a <filename>recovery.conf</> file present, the server will start
- in Hot Standby mode by default, though <varname>recovery_connections</> can
- be disabled via <filename>postgresql.conf</>. The server might take
- some time to enable recovery connections since the server must first complete
+ If <varname>hot_standby</> is turned <literal>on</> in
+ <filename>postgresql.conf</> and there is a <filename>recovery.conf</>
+ file present, the server will run in Hot Standby mode.
+ However, it may take some time for Hot Standby connections to be allowed,
+ because the server will not accept connections until it has completed
sufficient recovery to provide a consistent state against which queries
- can run before enabling read only connections. During this period,
+ can run. During this period,
clients that attempt to connect will be refused with an error message.
- To confirm the server has come up, either loop retrying to connect from
+ To confirm the server has come up, either loop trying to connect from
the application, or look for these messages in the server logs:
<programlisting>
LOG: database system is ready to accept read only connections
</programlisting>
- Consistency information is recorded once per checkpoint on the primary, as long
- as <varname>wal_level</> is set to <literal>hot_standby</> on the primary. It is not possible
- to enable recovery connections on the standby when reading WAL written during the
- period that <varname>wal_level</> was not set to <literal>hot_standby</> on the primary.
- Reaching a consistent state can also be delayed in the presence
- of both of these conditions:
+ Consistency information is recorded once per checkpoint on the primary.
+ It is not possible to enable hot standby when reading WAL
+ written during a period when <varname>wal_level</> was not set to
+ <literal>hot_standby</> on the primary. Reaching a consistent state can
+ also be delayed in the presence of both of these conditions:
<itemizedlist>
<listitem>
if they have been changed on the primary. For these parameters,
the value on the standby must
be equal to or greater than the value on the primary. If these parameters
- are not set high enough then the standby will not be able to process
- recovering transactions properly. If these values are set too low
- the server will halt. Higher values can then be supplied and the server
- restarted to begin recovery again. The parameters are:
+ are not set high enough then the standby will refuse to start.
+ Higher values can then be supplied and the server
+ restarted to begin recovery again. These parameters are:
<itemizedlist>
<listitem>
<para>
It is important that the administrator consider the appropriate setting
- of <varname>max_standby_delay</>, set in <filename>postgresql.conf</>.
+ of <varname>max_standby_delay</>,
+ which can be set in <filename>postgresql.conf</>.
There is no optimal setting, so it should be set according to business
priorities. For example if the server is primarily tasked as a High
Availability server, then you may wish to lower
server for decision support queries then it might be acceptable to set this
to a value of many hours (in seconds). It is also possible to set
<varname>max_standby_delay</> to -1 which means wait forever for queries
- to complete, if there are conflicts; this will be useful when performing
+ to complete; this will be useful when performing
an archive recovery from a backup.
</para>
all users are read-only; no changes occur to the data values
themselves. Users will still write large sort temporary files and
re-generate relcache info files, so no part of the database
- is truly read-only during hot standby mode. There is no restriction
- on the use of set returning functions, or other users of
- <function>tuplestore</>/<function>tuplesort</>
- code. Note also that writes to remote databases will still be possible,
+ is truly read-only during hot standby mode.
+ Note also that writes to remote databases will still be possible,
even though the transaction is read-only locally.
</para>
<title>Hot Standby Parameter Reference</title>
<para>
- Various parameters have been mentioned above in <xref linkend="hot-standby-admin">
+ Various parameters have been mentioned above in
+ <xref linkend="hot-standby-admin">
and <xref linkend="hot-standby-conflict">.
</para>
<para>
- On the primary, parameters <varname>wal_level</> and
- <varname>vacuum_defer_cleanup_age</> can be used.
- <varname>max_standby_delay</> has no effect if set on the primary.
+ On the primary, parameters <xref linkend="guc-wal-level"> and
+ <xref linkend="guc-vacuum-defer-cleanup-age"> can be used.
+ <xref linkend="guc-max-standby-delay"> has no effect if set on the primary.
</para>
<para>
- On the standby, parameters <varname>recovery_connections</> and
- <varname>max_standby_delay</> can be used.
- <varname>vacuum_defer_cleanup_age</> has no effect during recovery.
+ On the standby, parameters <xref linkend="guc-hot-standby"> and
+ <xref linkend="guc-max-standby-delay"> can be used.
+ <xref linkend="guc-vacuum-defer-cleanup-age"> has no effect during
+ recovery.
</para>
</sect2>
</listitem>
<listitem>
<para>
- Valid starting points for recovery connections are generated at each
+ Valid starting points for standby queries are generated at each
checkpoint on the master. If the standby is shut down while the master
is in a shutdown state, it might not be possible to re-enter Hot Standby
until the primary is started up, so that it generates further starting
that normally take <literal>AccessExclusiveLocks</>, or you plan on having one
large transaction that takes many <literal>AccessExclusiveLocks</>, you are
advised to select a larger value of <varname>max_locks_per_transaction</>,
- up to, but never more than twice the value of the parameter setting on
+ perhaps as much as twice the value of the parameter on
the primary server. You need not consider this at all if
your setting of <varname>max_prepared_transactions</> is <literal>0</>.
</para>
* Portions Copyright (c) 1996-2010, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
- * $PostgreSQL: pgsql/src/backend/access/transam/xlog.c,v 1.405 2010/04/28 16:10:40 heikki Exp $
+ * $PostgreSQL: pgsql/src/backend/access/transam/xlog.c,v 1.406 2010/04/29 21:36:19 tgl Exp $
*
*-------------------------------------------------------------------------
*/
int XLogArchiveTimeout = 0;
bool XLogArchiveMode = false;
char *XLogArchiveCommand = NULL;
-bool XLogRequestRecoveryConnections = true;
+bool EnableHotStandby = false;
int MaxStandbyDelay = 30;
bool fullPageWrites = true;
bool log_checkpoints = false;
* translation
*/
#define RecoveryRequiresIntParameter(param_name, currValue, minValue) \
-{ \
+do { \
if (currValue < minValue) \
ereport(ERROR, \
- (errmsg("recovery connections cannot continue because " \
- "%s = %u is a lower setting than on WAL source server (value was %u)", \
- param_name, \
- currValue, \
- minValue))); \
-}
+ (errmsg("hot standby is not possible because " \
+ "%s = %d is a lower setting than on the master server " \
+ "(its value was %d)", \
+ param_name, \
+ currValue, \
+ minValue))); \
+} while(0)
/*
* Check to see if required parameters are set high enough on this server
if (InArchiveRecovery && ControlFile->wal_level == WAL_LEVEL_MINIMAL)
{
ereport(WARNING,
- (errmsg("WAL was generated with wal_level='minimal', data may be missing"),
- errhint("This happens if you temporarily set wal_level='minimal' without taking a new base backup.")));
+ (errmsg("WAL was generated with wal_level=\"minimal\", data may be missing"),
+ errhint("This happens if you temporarily set wal_level=\"minimal\" without taking a new base backup.")));
}
/*
* For Hot Standby, the WAL must be generated with 'hot_standby' mode,
* and we must have at least as many backend slots as the primary.
*/
- if (InArchiveRecovery && XLogRequestRecoveryConnections)
+ if (InArchiveRecovery && EnableHotStandby)
{
if (ControlFile->wal_level < WAL_LEVEL_HOT_STANDBY)
ereport(ERROR,
- (errmsg("recovery connections cannot start because wal_level was not set to 'hot_standby' on the WAL source server")));
+ (errmsg("hot standby is not possible because wal_level was not set to \"hot_standby\" on the master server"),
+ errhint("Either set wal_level to \"hot_standby\" on the master, or turn off hot_standby here.")));
/* We ignore autovacuum_max_workers when we make this test. */
RecoveryRequiresIntParameter("max_connections",
- MaxConnections, ControlFile->MaxConnections);
+ MaxConnections,
+ ControlFile->MaxConnections);
RecoveryRequiresIntParameter("max_prepared_xacts",
- max_prepared_xacts, ControlFile->max_prepared_xacts);
+ max_prepared_xacts,
+ ControlFile->max_prepared_xacts);
RecoveryRequiresIntParameter("max_locks_per_xact",
- max_locks_per_xact, ControlFile->max_locks_per_xact);
+ max_locks_per_xact,
+ ControlFile->max_locks_per_xact);
}
}
CheckRequiredParameterValues();
/*
- * Initialize recovery connections, if enabled. We won't let backends
+ * Initialize for Hot Standby, if enabled. We won't let backends
* in yet, not until we've reached the min recovery point specified in
* control file and we've established a recovery snapshot from a
* running-xacts WAL record.
*/
- if (InArchiveRecovery && XLogRequestRecoveryConnections)
+ if (InArchiveRecovery && EnableHotStandby)
{
TransactionId *xids;
int nxids;
ereport(DEBUG1,
- (errmsg("initializing recovery connections")));
+ (errmsg("initializing for hot standby")));
InitRecoveryTransactionEnvironment();
#endif
/*
- * Properly accept or ignore signals the postmaster might send us
+ * Properly accept or ignore signals the postmaster might send us.
+ *
+ * Note: ideally we'd not enable handle_standby_sig_alarm unless actually
+ * doing hot standby, but we don't know that yet. Rely on it to not do
+ * anything if it shouldn't.
*/
pqsignal(SIGHUP, StartupProcSigHupHandler); /* reload config file */
pqsignal(SIGINT, SIG_IGN); /* ignore query cancel */
pqsignal(SIGTERM, StartupProcShutdownHandler); /* request shutdown */
pqsignal(SIGQUIT, startupproc_quickdie); /* hard crash time */
- if (XLogRequestRecoveryConnections)
+ if (EnableHotStandby)
pqsignal(SIGALRM, handle_standby_sig_alarm); /* ignored unless
* InHotStandby */
else
*
*
* IDENTIFICATION
- * $PostgreSQL: pgsql/src/backend/storage/ipc/procarray.c,v 1.67 2010/04/28 00:09:05 tgl Exp $
+ * $PostgreSQL: pgsql/src/backend/storage/ipc/procarray.c,v 1.68 2010/04/29 21:36:19 tgl Exp $
*
*-------------------------------------------------------------------------
*/
size = add_size(size, mul_size(sizeof(PGPROC *), PROCARRAY_MAXPROCS));
/*
- * During recovery processing we have a data structure called
+ * During Hot Standby processing we have a data structure called
* KnownAssignedXids, created in shared memory. Local data structures are
* also created in various backends during GetSnapshotData(),
* TransactionIdIsInProgress() and GetRunningTransactionData(). All of the
* main structures created in those functions must be identically sized,
* since we may at times copy the whole of the data structures around. We
* refer to this size as TOTAL_MAX_CACHED_SUBXIDS.
+ *
+ * Ideally we'd only create this structure if we were actually doing
+ * hot standby in the current run, but we don't know that yet at the
+ * time shared memory is being set up.
*/
#define TOTAL_MAX_CACHED_SUBXIDS \
((PGPROC_MAX_CACHED_SUBXIDS + 1) * PROCARRAY_MAXPROCS)
- if (XLogRequestRecoveryConnections)
+ if (EnableHotStandby)
{
size = add_size(size,
mul_size(sizeof(TransactionId),
}
/* Create or attach to the KnownAssignedXids arrays too, if needed */
- if (XLogRequestRecoveryConnections)
+ if (EnableHotStandby)
{
KnownAssignedXids = (TransactionId *)
ShmemInitStruct("KnownAssignedXids",
* Written by Peter Eisentraut <peter_e@gmx.net>.
*
* IDENTIFICATION
- * $PostgreSQL: pgsql/src/backend/utils/misc/guc.c,v 1.552 2010/04/28 16:10:42 heikki Exp $
+ * $PostgreSQL: pgsql/src/backend/utils/misc/guc.c,v 1.553 2010/04/29 21:36:19 tgl Exp $
*
*--------------------------------------------------------------------
*/
},
{
- {"recovery_connections", PGC_POSTMASTER, WAL_SETTINGS,
- gettext_noop("During recovery, allows connections and queries. "
- " During normal running, causes additional info to be written"
- " to WAL to enable hot standby mode on WAL standby nodes."),
+ {"hot_standby", PGC_POSTMASTER, WAL_SETTINGS,
+ gettext_noop("Allows connections and queries during recovery."),
NULL
},
- &XLogRequestRecoveryConnections,
- true, NULL, NULL
+ &EnableHotStandby,
+ false, NULL, NULL
},
{
# - Hot Standby -
-#recovery_connections = on # allows connections during recovery
-#max_standby_delay = 30s # max acceptable standby lag (s) to allow queries
- # to complete without conflict; -1 disables
-#vacuum_defer_cleanup_age = 0 # num transactions by which cleanup is deferred
+#hot_standby = off # allows queries during recovery
+#max_standby_delay = 30s # max acceptable lag (s) to allow queries to
+ # complete without conflict; -1 means forever
+#vacuum_defer_cleanup_age = 0 # num transactions by which cleanup is deferred
# - Replication -
* Portions Copyright (c) 1996-2010, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
- * $PostgreSQL: pgsql/src/include/access/xlog.h,v 1.110 2010/04/28 16:10:43 heikki Exp $
+ * $PostgreSQL: pgsql/src/include/access/xlog.h,v 1.111 2010/04/29 21:36:19 tgl Exp $
*/
#ifndef XLOG_H
#define XLOG_H
extern int CheckPointSegments;
extern int wal_keep_segments;
extern int XLOGbuffers;
+extern int XLogArchiveTimeout;
extern bool XLogArchiveMode;
extern char *XLogArchiveCommand;
-extern int XLogArchiveTimeout;
-extern bool log_checkpoints;
-extern bool XLogRequestRecoveryConnections;
+extern bool EnableHotStandby;
extern int MaxStandbyDelay;
+extern bool log_checkpoints;
+
/* WAL levels */
typedef enum WalLevel
{
projects / postgresql / commitdiff