Re: Clarification to pg_upgrade docs on reverting to old cluster
Daniel Gustafsson <[email protected]>
| Newsgroups | gmane.comp.db.postgresql.devel.documentation |
|---|---|
| Message-ID | <ywhFn7QMoEFtC4Juck-QQ5i__Z6nxZGy5YwAirAmY0Bn55Mf0CEjAnnb3f2DHU5ARCAlFkry5w5FKEZgcnRebn8qAX3YDvOAURq-I_c4Ac8=@yesql.se> |
On Friday, April 5, 2019 2:26 PM, Magnus Hagander <[email protected]> wrote: > On Thu, Apr 4, 2019 at 11:14 PM Daniel Gustafsson <[email protected]> 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
pg_upgrade_revert_cluster-v2.patch
(application/octet-stream, 3.2 KB)
From 21eee213f0a169c4122549bd729d600edab4dac9 Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson <[email protected]> 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