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

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
index c167cd9703fdd5b370aebfceebf84a4bb448fcc7..261177c90312e0c6217027df8e5e9809cb1f1e92 100644 (file)
--- 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
index 504881d52949ae4b3f5ea33de79ce0ae1e1b6f32..4f59fd19c2b2e2994de40d0ef7ac9bdd183be8e7 100644 (file)
--- 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>