granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/create_collation.sgml

   1 <!-- doc/src/sgml/ref/create_collation.sgml -->
   2
   3 <refentry id="SQL-CREATECOLLATION">
   4  <refmeta>
   5   <refentrytitle>CREATE COLLATION</refentrytitle>
   6   <manvolnum>7</manvolnum>
   7   <refmiscinfo>SQL - Language Statements</refmiscinfo>
   8  </refmeta>
   9
  10  <refnamediv>
  11   <refname>CREATE COLLATION</refname>
  12   <refpurpose>define a new collation</refpurpose>
  13  </refnamediv>
  14
  15  <indexterm zone="sql-createcollation">
  16   <primary>CREATE COLLATION</primary>
  17  </indexterm>
  18
  19  <refsynopsisdiv>
  20 <synopsis>
  21 CREATE COLLATION <replaceable>name</replaceable> (
  22     [ LOCALE = <replaceable>locale</replaceable>, ]
  23     [ LC_COLLATE = <replaceable>lc_collate</replaceable>, ]
  24     [ LC_CTYPE = <replaceable>lc_ctype</replaceable> ]
  25 )
  26 CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_collation</replaceable>
  27 </synopsis>
  28  </refsynopsisdiv>
  29
  30  <refsect1 id="sql-createcollation-description">
  31   <title>Description</title>
  32
  33   <para>
  34    <command>CREATE COLLATION</command> defines a new collation using
  35    the specified operating system locale settings,
  36    or by copying an existing collation.
  37  </para>
  38
  39   <para>
  40    To be able to create a collation, you must
  41    have <literal>CREATE</literal> privilege on the destination schema.
  42   </para>
  43  </refsect1>
  44
  45
  46  <refsect1>
  47   <title>Parameters</title>
  48
  49    <variablelist>
  50     <varlistentry>
  51      <term><replaceable>name</replaceable></term>
  52
  53      <listitem>
  54       <para>
  55        The name of the collation. The collation name can be
  56        schema-qualified. If it is not, the collation is defined in the
  57        current schema. The collation name must be unique within that
  58        schema.  (The system catalogs can contain collations with the
  59        same name for other encodings, but these are ignored if the
  60        database encoding does not match.)
  61       </para>
  62      </listitem>
  63     </varlistentry>
  64
  65     <varlistentry>
  66      <term><replaceable>locale</replaceable></term>
  67
  68      <listitem>
  69       <para>
  70        This is a shortcut for setting <symbol>LC_COLLATE</symbol>
  71        and <symbol>LC_CTYPE</symbol> at once.  If you specify this,
  72        you cannot specify either of those parameters.
  73       </para>
  74      </listitem>
  75     </varlistentry>
  76
  77     <varlistentry>
  78      <term><replaceable>lc_collate</replaceable></term>
  79
  80      <listitem>
  81       <para>
  82        Use the specified operating system locale for
  83        the <symbol>LC_COLLATE</symbol> locale category.  The locale
  84        must be applicable to the current database encoding.
  85        (See <xref linkend="sql-createdatabase"> for the precise
  86        rules.)
  87       </para>
  88      </listitem>
  89     </varlistentry>
  90
  91     <varlistentry>
  92      <term><replaceable>lc_ctype</replaceable></term>
  93
  94      <listitem>
  95       <para>
  96        Use the specified operating system locale for
  97        the <symbol>LC_CTYPE</symbol> locale category.  The locale
  98        must be applicable to the current database encoding.
  99        (See <xref linkend="sql-createdatabase"> for the precise
 100        rules.)
 101       </para>
 102      </listitem>
 103     </varlistentry>
 104
 105     <varlistentry>
 106      <term><replaceable>existing_collation</replaceable></term>
 107
 108      <listitem>
 109       <para>
 110        The name of an existing collation to copy.  The new collation
 111        will have the same properties as the existing one, but it
 112        will be an independent object.
 113       </para>
 114      </listitem>
 115     </varlistentry>
 116    </variablelist>
 117  </refsect1>
 118
 119
 120  <refsect1 id="sql-createcollation-notes">
 121   <title>Notes</title>
 122
 123   <para>
 124    Use <command>DROP COLLATION</command> to remove user-defined collations.
 125   </para>
 126
 127   <para>
 128    See <xref linkend="collation"> for more information about collation
 129    support in PostgreSQL.
 130   </para>
 131  </refsect1>
 132
 133  <refsect1 id="sql-createcollation-examples">
 134   <title>Examples</title>
 135
 136   <para>
 137    To create a collation from the operating system locale
 138    <literal>fr_FR.utf8</literal>
 139    (assuming the current database encoding is <literal>UTF8</literal>):
 140 <programlisting>
 141 CREATE COLLATION french (LOCALE = 'fr_FR.utf8');
 142 </programlisting>
 143   </para>
 144
 145   <para>
 146    To create a collation from an existing collation:
 147 <programlisting>
 148 CREATE COLLATION german FROM "de_DE";
 149 </programlisting>
 150    This can be convenient to be able to use operating-system-independent
 151    collation names in applications.
 152   </para>
 153  </refsect1>
 154
 155
 156  <refsect1 id="sql-createcollation-compat">
 157   <title>Compatibility</title>
 158
 159   <para>
 160    There is a <command>CREATE COLLATION</command> statement in the SQL
 161    standard, but it is limited to copying an existing collation.  The
 162    syntax to create a new collation is
 163    a <productname>PostgreSQL</productname> extension.
 164   </para>
 165  </refsect1>
 166
 167
 168  <refsect1 id="sql-createcollation-seealso">
 169   <title>See Also</title>
 170
 171   <simplelist type="inline">
 172    <member><xref linkend="sql-altercollation"></member>
 173    <member><xref linkend="sql-dropcollation"></member>
 174   </simplelist>
 175  </refsect1>
 176
 177 </refentry>