Re: backup.sgml-cmd-v003.patch

On 09/27/2013 03:56 AM, Robert Haas wrote:
> On Thu, Sep 26, 2013 at 1:15 PM, Ivan Lezhnjov IV
> <iliv(at)commandprompt(dot)com> wrote:
>> Thanks for a detailed response. I attached a patch file that builds on your corrections and introduces some of the edits discussed above.
>
> This patch makes at least five unrelated sets of changes:
>
> 1. Attempting to encourage people to consider custom format dumps.
> 2. Suggesting that superuser access isn't necessary to dump the database.
> 3. Adding a note that OIDs on user objects are deprecated.
> 4. Describing the manner in which pg_dump can be used with pg_dumpall
> to back up all databases in a cluster.
> 5. Promoting pigz.
>
> It's not a good idea to bundle so many unrelated changes together into
> a single patch,

This isn't software, it is docs. It is ridiculous to suggest we break
this up into 3-4 patches. This is a small doc patch to a single doc file
(backup.sgml).

>
> I think that #3 and #5 have no business are things we shouldn't do at
> all. There are many compression utilities in the world other than
> gzip, and everyone has their favorites. I see no reason why we should
> promote one over the other.

Then a rewording that states that multi-threaded compression is
available perhaps and list a couple? Because pigz over gzip is a no
brainer but there are also the equiv for bzip2 etc...

> Certainly, the fact that you yourself
> have found pigz useful is not sufficient evidence that everyone should
> prefer it.

Smart people would :P At least over gzip. If you have more than one core
it is one of those... duh things.

> And, while it's true that OIDs on user objects are
> deprecated, I don't think the pg_dump documentation necessarily needs
> to recapitulate this point particularly; hopefully, it's documented
> elsewhere; if not, this isn't the right place to mention it.

Fair enough.

> If,
> contrary to my feelings on the matter, we do decide to make a change
> in either of these areas, it's unrelated to the rest of this patch and
> needs to be submitted and discussed separately.
>
> I think that #2 is probably a worthwhile change in some form.
> However, I don't particularly agree with the way you've worded it
> here. This section is trying to give a general overview of how to
> back up your whole database; it's not the pg_dump reference page,

[..]

> superuser privileges; it's the selective-dump case where you can often
> get by without them. I've attached a proposed patch along these lines
> for your consideration.

That's fair.

>
> The remaining changes (#1 and #4) can probably be blended together in
> a single patch. However, I think that you need to make more of an
> effort to use neutral wording. The purpose of the documentation is
> not to pass judgement on the tools. Examples:
>
> + The above example creates a plain text file. This type of dump can be used
> + to restore a database in full. However there are more sophisticated
> + <productname>PostgreSQL</> backup formats which allow for far greater
> + control when working with backups. One of these is
> + the <quote>custom</quote> format, which the following more elaborate
> + example creates:
>
> I don't find it helpful to classify the other formats as more
> sophisticated or to say that they allow far greater control, or to
> call the example elaborate. What's important is what you can do, and
> there's basically one thing: selective restores. So I think you could
> replace all that, the following example, and the paragraph after that
> with: The above example creates a plain text file. pg_dump can also
> create backups in other formats, such as the custom format. This may
> be advantageous, since all formats other than the plain text file
> format make it possible to selectively restore objects from the dump.
> See <xref linkend="app-pgrestore"> for more details.

I can buy into that but I don't think it gives the other formats
justice. Plain text format is rather useless in the sense of a backup.

>
> + <para>
> + Unfortunately, <application>pg_dumpall</> can only create plaintext
> + backups. However, it is currently the only way to backup the globals in you
>
> Similarly, let's not label pg_dumpall's behavior as unfortunate.

Uh, pg_dumpall's behavior is crap. Unfortunate was being polite. Alas
you are correct, in documentation we should be neutral. I agree, let's
remove the word Unfortunately.

> I
> think it's appropriate to explain the pg_dumpall -g / pg_dump -Fc
> combination somewhere in the documentation, as it is widely used and
> very useful. But I don't think it's useful to imply to users that the
> tools are inadequate; generally, they're not, improvements that we'd
> like to make nonwithstanding.

Generally speaking I would agree with you but in this case I do not. The
way we have to back up things, including things that aren't backed up
nor documented (alter database?), are inadequate.

That said, that is an argument for another time. Outside of what I have
said I agree.

Joshua D. Drake

P.S. Sorry for the late reply. I got on Iliv to wrap up this patch and
he asked me if we want to put that much effort into it. I thought I
would respond before we decide.

--
Command Prompt, Inc. - http://www.commandprompt.com/ 509-416-6579
PostgreSQL Support, Training, Professional Services and Development
High Availability, Oracle Conversion, Postgres-XC, @cmdpromptinc
For my dreams of your image that blossoms
a rose in the deeps of my heart. - W.B. Yeats