2011-02-12 14:54:13 +01:00
<!--
doc/src/sgml/ref/alter_collation.sgml
PostgreSQL documentation
-->
2017-10-20 03:16:39 +02:00
<refentry id="sql-altercollation">
2014-02-24 03:25:35 +01:00
<indexterm zone="sql-altercollation">
<primary>ALTER COLLATION</primary>
</indexterm>
2011-02-12 14:54:13 +01:00
<refmeta>
<refentrytitle>ALTER COLLATION</refentrytitle>
<manvolnum>7</manvolnum>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ALTER COLLATION</refname>
<refpurpose>change the definition of a collation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
2021-05-07 10:17:42 +02:00
ALTER COLLATION <replaceable>name</replaceable> REFRESH VERSION
2011-02-12 14:54:13 +01:00
ALTER COLLATION <replaceable>name</replaceable> RENAME TO <replaceable>new_name</replaceable>
2020-09-17 11:39:28 +02:00
ALTER COLLATION <replaceable>name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
2011-02-12 14:54:13 +01:00
ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_schema</replaceable>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>ALTER COLLATION</command> changes the definition of a
collation.
</para>
<para>
2017-10-09 03:44:17 +02:00
You must own the collation to use <command>ALTER COLLATION</command>.
2011-02-12 14:54:13 +01:00
To alter the owner, you must also be a direct or indirect member of the new
owning role, and that role must have <literal>CREATE</literal> privilege on
the collation's schema. (These restrictions enforce that altering the
owner doesn't do anything you couldn't do by dropping and recreating the
collation. However, a superuser can alter ownership of any collation
anyway.)
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing collation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">new_name</replaceable></term>
<listitem>
<para>
The new name of the collation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">new_owner</replaceable></term>
<listitem>
<para>
The new owner of the collation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">new_schema</replaceable></term>
<listitem>
<para>
The new schema for the collation.
</para>
</listitem>
</varlistentry>
2017-03-23 20:25:34 +01:00
2021-05-07 10:17:42 +02:00
<varlistentry>
<term><literal>REFRESH VERSION</literal></term>
<listitem>
<para>
Update the collation's version.
See <xref linkend="sql-altercollation-notes"/> below.
</para>
</listitem>
</varlistentry>
2011-02-12 14:54:13 +01:00
</variablelist>
</refsect1>
2021-05-07 10:17:42 +02:00
<refsect1 id="sql-altercollation-notes" xreflabel="Notes">
<title>Notes</title>
<para>
2022-01-28 08:21:36 +01:00
When a collation object is created, the provider-specific version of the
collation is recorded in the system catalog. When the collation is used,
the current version is
2021-05-07 10:17:42 +02:00
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
2022-01-28 08:21:36 +01:00
in legitimate circumstances, such as when upgrading the operating system
to a new major version or when
2021-05-07 10:17:42 +02:00
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
2022-01-28 08:21:36 +01:00
current collation version and will make the warning go away. Note that this
2021-05-07 10:17:42 +02:00
does not actually check whether all affected objects have been rebuilt
correctly.
</para>
<para>
2021-05-07 11:47:08 +02:00
When using collations provided by <literal>libc</literal>, version
information is recorded on systems using the GNU C library (most Linux
2022-01-28 08:21:36 +01:00
systems), FreeBSD and Windows. When using collations provided by ICU, the
version information is provided by the ICU library and is available on all
platforms.
2021-05-07 10:17:42 +02:00
</para>
2021-05-07 11:47:08 +02:00
<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>
<para>
When using Windows for collations, version information is only available
for collations defined with BCP 47 language tags such as
2022-01-27 18:28:21 +01:00
<literal>en-US</literal>.
2021-05-07 11:47:08 +02:00
</para>
</note>
2021-05-07 10:17:42 +02:00
<para>
2022-02-14 08:09:04 +01:00
For the database default collation, there is an analogous command
<literal>ALTER DATABASE ... REFRESH COLLATION VERSION</literal>.
2021-05-07 10:17:42 +02:00
</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>
2011-02-12 14:54:13 +01:00
<refsect1>
<title>Examples</title>
<para>
To rename the collation <literal>de_DE</literal> to
<literal>german</literal>:
<programlisting>
ALTER COLLATION "de_DE" RENAME TO german;
</programlisting>
</para>
<para>
To change the owner of the collation <literal>en_US</literal> to
<literal>joe</literal>:
<programlisting>
ALTER COLLATION "en_US" OWNER TO joe;
2011-08-07 09:49:45 +02:00
</programlisting></para>
2011-02-12 14:54:13 +01:00
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
There is no <command>ALTER COLLATION</command> statement in the SQL
standard.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
2017-11-23 15:39:47 +01:00
<member><xref linkend="sql-createcollation"/></member>
<member><xref linkend="sql-dropcollation"/></member>
2011-02-12 14:54:13 +01:00
</simplelist>
</refsect1>
</refentry>