Subject: pg_upgrade docs are confusing if PostgreSQL's versioning system/language isn't known to reader

From: PG Doc comments form <[email-masked]>
Date: Mon, 18 Dec 2017 21:30:41 +0000

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.6/static/pgupgrade.html
Description:

If a reader who is unfamiliar with PostgreSQL&#39;s versioning (where 9.5 and
9.6 are considered major versions) reads the documentation, it is unclear if
they need to use pg_upgrade to migrate from 9.5 to 9.6, for example.

The documentation says upgrading &quot;from 9.6.3 to the current major release&quot;
requires pg_upgrade, but not &quot;from 9.6.2 to 9.6.3&quot;. 

The problem with that language is that the current release of PostgreSQL is
10.  So is pg_upgrade required to upgrade from 9.6.3 to current (10) because
9 and 10 are major versions or because 9.6 and 10.0 are major versions? (the
latter).

It would be clearer if the documentation covered all three cases:
9.6.3 -&gt; 10.0.0 and 9.5.1 -&gt; 9.6.3: pg_upgrade should be used
9.6.2 -&gt; 9.6.3: pg_upgrade not needed

Or if the documentation simply noted that the second decimal is considered a
major release.

Thanks for PostgreSQL! 

Jim

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 25 Jan 2018 19:26:18 -0500

> Or if the documentation simply noted that the second decimal is considered a

How is this attached patch?

-- 
  Bruce Momjian  <[email-masked]>        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 +
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
new file mode 100644
index 055eac3..ed34a64
*** a/doc/src/sgml/ref/pgupgrade.sgml
--- b/doc/src/sgml/ref/pgupgrade.sgml
***************
*** 40,46 ****
    major version without the data dump/reload typically required for
    major version upgrades, e.g. from 9.6.3 to the current major release
    of <productname>PostgreSQL</productname>.  It is not required for minor version upgrades, e.g. from
!   9.6.2 to 9.6.3.
   </para>
  
   <para>
--- 40,46 ----
    major version without the data dump/reload typically required for
    major version upgrades, e.g. from 9.6.3 to the current major release
    of <productname>PostgreSQL</productname>.  It is not required for minor version upgrades, e.g. from
!   9.6.2 to 9.6.3 or from 10.1 to 10.2.
   </para>
  
   <para>

---

From: Jim Ryan <[email-masked]>
Date: Fri, 26 Jan 2018 12:04:17 -0500

Hey Bruce,

Thanks for working on this, but wouldn't pg_upgrade be needed from 10.1 to
10.2?  Aren't those considered major versions, or am I misunderstanding?

The source of my (and potentially others) confusion is if from 9.1 to 9.2
is considered a major version change or not.  I think most users would
assume from 9.x to 10.x is a major version change.  The ambiguity is in 9.x
to 9.y.

Thanks,
Jim

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 26 Jan 2018 12:21:02 -0500

> 10.2?  Aren't those considered major versions, or am I misunderstanding?

Uh, it is confusing.  We switched in PG 10 from changing the _third_
number for a minor release to changing the second number.  The next
major release of Postgres will be PG 11.

> The source of my (and potentially others) confusion is if from 9.1 to 9.2 is
> considered a major version change or not.  I think most users would assume from
> 9.x to 10.x is a major version change.  The ambiguity is in 9.x to 9.y.  

Does the patch make sense now?

---------------------------------------------------------------------------

---

From: Jim Ryan <[email-masked]>
Date: Fri, 26 Jan 2018 12:26:44 -0500

Ah! Thank you.  That makes more sense.  I think this could still be
confusing for users who did not know about this change and are on 9.x,
because the docs now seemingly imply that they would not need to use
pg_upgrade when moving from 9.x to 9.y, when they actually do.  Is
explaining the recent versioning change outside the scope of these docs?
If so, then perhaps a link to the versioning policy would work?

Jim

On Fri, Jan 26, 2018 at 12:21 PM, Bruce Momjian <[email-masked]> wrote:

> >     > If a reader who is unfamiliar with PostgreSQL&#39;s versioning
> (where 9.5
> >     and
> >     > 9.6 are considered major versions) reads the documentation, it is
> unclear
> >     if
> >     > The documentation says upgrading &quot;from 9.6.3 to the current
> major
> >     release&quot;
> >     > The problem with that language is that the current release of
> PostgreSQL
> >     is
> >     > 10.  So is pg_upgrade required to upgrade from 9.6.3 to current
> (10)
> >     because
> >     > 9 and 10 are major versions or because 9.6 and 10.0 are major
> versions?
> >     (the
> >     > latter).
> >     >

---

From: "David G. Johnston" <[email-masked]>
Date: Fri, 26 Jan 2018 11:35:09 -0700

> assume from 9.x to 10.x is a major version change.  The ambiguity is in 9.x
Which is why we changed ;)

Starting with 10 the one and only value after the decimal is a minor
version bug fix release.  The next major version will be 11.

Of versions beginning with 9 there were 7 major versions - 9.0 to 9.6; the
third position value denoted the minor bug fix release.

pg-upgrade is only required for upgrading between major versions.

On our homeoage we list every major release that is currently supported.

David J.

---

From: Bruce Momjian <[email-masked]>
Date: Sat, 27 Jan 2018 10:05:43 -0500

On Fri, Jan 26, 2018 at 11:35:09AM -0700, David G. Johnston wrote:
> Starting with 10 the one and only value after the decimal is a minor version
> bug fix release.  The next major version will be 11.
> 

I decided I needed to be more explicit about the major version numbers
so I have added major and minor examples for the 9.6.x series and 10.x
series releases.  Patch attached.

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
new file mode 100644
index 055eac3..cf4550b
*** a/doc/src/sgml/ref/pgupgrade.sgml
--- b/doc/src/sgml/ref/pgupgrade.sgml
***************
*** 38,46 ****
    <application>pg_upgrade</application> (formerly called <application>pg_migrator</application>) allows data
    stored in <productname>PostgreSQL</productname> data files to be upgraded to a later <productname>PostgreSQL</productname>
    major version without the data dump/reload typically required for
!   major version upgrades, e.g. from 9.6.3 to the current major release
!   of <productname>PostgreSQL</productname>.  It is not required for minor version upgrades, e.g. from
!   9.6.2 to 9.6.3.
   </para>
  
   <para>
--- 38,46 ----
    <application>pg_upgrade</application> (formerly called <application>pg_migrator</application>) allows data
    stored in <productname>PostgreSQL</productname> data files to be upgraded to a later <productname>PostgreSQL</productname>
    major version without the data dump/reload typically required for
!   major version upgrades, e.g. from 9.5.8 to 9.6.4 or from 10.7 to 11.2.
!   It is not required for minor version upgrades, e.g. from 9.6.2 to 9.6.3
!   or from 10.1 to 10.2.
   </para>
  
   <para>

---

From: "David G. Johnston" <[email-masked]>
Date: Mon, 29 Jan 2018 18:16:50 -0700

> series releases.  Patch attached.
​Thanks!​

​+1

​David J.

---

From: Jim Ryan <[email-masked]>
Date: Mon, 29 Jan 2018 21:31:46 -0500

This looks great.  Thanks for working on it.

Jim

On Sat, Jan 27, 2018 at 10:05 AM, Bruce Momjian <[email-masked]> wrote:

> version

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 31 Jan 2018 17:10:15 -0500

> This looks great.  Thanks for working on it.

Done.