From a59624167e0323e8e37d6d7deb28368be8c0f03e Mon Sep 17 00:00:00 2001
From: Radim Marek <radim@boringsql.com>
Date: Sun, 27 Sep 2026 08:46:18 -0700
Subject: [PATCH v2] doc: Document REPACK limits and point to VACUUM for
 wraparound

REPACK (CONCURRENTLY) uses some memory per concurrently updated or
deleted row and fails after about 100 million of them.  Document that,
and say that VACUUM, not REPACK, is the tool to prevent wraparound.

Discussion: https://postgr.es/m/CAJgoLk+dodrwuwCuXERGYwgjQzSwrKd+xgitYrL32oWDt39zvA@mail.gmail.com
---
 doc/src/sgml/ref/repack.sgml | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc/src/sgml/ref/repack.sgml b/doc/src/sgml/ref/repack.sgml
index 346cba89c90..61762badbf0 100644
--- a/doc/src/sgml/ref/repack.sgml
+++ b/doc/src/sgml/ref/repack.sgml
@@ -259,6 +259,14 @@ REPACK [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] USING
        are also stored separately in a temporary file, until they can be
        processed.
       </para>
+      <para>
+       The more rows other transactions change while
+       <command>REPACK</command> runs, the more time, temporary space and
+       memory it needs to apply those changes.  Each row that is updated or
+       deleted takes a small amount of backend memory, not limited by
+       <xref linkend="guc-maintenance-work-mem"/>, and the command fails if
+       more than about 100 million rows are updated or deleted this way.
+      </para>
      </note>
 
      <para>
@@ -384,6 +392,23 @@ REPACK [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] USING
     on the table.
    </para>
 
+   <para>
+    <command>REPACK</command> is meant to remove bloat and, with
+    <literal>USING INDEX</literal>, to cluster the table, in order to improve
+    performance.  Although it also advances the table's
+    <structfield>relfrozenxid</structfield>, it is not a good way to prevent
+    transaction ID wraparound: it rewrites the whole table and all of its
+    indexes, so it takes much longer than <command>VACUUM</command>, and it
+    can fail after most of the work is done, especially with
+    <literal>CONCURRENTLY</literal> on a busy table.  Use
+    <command>VACUUM</command> for that instead (see
+    <xref linkend="vacuum-for-wraparound"/>).  When a table gets close to
+    wraparound, <command>VACUUM</command> skips index vacuuming on its own
+    (see <xref linkend="guc-vacuum-failsafe-age"/>), and its
+    <link linkend="sql-vacuum"><literal>INDEX_CLEANUP OFF</literal></link>
+    option can do the same earlier.
+   </para>
+
    <para>
     <command>REPACK</command> refuses to process a table on which an invalid
     index exists.  Such indexes must be dropped or reindexed by the user ahead
-- 
2.37.1 (Apple Git-137.1)