Skip to content

Commit cb45dc3

Browse files
jeff-davisjeff-davis
committed
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
1 parent bba2fbc commit cb45dc3

File tree

5 files changed

+40
-23
lines changed

5 files changed

+40
-23
lines changed

‎doc/src/sgml/ref/pg_dump.sgml

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -521,8 +521,8 @@ PostgreSQL documentation
521521
Dump only the object definitions (schema), not data or statistics.
522522
</para>
523523
<para>
524-
This option is mutually exclusive to <option>--data-only</option>
525-
and <option>--statistics-only</option>.
524+
This option cannot be used with <option>--data-only</option>
525+
or <option>--statistics-only</option>.
526526
It is similar to, but for historical reasons not identical to,
527527
specifying
528528
<option>--section=pre-data --section=post-data</option>.
@@ -1635,12 +1635,14 @@ CREATE DATABASE foo WITH TEMPLATE template0;
16351635
</para>
16361636

16371637
<para>
1638-
The dump file produced by <application>pg_dump</application>
1639-
does not contain the statistics used by the optimizer to make
1640-
query planning decisions. Therefore, it is wise to run
1641-
<command>ANALYZE</command> after restoring from a dump file
1642-
to ensure optimal performance; see <xref linkend="vacuum-for-statistics"/>
1643-
and <xref linkend="autovacuum"/> for more information.
1638+
By default, <command>pg_dump</command> will include most optimizer
1639+
statistics in the resulting dump file. However, some statistics may not be
1640+
included, such as those created explicitly with <xref
1641+
linkend="sql-createstatistics"/> or custom statistics added by an
1642+
extension. Therefore, it may be useful to run <command>ANALYZE</command>
1643+
after restoring from a dump file to ensure optimal performance; see <xref
1644+
linkend="vacuum-for-statistics"/> and <xref linkend="autovacuum"/> for more
1645+
information.
16441646
</para>
16451647

16461648
<para>

‎doc/src/sgml/ref/pg_dumpall.sgml

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -830,10 +830,14 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
830830
</para>
831831

832832
<para>
833-
Once restored, it is wise to run <command>ANALYZE</command> on each
834-
database so the optimizer has useful statistics. You
835-
can also run <command>vacuumdb -a -z</command> to analyze all
836-
databases.
833+
By default, <command>pg_dumpall</command> will include most optimizer
834+
statistics in the resulting dump file. However, some statistics may not be
835+
included, such as those created explicitly with <xref
836+
linkend="sql-createstatistics"/> or custom statistics added by an
837+
extension. Therefore, it may be useful to run <command>ANALYZE</command>
838+
on each database after restoring from a dump file to ensure optimal
839+
performance. You can also run <command>vacuumdb -a -z</command> to analyze
840+
all databases.
837841
</para>
838842

839843
<para>

‎doc/src/sgml/ref/pg_restore.sgml

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -483,8 +483,8 @@ PostgreSQL documentation
483483
to the extent that schema entries are present in the archive.
484484
</para>
485485
<para>
486-
This option is mutually exclusive of <option>--data-only</option>
487-
and <option>--statistics-only</option>.
486+
This option cannot be used with <option>--data-only</option>
487+
or <option>--statistics-only</option>.
488488
It is similar to, but for historical reasons not identical to,
489489
specifying
490490
<option>--section=pre-data --section=post-data --no-statistics</option>.
@@ -1080,10 +1080,12 @@ CREATE DATABASE foo WITH TEMPLATE template0;
10801080
</para>
10811081

10821082
<para>
1083-
Once restored, it is wise to run <command>ANALYZE</command> on each
1084-
restored table so the optimizer has useful statistics; see
1085-
<xref linkend="vacuum-for-statistics"/> and
1086-
<xref linkend="autovacuum"/> for more information.
1083+
By default, <command>pg_restore</command> will restore optimizer statistics
1084+
if included in the dump file. If not all statistics were restored, it may
1085+
be useful to run <command>ANALYZE</command> on each restored table so the
1086+
optimizer has useful statistics; see <xref
1087+
linkend="vacuum-for-statistics"/> and <xref linkend="autovacuum"/> for more
1088+
information.
10871089
</para>
10881090

10891091
</refsect1>

‎doc/src/sgml/ref/pgupgrade.sgml

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -792,10 +792,19 @@ psql --username=postgres --file=script.sql postgres
792792
<title>Statistics</title>
793793

794794
<para>
795-
Because optimizer statistics are not transferred by <command>pg_upgrade</command>, you will
796-
be instructed to run a command to regenerate that information at the end
797-
of the upgrade. You might need to set connection parameters to
798-
match your new cluster.
795+
Unless the <option>--no-statistics</option> option is specified,
796+
<command>pg_upgrade</command> will transfer most optimizer statistics
797+
from the old cluster to the new cluster. However, some statistics may
798+
not be transferred, such as those created explicitly with <xref
799+
linkend="sql-createstatistics"/> or custom statistics added by an
800+
extension.
801+
</para>
802+
803+
<para>
804+
Because not all statistics are not transferred by
805+
<command>pg_upgrade</command>, you will be instructed to run a command to
806+
regenerate that information at the end of the upgrade. You might need to
807+
set connection parameters to match your new cluster.
799808
</para>
800809

801810
<para>

‎src/bin/pg_upgrade/check.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -779,7 +779,7 @@ output_completion_banner(char *deletion_script_file_name)
779779
}
780780

781781
pg_log(PG_REPORT,
782-
"Optimizer statistics are not transferred by pg_upgrade.\n"
782+
"Some optimizer statistics may not have been transferred by pg_upgrade.\n"
783783
"Once you start the new server, consider running:\n"
784784
" %s/vacuumdb %s--all --analyze-in-stages", new_cluster.bindir, user_specification.data);
785785

0 commit comments

Comments
 (0)