Subject: per feedback I received directly, pg_dump manpage patch

From: "Joshua D. Drake" <[email-masked]>
Date: Wed, 27 May 2015 16:17:06 -0700

The man page does not clearly state that pg_dump will not dump things 
like users or roles. It does mention briefly in the notes section that 
pg_dumpall is needed for items that are set via SET but that isn't very 
clear on the other items.
-- 
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.
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index a6e7b08..4cb647c 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -45,6 +45,14 @@ PostgreSQL documentation
    accessing the database (readers or writers).
   </para>
 
+  <warning>
+  <para>
+  <xref linkend="app-pg-dumpall"> is required for a full backup as 
+  <application>pg_dump</application> does not backup the required global
+  options such as user or roles.
+  </para>
+  </warning>
+
   <para>
    Dumps can be output in script or archive file formats. Script
    dumps are plain-text files containing the SQL commands required

-- 
Sent via pgsql-docs mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 27 May 2015 22:31:01 -0300

Joshua D. Drake wrote:
> The man page does not clearly state that pg_dump will not dump things like
> users or roles. It does mention briefly in the notes section that pg_dumpall
> is needed for items that are set via SET but that isn't very clear on the
> other items.

I agree that we need a warning about this, but I think it should be a
bit more generic rather than focused exclusively on pg_dumpall; perhaps
something like "global objs such as roles/tblspcs should be backed up
separately, for example using pg_dumpall".

I didn't check the location of the warning in your patch, or whether a
warning is really appropriate rather than, say, <note> or a plain
<para>.

-- 
Álvaro Herrera                http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

---

From: "Joshua D. Drake" <[email-masked]>
Date: Wed, 27 May 2015 18:37:13 -0700

> separately, for example using pg_dumpall".

As the only way to back up global objects is pg_dumpall....?

> warning is really appropriate rather than, say, <note> or a plain

The warning is directly after the first paragraph. I thought about using 
<note> but I think this does warrant a <warning>. You can't actually 
restore a database correctly without pg_dump + pg_dumpall (in this context).

JD

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 27 May 2015 22:53:12 -0300

> As the only way to back up global objects is pg_dumpall....?

Well, my point is that the roles could be set up separately by other
means.

> <note> but I think this does warrant a <warning>. You can't actually restore
> a database correctly without pg_dump + pg_dumpall (in this context).

Okay, +0 there.  (That is, I don't disagree with you but I won't stand
in the way of others disagreeing on that point.)

---

From: "Joshua D. Drake" <[email-masked]>
Date: Wed, 27 May 2015 18:57:45 -0700

> Well, my point is that the roles could be set up separately by other

True but this is about pg_dump right? I mean contextually it doesn't 
matter if they can issue a separate SQL command as we are talking about 
getting a backup/dump that makes it so you don't have to issue a 
separate SQL command.

JD

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 28 May 2015 14:16:33 -0400

> clear on the other items.

How about this patch?

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index a6e7b08..33a1902 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -46,6 +46,12 @@
   </para>
 
   <para>
+   <application>pg_dump</application> only dumps a single database.  To save
+   global objects that are common to all databases in a cluster, such as roles
+   and tablespaces, use <xref linkend="app-pg-dumpall">.
+  </para>
+
+  <para>
    Dumps can be output in script or archive file formats. Script
    dumps are plain-text files containing the SQL commands required
    to reconstruct the database to the state it was in at the time it was

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 28 May 2015 14:18:49 -0400

> warning is really appropriate rather than, say, <note> or a plain

The problem is that every time we get a bug report that some user
tripped over something that was not clear in the documentation, the
patch wants to add a note or warning, which causes some parts of the
documentation to degrade into just a series of warning boxes.  The fewer
warning boxes there are, however, the more likely the user will actually
read all of the documentation, I think.

---

From: "Joshua D. Drake" <[email-masked]>
Date: Thu, 28 May 2015 12:27:05 -0700

>> clear on the other items.

I would change the word save to backup but other than that, looks good.

JD

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 13 Jun 2015 21:50:30 -0400

> I would change the word save to backup but other than that, looks good.

committed