docs: clarify pg_upgrade's recovery behavior

The previous paragraph trying to explain --check, --link, and no --link
modes and the various points of failure was too complex.  Instead, use
bullet lists and sublists.

Reported-by: Daniel Gustafsson

Discussion: https://postgr.es/m/qtqiv7hI87s_Xvz5ZXHCaH-1-_AZGpIDJowzlRjF3-AbCr3RhSNydM_JCuJ8DE4WZozrtxhIWmyYTbv0syKyfGB6cYMQitp9yN-NZMm-oAo=@yesql.se

Backpatch-through: 9.4
This commit is contained in:
Bruce Momjian 2019-04-17 18:01:02 -04:00
parent 1a75c1d0c5
commit 64bbe10399
1 changed files with 36 additions and 16 deletions

View File

@ -678,32 +678,52 @@ psql --username=postgres --file=script.sql postgres
<itemizedlist>
<listitem>
<para>
If you ran <command>pg_upgrade</command>
with <option>--check</option>, no modifications were made to the old
cluster and you can re-use it anytime.
If the <option>--check</option> option was used, the old cluster
was unmodified; it can be restarted.
</para>
</listitem>
<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 the <option>--link</option> option was <emphasis>not</emphasis>
used, the old cluster was unmodified; it can be restarted.
</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 the <option>--link</option> option was used, the data
files might be shared between the old and new cluster:
<itemizedlist>
<listitem>
<para>
If <command>pg_upgrade</command> aborted before linking started,
the old cluster was unmodified; it can be restarted.
</para>
</listitem>
<listitem>
<para>
If you did <emphasis>not</emphasis> start the new cluster, the old
cluster was unmodified 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 you did start the new cluster, it has written to 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>
</itemizedlist>
</para>
</listitem>
</itemizedlist>