Re: Rewriting backup.sgml (patch attached)

Hello Joshua,

My 0.02 €:

> Alright, per previous discussions I went through the backup.sgml page. I have
> gone thoroughly through:
>
> sql dump
> pg_dump
> pg_restore
> handling large databases
>
> I removed file based backups

I strongly disagree:

The section is interesting at least for the arguments that explain why
this approach has drawbacks. These caveats are important and should be
preserved. Moreover people may be happy with filesystem snapshots, why
not. Probably having a database running on top of such a journaled FS is
not the best choice, but it may happen for good reasons.

The point of a documentation is not to hide options, but to allow the
admin to do informed choices depending on her environment and constraints
that you do not know about, and help her to implement the chosen option
correctly and effectively. An option with drawbacks may be the good one.

I would rather emphasize the caveats, if this is the desired effect, say
adding more "caution" or "warning" here and there, than removing this
section altogether. Maybe move the troublesome option as the last one. But
not remove it.

> I do not want to progress any farther on this until I get some feedback.

<para>
- There are three fundamentally different approaches to backing up
+ There are four different approaches to backing up
<productname>PostgreSQL</> data:
<itemizedlist>
<listitem><para><acronym>SQL</> dump</para></listitem>
- <listitem><para>File system level backup</para></listitem>
- <listitem><para>Continuous archiving</para></listitem>
+ <listitem><para><acronym>PITR</>, Point in Time
Recovery</para></listitem>
</itemizedlist>

I'm not sure that the "four" announced in from of a list of 2 items is
right...

- After restoring a backup, it is wise to run <xref
+ After restoring a backup, one should execute <xref

Docs are too often impersonal boring things, in competition with standards
on that account. The occasional light tone and style, if it does not
hinder clarity and comprehension, is not necessarily a bad thing.

Maybe a summary of backup approaches, maybe in the form of a table, could
be a good thing at the end of the chapter introduction.

The introduction may emphasize the need to have tested backup plans.

You have added a warning about the fact that pg_dump does not save all the
necessary data to restore the database. Good. I would suggest to go a step
further and discuss that it needs to be considered at the beginning of the
"SQL Dump" section, and maybe even in the chapter introduction.

Otherwise, the reorganized, detailed and explained options and practical
advices around pg_dump looks good.

--
Fabien.