From eee71cdfdaff3295d52c1213d47ec1754e87a1f8 Mon Sep 17 00:00:00 2001
From: Sami Imseih <simseih@amazon.com>
Date: Tue, 10 Mar 2026 19:04:03 -0500
Subject: [PATCH v1 1/1] autovacuum scheduling improvements - docs

---
 doc/src/sgml/maintenance.sgml | 95 +++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 7c958b06273..16b50f8e5b6 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1054,6 +1054,99 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
     not automatically interrupted.
    </para>
 
+   <sect3 id="autovacuum-priority">
+    <title>Processing Priority</title>
+
+   <para>
+    Autovacuum decides what to process in two steps: first it picks a
+    database, then it orders the tables within that database.
+   </para>
+
+   <para>
+    The launcher first checks for databases at risk of wraparound,
+    with transaction ID wraparound taking precedence over multixact
+    wraparound.  If no database is at risk, the least recently
+    auto-vacuumed database is selected.  Databases that have never been
+    connected to, or that have had no activity since the statistics were
+    last reset, are not considered except when at risk of wraparound.
+   </para>
+
+   <para>
+    Within a database, the autovacuum worker builds a list of all tables
+    that need vacuuming or analyzing and sorts them by a
+    <firstterm>priority score</firstterm>.  Tables with higher scores are
+    processed first.
+   </para>
+
+   <para>
+    The score for each table is calculated as the maximum of several
+    component scores, each representing how far the table has exceeded a
+    particular threshold.  Each component is multiplied by a configurable
+    weight parameter:
+
+    <itemizedlist>
+     <listitem>
+      <para>
+       <xref linkend="guc-autovacuum-vacuum-score-weight"/>: the ratio of
+       dead tuples to the table's vacuum threshold.  For example, if a table
+       has 100 dead tuples and its vacuum threshold is 80, this component's
+       score is 1.25.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <xref linkend="guc-autovacuum-vacuum-insert-score-weight"/>: the ratio
+       of inserted tuples (since the last vacuum) to the table's insert
+       vacuum threshold.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <xref linkend="guc-autovacuum-analyze-score-weight"/>: the ratio of
+       modified tuples (since the last analyze) to the table's analyze
+       threshold.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <xref linkend="guc-autovacuum-freeze-score-weight"/>: the ratio of
+       the table's transaction ID age
+       (<structfield>relfrozenxid</structfield>) to
+       <xref linkend="guc-autovacuum-freeze-max-age"/>.  This component is
+       only considered for tables that have already exceeded their freeze max
+       age.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <xref linkend="guc-autovacuum-multixact-freeze-score-weight"/>: the
+       ratio of the table's multixact age
+       (<structfield>relminmxid</structfield>) to
+       <xref linkend="guc-autovacuum-multixact-freeze-max-age"/>.  Like the
+       freeze score, this is only considered for tables past their multixact
+       freeze max age.
+      </para>
+     </listitem>
+    </itemizedlist>
+
+    The final score is the maximum of these weighted components.
+   </para>
+
+   <para>
+    Tables that are approaching transaction ID or multixact wraparound receive
+    additional priority.  Once a table's age surpasses
+    <xref linkend="guc-vacuum-failsafe-age"/> or
+    <xref linkend="guc-vacuum-multixact-failsafe-age"/>, its freeze score is
+    scaled aggressively so that it sorts toward the top of the list.
+   </para>
+
+   <para>
+    All weights default to 1.0.  Reducing a weight to a value below 1.0
+    decreases the influence of that component on the final score, making
+    tables that exceed that particular threshold less likely to be processed
+    first.
+   </para>
+
    <warning>
     <para>
      Regularly running commands that acquire locks conflicting with a
@@ -1061,6 +1154,8 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
      effectively prevent autovacuums from ever completing.
     </para>
    </warning>
+
+   </sect3>
   </sect2>
  </sect1>
 
-- 
2.50.1 (Apple Git-155)