Subject: BUG #19529: Documentation appears inconsistent with pg_dump --statistics behavior for CREATE STATISTICS objects

From: PG Bug reporting form <[email-masked]>
Date: Fri, 19 Jun 2026 07:17:44 +0000

The following bug has been logged on the website:

Bug reference:      19529
Logged by:          Igi Izumi
Email address:      [email-masked]
PostgreSQL version: 19beta1
Operating system:   Rocky Linux 10.2 x86_64
Description:        

The PostgreSQL 19 pg_dump documentation currently states:
"When --statistics is specified, pg_dump will include most optimizer
statistics in the resulting dump file. This does not include all statistics,
such as those created explicitly with CREATE STATISTICS, custom statistics
added by an extension, or statistics collected by the cumulative statistics
system. Therefore, it may still be useful to run ANALYZE after restoring
from a dump file to ensure optimal performance; see Section 24.1.3 and
Section 24.1.6 for more information."
https://www.postgresql.org/docs/19/app-pgdump.html

However, PostgreSQL 19 introduced support for restoring extended statistics
with pg_restore_extended_stats(), and the following commits appear to add
support for dumping and restoring CREATE STATISTICS data:

・Include extended statistics data in pg_dump
https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=c32fb29e9

・Add pg_restore_extended_stats()
https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=0e80f3f88

Because of these changes, it appears that statistics created explicitly with
CREATE STATISTICS are now handled by pg_dump --statistics, while the
PostgreSQL 19 documentation still states that they are not included.

Could you please confirm whether the documentation is correct, or whether
this is a documentation bug?

---

From: Fujii Masao <[email-masked]>
Date: Sun, 21 Jun 2026 00:55:34 +0900

> this is a documentation bug?

This looks like a documentation oversight in (maybe) the commit that
added extended statistics support to pg_dump.

I say that because I confirmed that pg_dump --statistics does dump
the extended statistics for table t after running:

    CREATE TABLE t (i int, j int);
    INSERT INTO t SELECT n, n FROM generate_series(1, 100) n;
    CREATE STATISTICS ON i, j FROM t;
    ANALYZE t;

Regards,

-- 
Fujii Masao

---

From: Michael Paquier <[email-masked]>
Date: Mon, 22 Jun 2026 16:50:34 +0900

> added extended statistics support to pg_dump.

This is a doc oversight.  While working on the support of extstats
for this release, I have looked at holes like this one in the docs,
and did not consider the pattern of a linkend based on
sql-createstatistics.

The report mentions pg_dump, but we have the same wrong pattern in the
doc pages for pg_dumpall and pg_upgrade, leading me to the attached
for these three holes.

Thoughts?
--
Michael
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index ae1bc14d2f26..0e0d53926af6 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1703,7 +1703,6 @@ CREATE DATABASE foo WITH TEMPLATE template0;
    When <option>--statistics</option> is specified,
    <command>pg_dump</command> will include most optimizer statistics in the
    resulting dump file.  This does not include 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. Therefore, it may still be useful to
    run <command>ANALYZE</command> after restoring from a dump file to ensure
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 8834b7ec141e..238c87c13f5f 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -893,7 +893,6 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
    When <option>--statistics</option> is specified,
    <command>pg_dumpall</command> will include most optimizer statistics in the
    resulting dump file. This does not include 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.  Therefore, it may still be useful to
    run <command>ANALYZE</command> on each database after restoring from a dump
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 38ca09b423c3..cc44983a9a8d 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -834,8 +834,7 @@ psql --username=postgres --file=script.sql postgres
      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
+     all statistics, such as custom statistics added by
      an extension, or statistics collected by the cumulative statistics system.
     </para>