codekingpro/portable-devtools

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 16.3 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">3CREATE [ 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 between7   two character set encodings.8  </p><p>9   Conversions that are marked <code class="literal">DEFAULT</code> can be used for10   automatic encoding conversion between client and server.  To support that11   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> privilege15   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 conversion18       is the default for this particular source to destination19       encoding. There should be only one default encoding in a schema20       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 be23       schema-qualified. If it is not, the conversion is defined in the24       current schema. The conversion name must be unique within a25       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 can32       be schema-qualified.  If it is not, the function will be looked33       up in the path.34      </p><p>35       The function must have the following signature:36 37</p><pre class="programlisting">38conv_proc(39    integer,  -- source encoding ID40    integer,  -- destination encoding ID41    cstring,  -- source string (null terminated C string)42    internal, -- destination (fill with a null terminated C string)43    integer,  -- source string length44    boolean   -- if true, don't throw an error if conversion fails45) RETURNS integer;46</pre><p>47       The return value is the number of source bytes that were successfully48       converted. If the last argument is false, the function must throw an49       error on invalid input, and the return value is always equal to the50       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 can53   be <code class="literal">SQL_ASCII</code>, as the server's behavior for cases54   involving the <code class="literal">SQL_ASCII</code> <span class="quote">“<span class="quote">encoding</span>”</span> is55   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 future60   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> to63   <code class="literal">LATIN1</code> using <code class="function">myfunc</code>:64</p><pre class="programlisting">65CREATE 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 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE DATABASE</td></tr></table></div></body></html>