Re: Hot Standby documentation updates

Applied; updated version attached. I talked to Greg via IM and we
decide to not use his buffer cleanup locks text below but to use
something simpler:

The standby waiting longer than <varname>max_standby_delay</>
to acquire a buffer cleanup lock.

---------------------------------------------------------------------------

Greg Smith wrote:
> Attached is a patch that fixes up a couple of spots I felt could use
> improvement in the Hot Standby documentation. Most of this is simple
> wordsmithing, or minor expansion of points I tried to explain more
> clearly. A few of the edits I'd marked up on paper were already applied
> in the last update done today--even the same commas added or removed in
> some spots. I think this section is closing in on complete and fully
> edited when we are all finding the same things to nitpick over.
>
> The main change I added here that could use a review is this addition:
>
> + Waiting to acquire buffer cleanup locks. This can occur when one
> + database backend is trying to access to data block that is
> "pinned"
> + by another backend that is making a change to it. Such pins
> should
> + normally be very short-lived, but they can take longer than normal
> + under some circumstances, such as when a cursor executing over
> + a set of data has stopped for some reason.
>
> That's how I interpreted what Simon told me about this subject, but I
> may not have captured the details accurately. I didn't think that
> saying something as ominous sounding as "Waiting to acquire buffer
> cleanup locks" should be there without any description at all what
> conditions that happens under, which is what's there right now.
>
> There are only two open things in these docs I'm still a little bugged by:
>
> -The first paragraph mentions "restoring a backup to an exact state with
> great precision"; I have no idea what that's supposed to mean in this
> context.
>
> -The section about stats collection says "The stats file is deleted at
> the start of recovery, so stats from primary and standby will differ;
> this is considered a feature not a bug". This left me going "why?", and
> some clarification of the reasoning or limitation causing that drift
> would be nice.
>
> P.S. I touched a few other files as well, related to a debate from
> dinner the other night that touched on Simon introducing more UK
> spelling into the docs. This is what the docs look like now:
>
> postgresql/doc/src/sgml $ grep -r behavior * | wc -l
> 386
>
> postgresql/doc/src/sgml $ grep -r behaviour * | wc -l
> 9
>
> Half of the latter were in the new material, so while on a binge fixing
> those I adjusted the mis-"behaviour"s in other sections too.
>
> --
> Greg Smith 2ndQuadrant US Baltimore, MD
> PostgreSQL Training, Services and Support
> greg(at)2ndQuadrant(dot)com www.2ndQuadrant.us
>

>
> --
> Sent via pgsql-docs mailing list (pgsql-docs(at)postgresql(dot)org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +