public inbox for [email protected]
help / color / mirror / Atom feedFrom: [email protected]
To: [email protected]
Subject: [PATCH] Doc: clarify that pg_upgrade statistics transfer works cross-version
Date: Mon, 23 Mar 2026 22:30:57 -0500
Message-ID: <CAM527d_Qt9ZGt99vgTaidfObRiDH0R5F_uEfum9zHeZbc+LwCQ@mail.gmail.com> (raw)
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
Attachments:
[text/x-patch] pg-stats-cross-version.patch (2.1K, ../CAM527d_Qt9ZGt99vgTaidfObRiDH0R5F_uEfum9zHeZbc+LwCQ@mail.gmail.com/2-pg-stats-cross-version.patch)
download | inline diff:
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
view thread (10+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected]
Subject: Re: [PATCH] Doc: clarify that pg_upgrade statistics transfer works cross-version
In-Reply-To: <CAM527d_Qt9ZGt99vgTaidfObRiDH0R5F_uEfum9zHeZbc+LwCQ@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox