diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/catalogs.sgml | 3 | ||||
| -rw-r--r-- | doc/src/sgml/charset.sgml | 38 | ||||
| -rw-r--r-- | doc/src/sgml/func.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_index.sgml | 15 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pgupgrade.sgml | 15 | ||||
| -rw-r--r-- | doc/src/sgml/ref/reindex.sgml | 9 |
6 files changed, 82 insertions, 2 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index c3f324f05eb..5fb9dca4258 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -3308,7 +3308,8 @@ SCRAM-SHA-256$<replaceable><iteration count></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> diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml index 2745b444176..832a701523d 100644 --- a/doc/src/sgml/charset.sgml +++ b/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"> diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 0398b4909bf..bf6004f321f 100644 --- a/doc/src/sgml/func.sgml +++ b/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> diff --git a/doc/src/sgml/ref/alter_index.sgml b/doc/src/sgml/ref/alter_index.sgml index 793119d2fc1..214005a86c5 100644 --- a/doc/src/sgml/ref/alter_index.sgml +++ b/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> @@ -113,6 +114,20 @@ ALTER INDEX ALL IN TABLESPACE <replaceable class="parameter">name</replaceable> </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> <para> diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index b59c5697a36..92e1d09a55c 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -216,6 +216,21 @@ PostgreSQL documentation </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> <listitem><para>show help, then exit</para></listitem> diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index fa43e3a9720..f6d425a6910 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -40,6 +40,15 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { IN <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 data. Although in theory this should never happen, in practice indexes can become corrupted due to software bugs or |