docs: Changing column type doesn't always require an index rebuild.

robertmhaas · robertmhaas · commit fa25bebb827a · 2022-04-01T08:48:44.000-04:00
James Coleman and Robert Haas, reviewed by Matthias van de Meent. Discussion: https://postgr.es/m/CAAaqYe90Ea3RG=A7H-ONvTcx549-oQhp07BrHErwM=AyH2ximg@mail.gmail.com
diff --git 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.
