mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-28 21:01:48 +02:00
ec48314708
Design problems were discovered in the handling of composite types and record types that would cause some relevant versions not to be recorded. Misgivings were also expressed about the use of the pg_depend catalog for this purpose. We're out of time for this release so we'll revert and try again. Commits reverted:1bf946bd
: Doc: Document known problem with Windows collation versions.cf002008
: Remove no-longer-relevant test case.ef387bed
: Fix bogus collation-version-recording logic.0fb0a050
: Hide internal error for pg_collation_actual_version(<bad OID>).ff942057
: Suppress "warning: variable 'collcollate' set but not used".d50e3b1f
: Fix assertion in collation version lookup.f24b1569
: Rethink extraction of collation dependencies.257836a7
: Track collation versions for indexes.cd6f479e
: Add pg_depend.refobjversion.7d1297df
: Remove pg_collation.collversion. Discussion: https://postgr.es/m/CA%2BhUKGLhj5t1fcjqAu8iD9B3ixJtsTNqyCCD4V0aTO9kAKAjjA%40mail.gmail.com
264 lines
7.8 KiB
Plaintext
264 lines
7.8 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/create_collation.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="sql-createcollation">
|
|
<indexterm zone="sql-createcollation">
|
|
<primary>CREATE COLLATION</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle>CREATE COLLATION</refentrytitle>
|
|
<manvolnum>7</manvolnum>
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>CREATE COLLATION</refname>
|
|
<refpurpose>define a new collation</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
CREATE COLLATION [ IF NOT EXISTS ] <replaceable>name</replaceable> (
|
|
[ LOCALE = <replaceable>locale</replaceable>, ]
|
|
[ LC_COLLATE = <replaceable>lc_collate</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>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="sql-createcollation-description">
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>CREATE COLLATION</command> defines a new collation using
|
|
the specified operating system locale settings,
|
|
or by copying an existing collation.
|
|
</para>
|
|
|
|
<para>
|
|
To be able to create a collation, you must
|
|
have <literal>CREATE</literal> privilege on the destination schema.
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>IF NOT EXISTS</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Do not throw an error if a collation with the same name already exists.
|
|
A notice is issued in this case. Note that there is no guarantee that
|
|
the existing collation is anything like the one that would have been created.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>name</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
The name of the collation. The collation name can be
|
|
schema-qualified. If it is not, the collation is defined in the
|
|
current schema. The collation name must be unique within that
|
|
schema. (The system catalogs can contain collations with the
|
|
same name for other encodings, but these are ignored if the
|
|
database encoding does not match.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>locale</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
This is a shortcut for setting <symbol>LC_COLLATE</symbol>
|
|
and <symbol>LC_CTYPE</symbol> at once. If you specify this,
|
|
you cannot specify either of those parameters.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>lc_collate</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Use the specified operating system locale for
|
|
the <symbol>LC_COLLATE</symbol> locale category.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>lc_ctype</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Use the specified operating system locale for
|
|
the <symbol>LC_CTYPE</symbol> locale category.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>provider</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Specifies the provider to use for locale services associated with this
|
|
collation. Possible values
|
|
are: <literal>icu</literal>,<indexterm><primary>ICU</primary></indexterm>
|
|
<literal>libc</literal>.
|
|
<literal>libc</literal> is the default.
|
|
The available choices depend on the operating system and build options.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>DETERMINISTIC</literal></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Specifies whether the collation should use deterministic comparisons.
|
|
The default is true. A deterministic comparison considers strings that
|
|
are not byte-wise equal to be unequal even if they are considered
|
|
logically equal by the comparison. PostgreSQL breaks ties using a
|
|
byte-wise comparison. Comparison that is not deterministic can make the
|
|
collation be, say, case- or accent-insensitive. For that, you need to
|
|
choose an appropriate <literal>LC_COLLATE</literal> setting
|
|
<emphasis>and</emphasis> set the collation to not deterministic here.
|
|
</para>
|
|
|
|
<para>
|
|
Nondeterministic collations are only supported with the ICU provider.
|
|
</para>
|
|
</listitem>
|
|
</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>
|
|
<para>
|
|
The name of an existing collation to copy. The new collation
|
|
will have the same properties as the existing one, but it
|
|
will be an independent object.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1 id="sql-createcollation-notes">
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
<command>CREATE COLLATION</command> takes a <literal>SHARE ROW
|
|
EXCLUSIVE</literal> lock, which is self-conflicting, on the
|
|
<structname>pg_collation</structname> system catalog, so only one
|
|
<command>CREATE COLLATION</command> command can run at a time.
|
|
</para>
|
|
|
|
<para>
|
|
Use <command>DROP COLLATION</command> to remove user-defined collations.
|
|
</para>
|
|
|
|
<para>
|
|
See <xref linkend="collation-create"/> for more information on how to create collations.
|
|
</para>
|
|
|
|
<para>
|
|
When using the <literal>libc</literal> collation provider, the locale must
|
|
be applicable to the current database encoding.
|
|
See <xref linkend="sql-createdatabase"/> for the precise rules.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="sql-createcollation-examples">
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
To create a collation from the operating system locale
|
|
<literal>fr_FR.utf8</literal>
|
|
(assuming the current database encoding is <literal>UTF8</literal>):
|
|
<programlisting>
|
|
CREATE COLLATION french (locale = 'fr_FR.utf8');
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
To create a collation using the ICU provider using German phone book sort order:
|
|
<programlisting>
|
|
CREATE COLLATION german_phonebook (provider = icu, locale = 'de-u-co-phonebk');
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
To create a collation from an existing collation:
|
|
<programlisting>
|
|
CREATE COLLATION german FROM "de_DE";
|
|
</programlisting>
|
|
This can be convenient to be able to use operating-system-independent
|
|
collation names in applications.
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1 id="sql-createcollation-compat">
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
There is a <command>CREATE COLLATION</command> statement in the SQL
|
|
standard, but it is limited to copying an existing collation. The
|
|
syntax to create a new collation is
|
|
a <productname>PostgreSQL</productname> extension.
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1 id="sql-createcollation-seealso">
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="sql-altercollation"/></member>
|
|
<member><xref linkend="sql-dropcollation"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
</refentry>
|