v4-0001-Docs-Index-rebuilding-is-sometimes-skipped-along-.patch

From 9bba318b31394af582659ecfcd5fd77ddf778164 Mon Sep 17 00:00:00 2001
From: jcoleman <jtc331@gmail.com>
Date: Tue, 29 Mar 2022 13:56:39 +0000
Subject: [PATCH v4] Docs: Index rebuilding is sometimes skipped along with
 table rewriting

In 367bc42 (for 9.2!) we "avoid index rebuild for no-rewrite ALTER TABLE
.. ALTER TYPE." This doesn't apply in all cases, but update the docs to
match so users don't conclude indexes must always be rewritten.
---
 doc/src/sgml/ref/alter_table.sgml | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 5c0735e08a..7027976fa9 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1366,7 +1366,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
     existing column, if the <literal>USING</literal> clause does not change
     the column contents and the old type is either binary coercible to the new
     type or an unconstrained domain over the new type, a table rewrite is not
-    needed; but any indexes on the affected columns must still be rebuilt.
+    needed. However, indexes must always be rebuilt unless the system can
+    verify that the new index would be logically equivalent to the existing one.
+    For example, if the collation for a column has been changed an index rebuild
+    is always required because the new sort order might be different. However, in
+    the absence of a collation change, a column can be changed from <type>text</type>
+    to <type>varchar</type> (or vice versa) without rebuilding the indexes because
+    these data types sort identically.
     Table and/or index rebuilds may take a
     significant amount of time for a large table; and will temporarily require
     as much as double the disk space.
-- 
2.20.1