Re: backup.sgml-cmd-v003.patch

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, because if there is disagreement about any item on the
list, then the patch doesn't go in. Moreover, we typically try to
commit one change at a time, so this leaves the eventual committer
with the unenviable task of splitting up the patch for commit.

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. Certainly, the fact that you yourself
have found pigz useful is not sufficient evidence that everyone should
prefer it. 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. 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,
which exists elsewhere. I would suggest that the relevant caveat here
is not so much that you might have a non-superuser account that just
happens to have enough privileges to back up the entire database, but
rather that we shouldn't give people the impression that the only
possible use of pg_dump is as for a full backup. Because in my
experience, a full-database backup almost always DOES require
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.

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.

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

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company