Message-ID: <1a7d3c03e6169e6340f9d77667433fd0cc5f5897.camel@cybertec.at>
Subject: Re: [PATCH] Doc: clarify that pg_upgrade statistics transfer works
 cross-version
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: nik@postgres.ai, pgsql-docs@lists.postgresql.org
Date: Tue, 24 Mar 2026 07:59:10 +0100
In-Reply-To: 
 <CAM527d_Qt9ZGt99vgTaidfObRiDH0R5F_uEfum9zHeZbc+LwCQ@mail.gmail.com>
References: 
	<CAM527d_Qt9ZGt99vgTaidfObRiDH0R5F_uEfum9zHeZbc+LwCQ@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.58.3 (3.58.3-1.fc43) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/1a7d3c03e6169e6340f9d77667433fd0cc5f5897.camel%40cybertec.at>
Precedence: bulk

On Mon, 2026-03-23 at 22:30 -0500, nik@postgres.ai wrote:
> I initially assumed that PG18's statistics transfer during pg_upgrade
> would only work when upgrading from PG18 to a future version. I hear
> this misconception from others fairly often too.
>=20
> In reality, it works when upgrading *to* PG18 from any older supported
> version (PG14, 15, 16, 17), because pg_upgrade uses the new cluster's
> pg_dump, which reads from standard catalog views (pg_class and
> pg_stats) that exist in all PostgreSQL versions. The pg_dump docs
> already note that "pg_dump can also dump from PostgreSQL servers older
> than its own version" =E2=80=94 so no changes needed there. The confusion
> seems specific to the major upgrade context.
>=20
> The attached patch adds a brief clarification to pgupgrade.sgml to addres=
s this.
>=20
> I tested pg_dump --statistics-only from PG18 against PG16 and PG14 =E2=80=
=94
> both work as expected, stats are transferred and restored correctly.

I agree that it would be a good idea to explicitly mention that
statistics are transferred when upgrading from older PostgreSQL
versions.  However, I think that your patch offers too much detail,
like from which relations the statistics are extracted.  Anybody
who wants to know that level of detail probably has to read the
source code anyway.

How about adding a simple remark, like

--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -837,6 +837,8 @@ psql --username=3Dpostgres --file=3Dscript.sql postgres
      all statistics, such as those created explicitly with
      <xref linkend=3D"sql-createstatistics"/>, custom statistics added by
      an extension, or statistics collected by the cumulative statistics sy=
stem.
+     Transferring optimizer statistics works regardless of the old cluster=
's
+     major version.
     </para>
=20
     <para>

Yours,
Laurenz Albe