MIME-Version: 1.0
References: 
 <CAM527d_Qt9ZGt99vgTaidfObRiDH0R5F_uEfum9zHeZbc+LwCQ@mail.gmail.com>
 <1a7d3c03e6169e6340f9d77667433fd0cc5f5897.camel@cybertec.at>
 <CAM527d89GmcMV5GD2PXS-a3ay3YE-HVSwV4NT0_o2ySf_5v8Kw@mail.gmail.com>
 <acKoBql5eQWpQH4N@momjian.us>
 <48ad7007c0bbca725847473fe410cdda5753c65d.camel@cybertec.at>
 <acLT6tXlMxgQRsT6@momjian.us>
 <c947af51d2ea8bc12985450fb7cfdb6d9679b578.camel@cybertec.at>
 <acQLbAQntxQzfhtP@momjian.us>
In-Reply-To: <acQLbAQntxQzfhtP@momjian.us>
From: Nikolay Samokhvalov <nik@postgres.ai>
Date: Wed, 25 Mar 2026 18:13:23 -0700
Message-ID: 
 <CAM527d9Qev=xKQHmp-9rMhhn65zw0g6hsJz-HHgLkbaScvqwDQ@mail.gmail.com>
Subject: Re: [PATCH] Doc: clarify that pg_upgrade statistics transfer works
 cross-version
To: Bruce Momjian <bruce@momjian.us>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>, pgsql-docs@lists.postgresql.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: 
 <https://www.postgresql.org/message-id/CAM527d9Qev%3DxKQHmp-9rMhhn65zw0g6hsJz-HHgLkbaScvqwDQ%40mail.gmail.com>
Precedence: bulk

two cents:

On Wed, Mar 25, 2026 at 9:21=E2=80=AFAM Bruce Momjian <bruce@momjian.us> wr=
ote:
>
> On Wed, Mar 25, 2026 at 07:03:01AM +0100, Laurenz Albe wrote:
> > On Tue, 2026-03-24 at 14:11 -0400, Bruce Momjian wrote:
> > > On Tue, Mar 24, 2026 at 05:53:27PM +0100, Laurenz Albe wrote:
> > > > Bruce, you are confusing me.  Your first sentence suggests that you
> > > > (erroneously) thought that upgrading statistics only works when upg=
rading
> > >
> > > Right.
> > >
> > > > *from* v18 or better.  But your last sentence suggests that you'd r=
ather
> > > > not add anything to the documentation that could dispel that miscon=
ception.
> > >
> > > So, we don't normally document cases where a limitation does not exis=
t.

I see it rather as an undocumented feature, not an undocumented
"limitation that doesn't exist".

> > > I think the logical place to document this is in the PG 18 release
> > > notes.  I am still confused why people, like myself, got this wrong.
> > > What is the source of the confusion?  Just unclear release notes?
> >
> > I understand now, thanks.  I agree with you in principle, but I wouldn'=
t
> > see that as a hard rule that should stand in the way of clarity.
> >
> > Let me quote a precedent from https://www.postgresql.org/docs/current/u=
pgrading.html
> >
> >   Minor releases never change the internal storage format and are alway=
s
> >   compatible with earlier and later minor releases of the same major
> >   version number. For example, version 10.1 is compatible with version =
10.0
> >   and version 10.6.
> >
> > To me, that clarifies that there is no limitation to performing minor
> > updates with a simple restart.  I think that is useful information.
>
> Right.
>
> > Perhaps you'd feel better if we phrase it as a limitation:
> >
> >   Transferring optimizer statistics only work when upgrading to Postgre=
SQL
> >   version v18 or later, but there is no such limitation to the version =
of
> >   the old cluster.
> >
> > I like my original suggestion better, though.
>
> Uh, we added the feature in PG 18, so why would we say it only works in
> PG 18 --- that is kind of obvious.  I am still asking, why did people,
> like me, think it only worked for _old_ PG 18 servers. If we find where
> that was communicated, we can clarify it _there_.

If you don't know anything about implementation, it is natural to
expect that something new will work only when both old and new
clusters support it. That's why I started with words that I see
everyone (includfing both of us) were originally confused. I bumped
into it in some blog posts and LinkedIn discussions after which
decided to clarify [1] since I couldn't find clarification anywhere on
surface =E2=80=93 only in source code, diving into implementation, and the
depth of discussions [2] [3] [4].

It would be great to get it covered in the 2nd (after source code)
source of truth-- the docs.

[1] https://postgres.ai/blog/20260324-pg18-stats-upgrade-across-versions
[2] https://www.postgresql.org/message-id/flat/aC5F1LX6-uL0wRV1%40nathan#f7=
1f3dcd5fd88ee970f0b1ea0a779298
[3] https://www.postgresql.org/message-id/flat/1322262.1741643606%40sss.pgh=
.pa.us#d666e5e99bbd955a4f258338b44389da
[4] https://www.postgresql.org/message-id/flat/Z_BcWVMvlUIJ_iuZ%40nathan#1f=
6ae665591cb5e5371552761aa90615