Reword doc blurb for vacuumdb --analyze-in-stages

Make users aware that using it in a database with existing stats might
cause transient problems.

Author: Nikolai Berkoff <nikolai.berkoff@pm.me>
Discussion: https://postgr.es/m/s-kSljtWXMWgMfGTztPTPcS80R8FHdOrBxDTnrQI6GMZbT7au1A4b0fzaSFtKwCI8nwN0MhgPLfVOTvJ7DwTjkip4P3d0o4VgrMJs4OLN-o=@pm.me

diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 223b986b920d4167b092d9d01b0d2ac48bde5c9a..d8cbf0e189d98a3a700834dcbee8ebe2e53e07ea 100644 (file)
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -398,15 +398,19 @@ PostgreSQL documentation
        <para>
         Only calculate statistics for use by the optimizer (no vacuum),
         like <option>--analyze-only</option>.  Run several (currently three)
-        stages of analyze with different configuration settings, to produce
-        usable statistics faster.
+        stages of analyze; the first stage uses the lowest possible statistics
+        target (see <xref linkend="guc-default-statistics-target"/>)
+        to produce usable statistics faster, and subsequent stages build the
+        full statistics.
        </para>
 
        <para>
-        This option is useful to analyze a database that was newly populated
-        from a restored dump or by <command>pg_upgrade</command>.  This option
-        will try to create some statistics as fast as possible, to make the
-        database usable, and then produce full statistics in the subsequent
+        This option is only useful to analyze a database that current has
+        no statistics or wholly incorrect ones, such as if it is newly
+        populated from a restored dump or by <command>pg_upgrade</command>.
+        Be aware that running this option in a database with existing
+        statistics may cause the query optimizer choices to become
+        transiently worse due to the low statistics targets of the early
         stages.
        </para>
       </listitem>