From 21eee213f0a169c4122549bd729d600edab4dac9 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Thu, 4 Apr 2019 21:21:48 +0200
Subject: [PATCH] docs: extend the pg_upgrade docs for cluster revert

Clarify in which situations the old cluster can be safely restarted
and when it cannot and need to be restored from backup.
---
 doc/src/sgml/ref/pgupgrade.sgml | 47 +++++++++++++++++++++++++++++------------
 1 file changed, 34 insertions(+), 13 deletions(-)

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index c896882dd1..598e86152c 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -686,24 +686,45 @@ psql --username=postgres --file=script.sql postgres
 
       <listitem>
        <para>
-        If you ran <command>pg_upgrade</command>
-        with <option>--link</option>, the data files are shared between the
-        old and new cluster. If you started the new cluster, the new
-        server has written to those shared files and it is unsafe to
-        use the old cluster.
+        If you ran <command>pg_upgrade</command> <emphasis>without</emphasis>
+        <option>--link</option>, the old cluster was not modified and you can
+        re-use it anytime.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        If you ran <command>pg_upgrade</command> <emphasis>without</emphasis>
-        <option>--link</option> or did not start the new server, the
-        old cluster was not modified except that, if linking
-        started, a <literal>.old</literal> suffix was appended to
-        <filename>$PGDATA/global/pg_control</filename>.  To reuse the old
-        cluster, possibly remove the <filename>.old</filename> suffix from
-        <filename>$PGDATA/global/pg_control</filename>; you can then restart the
-        old cluster.
+        If you ran <command>pg_upgrade</command> with <option>--link</option>,
+        the data files are shared between the old and new cluster.
+
+        <itemizedlist>
+         <listitem>
+          <para>
+           If you started the new cluster, the new server has written to those
+           shared files and it is unsafe to use the old cluster.  The old
+           cluster will need to be restored from backup in this case.
+          </para>
+         </listitem>
+
+         <listitem>
+          <para>
+           If you did <emphasis>not</emphasis> start the new server, the old
+           cluster was not modified except that, when linking started, a
+           <literal>.old</literal> suffix was appended to
+           <filename>$PGDATA/global/pg_control</filename>.  To reuse the old
+           cluster, remove the <filename>.old</filename> suffix from
+           <filename>$PGDATA/global/pg_control</filename>; you can then restart
+           the old cluster.
+          </para>
+         </listitem>
+
+         <listitem>
+          <para>
+           If <command>pg_upgrade</command> was aborted before linking started,
+           then the old cluster was not modified and can be restarted.
+          </para>
+         </listitem>
+        </itemizedlist>
        </para>
       </listitem>
      </itemizedlist>
-- 
2.14.1.145.gb3622a4ee