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 c167cd9703f..261177c9031 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 504881d5294..4f59fd19c2b 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>
--
GitLab