</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 using the ICU provider, based on the root ICU locale,
   with custom rules:
<programlisting>
<![CDATA[CREATE COLLATION custom (provider = icu, locale = 'und', rules = '&V << w <<< W');]]>
</programlisting>
   See <xref linkend="icu-tailoring-rules"/> for further details and examples
   on the rules syntax.
  </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>