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 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 15.4 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">
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 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 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE DATABASE</td></tr></table></div></body></html>
|
