Обсуждение: Clarification to pg_upgrade docs on reverting to old cluster

Reading the pg_upgrade reference page, I get the feeling that one of the
bullets under "Reverting to old cluster" is a bit thin on detail to be helpful
to newcomers:

    "If you ran pg_upgrade with --link, 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."

This is perfectly correct, but it fails to provide information on what to do
next in case reverting is in fact what the user wants.  The attached patch adds
a short sentence saying the old cluster should be restored from backups at this
point.

cheers ./daniel

On 4/5/19 8:26 AM, Magnus Hagander wrote:
>
>
> On Thu, Apr 4, 2019 at 11:14 PM Daniel Gustafsson <daniel@yesql.se
> <mailto:daniel@yesql.se>> wrote:
>
>     Reading the pg_upgrade reference page, I get the feeling that one of the
>     bullets under "Reverting to old cluster" is a bit thin on detail to
>     be helpful
>     to newcomers:
>
>         "If you ran pg_upgrade with --link, 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."
>
>     This is perfectly correct, but it fails to provide information on
>     what to do
>     next in case reverting is in fact what the user wants.  The attached
>     patch adds
>     a short sentence saying the old cluster should be restored from
>     backups at this
>     point.
>
>
> Let's have two non-english natives discuss it :), 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?

I would go with:

"If you need to restore the old cluster, you will have to do so using
backups that you took prior to the upgrade."

Or if you want to be overly verbose:

"If you need to restore the old cluster, you will have to do so using
backups that you made prior to the upgrade as the --link does not create
a copy of the old cluster files."

Jonathan

On Thu, Apr 4, 2019 at 11:14 PM Daniel Gustafsson <daniel@yesql.se> wrote:

Reading the pg_upgrade reference page, I get the feeling that one of the

bullets under "Reverting to old cluster" is a bit thin on detail to be helpful

to newcomers:

    "If you ran pg_upgrade with --link, 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."

This is perfectly correct, but it fails to provide information on what to do

next in case reverting is in fact what the user wants.  The attached patch adds

a short sentence saying the old cluster should be restored from backups at this

point.

Let's have two non-english natives discuss it :),

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? 

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?

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 +

On Friday, April 12, 2019 3:48 AM, Bruce Momjian <bruce@momjian.us> wrote:

> 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.

The order of the bullets is much better in your patch, thanks!

cheers ./daniel

On Fri, Apr 12, 2019 at 06:53:14AM +0000, Daniel Gustafsson wrote:
> On Friday, April 12, 2019 3:48 AM, Bruce Momjian <bruce@momjian.us> wrote:
> 
> > 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.
> 
> The order of the bullets is much better in your patch, thanks!

Patch applied and backpatched through 9.4.  Thanks.

-- 
  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 +