pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedClarification to pg_upgrade docs on reverting to old cluster
7+ messages / 4 participants
[nested] [flat]
Commits from this thread:
2019-04-17 dfdab98cde 39a93fd294 64bbe10399 83be50d9a9 58507a83c8 8b947ab430 docs: clarify pg_upgrade's recovery behavior
* Clarification to pg_upgrade docs on reverting to old cluster
@ 2019-04-04 21:13 Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 7+ messages in thread
From: Daniel Gustafsson @ 2019-04-04 21:13 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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
Attachments:
pg_upgrade_revert_cluster.patch (application/octet-stream, 1.1K) download
From 1152e387399355e4df7ccb582adda51ccd594d69 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
Add a small clarification to the pg_upgrade documentation regarding
reverting to the old cluster.
---
doc/src/sgml/ref/pgupgrade.sgml | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index c896882dd1..655802f8d6 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -690,7 +690,8 @@ psql --username=postgres --file=script.sql postgres
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.
+ use the old cluster. The old cluster will need to be restored from
+ backups at this point.
</para>
</listitem>
--
2.14.1.145.gb3622a4ee
* Re: Clarification to pg_upgrade docs on reverting to old cluster
@ 2019-04-05 12:26 Magnus Hagander <magnus@hagander.net>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 2 replies; 7+ messages in thread
From: Magnus Hagander @ 2019-04-05 12:26 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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?
--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/;
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Clarification to pg_upgrade docs on reverting to old cluster
@ 2019-04-05 14:15 Jonathan S. Katz <jkatz@postgresql.org>
parent: Magnus Hagander <magnus@hagander.net>
1 sibling, 0 replies; 7+ messages in thread
From: Jonathan S. Katz @ 2019-04-05 14:15 UTC (permalink / raw)
To: Magnus Hagander <magnus@hagander.net>; Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Clarification to pg_upgrade docs on reverting to old cluster
@ 2019-04-05 14:23 Daniel Gustafsson <daniel@yesql.se>
parent: Magnus Hagander <magnus@hagander.net>
1 sibling, 1 reply; 7+ messages in thread
From: Daniel Gustafsson @ 2019-04-05 14:23 UTC (permalink / raw)
To: Magnus Hagander <magnus@hagander.net>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Friday, April 5, 2019 2:26 PM, Magnus Hagander <magnus@hagander.net> wrote:
> 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 :),
What could possibly go wrong =)
> 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?
cheers ./daniel
Attachments:
pg_upgrade_revert_cluster-v2.patch (application/octet-stream, 3.2K) download
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
* Re: Clarification to pg_upgrade docs on reverting to old cluster
@ 2019-04-12 01:48 Bruce Momjian <bruce@momjian.us>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2019-04-12 01:48 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Magnus Hagander <magnus@hagander.net>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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) download
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>
* Re: Clarification to pg_upgrade docs on reverting to old cluster
@ 2019-04-12 06:53 Daniel Gustafsson <daniel@yesql.se>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: Daniel Gustafsson @ 2019-04-12 06:53 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Magnus Hagander <magnus@hagander.net>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Clarification to pg_upgrade docs on reverting to old cluster
@ 2019-04-17 22:01 Bruce Momjian <bruce@momjian.us>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 0 replies; 7+ messages in thread
From: Bruce Momjian @ 2019-04-17 22:01 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Magnus Hagander <magnus@hagander.net>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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 +
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2019-04-17 22:01 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-04-04 21:13 Clarification to pg_upgrade docs on reverting to old cluster Daniel Gustafsson <daniel@yesql.se>
2019-04-05 12:26 ` Magnus Hagander <magnus@hagander.net>
2019-04-05 14:15 ` Jonathan S. Katz <jkatz@postgresql.org>
2019-04-05 14:23 ` Daniel Gustafsson <daniel@yesql.se>
2019-04-12 01:48 ` Bruce Momjian <bruce@momjian.us>
2019-04-12 06:53 ` Daniel Gustafsson <daniel@yesql.se>
2019-04-17 22:01 ` Bruce Momjian <bruce@momjian.us>
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