Hi hackers, 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. -- Nik
From 339ce77cac927e463324276a6691962c1de852d6 Mon Sep 17 00:00:00 2001 From: Nikolay Samokhvalov <[email protected]> Date: Tue, 24 Mar 2026 03:26:24 +0000 Subject: [PATCH] Doc: clarify that pg_upgrade statistics transfer works cross-version. Clarify in pgupgrade.sgml that optimizer statistics transfer works regardless of the old cluster's major version. The new cluster's pg_dump reads statistics from standard catalog views (pg_class and pg_stats) in the old cluster, which exist in all supported PostgreSQL versions. The restore functions (pg_restore_relation_stats and pg_restore_attribute_stats) only need to exist on the target cluster. Tested with PG14->PG18 and PG16->PG18. --- doc/src/sgml/ref/pgupgrade.sgml | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 38ca09b..d552907 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -833,10 +833,15 @@ psql --username=postgres --file=script.sql postgres <para> Unless the <option>--no-statistics</option> option is specified, <command>pg_upgrade</command> will transfer most optimizer statistics - from the old cluster to the new cluster. This does not transfer - 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. + from the old cluster to the new cluster. This works regardless of + the old cluster's major version, because the new cluster's + <command>pg_dump</command> reads statistics from standard catalog views + (<structname>pg_class</structname> and <structname>pg_stats</structname>) + that exist in all supported <productname>PostgreSQL</productname> + versions. However, some statistics are not transferred: those created + with <xref linkend="sql-createstatistics"/>, custom statistics added by + an extension, and statistics collected by the cumulative statistics + system. </para> <para> -- 2.43.0
