From 0d789520619803cf6629ebf980e116d733b6756f Mon Sep 17 00:00:00 2001
From: Masahiko Sawada
Date: Tue, 9 Dec 2025 10:51:14 -0800
Subject: Add mode and started_by columns to pg_stat_progress_vacuum view.

The new columns, mode and started_by, indicate the vacuum
mode ('normal', 'aggressive', or 'failsafe') and the initiator of the
vacuum ('manual', 'autovacuum', or 'autovacuum_wraparound'),
respectively. This allows users and monitoring tools to better
understand VACUUM behavior.

Bump catalog version.

Author: Shinya Kato <shinya11.kato@gmail.com>
Reviewed-by: Kirill Reshke <reshkekirill@gmail.com>
Reviewed-by: Nathan Bossart <nathandbossart@gmail.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Reviewed-by: Masahiko Sawada <sawada.mshk@gmail.com>
Reviewed-by: Sami Imseih <samimseih@gmail.com>
Reviewed-by: Michael Paquier <michael@paquier.xyz>
Reviewed-by: Yu Wang <wangyu_runtime@163.com>
Discussion: https://postgr.es/m/CAOzEurQcOY-OBL_ouEVfEaFqe_md3vB5pXjR_m6L71Dcp1JKCQ@mail.gmail.com
---
 doc/src/sgml/maintenance.sgml |  7 ++--
 doc/src/sgml/monitoring.sgml  | 75 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+), 2 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index f4f0433ef6f..08e6489afb8 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1018,8 +1018,11 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
     see <xref linkend="table-lock-compatibility"/>.  However, if the autovacuum
     is running to prevent transaction ID wraparound (i.e., the autovacuum query
     name in the <structname>pg_stat_activity</structname> view ends with
-    <literal>(to prevent wraparound)</literal>), the autovacuum is not
-    automatically interrupted.
+    <literal>(to prevent wraparound)</literal> or the
+    <structfield>started_by</structfield> column in the
+    <structname>pg_stat_progress_vacuum</structname> view shows
+    <literal>autovacuum_wraparound</literal> value), the autovacuum is
+    not automatically interrupted.
    </para>
 
    <warning>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index d2dd5e28365..cc2b590e7a2 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -6710,6 +6710,81 @@ FROM pg_stat_get_backend_idset() AS backendid;
        stale.
       </para></entry>
      </row>
+
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>mode</structfield> <type>text</type>
+      </para>
+      <para>
+       The mode in which the current <command>VACUUM</command> operation is
+       running. See <xref linkend="vacuum-for-wraparound"/> for details of each
+       mode. Possible values are:
+       <itemizedlist>
+        <listitem>
+         <para>
+          <literal>normal</literal>: The operation is performing a standard
+          vacuum. It is neither required to run in aggressive mode nor operating
+          in failsafe mode.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          <literal>aggressive</literal>: The operation is running an aggressive
+          vacuum, which must scan every page that is not marked all-frozen.
+          The parameters <xref linkend="guc-vacuum-freeze-table-age"/> and
+          <xref linkend="guc-vacuum-multixact-freeze-table-age"/> determine when a
+          table requires aggressive vacuuming.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          <literal>failsafe</literal>: The vacuum has entered failsafe mode,
+          in which it performs only the minimum work necessary to avoid
+          transaction ID or multixact ID wraparound failure.
+          The parameters <xref linkend="guc-vacuum-failsafe-age"/> and
+          <xref linkend="guc-vacuum-multixact-failsafe-age"/> determine when the
+          vacuum enters failsafe mode. The vacuum may start in this mode or
+          switch to it while running; the value of the
+          <structfield>mode</structfield> column may transition from another
+          mode to <literal>failsafe</literal> during the operation.
+         </para>
+        </listitem>
+       </itemizedlist>
+      </para></entry>
+     </row>
+
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>started_by</structfield> <type>text</type>
+      </para>
+      <para>
+       Shows what caused the current <command>VACUUM</command> operation to be
+       started. Possible values are:
+       <itemizedlist>
+        <listitem>
+         <para>
+          <literal>manual</literal>: The vacuum was started by an explicit
+          <command>VACUUM</command> command.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          <literal>autovacuum</literal>: The vacuum was started by an autovacuum
+          worker. Vacuums run by autovacuum workers may be interrupted due to
+          lock conflicts.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          <literal>autovacuum_wraparound</literal>: The vacuum was started by an
+          autovacuum worker to prevent transaction ID or multixact ID
+          wraparound. Vacuums run for wraparound protection are not interrupted
+          due to lock conflicts.
+         </para>
+        </listitem>
+       </itemizedlist>
+      </para></entry>
+     </row>
     </tbody>
    </tgroup>
   </table>
-- 
cgit v1.2.3