backup.sgml-cmd-v003.patch

Hi,

Could you add this documentation patch to the next commit fest such as it
doesn't get lost in the stack?
https://commitfest.postgresql.org/action/commitfest_view?id=19

On Thu, Aug 1, 2013 at 2:08 AM, Ivan Lezhnjov IV <iliv@commandprompt.com>wrote:

The patch does pass 'make check' and 'make html' successfully.

Your patch does not add new code, but just documentation, so there is no
risk that make check would fail, except if an error has been introduced by
another commit at some point...

Thanks,
--
Michael

Michael Paquier escribi�:

On Thu, Aug 1, 2013 at 2:08 AM, Ivan Lezhnjov IV <iliv@commandprompt.com>wrote:

The patch does pass 'make check' and 'make html' successfully.

Your patch does not add new code, but just documentation, so there is no
risk that make check would fail, except if an error has been introduced by
another commit at some point...

There's "make check" in the doc/src/sgml directory. It checks for SGML
consistency, absence of tabs and such.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Aug 1, 2013 at 9:39 AM, Alvaro Herrera <alvherre@2ndquadrant.com>wrote:

Michael Paquier escribió:

On Thu, Aug 1, 2013 at 2:08 AM, Ivan Lezhnjov IV <iliv@commandprompt.com
wrote:

The patch does pass 'make check' and 'make html' successfully.

Your patch does not add new code, but just documentation, so there is no
risk that make check would fail, except if an error has been introduced

by

another commit at some point...

There's "make check" in the doc/src/sgml directory. It checks for SGML
consistency, absence of tabs and such.

Oh thanks. Sorry for my mistake. This is good to know.
--
Michael

On 07/31/2013 12:08:12 PM, Ivan Lezhnjov IV wrote:

Patch filename: backup.sgml-cmd-v003.patch

The third version of this patch takes into consideration feedback
received after original submission (it can be read starting from this
message /messages/by-id/CA
+Tgmoaq-9D_mst113TdW=Ar8mpgBc+x6T61AzK3eMhww9gRcQ@mail.gmail.com)

Essentially, it addresses the points that were raised in community
feedback and offers better worded statements that avoid implying that
some features are being deprecated when it isn't the case. We also
spent some more time polishing other details, like making adjustments
to the tone of the text so that it sounds more like a manual, and
less
like a blog post. More importantly, this chapter now makes it clear
that superuser privileges are not always required to perform a
successful backup because in practice as long as the role used to
make
a backup has sufficient read privileges on all of the objects a user
is interested in it's going to work just fine. We also mention and
show examples of usage for pg_restore and pigz alongside with gzip,
and probably something else too.

Hi Ivan,

I'm reviewing your patch. I did not read the entirety of the
thread referenced above. I apologize if this causes problems.

Attached is backup-sgml-cmnd-v003_1.patch to be applied on top of
backup-sgml-cmnd-v003.patch and containing my edits. You will
eventually want to produce a single patch (but see below).
Meanwhile this might help you keep track of my changes.

Attached also is your original v3 patch.

---

Cleaned up and clarified here and there.

The bit about OIDs being depreciated might properly belong in
a separate patch. The same might be said about adding mention of pigz.
If you submit these as separate patch file attachments
they can always be applied in a single commit, but the reverse is
more work for the committer. (Regardless, I see no reason to
have separate commitfest entries or anything other than multiple
attachments to the email that finalizes our discussion.)

Minimally modified to note the existence of directory dumps. It may
be that the utility/flexibility of directory dumps should also be
mentioned.

My thought is that the part beginning with "The options in detail
are:" should not describe all the possibilities for the --format
option, that being better left to the reference section. Likewise,
this being prose, it might be best to describe all the options
in-line, instead of presented as a list. I have left it as-is
for you to improve as seen fit.

I have frobbed your <programlisting> to adjust the indentation and
line-wrap style. I submit it here for consideration in case this
style is attractive. This is nothing but conceit. We should use the
same style used elsewhere in the documentation. (I can't think
offhand of a place to look for a line-wrapped shell example. If you
can't find one I'll take a look and if neither of us finds one we'll
then have choices.)

I don't know that it's necessary to include pigz examples, because it
sounds like pigz is a drop-in gzip replacement. I've left your
examples in, in case you feel they are necessary.

The existing text of the SQL Dump section could use some alteration to
reduce redundancy and add clarity. I'm thinking specifically of
mention of pg_restore as being required to restore custom format
backups and of the default pg_dump output being not just "plain text"
but being a collection of SQL commands. Yes, the latter is obvious
upon reflection, psql being what it is, but I think it would be
helpful to spell this out. Especially in the context of the current
patch. There could well be other areas like this to be addressed.

Overall I have pretty good feelings about this patch. Backup and
restore is complex and although this patch leaves a lot of issues
unmentioned it seems a step in the right direction.

Regards,

Karl <kop@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 9a80062..36bf000 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -49,8 +49,9 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
    does not operate with special permissions. In particular, it must
    have read access to all tables that you want to back up. Whether
    it is going to have proper access permissions is determined by
