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.
>
> 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" — so no changes needed there. The confusion
> seems specific to the major upgrade context.
>
> The attached patch adds a brief clarification to pgupgrade.sgml to address this.
>
> I tested pg_dump --statistics-only from PG18 against PG16 and PG14 —
> 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=postgres --file=script.sql postgres
all statistics, such as those created explicitly with
<xref linkend="sql-createstatistics"/>, custom statistics added by
an extension, or statistics collected by the cumulative statistics system.
+ Transferring optimizer statistics works regardless of the old cluster's
+ major version.
</para>
<para>
Yours,
Laurenz Albe
