summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/sql-createconversion.html
blob: 726ccb42c9d53b659e2f8914317208760c717c97 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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 xmlns="http://www.w3.org/TR/xhtml1/transitional" 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 14.5 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></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">
CREATE [ DEFAULT ] CONVERSION <em class="replaceable"><code>name</code></em>
    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>
</pre></div><div class="refsect1" id="SQL-CREATECONVERSION-DESCRIPTION"><h2>Description</h2><p>
   <code class="command">CREATE CONVERSION</code> defines a new conversion between
   two character set encodings.
  </p><p>
   Conversions that are marked <code class="literal">DEFAULT</code> can be used for
   automatic encoding conversion between client and server.  To support that
   usage, two conversions, from encoding A to B <span class="emphasis"><em>and</em></span>
   from encoding B to A, must be defined.
  </p><p>
   To be able to create a conversion, you must have <code class="literal">EXECUTE</code> privilege
   on the function and <code class="literal">CREATE</code> privilege on the destination schema.
  </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>
       The <code class="literal">DEFAULT</code> 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.
      </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
       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.
      </p></dd><dt><span class="term"><em class="replaceable"><code>source_encoding</code></em></span></dt><dd><p>
       The source encoding name.
      </p></dd><dt><span class="term"><em class="replaceable"><code>dest_encoding</code></em></span></dt><dd><p>
       The destination encoding name.
      </p></dd><dt><span class="term"><em class="replaceable"><code>function_name</code></em></span></dt><dd><p>
       The function used to perform the conversion.  The function name can
       be schema-qualified.  If it is not, the function will be looked
       up in the path.
      </p><p>
       The function must have the following signature:

</p><pre class="programlisting">
conv_proc(
    integer,  -- source encoding ID
    integer,  -- destination encoding ID
    cstring,  -- source string (null terminated C string)
    internal, -- destination (fill with a null terminated C string)
    integer,  -- source string length
    boolean   -- if true, don't throw an error if conversion fails
) RETURNS integer;
</pre><p>
       The return value is the number of source bytes that were successfully
       converted. If the last argument is false, the function must throw an
       error on invalid input, and the return value is always equal to the
       source string length.
      </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATECONVERSION-NOTES"><h2>Notes</h2><p>
   Neither the source nor the destination encoding can
   be <code class="literal">SQL_ASCII</code>, as the server's behavior for cases
   involving the <code class="literal">SQL_ASCII</code> <span class="quote"><span class="quote">encoding</span></span> is
   hard-wired.
  </p><p>
   Use <code class="command">DROP CONVERSION</code> to remove user-defined conversions.
  </p><p>
   The privileges required to create a conversion might be changed in a future
   release.
  </p></div><div class="refsect1" id="SQL-CREATECONVERSION-EXAMPLES"><h2>Examples</h2><p>
   To create a conversion from encoding <code class="literal">UTF8</code> to
   <code class="literal">LATIN1</code> using <code class="function">myfunc</code>:
</p><pre class="programlisting">
CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc;
</pre></div><div class="refsect1" id="SQL-CREATECONVERSION-COMPAT"><h2>Compatibility</h2><p>
    <code class="command">CREATE CONVERSION</code>
    is a <span class="productname">PostgreSQL</span> extension.
    There is no <code class="command">CREATE CONVERSION</code>
    statement in the SQL standard, but a <code class="command">CREATE TRANSLATION</code>
    statement that is very similar in purpose and syntax.
  </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 xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></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 14.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE DATABASE</td></tr></table></div></body></html>