Make pg_restore usage examples more useful: illustrate restoring into

both the same database name and a different one.

Author: tglsfdc

doc/src/sgml/ref/pg_restore.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.63 2006/10/14 23:07:22 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.64 2006/11/26 18:11:11 tgl Exp $ -->
 
 <refentry id="APP-PGRESTORE">
  <refmeta>
@@ -580,34 +580,54 @@ CREATE DATABASE foo WITH TEMPLATE template0;
   <title>Examples</title>
 
   <para>
-   To dump a database called <literal>mydb</> to a <filename>tar</filename>
-   file:
+   Assume we have dumped a database called <literal>mydb</> into a
+   custom-format dump file:
 
 <screen>
-<prompt>$</prompt> <userinput>pg_dump -Ft mydb &gt; db.tar</userinput>
+<prompt>$</prompt> <userinput>pg_dump -Fc mydb &gt; db.dump</userinput>
 </screen>
   </para>
 
   <para>
-   To reload this dump into an
-   existing database called <literal>newdb</>:
+   To drop the database and recreate it from the dump:
 
 <screen>
-<prompt>$</prompt> <userinput>pg_restore -d newdb db.tar</userinput>
+<prompt>$</prompt> <userinput>dropdb mydb</userinput>
+<prompt>$</prompt> <userinput>pg_restore -C -d postgres db.dump</userinput>
 </screen>
+
+   The database named in the <option>-d</> switch can be any database existing
+   in the cluster; <application>pg_restore</> only uses it to issue the
+   <command>CREATE DATABASE</> command for <literal>mydb</>.  With
+   <option>-C</>, data is always restored into the database name that appears
+   in the dump file.
+  </para>
+
+  <para>
+   To reload the dump into a new database called <literal>newdb</>:
+
+<screen>
+<prompt>$</prompt> <userinput>createdb -T template0 newdb</userinput>
+<prompt>$</prompt> <userinput>pg_restore -d newdb db.dump</userinput>
+</screen>
+
+   Notice we don't use <option>-C</>, and instead connect directly to the
+   database to be restored into.  Also note that we clone the new database
+   from <literal>template0</> not <literal>template1</>, to ensure it is
+   initially empty.
   </para>
 
   <para>
    To reorder database items, it is first necessary to dump the table of
    contents of the archive:
 <screen>
-<prompt>$</prompt> <userinput>pg_restore -l archive.file &gt; archive.list</userinput>
+<prompt>$</prompt> <userinput>pg_restore -l db.dump &gt; db.list</userinput>
 </screen>
    The listing file consists of a header and one line for each item, e.g.,
 <programlisting>
 ;
 ; Archive created at Fri Jul 28 22:28:36 2000
-;     dbname: birds
+;     dbname: mydb
 ;     TOC Entries: 74
 ;     Compression: 0
 ;     Dump Version: 1.4-0
@@ -645,7 +665,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    could be used as input to <application>pg_restore</application> and would only restore
    items 10 and 6, in that order:
 <screen>
-<prompt>$</prompt> <userinput>pg_restore -L archive.list archive.file</userinput>
+<prompt>$</prompt> <userinput>pg_restore -L db.list db.dump</userinput>
 </screen>
   </para>