Debian Codegraph @

doc/src/sgml/ref/create_conversion.sgml

raw
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>