Update pg_upgrade docs to mention its use in a less risk-warning way,

bmomjian · bmomjian · commit 49450f01eca3 · 2011-01-31T15:21:51.000-05:00
and update the pg_upgrade docs to mention its reliance on no changes to
the storage format (the later based on Robert Haas's patch).
diff --git a/doc/src/sgml/pgupgrade.sgml b/doc/src/sgml/pgupgrade.sgml
@@ -17,9 +17,19 @@
  </para>
 
  <para>
-  <application>pg_upgrade</> works because, though new features are
-  regularly added to PostgreSQL major releases, the internal data storage
-  format rarely changes.  <application>pg_upgrade</> does its best to
+  Major PostgreSQL releases regularly add new features that often
+  change the layout of the system tables, but the internal data storage
+  format rarely changes.  <application>pg_upgrade</> uses this fact
+  to perform rapid upgrades by creating new system tables and simply
+  reusing the old user data files.  If a future major release ever
+  changes the data storage format in a way that makes the old data
+  format unreadable, <application>pg_upgrade</> will not be usable
+  for such upgrades.  (The community will attempt to avoid such
+  situations.)
+ </para>
+
+ <para>
+  <application>pg_upgrade</> does its best to
   make sure the old and new clusters are binary-compatible, e.g.  by
   checking for compatible compile-time settings, including 32/64-bit
   binaries.  It is important that
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
@@ -1692,17 +1692,13 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
   </sect2>
 
   <sect2 id="upgrading-methods-other">
-   <title>Other data migration methods</title>
+   <title>Non-Dump Upgrade Methods</title>
 
    <para>
-    The <filename>contrib</> program
-    <link linkend="pgupgrade"><application>pg_upgrade</application></link>
-    allows an installation to be migrated in-place from one major
-    <productname>PostgreSQL</> version to the next.  Keep in mind that this
-    method does not provide any scope for running old and new versions
-    concurrently.  Also, <application>pg_upgrade</application> is much less
-    battle-tested than <application>pg_dump</application>, so having an
-    up-to-date backup is strongly recommended in case something goes wrong.
+    The <link linkend="pgupgrade">pg_upgrade</link> module allows an
+    installation to be migrated in-place from one major
+    <productname>PostgreSQL</> version to the next.  Upgrades can be
+    performed in minutes.
    </para>
 
    <para>