-   privileges granted to a role used to connect to a database.
-   As long as the role has read access to tables, sequences, etc.
+   the privileges granted to the role used to connect to the database server.
+   Although a superuser role will always have the necessary permissions
+   as long as the role used has read access to tables, sequences, etc.
    it need not to be a superuser role.
   </para>
 
@@ -106,22 +107,28 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
   </important>
 
   <para>
-   This type of dump can be used to restore a database in full. However,
-   there is a more sophisticated form of <productname>PostgreSQL</> backup
-   that allows for far greater control when working with backups. A syntax looks like this:
+   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:
+
 <synopsis>
 pg_dump -U <replaceable class="parameter">username</replaceable> --format=c --file=<replaceable class="parameter">mydatabase.sqlc</replaceable> <replaceable class="parameter">dbname</replaceable>
 </synopsis>
    The options in detail are:
 <synopsis>
  -U, --username=NAME      connect as specified database user
- -F, --format=c|t|p       output file format (custom, tar, plain text)
+ -F, --format=c|d|t|p     output file format (custom, directory, tar, plain text)
  -f, --file=FILENAME      output file name
 </synopsis>
-   The most important of which is <replaceable class="parameter">--format</replaceable>.
-   By default <application>pg_dump</> uses the plaintext format. In
-   some cases you may be better off using a custom format backup, though.
-   The custom format allows for a wealth of customizability.
+
+   The most interesting of these
+   is <replaceable class="parameter">--format</replaceable>.  By
+   default <application>pg_dump</> creates a plaintext backup.  You may be
+   better off creating a custom format backup, since the custom format is much
+   more flexible.
   </para>
 
   <para>
@@ -131,11 +138,11 @@ pg_dump -U <replaceable class="parameter">username</replaceable> --format=c --fi
 <synopsis>
 pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">dbname</replaceable> --index=<replaceable class="parameter">indexname</replaceable>
 </synopsis>
-   If you wanted to restore only a single function:
+   To restore only a single function:
 <synopsis>
 pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">dbname</replaceable> --function=<replaceable class="parameter">functionname(args)</replaceable>
 </synopsis>
-   If you wanted to restore only a single table:
+   To restore only a single table:
 <synopsis>
 pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">dbname</replaceable> --table=<replaceable class="parameter">tablename</replaceable>
 </synopsis>
@@ -151,8 +158,8 @@ pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<re
 <synopsis>
 psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class="parameter">infile</replaceable>
 </synopsis>
