From 792353f7d520482414e3bb5e44ed344cf78b54c6 Mon Sep 17 00:00:00 2001
From: Bruce Momjian
Date: Mon, 17 Nov 2025 18:55:41 -0500
Subject: doc:  clarify that pg_upgrade preserves "optimizer" stats.

Reported-by: Rambabu V

Author: Robert Treat

Discussion: https://postgr.es/m/CADtiZxrUzRRX6edyN2y-7U5HA8KSXttee7K=EFTLXjwG1SCE4A@mail.gmail.com

Backpatch-through: 18
---
 doc/src/sgml/ref/pg_dump.sgml    | 13 +++++++------
 doc/src/sgml/ref/pg_dumpall.sgml | 13 +++++++------
 2 files changed, 14 insertions(+), 12 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index ae7718e1a93..bd0d59a6ac0 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1393,7 +1393,7 @@ PostgreSQL documentation
       <term><option>--statistics</option></term>
       <listitem>
        <para>
-        Dump statistics.
+        Dump optimizer statistics.
        </para>
       </listitem>
      </varlistentry>
@@ -1403,7 +1403,7 @@ PostgreSQL documentation
       <listitem>
        <para>
         Dump only the statistics, not the schema (data definitions) or data.
-        Statistics for tables, materialized views, foreign tables,
+        Optimizer statistics for tables, materialized views, foreign tables,
         and indexes are dumped.
        </para>
       </listitem>
@@ -1699,11 +1699,12 @@ CREATE DATABASE foo WITH TEMPLATE template0;
   </para>
 
   <para>
-   If <option>--statistics</option> is specified,
+   When <option>--statistics</option> is specified,
    <command>pg_dump</command> will include most optimizer statistics in the
-   resulting dump file.  However, some statistics may not be included, such as
-   those created explicitly with <xref linkend="sql-createstatistics"/> or
-   custom statistics added by an extension.  Therefore, it may be useful to
+   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
    optimal performance; see <xref linkend="vacuum-for-statistics"/> and <xref
    linkend="autovacuum"/> for more information.
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 9f639f61db0..8834b7ec141 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -639,7 +639,7 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
       <term><option>--statistics</option></term>
       <listitem>
        <para>
-        Dump statistics.
+        Dump optimizer statistics.
        </para>
       </listitem>
      </varlistentry>
@@ -649,7 +649,7 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
       <listitem>
        <para>
         Dump only the statistics, not the schema (data definitions) or data.
-        Statistics for tables, materialized views, foreign tables,
+        Optimizer statistics for tables, materialized views, foreign tables,
         and indexes are dumped.
        </para>
       </listitem>
@@ -890,11 +890,12 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
   </para>
 
   <para>
-   If <option>--statistics</option> is specified,
+   When <option>--statistics</option> is specified,
    <command>pg_dumpall</command> will include most optimizer statistics in the
-   resulting dump file.  However, some statistics may not be included, such as
-   those created explicitly with <xref linkend="sql-createstatistics"/> or
-   custom statistics added by an extension.  Therefore, it may be useful to
+   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
    file to ensure optimal performance.  You can also run <command>vacuumdb -a
    -z</command> to analyze all databases.
-- 
cgit v1.2.3