diff options
Diffstat (limited to 'doc/src/sgml/ref')
| -rw-r--r-- | doc/src/sgml/ref/alter_collation.sgml | 63 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_index.sgml | 15 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_collation.sgml | 21 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pgupgrade.sgml | 15 | ||||
| -rw-r--r-- | doc/src/sgml/ref/reindex.sgml | 9 |
5 files changed, 84 insertions, 39 deletions
diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml index 65429aabe28..af9ff2867b7 100644 --- a/doc/src/sgml/ref/alter_collation.sgml +++ b/doc/src/sgml/ref/alter_collation.sgml @@ -21,6 +21,8 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> +ALTER COLLATION <replaceable>name</replaceable> REFRESH VERSION + ALTER COLLATION <replaceable>name</replaceable> RENAME TO <replaceable>new_name</replaceable> ALTER COLLATION <replaceable>name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_ROLE | CURRENT_USER | SESSION_USER } ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_schema</replaceable> @@ -86,9 +88,70 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche </listitem> </varlistentry> + <varlistentry> + <term><literal>REFRESH VERSION</literal></term> + <listitem> + <para> + Update the collation's version. + See <xref linkend="sql-altercollation-notes"/> below. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> + <refsect1 id="sql-altercollation-notes" xreflabel="Notes"> + <title>Notes</title> + + <para> + When using collations provided by the ICU library, the ICU-specific version + of the collator is recorded in the system catalog when the collation object + is created. When the collation is used, the current version is + checked against the recorded version, and a warning is issued when there is + a mismatch, for example: +<screen> +WARNING: collation "xx-x-icu" has version mismatch +DETAIL: The collation in the database was created using version 1.2.3.4, but the operating system provides version 2.3.4.5. +HINT: Rebuild all objects affected by this collation and run ALTER COLLATION pg_catalog."xx-x-icu" REFRESH VERSION, or build PostgreSQL with the right library version. +</screen> + A change in collation definitions can lead to corrupt indexes and other + problems because the database system relies on stored objects having a + certain sort order. Generally, this should be avoided, but it can happen + in legitimate circumstances, such as when + using <command>pg_upgrade</command> to upgrade to server binaries linked + with a newer version of ICU. When this happens, all objects depending on + the collation should be rebuilt, for example, + using <command>REINDEX</command>. When that is done, the collation version + can be refreshed using the command <literal>ALTER COLLATION ... REFRESH + VERSION</literal>. This will update the system catalog to record the + current collator version and will make the warning go away. Note that this + does not actually check whether all affected objects have been rebuilt + correctly. + </para> + <para> + When using collations provided by <literal>libc</literal> and + <productname>PostgreSQL</productname> was built with the GNU C library, the + C library's version is used as a collation version. Since collation + definitions typically change only with GNU C library releases, this provides + some defense against corruption, but it is not completely reliable. + </para> + <para> + Currently, there is no version tracking for the database default collation. + </para> + + <para> + The following query can be used to identify all collations in the current + database that need to be refreshed and the objects that depend on them: +<programlisting><![CDATA[ +SELECT pg_describe_object(refclassid, refobjid, refobjsubid) AS "Collation", + pg_describe_object(classid, objid, objsubid) AS "Object" + FROM pg_depend d JOIN pg_collation c + ON refclassid = 'pg_collation'::regclass AND refobjid = c.oid + WHERE c.collversion <> pg_collation_actual_version(c.oid) + ORDER BY 1, 2; +]]></programlisting></para> + </refsect1> + <refsect1> <title>Examples</title> diff --git a/doc/src/sgml/ref/alter_index.sgml b/doc/src/sgml/ref/alter_index.sgml index 4b446384c26..e26efec064b 100644 --- a/doc/src/sgml/ref/alter_index.sgml +++ b/doc/src/sgml/ref/alter_index.sgml @@ -25,7 +25,6 @@ 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> [ NO ] 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> @@ -114,20 +113,6 @@ 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/create_collation.sgml b/doc/src/sgml/ref/create_collation.sgml index b97842071f9..58f5f0cd63a 100644 --- a/doc/src/sgml/ref/create_collation.sgml +++ b/doc/src/sgml/ref/create_collation.sgml @@ -27,6 +27,7 @@ CREATE COLLATION [ IF NOT EXISTS ] <replaceable>name</replaceable> ( [ LC_CTYPE = <replaceable>lc_ctype</replaceable>, ] [ PROVIDER = <replaceable>provider</replaceable>, ] [ DETERMINISTIC = <replaceable>boolean</replaceable>, ] + [ VERSION = <replaceable>version</replaceable> ] ) CREATE COLLATION [ IF NOT EXISTS ] <replaceable>name</replaceable> FROM <replaceable>existing_collation</replaceable> </synopsis> @@ -149,6 +150,26 @@ CREATE COLLATION [ IF NOT EXISTS ] <replaceable>name</replaceable> FROM <replace </varlistentry> <varlistentry> + <term><replaceable>version</replaceable></term> + + <listitem> + <para> + Specifies the version string to store with the collation. Normally, + this should be omitted, which will cause the version to be computed + from the actual version of the collation as provided by the operating + system. This option is intended to be used + by <command>pg_upgrade</command> for copying the version from an + existing installation. + </para> + + <para> + See also <xref linkend="sql-altercollation"/> for how to handle + collation version mismatches. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><replaceable>existing_collation</replaceable></term> <listitem> diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 4737d97d202..a83c63cd98f 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -216,21 +216,6 @@ 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 53c362dcd3e..e6b25ee670f 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -42,15 +42,6 @@ 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 |