Thread: Further Hot Standby documentation required
Recent changes to parameters aren't yet sufficiently well documented and I'd like to see this improved by the authors of those patches. I accept the behaviour changes, but we need full docs to explain them. * hot_standby doesn't mention that wal_level = hot_standby is also required, nor is there a xref. * wal_level = 'hot_standby' doesn't mention that the second parameter also needs to be set, nor is there a xref. * wal_level doesn't describe what the impacts are on a standby if the level is changed on the primary, nor is there a caution or a warning of any kind. For example, if a standby is setup with hot_standby = on and the primary is set wal_level = archive, does the standby start working if the primary changes wal_level = hot_standby? What happens if the primary is set wal_level = hot_standby and is then changed to archive? * wal_level doesn't explicitly describe that the levels are in sequence and that hot_standby is a superset of archive. The comment "so at least archive level must be used to enable .... streaming replication." can be misinterpreted to mean that hot_standby level cannot be used with SR, unless the "at least archive level" is successfully interpreted with the understanding that minimal < archive < hot_standby. So would like to see that made explicit. -- Simon Riggs www.2ndQuadrant.com
Simon Riggs wrote: > > Recent changes to parameters aren't yet sufficiently well documented and > I'd like to see this improved by the authors of those patches. I accept > the behaviour changes, but we need full docs to explain them. > > * hot_standby doesn't mention that wal_level = hot_standby is also > required, nor is there a xref. > > * wal_level = 'hot_standby' doesn't mention that the second parameter > also needs to be set, nor is there a xref. > > * wal_level doesn't describe what the impacts are on a standby if the > level is changed on the primary, nor is there a caution or a warning of > any kind. For example, if a standby is setup with hot_standby = on and > the primary is set wal_level = archive, does the standby start working > if the primary changes wal_level = hot_standby? What happens if the > primary is set wal_level = hot_standby and is then changed to archive? > > * wal_level doesn't explicitly describe that the levels are in sequence > and that hot_standby is a superset of archive. The comment "so at least > archive level must be used to enable .... streaming replication." can be > misinterpreted to mean that hot_standby level cannot be used with SR, > unless the "at least archive level" is successfully interpreted with the > understanding that minimal < archive < hot_standby. So would like to see > that made explicit. I totally agree. Also, there is the new requirement to set wal_level for PITR, which is not documented as a necessary setup step yet. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com
Bruce Momjian wrote: > Simon Riggs wrote: >> * wal_level = 'hot_standby' doesn't mention that the second parameter >> also needs to be set, nor is there a xref. Fixed. >> * wal_level doesn't describe what the impacts are on a standby if the >> level is changed on the primary, nor is there a caution or a warning of >> any kind. For example, if a standby is setup with hot_standby = on and >> the primary is set wal_level = archive, does the standby start working >> if the primary changes wal_level = hot_standby? What happens if the >> primary is set wal_level = hot_standby and is then changed to archive? Hmm, feels like it should rather be documented in the hot_standby setting, it affects the standby not the master after all. How about this: --- config.sgml 2 May 2010 11:32:53 -0000 1.274 +++ config.sgml 3 May 2010 09:06:19 -0000 @@ -1931,6 +1933,19 @@ <para> Specifies whether or not you can connect and run queries during recovery,as described in <xref linkend="hot-standby">. + </para> + <para> + Hot Standby requires <xref linkend="guc-wal-level"> to be set + to <literal>hot_standby</> in the primary server. If it was not + while the WAL being replayed was generated, and + <varname>hot_standby</> is set to <literal>on</>, the server will + refuse to start up. Also, if <varname>wal_level</> is changed on + the primary server while a standby is active in hot standby mode, and + the primary server is restarted for the setting to take effect, the + standby will shut down as soon as it sees the checkpoint record + generated at the restart of the primary server. + </para> + <para> 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. >> * wal_level doesn't explicitly describe that the levels are in sequence >> and that hot_standby is a superset of archive. It does say: "The default value is <literal>minimal</>, which writes 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." Want to propose a better wording? > I totally agree. Also, there is the new requirement to set wal_level > for PITR, which is not documented as a necessary setup step yet. Fixed. -- Heikki Linnakangas EnterpriseDB http://www.enterprisedb.com
On Mon, 2010-05-03 at 12:17 +0300, Heikki Linnakangas wrote: > >> * wal_level doesn't describe what the impacts are on a standby if the > >> level is changed on the primary, nor is there a caution or a warning of > >> any kind. For example, if a standby is setup with hot_standby = on and > >> the primary is set wal_level = archive, does the standby start working > >> if the primary changes wal_level = hot_standby? What happens if the > >> primary is set wal_level = hot_standby and is then changed to archive? > > Hmm, feels like it should rather be documented in the hot_standby > setting, it affects the standby not the master after all. Danger of action at a distance. The change is on the master, but the effect is on the standby. The person changing the master must be warned of the danger that they will bring down the standby, so it must go with the parameter, not only with the HS docs. Doesn't this new behaviour prevent startup-from-a-shutdown-checkpoint? Whether it does or not, we need it to be documented. > >> * wal_level doesn't explicitly describe that the levels are in sequence > >> and that hot_standby is a superset of archive. > > It does say: > "The default value is <literal>minimal</>, which writes 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." > > Want to propose a better wording? "so at least archive level" changed to "so a setting of either archive or hot_standby" That way there is no concept of an ordering required to understand the sentence because it is explicit. -- Simon Riggs www.2ndQuadrant.com
Simon Riggs wrote: > Doesn't this new behaviour prevent startup-from-a-shutdown-checkpoint? No. >>>> * wal_level doesn't explicitly describe that the levels are in sequence >>>> and that hot_standby is a superset of archive. >> It does say: >> "The default value is <literal>minimal</>, which writes 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." >> >> Want to propose a better wording? > > "so at least archive level" > > changed to > > "so a setting of either archive or hot_standby" > > That way there is no concept of an ordering required to understand the > sentence because it is explicit. Ok, changed along those lines. -- Heikki Linnakangas EnterpriseDB http://www.enterprisedb.com
On Mon, 2010-05-03 at 10:50 +0100, Simon Riggs wrote: > On Mon, 2010-05-03 at 12:17 +0300, Heikki Linnakangas wrote: > > > >> * wal_level doesn't describe what the impacts are on a standby if the > > >> level is changed on the primary, nor is there a caution or a warning of > > >> any kind. For example, if a standby is setup with hot_standby = on and > > >> the primary is set wal_level = archive, does the standby start working > > >> if the primary changes wal_level = hot_standby? What happens if the > > >> primary is set wal_level = hot_standby and is then changed to archive? > > > > Hmm, feels like it should rather be documented in the hot_standby > > setting, it affects the standby not the master after all. > > Danger of action at a distance. The change is on the master, but the > effect is on the standby. The person changing the master must be warned > of the danger that they will bring down the standby, so it must go with > the parameter, not only with the HS docs. Don't really understand why you left that bit out. Are you just leaving this for me, or is there a specific objection to adding the warning? -- Simon Riggs www.2ndQuadrant.com
Simon Riggs wrote: > On Mon, 2010-05-03 at 10:50 +0100, Simon Riggs wrote: >> On Mon, 2010-05-03 at 12:17 +0300, Heikki Linnakangas wrote: >> >>>>> * wal_level doesn't describe what the impacts are on a standby if the >>>>> level is changed on the primary, nor is there a caution or a warning of >>>>> any kind. For example, if a standby is setup with hot_standby = on and >>>>> the primary is set wal_level = archive, does the standby start working >>>>> if the primary changes wal_level = hot_standby? What happens if the >>>>> primary is set wal_level = hot_standby and is then changed to archive? >>> Hmm, feels like it should rather be documented in the hot_standby >>> setting, it affects the standby not the master after all. >> Danger of action at a distance. The change is on the master, but the >> effect is on the standby. The person changing the master must be warned >> of the danger that they will bring down the standby, so it must go with >> the parameter, not only with the HS docs. > > Don't really understand why you left that bit out. > > Are you just leaving this for me, or is there a specific objection to > adding the warning? Sorry, I just didn't have the time & energy to figure out what to do about that. Feel free to fix as you see fit. -- Heikki Linnakangas EnterpriseDB http://www.enterprisedb.com
On Mon, 2010-05-03 at 23:28 +0300, Heikki Linnakangas wrote: > Sorry, I just didn't have the time & energy to figure out what to do > about that. Feel free to fix as you see fit. Yeh, I sometimes feel like that towards other hacker's comments as well. -- Simon Riggs www.2ndQuadrant.com