Re: Documentation on PITR still scarce

Joachim Wieland <joe(at)mcknight(dot)de> wrote on 05.11.2004, 16:28:38:
> Hi there,
>
> I just wanted to try the PITR feature in beta and got it working somehow.
> However I think the docs on this point are still not sufficient enough.
>
> We have to assume that people will have a closer look at the backup/recovery
> documentation as soon as 8.0 ships, because we're kinda heavily advertizing
> for 8.0 with the PITR feature.
>
> In chapter 22, "Backup and Restore", there is not a single example of a
> recovery.conf, nor is any of these parameters even mentioned:
>
> recovery_target_time
> recovery_target_xid
> recovery_target_timeline
> recovery_target_inclusive
>
> There's an example file in the source tree in backend/access/transam
> however.
>
> So from looking at the docs only it's quite difficult to figure out how it
> works in practice. I'd appreciate an example with multiple timelines as
> well.
>

Joachim,

Thanks for your interest in PITR and your feedback, which is much
appreciated. I'm sorry you've had difficulty.

I've read the documentation again, so can vouch for the accuracy of it -
it also contains descriptions and advisories that are useful to you.
Tom wrote this and my opinion was/is that it is very clear and helpful.

Ch22 does specifically point you to the recovery.conf.sample file and
describes where to find it. It also tells you the type of information
you can specify within it, though you are right in that it doesn't
specifically describe each parameter. The sample file gives additional
information, just as occurs with pg_hba.conf. I don't see any need to
replicate the sample file in the docs, do you?

You're not the first person to ask for more docs. It's difficult for me
to see how to improve what's there. I'm hampered by understanding it
already, if that makes sense. PostgreSQL transactional recovery is very
similar to SQL Server, DB2 and Oracle recovery. Obviously, if you're
new to the whole subject of transactional recovery then the docs are
fairly sparse ... but the docs aren't intended to be a basic course in
database transactional recovery. Oracle, for example, cover this in a 3
day course. [My company teaches a short course on PostgreSQL PITR,
which is one way that we recoup the cost of developing the software...
It's possible for me to arrange courses outside of the UK also, if I
get invitations or there is general demand. ...Please excuse OT
discussion]

I did originally submit some documentation for this to PATCHES, as of
mid-August; perhaps that may shed more light. That did contain some
descriptive examples, but not worked ones.

If you have specific questions, I can answer those. There haven't been
any specific questions asked that aren't covered in the docs or the
sample file, other than these:

> recovery_target_time

This is the stopping point mentioned in the docs.

> recovery_target_inclusive

This parameter allows you to specify whether you should stop AT/ON (i.e.
inclusive [<=]) or just before the recovery_target (i.e. exclusive
[<]).

I'll add a few more lines to the chapter to include those descriptions.

I would encourage you and other users to submit a documentation patch
yourself if you find better ways of explaining what it's for, how to
make it work etc..

Best Regards,

Simon Riggs
2nd Quadrant
www.2ndquadrant.com