Re: Clarification to pg_upgrade docs on reverting to old cluster
Bruce Momjian <[email protected]>
| Newsgroups | gmane.comp.db.postgresql.devel.documentation |
|---|---|
| Message-ID | <[email protected]> |
On Fri, Apr 5, 2019 at 02:23:22PM +0000, Daniel Gustafsson wrote: > On Friday, April 5, 2019 2:26 PM, Magnus Hagander <[email protected]> wrote: > but wouldn't it sound better with "in this case" than "at this point"? And > as a really small nitpick, restore from backup, rather than backups? > > > Agreed. > > > The third bulletpoint also seems quite complicated really. If we're > tweaking these, wouldn't it be better if we split that one in two -- one > for "if you ran it without --link", that should reallyi be listed above any > of the other options? > > > Looking at it closer I tend to agree, and updated the patch to split this up in > an attempt to make it a bit clearer for newcomers to pg_upgrade. How about the > attached version? I agree that current paragraph is terrible --- it is too dense and confusing. I liked your sub-bullets. I adjusted your patch to tighten the language, and reordered the entries to appear in the order the actions would be performed. Updated patch attached. -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription +
pg_upgrade.diff
(text/x-diff, 3 KB)
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index f6d423ee13..0c4b16d32c 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -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>