From cb45dc3afb05ce5e5267b1a9be4725d0be7ee33c Mon Sep 17 00:00:00 2001 From: Jeff Davis Date: Sat, 22 Feb 2025 10:03:11 -0800 Subject: [PATCH] Documentation fixups for dumping statistics. Reported-by: Hayato Kuroda (Fujitsu) Reported-by: Andrew Dunstan 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 | 18 ++++++++++-------- doc/src/sgml/ref/pg_dumpall.sgml | 12 ++++++++---- doc/src/sgml/ref/pg_restore.sgml | 14 ++++++++------ doc/src/sgml/ref/pgupgrade.sgml | 17 +++++++++++++---- src/bin/pg_upgrade/check.c | 2 +- 5 files changed, 40 insertions(+), 23 deletions(-) diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index c7a22022fa6..1975054d7bf 100644 --- 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. - This option is mutually exclusive to - and . + This option cannot be used with + or . It is similar to, but for historical reasons not identical to, specifying . @@ -1635,12 +1635,14 @@ CREATE DATABASE foo WITH TEMPLATE template0; - The dump file produced by pg_dump - does not contain the statistics used by the optimizer to make - query planning decisions. Therefore, it is wise to run - ANALYZE after restoring from a dump file - to ensure optimal performance; see - and for more information. + By default, pg_dump will include most optimizer + statistics in the resulting dump file. However, some statistics may not be + included, such as those created explicitly with or custom statistics added by an + extension. Therefore, it may be useful to run ANALYZE + after restoring from a dump file to ensure optimal performance; see and for more + information. diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index f0823765c4e..c2fa5be9519 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -830,10 +830,14 @@ exclude database PATTERN - Once restored, it is wise to run ANALYZE on each - database so the optimizer has useful statistics. You - can also run vacuumdb -a -z to analyze all - databases. + By default, pg_dumpall will include most optimizer + statistics in the resulting dump file. However, some statistics may not be + included, such as those created explicitly with or custom statistics added by an + extension. Therefore, it may be useful to run ANALYZE + on each database after restoring from a dump file to ensure optimal + performance. You can also run vacuumdb -a -z to analyze + all databases. diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index b4031708430..199ea3345f3 100644 --- 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. - This option is mutually exclusive of - and . + This option cannot be used with + or . It is similar to, but for historical reasons not identical to, specifying . @@ -1080,10 +1080,12 @@ CREATE DATABASE foo WITH TEMPLATE template0; - Once restored, it is wise to run ANALYZE on each - restored table so the optimizer has useful statistics; see - and - for more information. + By default, pg_restore will restore optimizer statistics + if included in the dump file. If not all statistics were restored, it may + be useful to run ANALYZE on each restored table so the + optimizer has useful statistics; see and for more + information. diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 6f29ffad76b..7bdd85c5cff 100644 --- 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 Statistics - Because optimizer statistics are not transferred by pg_upgrade, 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 is specified, + pg_upgrade 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 or custom statistics added by an + extension. + + + + Because not all statistics are not transferred by + pg_upgrade, 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. diff --git a/src/bin/pg_upgrade/check.c b/src/bin/pg_upgrade/check.c index d6f629dd3a2..88db8869b6e 100644 --- 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);