Re: Rewriting backup.sgml (patch attached) - Mailing list pgsql-hackers

From Fabien COELHO
Subject Re: Rewriting backup.sgml (patch attached)
Date
Msg-id alpine.DEB.2.10.1505200744050.9596@sto
Whole thread Raw
In response to Rewriting backup.sgml (patch attached)  ("Joshua D. Drake" <jd@commandprompt.com>)
List pgsql-hackers
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.

pgsql-hackers by date:

Previous
From: Peter Geoghegan
Date:
Subject: Re: jsonb concatenate operator's semantics seem questionable
Next
From: Noah Misch
Date:
Subject: Re: a few thoughts on the schedule