Track collation versions for indexes.

Record the current version of dependent collations in pg_depend when
creating or rebuilding an index.  When accessing the index later, warn
that the index may be corrupted if the current version doesn't match.

Thanks to Douglas Doole, Peter Eisentraut, Christoph Berg, Laurenz Albe,
Michael Paquier, Robert Haas, Tom Lane and others for very helpful
discussion.

Author: Thomas Munro <thomas.munro@gmail.com>
Author: Julien Rouhaud <rjuju123@gmail.com>
Reviewed-by: Peter Eisentraut <peter.eisentraut@2ndquadrant.com> (earlier versions)
Discussion: https://postgr.es/m/CAEepm%3D0uEQCpfq_%2BLYFBdArCe4Ot98t1aR4eYiYTe%3DyavQygiQ%40mail.gmail.com

Author: macdice

doc/src/sgml/catalogs.sgml

@@ -3308,7 +3308,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        <structfield>refobjversion</structfield> <type>text</type>
        </para>
        <para>
-        An optional version for the referenced object.
+        An optional version for the referenced object.  Currently used for
+        indexes' collations (see <xref linkend="collation-versions"/>).
        </para>
       </entry>
      </row>

doc/src/sgml/charset.sgml

@@ -948,6 +948,44 @@ CREATE COLLATION ignore_accents (provider = icu, locale = 'und-u-ks-level1-kc-tr
     </tip>
    </sect3>
   </sect2>
+
+  <sect2 id="collation-versions">
+   <title>Collation Versions</title>
+
+   <para>
+    The sort order defined by a collation is not necessarily fixed over time.
+    <productname>PostgreSQL</productname> relies on external libraries that
+    are subject to operating system upgrades, and can also differ between
+    servers involved in binary replication and file-system-level migration.
+    Persistent data structures such as B-trees that depend on sort order might
+    be corrupted by any resulting change.
+    <productname>PostgreSQL</productname> defends against this by recording the
+    current version of each referenced collation for any index that depends on
+    it in the
+    <link linkend="catalog-pg-depend"><structname>pg_depend</structname></link>
+    catalog, if the collation provider makes that information available.  If the
+    provider later begins to report a different version, a warning will be
+    issued when the index is accessed, until either the
+    <xref linkend="sql-reindex"/> command or the
+    <xref linkend="sql-alterindex"/> command is used to update the version.
+   </para>
+   <para>
+    Version information is available from the
+    <literal>icu</literal> provider on all operating systems.  For the
+    <literal>libc</literal> provider, versions are currently only available
+    on systems using the GNU C library (most Linux systems) and Windows.
+   </para>
+
+   <note>
+    <para>
+     When using the GNU C library for collations, the C library's version
+     is used as a proxy for the collation version.  Many Linux distributions
+     change collation definitions only when upgrading the C library, but this
+     approach is imperfect as maintainers are free to back-port newer
+     collation definitions to older C library releases.
+    </para>
+   </note>
+  </sect2>
  </sect1>
 
  <sect1 id="multibyte">

doc/src/sgml/func.sgml

@@ -25444,7 +25444,9 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
        </para>
        <para>
         Returns the actual version of the collation object as it is currently
-        installed in the operating system.
+        installed in the operating system.  <literal>null</literal> is returned
+        on operating systems where <productname>PostgreSQL</productname>
+        doesn't have support for versions.
        </para></entry>
       </row>
 

doc/src/sgml/ref/alter_index.sgml

@@ -25,6 +25,7 @@ ALTER INDEX [ IF EXISTS ] <replaceable class="parameter">name</replaceable> RENA
 ALTER INDEX [ IF EXISTS ] <replaceable class="parameter">name</replaceable> SET TABLESPACE <replaceable class="parameter">tablespace_name</replaceable>
 ALTER INDEX <replaceable class="parameter">name</replaceable> ATTACH PARTITION <replaceable class="parameter">index_name</replaceable>
 ALTER INDEX <replaceable class="parameter">name</replaceable> DEPENDS ON EXTENSION <replaceable class="parameter">extension_name</replaceable>
+ALTER INDEX <replaceable class="parameter">name</replaceable> ALTER COLLATION <replaceable class="parameter">collation_name</replaceable> REFRESH VERSION
 ALTER INDEX [ IF EXISTS ] <replaceable class="parameter">name</replaceable> SET ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )
 ALTER INDEX [ IF EXISTS ] <replaceable class="parameter">name</replaceable> RESET ( <replaceable class="parameter">storage_parameter</replaceable> [, ... ] )
 ALTER INDEX [ IF EXISTS ] <replaceable class="parameter">name</replaceable> ALTER [ COLUMN ] <replaceable class="parameter">column_number</replaceable>
@@ -112,6 +113,20 @@ ALTER INDEX ALL IN TABLESPACE <replaceable class="parameter">name</replaceable>
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><literal>ALTER COLLATION <replaceable class="parameter">collation_name</replaceable> REFRESH VERSION</literal></term>
+    <listitem>
+     <para>
+      Silences warnings about mismatched collation versions, by declaring
+      that the index is compatible with the current collation definition.
+      Be aware that incorrect use of this command can hide index corruption.
+      If you don't know whether a collation's definition has changed
+      incompatibly, <xref linkend="sql-reindex"/> is a safe alternative.
+      See <xref linkend="collation-versions"/> for more information.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><literal>SET ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>

doc/src/sgml/ref/pgupgrade.sgml

@@ -215,6 +215,21 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>--index-collation-versions-unknown</option></term>
+      <listitem>
+       <para>
+        When upgrading indexes from releases before 14 that didn't track
+        collation versions, <application>pg_upgrade</application>
+        assumes by default that the upgraded indexes are compatible with the
+        currently installed versions of relevant collations (see
+        <xref linkend="collation-versions"/>).  Specify
+        <option>--index-collation-versions-unknown</option> to mark
+        them as needing to be rebuilt instead.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option>-?</option></term>
       <term><option>--help</option></term>

doc/src/sgml/ref/reindex.sgml

@@ -38,6 +38,15 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { IN
    several scenarios in which to use <command>REINDEX</command>:
 
    <itemizedlist>
+    <listitem>
+     <para>
+      The index depends on the sort order of a collation, and the definition
+      of the collation has changed.  This can cause index scans to fail to
+      find keys that are present.  See <xref linkend="collation-versions"/> for
+      more information.
+     </para>
+    </listitem>
+
     <listitem>
      <para>
       An index has become corrupted, and no longer contains valid