-    where <replaceable class="parameter">infile</replaceable> is the
-    file output by the <application>pg_dump</> command. The database <replaceable
+    where <replaceable class="parameter">infile</replaceable> is a plaintext
+    backup output by the <application>pg_dump</> command. The database <replaceable
     class="parameter">dbname</replaceable> will not be created by this
     command, so you must create it yourself from <literal>template0</>
     before executing <application>psql</> (e.g., with
@@ -215,9 +222,11 @@ pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>h
    </important>
 
    <para>
-    When it comes to restoring a dump with a custom format the command
-    used to restore a backup file is <application>pg_restore</>. It has
-    similar options to <application>pg_dump</>. A simple restore:
+    The <application>psql</> command is a way, as shown above, to restore
+    plaintext backups.  To restore a custom format backup
+    the <application>pg_restore</> command must be used. It has options
+    similar to those of <application>pg_dump</>. A simple use
+    of <application>pg_restore</> is:
 <synopsis>
 pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">databasename</replaceable> <replaceable class="parameter">filename</replaceable>
 </synopsis>
@@ -228,21 +237,13 @@ pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<re
     <para>
      Do not confuse <option>--file</> with <replaceable
      class="parameter">filename</replaceable>. The
-     <option>--file</> option is used to turn a custom format backup
-     into a plaintext backup. The value of <option>--file</> will be
-     used as the output file for that transformation.
+     <option>--file</> option can be used when converting backups from one
+     form to another, the value of <option>--file</> specifying the name of
+     the output file.
     </para>
    </important>
 
    <para>
-    If what you have is a plaintext backup <application>pg_restore</> can
-    not be used as a restoration mechanism. You can use <application>psql</> to restore it:
-<programlisting>
-psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class="parameter">backupfile</replaceable>
-</programlisting>
-   </para>
-
-   <para>
     After restoring a backup, it is wise to run <xref
     linkend="sql-analyze"> on each
     database so the query optimizer has useful statistics;
@@ -298,11 +299,11 @@ psql -f <replaceable class="parameter">infile</replaceable> postgres
     look like this:
 <programlisting>
 pg_dumpall -g -Uusername --file=globals.sql;
-psql -AtU postgres -c "SELECT datname FROM pg_database \
-                          WHERE NOT datistemplate"| \
-while read f;
-   do pg_dump -Upostgres --format=c --file=$f.sqlc $f;
-done;
+psql -AtU postgres 
+     -c "SELECT datname FROM pg_database WHERE NOT datistemplate" \
+  | while read f;
+      do pg_dump -Upostgres --format=c --file=$f.sqlc $f;
+    done;
 </programlisting>
    </para>
   </sect2>
@@ -322,9 +323,9 @@ done;
     <title>Use compressed dumps.</title>
     <para>
      You can use your favorite compression program, for example
-     <application>gzip</application> or <application>pigz</application> which 
-     is a parallel implementation of <application>gzip</application> for modern
-     multi-processor, multi-core machines:
+     <application>gzip</application> or <application>pigz</application> 
+     (a parallel implementation of <application>gzip</application> for modern
+     multi-processor, multi-core machines):
 
 <programlisting>
 pg_dump <replaceable class="parameter">dbname</replaceable> | gzip &gt; <replaceable class="parameter">filename</replaceable>.gz

On 09/02/2013 10:56:54 PM, Karl O. Pinc wrote:

I have frobbed your <programlisting> to adjust the indentation and
line-wrap style.

Oops. Somehow left a \ out of this. Anyhow, you get the idea.

Karl <kop@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Sep 3, 2013, at 6:56 AM, Karl O. Pinc <kop@meme.com> wrote:

On 07/31/2013 12:08:12 PM, Ivan Lezhnjov IV wrote:

Patch filename: backup.sgml-cmd-v003.patch

The third version of this patch takes into consideration feedback
received after original submission (it can be read starting from this
message /messages/by-id/CA
+Tgmoaq-9D_mst113TdW=Ar8mpgBc+x6T61AzK3eMhww9gRcQ@mail.gmail.com)

Essentially, it addresses the points that were raised in community
feedback and offers better worded statements that avoid implying that
some features are being deprecated when it isn't the case. We also
spent some more time polishing other details, like making adjustments
to the tone of the text so that it sounds more like a manual, and
less
like a blog post. More importantly, this chapter now makes it clear
that superuser privileges are not always required to perform a
successful backup because in practice as long as the role used to
make
a backup has sufficient read privileges on all of the objects a user
is interested in it's going to work just fine. We also mention and
show examples of usage for pg_restore and pigz alongside with gzip,
and probably something else too.

Hi Ivan,

I'm reviewing your patch. I did not read the entirety of the
thread referenced above. I apologize if this causes problems.

Attached is backup-sgml-cmnd-v003_1.patch to be applied on top of
backup-sgml-cmnd-v003.patch and containing my edits. You will
eventually want to produce a single patch (but see below).
Meanwhile this might help you keep track of my changes.

Attached also is your original v3 patch.

---

Cleaned up and clarified here and there.

The bit about OIDs being depreciated might properly belong in
a separate patch. The same might be said about adding mention of pigz.
If you submit these as separate patch file attachments
they can always be applied in a single commit, but the reverse is
more work for the committer. (Regardless, I see no reason to
have separate commitfest entries or anything other than multiple
attachments to the email that finalizes our discussion.)

Hello,

took me a while to get here, but a lot has been going on...

Okay, I'm new and I don't know why a single patch like this is more work for a commiter? Just so I understand and know.

Minimally modified to note the existence of directory dumps. It may
be that the utility/flexibility of directory dumps should also be
mentioned.

My thought is that the part beginning with "The options in detail
are:" should not describe all the possibilities for the --format
option, that being better left to the reference section. Likewise,
this being prose, it might be best to describe all the options
in-line, instead of presented as a list. I have left it as-is
for you to improve as seen fit.

Agreed, it probably looks better as a sentence.

I have frobbed your <programlisting> to adjust the indentation and
line-wrap style. I submit it here for consideration in case this
style is attractive. This is nothing but conceit. We should use the
same style used elsewhere in the documentation. (I can't think
offhand of a place to look for a line-wrapped shell example. If you
can't find one I'll take a look and if neither of us finds one we'll
then have choices.)

Looks good to me.

I don't know that it's necessary to include pigz examples, because it
sounds like pigz is a drop-in gzip replacement. I've left your
examples in, in case you feel they are necessary.

We do. We believe it can encourage more people to consider using it. The way we see it, most people seem to be running mutlicore systems these days, yet many simply are not aware of pigz. We have been routinely informing our customers of pigz as an alternative to tried and tested gzip when helping optimize their configurations, and all of them without exception went for it. I guess everybody just likes to squeeze some extra juice for free.

The existing text of the SQL Dump section could use some alteration to
reduce redundancy and add clarity. I'm thinking specifically of
mention of pg_restore as being required to restore custom format
backups and of the default pg_dump output being not just "plain text"
but being a collection of SQL commands. Yes, the latter is obvious
upon reflection, psql being what it is, but I think it would be
helpful to spell this out. Especially in the context of the current
patch. There could well be other areas like this to be addressed.

I don't quite follow you here. I mean, I kinda understand what you mean in general, but when I look at the text I fail to see what you had in mind specifically.

For example, pg_restore is mentioned only 3 times in section 24.1. Each mention seems pretty essential to me. And the text flow is pretty natural.

Also, about plain text format being a collection of SQL commands. The very first paragraph of the section 24.1 reads "The idea behind this dump method is to generate a text file with SQL commands that, when fed back to the server, will recreate the database in the same state as it was at the time of the dump. PostgreSQL provides the utility program pg_dump for this purpose."

Overall I have pretty good feelings about this patch. Backup and
restore is complex and although this patch leaves a lot of issues
unmentioned it seems a step in the right direction.

Thanks for a detailed response. I attached a patch file that builds on your corrections and introduces some of the edits discussed above.

Ivan

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index ccb76d8..d6d82f0 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -38,7 +38,7 @@
 pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable class="parameter">outfile</replaceable>
 </synopsis>
    As you see, <application>pg_dump</> writes its result to the
-   standard output. We will see below how this can be useful.
+   standard output.
   </para>
 
   <para>
@@ -47,8 +47,12 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
    that you can perform this backup procedure from any remote host that has
    access to the database. But remember that <application>pg_dump</>
    does not operate with special permissions. In particular, it must
-   have read access to all tables that you want to back up, so in
-   practice you almost always have to run it as a database superuser.
+   have read access to all tables that you want to back up. Whether
+   it is going to have proper access permissions is determined by
+   the privileges granted to the role used to connect to the database server.
+   Although a superuser role will always have the necessary permissions
+   as long as the role used has read access to tables, sequences, etc.
+   it need not to be a superuser role.
   </para>
 
   <para>
@@ -95,13 +99,53 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
 
   <important>
    <para>
-    If your database schema relies on OIDs (for instance, as foreign
-    keys) you must instruct <application>pg_dump</> to dump the OIDs
-    as well. To do this, use the <option>-o</option> command-line
-    option.
+    The use of OIDs on user objects is deprecated. If your database schema
+    relies on OIDs (for instance, as foreign keys) you must instruct
+    <application>pg_dump</> to dump the OIDs as well. To do this, use 
+    the <option>-o</option> command-line option.
    </para>
   </important>
 
+  <para>
+   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:
+
+<synopsis>
+pg_dump -U <replaceable class="parameter">username</replaceable> --format=c --file=<replaceable class="parameter">mydatabase.sqlc</replaceable> <replaceable class="parameter">dbname</replaceable>
+</synopsis>
+   where  <replaceable class="parameter">-U</replaceable> instructs <application>pg_dump</> to connect as specified database user, 
+   <replaceable class="parameter">--format</replaceable> sets output file format 
+   as custom (other supported options are: directory, tar, plain text) and 
+   <replaceable class="parameter">--file</replaceable> specifies output file name.
+
+   The most interesting of these is 
+   <replaceable class="parameter">--format</replaceable>.  By default 
+   <application>pg_dump</> creates a plaintext backup.  You may be
+   better off creating a custom format backup, since the custom format is much
+   more flexible.
+  </para>
+
+  <para>
+   Using the custom format you are able to restore single objects from a
+   backup. For example to restore only a specified index from a backup
+   file:
+<synopsis>
+pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">dbname</replaceable> --index=<replaceable class="parameter">indexname</replaceable>
+</synopsis>
+   To restore only a single function:
+<synopsis>
+pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">dbname</replaceable> --function=<replaceable class="parameter">functionname(args)</replaceable>
+</synopsis>
+   To restore only a single table:
+<synopsis>
+pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">dbname</replaceable> --table=<replaceable class="parameter">tablename</replaceable>
+</synopsis>
+  </para>
+
   <sect2 id="backup-dump-restore">
    <title>Restoring the Dump</title>
 
@@ -112,8 +156,8 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
 <synopsis>
 psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class="parameter">infile</replaceable>
 </synopsis>
-    where <replaceable class="parameter">infile</replaceable> is the
-    file output by the <application>pg_dump</> command. The database <replaceable
+    where <replaceable class="parameter">infile</replaceable> is a plaintext
+    backup output by the <application>pg_dump</> command. The database <replaceable
     class="parameter">dbname</replaceable> will not be created by this
     command, so you must create it yourself from <literal>template0</>
     before executing <application>psql</> (e.g., with
@@ -176,6 +220,28 @@ pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>h
    </important>
 
    <para>
+    The <application>psql</> command is a way, as shown above, to restore
+    plaintext backups.  To restore a custom format backup
+    the <application>pg_restore</> command must be used. It has options
+    similar to those of <application>pg_dump</>. A simple use
+    of <application>pg_restore</> is:
+<synopsis>
+pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">databasename</replaceable> <replaceable class="parameter">filename</replaceable>
+</synopsis>
+    Where <replaceable class="parameter">filename</replaceable> is the name of the backup file.
+   </para>
+
+   <important>
+    <para>
+     Do not confuse <option>--file</> with <replaceable
+     class="parameter">filename</replaceable>. The
+     <option>--file</> option can be used when converting backups from one
+     form to another, the value of <option>--file</> specifying the name of
+     the output file.
+    </para>
+   </important>
+
+   <para>
     After restoring a backup, it is wise to run <xref
     linkend="sql-analyze"> on each
     database so the query optimizer has useful statistics;
@@ -222,6 +288,22 @@ psql -f <replaceable class="parameter">infile</replaceable> postgres
     each database will be internally consistent, the snapshots of
     different databases might not be exactly in-sync.
    </para>
+
+   <para>
+    Unfortunately, <application>pg_dumpall</> can only create plaintext
+    backups. However, it is currently the only way to backup the globals in your
+    cluster. So, a reasonable backup strategy to backup your globals and
+    produce a flexible backup of every database in the cluster would
+    look like this:
+<programlisting>
+pg_dumpall -g -Uusername --file=globals.sql;
+psql -AtU postgres
+     -c "SELECT datname FROM pg_database WHERE NOT datistemplate" \
+  | while read f;
+      do pg_dump -Upostgres --format=c --file=$f.sqlc $f;
+    done;
+</programlisting>
+   </para>
   </sect2>
 
   <sect2 id="backup-dump-large">
@@ -239,12 +321,21 @@ psql -f <replaceable class="parameter">infile</replaceable> postgres
     <title>Use compressed dumps.</title>
     <para>
      You can use your favorite compression program, for example
-     <application>gzip</application>:
+     <application>gzip</application> or <application>pigz</application>
+     (a parallel implementation of <application>gzip</application> for modern
+     multi-processor, multi-core machines):
 
 <programlisting>
 pg_dump <replaceable class="parameter">dbname</replaceable> | gzip &gt; <replaceable class="parameter">filename</replaceable>.gz
 </programlisting>
 
+     or:
+
+<programlisting>
+pg_dump <replaceable class="parameter">dbname</replaceable> | pigz &gt; <replaceable class="parameter">filename</replaceable>.gz
+</programlisting>
+
+
      Reload with:
 
 <programlisting>
@@ -254,7 +345,7 @@ gunzip -c <replaceable class="parameter">filename</replaceable>.gz | psql <repla
      or:
 
 <programlisting>
-cat <replaceable class="parameter">filename</replaceable>.gz | gunzip | psql <replaceable class="parameter">dbname</replaceable>
+pigz -dc <replaceable class="parameter">filename</replaceable>.gz | psql <replaceable class="parameter">dbname</replaceable>
 </programlisting>
     </para>
    </formalpara>

On 09/26/2013 12:15:25 PM, Ivan Lezhnjov IV wrote:

On Sep 3, 2013, at 6:56 AM, Karl O. Pinc <kop@meme.com> wrote:

On 07/31/2013 12:08:12 PM, Ivan Lezhnjov IV wrote:

Patch filename: backup.sgml-cmd-v003.patch

The third version of this patch takes into consideration feedback
received after original submission (it can be read starting from

this

message /messages/by-id/CA
+Tgmoaq-9D_mst113TdW=Ar8mpgBc+x6T61AzK3eMhww9gRcQ@mail.gmail.com)

Essentially, it addresses the points that were raised in community
feedback and offers better worded statements that avoid implying

that

some features are being deprecated when it isn't the case. We also
spent some more time polishing other details, like making

adjustments

to the tone of the text so that it sounds more like a manual, and
less
like a blog post. More importantly, this chapter now makes it

clear

that superuser privileges are not always required to perform a
successful backup because in practice as long as the role used to
make
a backup has sufficient read privileges on all of the objects a

user

is interested in it's going to work just fine. We also mention and
show examples of usage for pg_restore and pigz alongside with

gzip,

and probably something else too.

---

Cleaned up and clarified here and there.

The bit about OIDs being depreciated might properly belong in
a separate patch. The same might be said about adding mention of

pigz.

If you submit these as separate patch file attachments
they can always be applied in a single commit, but the reverse is
more work for the committer. (Regardless, I see no reason to
have separate commitfest entries or anything other than multiple
attachments to the email that finalizes our discussion.)

Hello,

took me a while to get here, but a lot has been going on...

No worries.

Okay, I'm new and I don't know why a single patch like this is more
work for a commiter? Just so I understand and know.

Different committers have different preferences but the general rule
is that it's work to split a patch into pieces if you don't like the
whole thing but it's easy to apply a bunch of small patches and
commit them all at once. Further each commit should represent
a single "feature" or conceptual change. Again, preferences vary
but I like to think that a good rule is that 1 commit should
be able to be described in a sentence, and not a run-on sentence
either that says I did this and I also did that and something else.
So if there's a question in your mind about whether a committer
will want your entire change, or if your patch changes unrelated
things then it does not hurt to submit it as separate patches.
All the patches can be attached to a single email and part of
a single commitfest tracking entry, usually. No need to get
crazy. These are just things to think about.

In your case I see 3 things happening:

oid depreciation

custom format explanation

pigz promotion

My thought is that the part beginning with "The options in detail
are:" should not describe all the possibilities for the --format
option, that being better left to the reference section. Likewise,
this being prose, it might be best to describe all the options
in-line, instead of presented as a list. I have left it as-is
for you to improve as seen fit.

Agreed, it probably looks better as a sentence.

Looks good.

I have frobbed your <programlisting> to adjust the indentation and
line-wrap style. I submit it here for consideration in case this
style is attractive. This is nothing but conceit. We should use

the

same style used elsewhere in the documentation.

Looks good to me.

I fixed the missing \ I messed up on last time
and slightly re-worded the previous sentence.

I've grep-ed through the sgml looking for multi-line shell scripts
and found only 1 (in sepgsql.sgm). I don't see a conflict with
the formatting/line-break convention used in the patch, although
it does differ slightly in indentation. I'm leaving the shell
script formatting in the patch as-is for the committer to judge.
(I like the way it looks but it is not a traditional style.)

I don't know that it's necessary to include pigz examples, because

it

sounds like pigz is a drop-in gzip replacement. I've left your
examples in, in case you feel they are necessary.

We do. We believe it can encourage more people to consider using it.
The way we see it, most people seem to be running mutlicore systems
these days, yet many simply are not aware of pigz.

Ok. It's your patch.

The existing text of the SQL Dump section could use some alteration

to

reduce redundancy and add clarity. I'm thinking specifically of
mention of pg_restore as being required to restore custom format
backups and of the default pg_dump output being not just "plain

text"

but being a collection of SQL commands. Yes, the latter is obvious
upon reflection, psql being what it is, but I think it would be
helpful to spell this out. Especially in the context of the

current

patch. There could well be other areas like this to be addressed.

I don't quite follow you here. I mean, I kinda understand what you
mean in general, but when I look at the text I fail to see what you
had in mind specifically.

Specifically, I was waving my hands about in a general fashion. ;-)

For example, pg_restore is mentioned only 3 times in section 24.1.
Each mention seems pretty essential to me. And the text flow is
pretty
natural.

Ok.

Also, about plain text format being a collection of SQL commands. The
very first paragraph of the section 24.1 reads "The idea behind this
dump method is to generate a text file with SQL commands that, when
fed back to the server, will recreate the database in the same state
as it was at the time of the dump. PostgreSQL provides the utility
program pg_dump for this purpose."

I have added/changed some text at the first use of "plain text"
to be more explicit. (Usually I would use <wordasword>
markup but the pg docs always seem to use <quote> instead,
which is fine so I've done that.)

I also removed some duplicate-ish text towards the end of the
section regards the nature of custom-format dumps in the
context of restoring same with pg_restore.

Thanks for a detailed response. I attached a patch file that builds
on
your corrections and introduces some of the edits discussed above.

Upon reflection it bothered me to have text in the dump section
talking about restore. I've moved this into the restore
section and tweaked the text leading into the paste.
This seems to work well but feel free to disagree.

I've one more thought; whether the business with
confusing --file with <filename> is really important enough
to be marked <important> and included
in-line. In general, too many of these
out of band comments detract from the flow of the document.
I've left the markup as-is, but you might consider changing
this into a <footnote>. (You'll need to move it into the
back of the preceding <para>.) The document currently contains very
few footnotes but this might be an appropriate case.
(I've not looked at the other footnotes to see what they
contain.)

I also see inconsistent use of the SQL term.
In some cases it's marked up with <acronym> and in
some cases not. I am ignoring the issue.

Attached is a patch for your review (applies against HEAD):
backup.sgml-cmd-v003_3.patch

If you like it
let me know and I'll get it sent to the committers
or if you want to make some more changes based on
comments above/break it into 3 patches/whatever
get those back to me.

Regards,

Karl <kop@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index ccb76d8..7e748b5 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -38,7 +38,7 @@
 pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable class="parameter">outfile</replaceable>
 </synopsis>
    As you see, <application>pg_dump</> writes its result to the
-   standard output. We will see below how this can be useful.
+   standard output.
   </para>
 
   <para>
@@ -47,8 +47,12 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
    that you can perform this backup procedure from any remote host that has
    access to the database. But remember that <application>pg_dump</>
    does not operate with special permissions. In particular, it must
-   have read access to all tables that you want to back up, so in
-   practice you almost always have to run it as a database superuser.
+   have read access to all tables that you want to back up. Whether
+   it is going to have proper access permissions is determined by
+   the privileges granted to the role used to connect to the database server.
+   Although a superuser role will always have the necessary permissions
+   as long as the role used has read access to tables, sequences, etc.
+   it need not to be a superuser role.
   </para>
 
   <para>
@@ -95,13 +99,38 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
 
   <important>
    <para>
-    If your database schema relies on OIDs (for instance, as foreign
-    keys) you must instruct <application>pg_dump</> to dump the OIDs
-    as well. To do this, use the <option>-o</option> command-line
-    option.
+    The use of OIDs on user objects is deprecated. If your database schema
+    relies on OIDs (for instance, as foreign keys) you must instruct
+    <application>pg_dump</> to dump the OIDs as well. To do this, use 
+    the <option>-o</option> command-line option.
    </para>
   </important>
 
+  <para>
+    The above example creates a <quote>plaintext</quote> backup -- a file that
+   contains SQL commands which, when executed, restore the database.  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:
+
+<synopsis>
+pg_dump -U <replaceable class="parameter">username</replaceable> --format=c --file=<replaceable class="parameter">mydatabase.sqlc</replaceable> <replaceable class="parameter">dbname</replaceable>
+</synopsis>
+   where  <replaceable class="parameter">-U</replaceable> instructs <application>pg_dump</> to connect as specified database user, 
+   <replaceable class="parameter">--format</replaceable> sets output file format 
+   as custom (other supported options are: directory, tar, plain text) and 
+   <replaceable class="parameter">--file</replaceable> specifies output file name.
+
+   The most interesting of these is 
+   <replaceable class="parameter">--format</replaceable>.  By default 
+   <application>pg_dump</> creates a plaintext backup.  You may be
+   better off creating a custom format backup, since the custom format is much
+   more flexible.
+  </para>
+
   <sect2 id="backup-dump-restore">
    <title>Restoring the Dump</title>
 
@@ -112,8 +141,8 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
 <synopsis>
 psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class="parameter">infile</replaceable>
 </synopsis>
-    where <replaceable class="parameter">infile</replaceable> is the
-    file output by the <application>pg_dump</> command. The database <replaceable
+    where <replaceable class="parameter">infile</replaceable> is a plaintext
+    backup output by the <application>pg_dump</> command. The database <replaceable
     class="parameter">dbname</replaceable> will not be created by this
     command, so you must create it yourself from <literal>template0</>
     before executing <application>psql</> (e.g., with
@@ -176,6 +205,46 @@ pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>h
    </important>
 
    <para>
+    The <application>psql</> command is a way, as shown above, to restore
+    plaintext backups.  To restore a custom format backup
+    the <application>pg_restore</> command must be used. It has options
+    similar to those of <application>pg_dump</>. A simple use
+    of <application>pg_restore</> to restore an entire backup is:
+<synopsis>
+pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">databasename</replaceable> <replaceable class="parameter">filename</replaceable>
+</synopsis>
+    Where <replaceable class="parameter">filename</replaceable> is the name of
+    the backup file.
+   </para>
+
+   <important>
+    <para>
+     Do not confuse <option>--file</> with <replaceable
+     class="parameter">filename</replaceable>. The
+     <option>--file</> option can be used when converting backups from one
+     form to another, the value of <option>--file</> specifying the name of
+     the output file.
+    </para>
+   </important>
+
+  <para>
+   Using the custom format you are able to restore single objects from a
+   backup. For example to restore only a specified index from a backup
+   file:
+<synopsis>
+pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">dbname</replaceable> --index=<replaceable class="parameter">indexname</replaceable>
+</synopsis>
+   To restore only a single function:
+<synopsis>
+pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">dbname</replaceable> --function=<replaceable class="parameter">functionname(args)</replaceable>
+</synopsis>
+   To restore only a single table:
+<synopsis>
+pg_restore -U <replaceable class="parameter">username</replaceable> --dbname=<replaceable class="parameter">dbname</replaceable> --table=<replaceable class="parameter">tablename</replaceable>
+</synopsis>
+  </para>
+
+   <para>
     After restoring a backup, it is wise to run <xref
     linkend="sql-analyze"> on each
     database so the query optimizer has useful statistics;
@@ -222,6 +291,21 @@ psql -f <replaceable class="parameter">infile</replaceable> postgres
     each database will be internally consistent, the snapshots of
     different databases might not be exactly in-sync.
    </para>
+
+   <para>
+    Unfortunately, <application>pg_dumpall</> can only create plaintext
+    backups. However, it is currently the only way to backup the globals in your
+    cluster. So, a reasonable backup strategy to backup your globals and
+    produce a flexible backup of every database in the cluster mig:
+<programlisting>
+pg_dumpall -g -Uusername --file=globals.sql;
+psql -AtU postgres \
+     -c "SELECT datname FROM pg_database WHERE NOT datistemplate" \
+  | while read f;
+      do pg_dump -Upostgres --format=c --file=$f.sqlc $f;
+    done;
+</programlisting>
+   </para>
   </sect2>
 
   <sect2 id="backup-dump-large">
@@ -239,12 +323,21 @@ psql -f <replaceable class="parameter">infile</replaceable> postgres
     <title>Use compressed dumps.</title>
     <para>
      You can use your favorite compression program, for example
-     <application>gzip</application>:
+     <application>gzip</application> or <application>pigz</application>
+     (a parallel implementation of <application>gzip</application> for modern
+     multi-processor, multi-core machines):
 
 <programlisting>
 pg_dump <replaceable class="parameter">dbname</replaceable> | gzip &gt; <replaceable class="parameter">filename</replaceable>.gz
 </programlisting>
 
+     or:
+
+<programlisting>
+pg_dump <replaceable class="parameter">dbname</replaceable> | pigz &gt; <replaceable class="parameter">filename</replaceable>.gz
+</programlisting>
+
+
      Reload with:
 
 <programlisting>
@@ -254,7 +347,7 @@ gunzip -c <replaceable class="parameter">filename</replaceable>.gz | psql <repla
      or:
 
 <programlisting>
-cat <replaceable class="parameter">filename</replaceable>.gz | gunzip | psql <replaceable class="parameter">dbname</replaceable>
+pigz -dc <replaceable class="parameter">filename</replaceable>.gz | psql <replaceable class="parameter">dbname</replaceable>
 </programlisting>
     </para>
    </formalpara>
@@ -293,8 +386,8 @@ cat <replaceable class="parameter">filename</replaceable>* | psql <replaceable c
 pg_dump -Fc <replaceable class="parameter">dbname</replaceable> &gt; <replaceable class="parameter">filename</replaceable>
 </programlisting>
 
-     A custom-format dump is not a script for <application>psql</>, but
-     instead must be restored with <application>pg_restore</>, for example:
+     A custom-format dump must be restored with <application>pg_restore</>,
+     for example:
 
 <programlisting>
 pg_restore -d <replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">filename</replaceable>

On Thu, Sep 26, 2013 at 1:15 PM, Ivan Lezhnjov IV
<iliv@commandprompt.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

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index ccb76d8..54681a0 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -47,8 +47,13 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
    that you can perform this backup procedure from any remote host that has
    access to the database. But remember that <application>pg_dump</>
    does not operate with special permissions. In particular, it must
-   have read access to all tables that you want to back up, so in
-   practice you almost always have to run it as a database superuser.
+   have read access to all tables that you want to back up, so in order
+   to back up the entire database you almost always have to run it as a
+   database superuser.  (If you do not sufficient privileges to back up the
+   entire database, you can still back up portions of the database to which
+   you do have access using options such as
+   <option>-n <replaceable>schema</replaceable></option>
+   or <option>-t <replaceable>table</replaceable></option>.)
   </para>
 
   <para>

Hi Robert,

On 09/27/2013 05:56:52 AM, Robert Haas wrote:

1. Attempting to encourage people to consider custom format dumps.

What's important is what you can do...

Your critique seems obvious in retrospect. Sorry you had
to step in here and do my job. The above point is particularly
salient. I will try to keep it in mind in the future.

Karl <kop@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Fri, Sep 27, 2013 at 9:49 AM, Karl O. Pinc <kop@meme.com> wrote:

Hi Robert,
On 09/27/2013 05:56:52 AM, Robert Haas wrote:

1. Attempting to encourage people to consider custom format dumps.

What's important is what you can do...

Your critique seems obvious in retrospect. Sorry you had
to step in here and do my job. The above point is particularly
salient. I will try to keep it in mind in the future.

Hey, your reviewing is much appreciated. I actually didn't notice
your reply before I sent mine; I started writing it yesterday
afternoon and finished this morning, so I wasn't intending to preempt
you in any way.

Thanks,

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 09/27/2013 03:56 AM, Robert Haas wrote:

On Thu, Sep 26, 2013 at 1:15 PM, Ivan Lezhnjov IV
<iliv@commandprompt.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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Nov 7, 2013 at 11:37 AM, Joshua D. Drake <jd@commandprompt.com> wrote:

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 don't think it's ridiculous, but you can certainly disagree.

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.

Should I go ahead and apply that portion, then?

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 11/08/2013 06:04 AM, Robert Haas wrote:

On Thu, Nov 7, 2013 at 11:37 AM, Joshua D. Drake <jd@commandprompt.com> wrote:

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 don't think it's ridiculous, but you can certainly disagree.

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.

Should I go ahead and apply that portion, then?

I am certainly not opposed.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Fri, Nov 8, 2013 at 1:33 PM, Joshua D. Drake <jd@commandprompt.com> wrote:

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.

Should I go ahead and apply that portion, then?

I am certainly not opposed.

OK, done.

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 11/08/2013 02:12:56 PM, Robert Haas wrote:

On Fri, Nov 8, 2013 at 1:33 PM, Joshua D. Drake
<jd@commandprompt.com>
wrote:

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.

Should I go ahead and apply that portion, then?

I am certainly not opposed.

OK, done.

So.... Joshusa/Ivan Do you want to send another
version of the patch with the committed changes
omitted for further review?

Karl <kop@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 11/08/2013 12:18 PM, Karl O. Pinc wrote:

On 11/08/2013 02:12:56 PM, Robert Haas wrote:

On Fri, Nov 8, 2013 at 1:33 PM, Joshua D. Drake
<jd@commandprompt.com>
wrote:

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.

Should I go ahead and apply that portion, then?

I am certainly not opposed.

OK, done.

So.... Joshusa/Ivan Do you want to send another
version of the patch with the committed changes
omitted for further review?

I have no problem having Ivan submit another patch, outside of the
multiple patch requirement. If you guys will accept a single patch file
with the agreed changes, then we are good.

Joshua D. Drake

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 11/08/2013 03:42:56 PM, Joshua D. Drake wrote:

On 11/08/2013 12:18 PM, Karl O. Pinc wrote:

On 11/08/2013 02:12:56 PM, Robert Haas wrote:

On Fri, Nov 8, 2013 at 1:33 PM, Joshua D. Drake
<jd@commandprompt.com>
wrote:

Should I go ahead and apply that portion, then?

I am certainly not opposed.

OK, done.

So.... Joshusa/Ivan Do you want to send another
version of the patch with the committed changes
omitted for further review?

I have no problem having Ivan submit another patch, outside of the
multiple patch requirement. If you guys will accept a single patch
file
with the agreed changes, then we are good.

I can't say what will be accepted and haven't really kept
track of what has been accepted. If there's more that
you want to patch then send that and we'll
work from there.

Karl <kop@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers