<!--
doc/src/sgml/ref/create_conversion.sgml
PostgreSQL documentation
-->

<refentry id="sql-createconversion">
 <indexterm zone="sql-createconversion">
  <primary>CREATE CONVERSION</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>CREATE CONVERSION</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE CONVERSION</refname>
  <refpurpose>define a new encoding conversion</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
CREATE [ DEFAULT ] CONVERSION <replaceable>name</replaceable>
    FOR <replaceable>source_encoding</replaceable> TO <replaceable>dest_encoding</replaceable> FROM <replaceable>function_name</replaceable>
</synopsis>
 </refsynopsisdiv>

 <refsect1 id="sql-createconversion-description">
  <title>Description</title>

  <para>
   <command>CREATE CONVERSION</command> defines a new conversion between
   two character set encodings.
  </para>

  <para>
   Conversions that are marked <literal>DEFAULT</literal> can be used for
   automatic encoding conversion between client and server.  To support that
   usage, two conversions, from encoding A to B <emphasis>and</emphasis>
   from encoding B to A, must be defined.
  </para>

  <para>
   To be able to create a conversion, you must have <literal>EXECUTE</literal> privilege
   on the function and <literal>CREATE</literal> privilege on the destination schema.
  </para>
 </refsect1>


 <refsect1>
  <title>Parameters</title>

   <variablelist>
    <varlistentry>
     <term><literal>DEFAULT</literal></term>

     <listitem>
      <para>
       The <literal>DEFAULT</literal> clause indicates that this conversion
       is the default for this particular source to destination
       encoding. There should be only one default encoding in a schema
       for the encoding pair.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>name</replaceable></term>

     <listitem>
      <para>
       The name of the conversion. The conversion name can be
       schema-qualified. If it is not, the conversion is defined in the
       current schema. The conversion name must be unique within a
       schema.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>source_encoding</replaceable></term>

     <listitem>
      <para>
       The source encoding name.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>dest_encoding</replaceable></term>

     <listitem>
      <para>
       The destination encoding name.
      </para>
     </listitem>
    </varlistentry>