261 lines
7.7 KiB
Plaintext
261 lines
7.7 KiB
Plaintext
<!-- doc/src/sgml/ref/create_collation.sgml -->
|
|
|
|
<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>
|