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

alvherre · alvherre · commit 00a354a13560 · 2021-11-05T11:22:30.000-03:00
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
@@ -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>
