Rename the parameter recovery_connections to hot_standby, to reduce possible

confusion with streaming-replication settings.  Also, change its default
value to "off", because of concern about executing new and poorly-tested
code during ordinary non-replicating operation.  Per discussion.

In passing do some minor editing of related documentation.
This commit is contained in:
Tom Lane 2010-04-29 21:36:19 +00:00
parent 72e316e4c8
commit f0488bd57c
7 changed files with 116 additions and 100 deletions

View File

@ -1,4 +1,4 @@
<!-- $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>
@ -1352,7 +1352,7 @@ SET ENABLE_SEQSCAN TO OFF;
<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>
@ -1362,7 +1362,7 @@ SET ENABLE_SEQSCAN TO OFF;
<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.
@ -1385,8 +1385,8 @@ SET ENABLE_SEQSCAN TO OFF;
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>
@ -1836,7 +1836,7 @@ SET ENABLE_SEQSCAN TO OFF;
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
@ -1860,8 +1860,7 @@ SET ENABLE_SEQSCAN TO OFF;
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>
@ -1873,7 +1872,7 @@ SET ENABLE_SEQSCAN TO OFF;
<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</>).
@ -1893,14 +1892,17 @@ SET ENABLE_SEQSCAN TO OFF;
</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</>
@ -1920,43 +1922,44 @@ SET ENABLE_SEQSCAN TO OFF;
<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>
@ -1966,7 +1969,7 @@ SET ENABLE_SEQSCAN TO OFF;
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>

View File

@ -1,4 +1,4 @@
<!-- $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>
@ -1127,7 +1127,8 @@ if (!triggered)
<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
@ -1137,7 +1138,7 @@ if (!triggered)
<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>
@ -1573,14 +1574,15 @@ if (!triggered)
<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>
@ -1592,12 +1594,11 @@ LOG: consistent recovery state reached
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>
@ -1622,10 +1623,9 @@ LOG: database system is ready to accept read only connections
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>
@ -1648,7 +1648,8 @@ LOG: database system is ready to accept read only connections
<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
@ -1657,7 +1658,7 @@ LOG: database system is ready to accept read only connections
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>
@ -1668,10 +1669,8 @@ LOG: database system is ready to accept read only connections
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>
@ -1837,20 +1836,22 @@ LOG: database system is ready to accept read only connections
<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>
@ -1880,7 +1881,7 @@ LOG: database system is ready to accept read only connections
</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
@ -1901,7 +1902,7 @@ LOG: database system is ready to accept read only connections
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>

View File

@ -7,7 +7,7 @@
* 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 $
*
*-------------------------------------------------------------------------
*/
@ -71,7 +71,7 @@ int XLOGbuffers = 8;
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;
@ -5571,15 +5571,16 @@ GetLatestXLogTime(void)
* 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
@ -5595,27 +5596,31 @@ CheckRequiredParameterValues(void)
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);
}
}
@ -5953,18 +5958,18 @@ StartupXLOG(void)
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();
@ -9055,13 +9060,17 @@ StartupProcessMain(void)
#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

View File

@ -37,7 +37,7 @@
*
*
* 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 $
*
*-------------------------------------------------------------------------
*/
@ -179,18 +179,22 @@ ProcArrayShmemSize(void)
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),
@ -234,7 +238,7 @@ CreateSharedProcArray(void)
}
/* Create or attach to the KnownAssignedXids arrays too, if needed */
if (XLogRequestRecoveryConnections)
if (EnableHotStandby)
{
KnownAssignedXids = (TransactionId *)
ShmemInitStruct("KnownAssignedXids",

View File

@ -10,7 +10,7 @@
* 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 $
*
*--------------------------------------------------------------------
*/
@ -1222,14 +1222,12 @@ static struct config_bool ConfigureNamesBool[] =
},
{
{"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
},
{

View File

@ -185,10 +185,10 @@
# - 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 -

View File

@ -6,7 +6,7 @@
* 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
@ -189,12 +189,13 @@ extern XLogRecPtr XactLastRecEnd;
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
{