Thread: Rewriting backup.sgml (patch attached)

Hello,

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 didn't really touch the red headed step child that is pg_dumpall
(although a word smithed it a little).

I tried to remove some of the conversationalist tone. This is technical
documentation not a story. I also removed as many extra words as
reasonable and added specific examples.

Now, I know some of you will say things like... why did you add -C to
the pg_dump line. The reason is simple, without it as new person is
going to get an error on restore. Our documentation should be explicit
not implicit.

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

Sincerely,

JD
--
Command Prompt, Inc. - http://www.commandprompt.com/  503-667-4564
PostgreSQL Centered full stack support, consulting and development.
Announcing "I'm offended" is basically telling the world you can't
control your own emotions, so everyone else should do it for you.

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
tobacking 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.