diff options
Diffstat (limited to 'doc/src/sgml/ref/create_collation.sgml')
| -rw-r--r-- | doc/src/sgml/ref/create_collation.sgml | 263 |
1 files changed, 263 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/create_collation.sgml b/doc/src/sgml/ref/create_collation.sgml new file mode 100644 index 0000000..58f5f0c --- /dev/null +++ b/doc/src/sgml/ref/create_collation.sgml @@ -0,0 +1,263 @@ +<!-- +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> |