Documentation fixups for dumping statistics.

Reported-by: Hayato Kuroda (Fujitsu) <[email protected]>
Reported-by: Andrew Dunstan <[email protected]>
Discussion: https://postgr.es/m/OSCPR01MB149665630030E7F54FDA8B27BF5C72@OSCPR01MB14966.jpnprd01.prod.outlook.com
Discussion: https://postgr.es/m/25d26774-25fa-46f2-9888-c6a707d1fef7@dunslane.net

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index c7a22022fa697e53022f1d6bf4fad4057e36c72b..1975054d7bfbbd685a318d3ee19634bf5f667043 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -521,8 +521,8 @@ PostgreSQL documentation
         Dump only the object definitions (schema), not data or statistics.
        </para>
        <para>
-        This option is mutually exclusive to <option>--data-only</option>
-        and <option>--statistics-only</option>.
+        This option cannot be used with <option>--data-only</option>
+        or <option>--statistics-only</option>.
         It is similar to, but for historical reasons not identical to,
         specifying
         <option>--section=pre-data --section=post-data</option>.
@@ -1635,12 +1635,14 @@ CREATE DATABASE foo WITH TEMPLATE template0;
   </para>
 
   <para>
-   The dump file produced by <application>pg_dump</application>
-   does not contain the statistics used by the optimizer to make
-   query planning decisions.  Therefore, it is wise 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.
+   By default, <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 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.
   </para>
 
   <para>

diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index f0823765c4e3fdf2aa850f2f67136c74b10fbbca..c2fa5be95193b79471a73004a53d195d1f5ac6e9 100644 (file)
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -830,10 +830,14 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
   </para>
 
   <para>
-   Once restored, it is wise to run <command>ANALYZE</command> on each
-   database so the optimizer has useful statistics. You
-   can also run <command>vacuumdb -a -z</command> to analyze all
-   databases.
+   By default, <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 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.
   </para>
 
   <para>

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index b403170843072f7e448385a0f334449455e38306..199ea3345f30cc361175f504321fd212563e15f9 100644 (file)
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -483,8 +483,8 @@ PostgreSQL documentation
         to the extent that schema entries are present in the archive.
        </para>
        <para>
-        This option is mutually exclusive of <option>--data-only</option>
-        and <option>--statistics-only</option>.
+        This option cannot be used with <option>--data-only</option>
+        or <option>--statistics-only</option>.
         It is similar to, but for historical reasons not identical to,
         specifying
         <option>--section=pre-data --section=post-data --no-statistics</option>.
@@ -1080,10 +1080,12 @@ CREATE DATABASE foo WITH TEMPLATE template0;
   </para>
 
   <para>
-   Once restored, it is wise to run <command>ANALYZE</command> on each
-   restored table so the optimizer has useful statistics; see
-   <xref linkend="vacuum-for-statistics"/> and
-   <xref linkend="autovacuum"/> for more information.
+   By default, <command>pg_restore</command> will restore optimizer statistics
+   if included in the dump file.  If not all statistics were restored, it may
+   be useful to run <command>ANALYZE</command> on each restored table so the
+   optimizer has useful statistics; see <xref
+   linkend="vacuum-for-statistics"/> and <xref linkend="autovacuum"/> for more
+   information.
   </para>
 
  </refsect1>

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 6f29ffad76baa3a274b37b2ff9948dfbe4e58aee..7bdd85c5cff40b468bcf7c044ee4e5f2c299e5ab 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -792,10 +792,19 @@ psql --username=postgres --file=script.sql postgres
     <title>Statistics</title>
 
     <para>
-     Because optimizer statistics are not transferred by <command>pg_upgrade</command>, you will
-     be instructed to run a command to regenerate that information at the end
-     of the upgrade.  You might need to set connection parameters to
-     match your new cluster.
+     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.  However, some statistics may
+     not be transferred, such as those created explicitly with <xref
+     linkend="sql-createstatistics"/> or custom statistics added by an
+     extension.
+    </para>
+
+    <para>
+     Because not all statistics are not transferred by
+     <command>pg_upgrade</command>, you will be instructed to run a command to
+     regenerate that information at the end of the upgrade.  You might need to
+     set connection parameters to match your new cluster.
     </para>
 
     <para>

diff --git a/src/bin/pg_upgrade/check.c b/src/bin/pg_upgrade/check.c
index d6f629dd3a2bd411cad9e3477275006ba87c8dfb..88db8869b6e06e1c90f627bbfe40cdc73448e0ab 100644 (file)
--- a/src/bin/pg_upgrade/check.c
+++ b/src/bin/pg_upgrade/check.c
@@ -779,7 +779,7 @@ output_completion_banner(char *deletion_script_file_name)
    }
 
    pg_log(PG_REPORT,
-          "Optimizer statistics are not transferred by pg_upgrade.\n"
+          "Some optimizer statistics may not have been transferred by pg_upgrade.\n"
           "Once you start the new server, consider running:\n"
           "    %s/vacuumdb %s--all --analyze-in-stages", new_cluster.bindir, user_specification.data);