From: nik@postgres.ai
MIME-Version: 1.0
Date: Mon, 23 Mar 2026 22:30:57 -0500
Message-ID: 
 <CAM527d_Qt9ZGt99vgTaidfObRiDH0R5F_uEfum9zHeZbc+LwCQ@mail.gmail.com>
Subject: [PATCH] Doc: clarify that pg_upgrade statistics transfer works
 cross-version
To: pgsql-docs@lists.postgresql.org
Content-Type: multipart/mixed; boundary="000000000000a17cd6064dbcc70c"
Archived-At: 
 <https://www.postgresql.org/message-id/CAM527d_Qt9ZGt99vgTaidfObRiDH0R5F_uEfum9zHeZbc%2BLwCQ%40mail.gmail.com>
Precedence: bulk

--000000000000a17cd6064dbcc70c
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

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" =E2=80=94 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 =E2=80=
=94
both work as expected, stats are transferred and restored correctly.

--
Nik

--000000000000a17cd6064dbcc70c
Content-Type: text/x-patch; charset="utf-8";
 name="pg-stats-cross-version.patch"
Content-Disposition: attachment; filename="pg-stats-cross-version.patch"
Content-Transfer-Encoding: base64
X-Attachment-Id: 523647afed55a108_0.1

RnJvbSAzMzljZTc3Y2FjOTI3ZTQ2MzMyNDI3NmE2NjkxOTYyYzFkZTg1MmQ2IE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiBOaWtvbGF5IFNhbW9raHZhbG92IDxuaWtAcG9zdGdyZXMuYWk+
CkRhdGU6IFR1ZSwgMjQgTWFyIDIwMjYgMDM6MjY6MjQgKzAwMDAKU3ViamVjdDogW1BBVENIXSBE
b2M6IGNsYXJpZnkgdGhhdCBwZ191cGdyYWRlIHN0YXRpc3RpY3MgdHJhbnNmZXIgd29ya3MKIGNy
b3NzLXZlcnNpb24uCgpDbGFyaWZ5IGluIHBndXBncmFkZS5zZ21sIHRoYXQgb3B0aW1pemVyIHN0
YXRpc3RpY3MgdHJhbnNmZXIgd29ya3MKcmVnYXJkbGVzcyBvZiB0aGUgb2xkIGNsdXN0ZXIncyBt
YWpvciB2ZXJzaW9uLiAgVGhlIG5ldyBjbHVzdGVyJ3MKcGdfZHVtcCByZWFkcyBzdGF0aXN0aWNz
IGZyb20gc3RhbmRhcmQgY2F0YWxvZyB2aWV3cyAocGdfY2xhc3MgYW5kCnBnX3N0YXRzKSBpbiB0
aGUgb2xkIGNsdXN0ZXIsIHdoaWNoIGV4aXN0IGluIGFsbCBzdXBwb3J0ZWQgUG9zdGdyZVNRTAp2
ZXJzaW9ucy4gIFRoZSByZXN0b3JlIGZ1bmN0aW9ucyAocGdfcmVzdG9yZV9yZWxhdGlvbl9zdGF0
cyBhbmQKcGdfcmVzdG9yZV9hdHRyaWJ1dGVfc3RhdHMpIG9ubHkgbmVlZCB0byBleGlzdCBvbiB0
aGUgdGFyZ2V0IGNsdXN0ZXIuCgpUZXN0ZWQgd2l0aCBQRzE0LT5QRzE4IGFuZCBQRzE2LT5QRzE4
LgotLS0KIGRvYy9zcmMvc2dtbC9yZWYvcGd1cGdyYWRlLnNnbWwgfCAxMyArKysrKysrKystLS0t
CiAxIGZpbGUgY2hhbmdlZCwgOSBpbnNlcnRpb25zKCspLCA0IGRlbGV0aW9ucygtKQoKZGlmZiAt
LWdpdCBhL2RvYy9zcmMvc2dtbC9yZWYvcGd1cGdyYWRlLnNnbWwgYi9kb2Mvc3JjL3NnbWwvcmVm
L3BndXBncmFkZS5zZ21sCmluZGV4IDM4Y2EwOWIuLmQ1NTI5MDcgMTAwNjQ0Ci0tLSBhL2RvYy9z
cmMvc2dtbC9yZWYvcGd1cGdyYWRlLnNnbWwKKysrIGIvZG9jL3NyYy9zZ21sL3JlZi9wZ3VwZ3Jh
ZGUuc2dtbApAQCAtODMzLDEwICs4MzMsMTUgQEAgcHNxbCAtLXVzZXJuYW1lPXBvc3RncmVzIC0t
ZmlsZT1zY3JpcHQuc3FsIHBvc3RncmVzCiAgICAgPHBhcmE+CiAgICAgIFVubGVzcyB0aGUgPG9w
dGlvbj4tLW5vLXN0YXRpc3RpY3M8L29wdGlvbj4gb3B0aW9uIGlzIHNwZWNpZmllZCwKICAgICAg
PGNvbW1hbmQ+cGdfdXBncmFkZTwvY29tbWFuZD4gd2lsbCB0cmFuc2ZlciBtb3N0IG9wdGltaXpl
ciBzdGF0aXN0aWNzCi0gICAgIGZyb20gdGhlIG9sZCBjbHVzdGVyIHRvIHRoZSBuZXcgY2x1c3Rl
ci4gIFRoaXMgZG9lcyBub3QgdHJhbnNmZXIKLSAgICAgYWxsIHN0YXRpc3RpY3MsIHN1Y2ggYXMg
dGhvc2UgY3JlYXRlZCBleHBsaWNpdGx5IHdpdGgKLSAgICAgPHhyZWYgbGlua2VuZD0ic3FsLWNy
ZWF0ZXN0YXRpc3RpY3MiLz4sIGN1c3RvbSBzdGF0aXN0aWNzIGFkZGVkIGJ5Ci0gICAgIGFuIGV4
dGVuc2lvbiwgb3Igc3RhdGlzdGljcyBjb2xsZWN0ZWQgYnkgdGhlIGN1bXVsYXRpdmUgc3RhdGlz
dGljcyBzeXN0ZW0uCisgICAgIGZyb20gdGhlIG9sZCBjbHVzdGVyIHRvIHRoZSBuZXcgY2x1c3Rl
ci4gIFRoaXMgd29ya3MgcmVnYXJkbGVzcyBvZgorICAgICB0aGUgb2xkIGNsdXN0ZXIncyBtYWpv
ciB2ZXJzaW9uLCBiZWNhdXNlIHRoZSBuZXcgY2x1c3RlcidzCisgICAgIDxjb21tYW5kPnBnX2R1
bXA8L2NvbW1hbmQ+IHJlYWRzIHN0YXRpc3RpY3MgZnJvbSBzdGFuZGFyZCBjYXRhbG9nIHZpZXdz
CisgICAgICg8c3RydWN0bmFtZT5wZ19jbGFzczwvc3RydWN0bmFtZT4gYW5kIDxzdHJ1Y3RuYW1l
PnBnX3N0YXRzPC9zdHJ1Y3RuYW1lPikKKyAgICAgdGhhdCBleGlzdCBpbiBhbGwgc3VwcG9ydGVk
IDxwcm9kdWN0bmFtZT5Qb3N0Z3JlU1FMPC9wcm9kdWN0bmFtZT4KKyAgICAgdmVyc2lvbnMuICBI
b3dldmVyLCBzb21lIHN0YXRpc3RpY3MgYXJlIG5vdCB0cmFuc2ZlcnJlZDogdGhvc2UgY3JlYXRl
ZAorICAgICB3aXRoIDx4cmVmIGxpbmtlbmQ9InNxbC1jcmVhdGVzdGF0aXN0aWNzIi8+LCBjdXN0
b20gc3RhdGlzdGljcyBhZGRlZCBieQorICAgICBhbiBleHRlbnNpb24sIGFuZCBzdGF0aXN0aWNz
IGNvbGxlY3RlZCBieSB0aGUgY3VtdWxhdGl2ZSBzdGF0aXN0aWNzCisgICAgIHN5c3RlbS4KICAg
ICA8L3BhcmE+CiAKICAgICA8cGFyYT4KLS0gCjIuNDMuMAoK
--000000000000a17cd6064dbcc70c--