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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
'\" t
.\" Title: CREATE CONVERSION
.\" Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 2024
.\" Manual: PostgreSQL 16.3 Documentation
.\" Source: PostgreSQL 16.3
.\" Language: English
.\"
.TH "CREATE CONVERSION" "7" "2024" "PostgreSQL 16.3" "PostgreSQL 16.3 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
CREATE_CONVERSION \- define a new encoding conversion
.SH "SYNOPSIS"
.sp
.nf
CREATE [ DEFAULT ] CONVERSION \fIname\fR
FOR \fIsource_encoding\fR TO \fIdest_encoding\fR FROM \fIfunction_name\fR
.fi
.SH "DESCRIPTION"
.PP
\fBCREATE CONVERSION\fR
defines a new conversion between two character set encodings\&.
.PP
Conversions that are marked
DEFAULT
can be used for automatic encoding conversion between client and server\&. To support that usage, two conversions, from encoding A to B
\fIand\fR
from encoding B to A, must be defined\&.
.PP
To be able to create a conversion, you must have
EXECUTE
privilege on the function and
CREATE
privilege on the destination schema\&.
.SH "PARAMETERS"
.PP
DEFAULT
.RS 4
The
DEFAULT
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\&.
.RE
.PP
\fIname\fR
.RS 4
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\&.
.RE
.PP
\fIsource_encoding\fR
.RS 4
The source encoding name\&.
.RE
.PP
\fIdest_encoding\fR
.RS 4
The destination encoding name\&.
.RE
.PP
\fIfunction_name\fR
.RS 4
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\&.
.sp
The function must have the following signature:
.sp
.if n \{\
.RS 4
.\}
.nf
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\*(Aqt throw an error if conversion fails
) RETURNS integer;
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.RE
.SH "NOTES"
.PP
Neither the source nor the destination encoding can be
SQL_ASCII, as the server\*(Aqs behavior for cases involving the
SQL_ASCII
\(lqencoding\(rq
is hard\-wired\&.
.PP
Use
\fBDROP CONVERSION\fR
to remove user\-defined conversions\&.
.PP
The privileges required to create a conversion might be changed in a future release\&.
.SH "EXAMPLES"
.PP
To create a conversion from encoding
UTF8
to
LATIN1
using
\fBmyfunc\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
CREATE CONVERSION myconv FOR \*(AqUTF8\*(Aq TO \*(AqLATIN1\*(Aq FROM myfunc;
.fi
.if n \{\
.RE
.\}
.SH "COMPATIBILITY"
.PP
\fBCREATE CONVERSION\fR
is a
PostgreSQL
extension\&. There is no
\fBCREATE CONVERSION\fR
statement in the SQL standard, but a
\fBCREATE TRANSLATION\fR
statement that is very similar in purpose and syntax\&.
.SH "SEE ALSO"
ALTER CONVERSION (\fBALTER_CONVERSION\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), DROP CONVERSION (\fBDROP_CONVERSION\fR(7))
|
