Re: [PATCH] Doc: clarify that pg_upgrade statistics transfer works cross-version

two cents:

On Wed, Mar 25, 2026 at 9:21 AM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
>
> 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 upgrading
> > >
> > > Right.
> > >
> > > > *from* v18 or better. But your last sentence suggests that you'd rather
> > > > not add anything to the documentation that could dispel that misconception.
> > >
> > > So, we don't normally document cases where a limitation does not exist.

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/upgrading.html
> >
> > Minor releases never change the internal storage format and are always
> > 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 PostgreSQL
> > 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 – 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#f71f3dcd5fd88ee970f0b1ea0a779298
[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#1f6ae665591cb5e5371552761aa90615