begriffs open source - ai-pg/blob - full-docs/src/sgml/html/sql-createconversion.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE CONVERSION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createcollation.html" title="CREATE COLLATION" /><link rel="next" href="sql-createdatabase.html" title="CREATE DATABASE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE CONVERSION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createcollation.html" title="CREATE COLLATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createdatabase.html" title="CREATE DATABASE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATECONVERSION"><div class="titlepage"></div><a id="id-1.9.3.60.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE CONVERSION</span></h2><p>CREATE CONVERSION — define a new encoding conversion</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 CREATE [ DEFAULT ] CONVERSION <em class="replaceable"><code>name</code></em>
   4     FOR <em class="replaceable"><code>source_encoding</code></em> TO <em class="replaceable"><code>dest_encoding</code></em> FROM <em class="replaceable"><code>function_name</code></em>
   5 </pre></div><div class="refsect1" id="SQL-CREATECONVERSION-DESCRIPTION"><h2>Description</h2><p>
   6    <code class="command">CREATE CONVERSION</code> defines a new conversion between
   7    two character set encodings.
   8   </p><p>
   9    Conversions that are marked <code class="literal">DEFAULT</code> can be used for
  10    automatic encoding conversion between client and server.  To support that
  11    usage, two conversions, from encoding A to B <span class="emphasis"><em>and</em></span>
  12    from encoding B to A, must be defined.
  13   </p><p>
  14    To be able to create a conversion, you must have <code class="literal">EXECUTE</code> privilege
  15    on the function and <code class="literal">CREATE</code> privilege on the destination schema.
  16   </p></div><div class="refsect1" id="id-1.9.3.60.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
  17        The <code class="literal">DEFAULT</code> clause indicates that this conversion
  18        is the default for this particular source to destination
  19        encoding. There should be only one default encoding in a schema
  20        for the encoding pair.
  21       </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
  22        The name of the conversion. The conversion name can be
  23        schema-qualified. If it is not, the conversion is defined in the
  24        current schema. The conversion name must be unique within a
  25        schema.
  26       </p></dd><dt><span class="term"><em class="replaceable"><code>source_encoding</code></em></span></dt><dd><p>
  27        The source encoding name.
  28       </p></dd><dt><span class="term"><em class="replaceable"><code>dest_encoding</code></em></span></dt><dd><p>
  29        The destination encoding name.
  30       </p></dd><dt><span class="term"><em class="replaceable"><code>function_name</code></em></span></dt><dd><p>
  31        The function used to perform the conversion.  The function name can
  32        be schema-qualified.  If it is not, the function will be looked
  33        up in the path.
  34       </p><p>
  35        The function must have the following signature:
  36
  37 </p><pre class="programlisting">
  38 conv_proc(
  39     integer,  -- source encoding ID
  40     integer,  -- destination encoding ID
  41     cstring,  -- source string (null terminated C string)
  42     internal, -- destination (fill with a null terminated C string)
  43     integer,  -- source string length
  44     boolean   -- if true, don't throw an error if conversion fails
  45 ) RETURNS integer;
  46 </pre><p>
  47        The return value is the number of source bytes that were successfully
  48        converted. If the last argument is false, the function must throw an
  49        error on invalid input, and the return value is always equal to the
  50        source string length.
  51       </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATECONVERSION-NOTES"><h2>Notes</h2><p>
  52    Neither the source nor the destination encoding can
  53    be <code class="literal">SQL_ASCII</code>, as the server's behavior for cases
  54    involving the <code class="literal">SQL_ASCII</code> <span class="quote">“<span class="quote">encoding</span>”</span> is
  55    hard-wired.
  56   </p><p>
  57    Use <code class="command">DROP CONVERSION</code> to remove user-defined conversions.
  58   </p><p>
  59    The privileges required to create a conversion might be changed in a future
  60    release.
  61   </p></div><div class="refsect1" id="SQL-CREATECONVERSION-EXAMPLES"><h2>Examples</h2><p>
  62    To create a conversion from encoding <code class="literal">UTF8</code> to
  63    <code class="literal">LATIN1</code> using <code class="function">myfunc</code>:
  64 </p><pre class="programlisting">
  65 CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc;
  66 </pre></div><div class="refsect1" id="SQL-CREATECONVERSION-COMPAT"><h2>Compatibility</h2><p>
  67     <code class="command">CREATE CONVERSION</code>
  68     is a <span class="productname">PostgreSQL</span> extension.
  69     There is no <code class="command">CREATE CONVERSION</code>
  70     statement in the SQL standard, but a <code class="command">CREATE TRANSLATION</code>
  71     statement that is very similar in purpose and syntax.
  72   </p></div><div class="refsect1" id="SQL-CREATECONVERSION-SEEALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterconversion.html" title="ALTER CONVERSION"><span class="refentrytitle">ALTER CONVERSION</span></a>, <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>, <a class="xref" href="sql-dropconversion.html" title="DROP CONVERSION"><span class="refentrytitle">DROP CONVERSION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createcollation.html" title="CREATE COLLATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createdatabase.html" title="CREATE DATABASE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE COLLATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE DATABASE</td></tr></table></div></body></html>