From f0488bd57c3745b5dbed80e884ee5452e77314c9 Mon Sep 17 00:00:00 2001 From: Tom Lane <tgl@sss.pgh.pa.us> Date: Thu, 29 Apr 2010 21:36:19 +0000 Subject: [PATCH] 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. --- doc/src/sgml/config.sgml | 55 ++++++++------- doc/src/sgml/high-availability.sgml | 69 ++++++++++--------- src/backend/access/transam/xlog.c | 51 ++++++++------ src/backend/storage/ipc/procarray.c | 12 ++-- src/backend/utils/misc/guc.c | 12 ++-- src/backend/utils/misc/postgresql.conf.sample | 8 +-- src/include/access/xlog.h | 9 +-- 7 files changed, 116 insertions(+), 100 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 93c9ff183c2..c84529f267f 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -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> diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index da0d4d5de5f..b2f1a583fc3 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -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> diff --git a/src/backend/access/transam/xlog.c b/src/backend/access/transam/xlog.c index 2d3dab39fe5..95c3c3a7d0a 100644 --- a/src/backend/access/transam/xlog.c +++ b/src/backend/access/transam/xlog.c @@ -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 diff --git a/src/backend/storage/ipc/procarray.c b/src/backend/storage/ipc/procarray.c index 3564cd5ab36..4fc1fc430be 100644 --- a/src/backend/storage/ipc/procarray.c +++ b/src/backend/storage/ipc/procarray.c @@ -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", diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c index 2404da84419..d913137b49d 100644 --- a/src/backend/utils/misc/guc.c +++ b/src/backend/utils/misc/guc.c @@ -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 }, { diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample index 57497115689..2ed84127f78 100644 --- a/src/backend/utils/misc/postgresql.conf.sample +++ b/src/backend/utils/misc/postgresql.conf.sample @@ -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 - diff --git a/src/include/access/xlog.h b/src/include/access/xlog.h index 6936a2a5791..7dfe03b4be7 100644 --- a/src/include/access/xlog.h +++ b/src/include/access/xlog.h @@ -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 { -- GitLab