doc/src/sgml/ref/create_conversion.sgml

   1 <!--
   2 doc/src/sgml/ref/create_conversion.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="sql-createconversion">
   7  <indexterm zone="sql-createconversion">
   8   <primary>CREATE CONVERSION</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle>CREATE CONVERSION</refentrytitle>
  13   <manvolnum>7</manvolnum>
  14   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>CREATE CONVERSION</refname>
  19   <refpurpose>define a new encoding conversion</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 CREATE [ DEFAULT ] CONVERSION <replaceable>name</replaceable>
  25     FOR <replaceable>source_encoding</replaceable> TO <replaceable>dest_encoding</replaceable> FROM <replaceable>function_name</replaceable>
  26 </synopsis>
  27  </refsynopsisdiv>
  28
  29  <refsect1 id="sql-createconversion-description">
  30   <title>Description</title>
  31
  32   <para>
  33    <command>CREATE CONVERSION</command> defines a new conversion between
  34    two character set encodings.
  35   </para>
  36
  37   <para>
  38    Conversions that are marked <literal>DEFAULT</literal> can be used for
  39    automatic encoding conversion between client and server.  To support that
  40    usage, two conversions, from encoding A to B <emphasis>and</emphasis>
  41    from encoding B to A, must be defined.
  42   </para>
  43
  44   <para>
  45    To be able to create a conversion, you must have <literal>EXECUTE</literal> privilege
  46    on the function and <literal>CREATE</literal> privilege on the destination schema.
  47   </para>
  48  </refsect1>
  49
  50
  51  <refsect1>
  52   <title>Parameters</title>
  53
  54    <variablelist>
  55     <varlistentry>
  56      <term><literal>DEFAULT</literal></term>
  57
  58      <listitem>
  59       <para>
  60        The <literal>DEFAULT</literal> clause indicates that this conversion
  61        is the default for this particular source to destination
  62        encoding. There should be only one default encoding in a schema
  63        for the encoding pair.
  64       </para>
  65      </listitem>
  66     </varlistentry>
  67
  68     <varlistentry>
  69      <term><replaceable>name</replaceable></term>
  70
  71      <listitem>
  72       <para>
  73        The name of the conversion. The conversion name can be
  74        schema-qualified. If it is not, the conversion is defined in the
  75        current schema. The conversion name must be unique within a
  76        schema.
  77       </para>
  78      </listitem>
  79     </varlistentry>
  80
  81     <varlistentry>
  82      <term><replaceable>source_encoding</replaceable></term>
  83
  84      <listitem>
  85       <para>
  86        The source encoding name.
  87       </para>
  88      </listitem>
  89     </varlistentry>
  90
  91     <varlistentry>
  92      <term><replaceable>dest_encoding</replaceable></term>
  93
  94      <listitem>
  95       <para>
  96        The destination encoding name.
  97       </para>
  98      </listitem>
  99     </varlistentry>
 100
 101     <varlistentry>
 102      <term><replaceable>function_name</replaceable></term>
 103
 104      <listitem>
 105       <para>
 106        The function used to perform the conversion.  The function name can
 107        be schema-qualified.  If it is not, the function will be looked
 108        up in the path.
 109       </para>
 110
 111       <para>
 112        The function must have the following signature:
 113
 114 <programlisting>
 115 conv_proc(
 116     integer,  -- source encoding ID
 117     integer,  -- destination encoding ID
 118     cstring,  -- source string (null terminated C string)
 119     internal, -- destination (fill with a null terminated C string)
 120     integer,  -- source string length
 121     boolean   -- if true, don't throw an error if conversion fails
 122 ) RETURNS integer;
 123 </programlisting>
 124        The return value is the number of source bytes that were successfully
 125        converted. If the last argument is false, the function must throw an
 126        error on invalid input, and the return value is always equal to the
 127        source string length.
 128       </para>
 129      </listitem>
 130     </varlistentry>
 131    </variablelist>
 132  </refsect1>
 133
 134  <refsect1 id="sql-createconversion-notes">
 135   <title>Notes</title>
 136
 137   <para>
 138    Neither the source nor the destination encoding can
 139    be <literal>SQL_ASCII</literal>, as the server's behavior for cases
 140    involving the <literal>SQL_ASCII</literal> <quote>encoding</quote> is
 141    hard-wired.
 142   </para>
 143
 144   <para>
 145    Use <command>DROP CONVERSION</command> to remove user-defined conversions.
 146   </para>
 147
 148   <para>
 149    The privileges required to create a conversion might be changed in a future
 150    release.
 151   </para>
 152  </refsect1>
 153
 154  <refsect1 id="sql-createconversion-examples">
 155   <title>Examples</title>
 156
 157   <para>
 158    To create a conversion from encoding <literal>UTF8</literal> to
 159    <literal>LATIN1</literal> using <function>myfunc</function>:
 160 <programlisting>
 161 CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc;
 162 </programlisting></para>
 163  </refsect1>
 164
 165
 166  <refsect1 id="sql-createconversion-compat">
 167   <title>Compatibility</title>
 168
 169   <para>
 170     <command>CREATE CONVERSION</command>
 171     is a <productname>PostgreSQL</productname> extension.
 172     There is no <command>CREATE CONVERSION</command>
 173     statement in the SQL standard, but a <command>CREATE TRANSLATION</command>
 174     statement that is very similar in purpose and syntax.
 175   </para>
 176  </refsect1>
 177
 178
 179  <refsect1 id="sql-createconversion-seealso">
 180   <title>See Also</title>
 181
 182   <simplelist type="inline">
 183    <member><xref linkend="sql-alterconversion"/></member>
 184    <member><xref linkend="sql-createfunction"/></member>
 185    <member><xref linkend="sql-dropconversion"/></member>
 186   </simplelist>
 187  </refsect1>
 188
 189 </refentry>