Hot Standby documentation updates

From: Greg Smith <greg(at)2ndquadrant(dot)com>
To: pgsql-docs(at)postgresql(dot)org, Simon Riggs <simon(at)2ndQuadrant(dot)com>
Subject: Hot Standby documentation updates
Date: 2010-02-18 08:11:21
Message-ID: 4B7CF629.4070103@2ndquadrant.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

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

Attachment Content-Type Size
hot-standby-doc-fix.diff text/x-patch 17.5 KB

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Fujii Masao 2010-02-18 11:37:18 Re: Re: [COMMITTERS] pgsql: Make standby server continuously retry restoring the next WAL
Previous Message Tom Lane 2010-02-17 17:07:34 Re: Re: [BUGS] BUG #4566: pg_stop_backup() reports incorrect STOP WAL LOCATION