From 49450f01eca39308989cf668f60b7c345e72fc7b Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Mon, 31 Jan 2011 15:21:51 -0500
Subject: [PATCH] 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).

---
 doc/src/sgml/pgupgrade.sgml | 16 +++++++++++++---
 doc/src/sgml/runtime.sgml   | 14 +++++---------
 2 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/doc/src/sgml/pgupgrade.sgml b/doc/src/sgml/pgupgrade.sgml
index c167cd9703..261177c903 100644
--- 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 504881d529..4f59fd19c2 100644
--- 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>
-- 
2.40.0