postgres.git / summary / log / commit / refs

commit    00a354a13560dc529ac34a303c85c265aaf033b7
Author:   Alvaro Herrera <alvherre@alvh.no-ip.org>
Date:     Fri Nov 05 14:22:30 2021 +0000
First released in: 15.0

    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


 doc/src/sgml/ref/vacuumdb.sgml | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 223b986b920..d8cbf0e189d 100644
--- 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>


[parent: bef47ff85df1]