Documentation fixups for dumping statistics.

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

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>
+        This option cannot be used with <option>--data-only</option>
-        and <option>--statistics-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>
+   By default, <command>pg_dump</command> will include most optimizer
-   does not contain the statistics used by the optimizer to make
+   statistics in the resulting dump file.  However, some statistics may not be
-   query planning decisions.  Therefore, it is wise to run
+   included, such as those created explicitly with <xref
-   <command>ANALYZE</command> after restoring from a dump file
+   linkend="sql-createstatistics"/> or custom statistics added by an
-   to ensure optimal performance; see <xref linkend="vacuum-for-statistics"/>
+   extension.  Therefore, it may be useful to run <command>ANALYZE</command>
-   and <xref linkend="autovacuum"/> for more information.
+   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>

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
+   By default, <command>pg_dumpall</command> will include most optimizer
-   database so the optimizer has useful statistics. You
+   statistics in the resulting dump file.  However, some statistics may not be
-   can also run <command>vacuumdb -a -z</command> to analyze all
+   included, such as those created explicitly with <xref
-   databases.
+   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>

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>
+        This option cannot be used with <option>--data-only</option>
-        and <option>--statistics-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
+   By default, <command>pg_restore</command> will restore optimizer statistics
-   restored table so the optimizer has useful statistics; see
+   if included in the dump file.  If not all statistics were restored, it may
-   <xref linkend="vacuum-for-statistics"/> and
+   be useful to run <command>ANALYZE</command> on each restored table so the
-   <xref linkend="autovacuum"/> for more information.
+   optimizer has useful statistics; see <xref
+   linkend="vacuum-for-statistics"/> and <xref linkend="autovacuum"/> for more
+   information.
   </para>
 
  </refsect1>

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
+     Unless the <option>--no-statistics</option> option is specified,
-     be instructed to run a command to regenerate that information at the end
+     <command>pg_upgrade</command> will transfer most optimizer statistics
-     of the upgrade.  You might need to set connection parameters to
+     from the old cluster to the new cluster.  However, some statistics may
-     match your new cluster.
+     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>

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);