backup.sgml-cmd-v001.patch

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index c4215be..4db52fa 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -102,6 +102,43 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
    </para>
   </important>
 
+  <para>
+   However, the backup created from this method has limited usefulness. It
+   can be used to restore a single database in full. A more useful form of
+   <productname>PostgreSQL</> backup syntax looks like this:
+<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, --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
+   practice, the plaintext format is useful for very small databases with
+   a minimal number of objects but other than that, it should be avoided.
+   The custom format allows for a wealth of customizability.
+  </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>
+   If you wanted 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:
+<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>
 
@@ -176,6 +213,35 @@ 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:
+<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 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.
+    </para>
+   </important>
+
+   <para>
+    If you make the mistake of creating 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;
@@ -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 and should be considered deprecated. However, it is the only way
+    to backup the globals in your cluster. 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">