From: Bruce Momjian <bruce@momjian.us>
To: Daniel Gustafsson <daniel@yesql.se>
Cc: Magnus Hagander <magnus@hagander.net>
Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Subject: Re: Clarification to pg_upgrade docs on reverting to old cluster
Date: Thu, 11 Apr 2019 21:48:46 -0400
Message-ID: <20190412014846.w4vcdhnmitry4yep@momjian.us> (raw)
In-Reply-To: <ywhFn7QMoEFtC4Juck-QQ5i__Z6nxZGy5YwAirAmY0Bn55Mf0CEjAnnb3f2DHU5ARCAlFkry5w5FKEZgcnRebn8qAX3YDvOAURq-I_c4Ac8=@yesql.se>
References: <qtqiv7hI87s_Xvz5ZXHCaH-1-_AZGpIDJowzlRjF3-AbCr3RhSNydM_JCuJ8DE4WZozrtxhIWmyYTbv0syKyfGB6cYMQitp9yN-NZMm-oAo=@yesql.se>
<CABUevExh8f947ZP1a=Xki4M_EndakxbWuMOnDdVEH5BRMZC+DA@mail.gmail.com>
<ywhFn7QMoEFtC4Juck-QQ5i__Z6nxZGy5YwAirAmY0Bn55Mf0CEjAnnb3f2DHU5ARCAlFkry5w5FKEZgcnRebn8qAX3YDvOAURq-I_c4Ac8=@yesql.se>
On Fri, Apr 5, 2019 at 02:23:22PM +0000, Daniel Gustafsson wrote:
> On Friday, April 5, 2019 2:26 PM, Magnus Hagander <magnus@hagander.net> 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 <bruce@momjian.us> 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 +
Attachments:pg_upgrade.diff (text/x-diff, 3.0K) downloaddiff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgmlindex 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>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: bruce@momjian.us, daniel@yesql.se, magnus@hagander.net, pgsql-docs@lists.postgresql.org
Subject: Re: Clarification to pg_upgrade docs on reverting to old cluster
In-Reply-To: <20190412014846.w4vcdhnmitry4yep@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox