begriffs open source - ai-pg/blob - full-docs/src/sgml/man7/CREATE_CONVERSION.7

   1 '\" t
   2 .\"     Title: CREATE CONVERSION
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATE CONVERSION" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 CREATE_CONVERSION \- define a new encoding conversion
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE [ DEFAULT ] CONVERSION \fIname\fR
  36     FOR \fIsource_encoding\fR TO \fIdest_encoding\fR FROM \fIfunction_name\fR
  37 .fi
  38 .SH "DESCRIPTION"
  39 .PP
  40 \fBCREATE CONVERSION\fR
  41 defines a new conversion between two character set encodings\&.
  42 .PP
  43 Conversions that are marked
  44 DEFAULT
  45 can be used for automatic encoding conversion between client and server\&. To support that usage, two conversions, from encoding A to B
  46 \fIand\fR
  47 from encoding B to A, must be defined\&.
  48 .PP
  49 To be able to create a conversion, you must have
  50 EXECUTE
  51 privilege on the function and
  52 CREATE
  53 privilege on the destination schema\&.
  54 .SH "PARAMETERS"
  55 .PP
  56 DEFAULT
  57 .RS 4
  58 The
  59 DEFAULT
  60 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\&.
  61 .RE
  62 .PP
  63 \fIname\fR
  64 .RS 4
  65 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\&.
  66 .RE
  67 .PP
  68 \fIsource_encoding\fR
  69 .RS 4
  70 The source encoding name\&.
  71 .RE
  72 .PP
  73 \fIdest_encoding\fR
  74 .RS 4
  75 The destination encoding name\&.
  76 .RE
  77 .PP
  78 \fIfunction_name\fR
  79 .RS 4
  80 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\&.
  81 .sp
  82 The function must have the following signature:
  83 .sp
  84 .if n \{\
  85 .RS 4
  86 .\}
  87 .nf
  88 conv_proc(
  89     integer,  \-\- source encoding ID
  90     integer,  \-\- destination encoding ID
  91     cstring,  \-\- source string (null terminated C string)
  92     internal, \-\- destination (fill with a null terminated C string)
  93     integer,  \-\- source string length
  94     boolean   \-\- if true, don\*(Aqt throw an error if conversion fails
  95 ) RETURNS integer;
  96 .fi
  97 .if n \{\
  98 .RE
  99 .\}
 100 .sp
 101 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\&.
 102 .RE
 103 .SH "NOTES"
 104 .PP
 105 Neither the source nor the destination encoding can be
 106 SQL_ASCII, as the server\*(Aqs behavior for cases involving the
 107 SQL_ASCII
 108 \(lqencoding\(rq
 109 is hard\-wired\&.
 110 .PP
 111 Use
 112 \fBDROP CONVERSION\fR
 113 to remove user\-defined conversions\&.
 114 .PP
 115 The privileges required to create a conversion might be changed in a future release\&.
 116 .SH "EXAMPLES"
 117 .PP
 118 To create a conversion from encoding
 119 UTF8
 120 to
 121 LATIN1
 122 using
 123 \fBmyfunc\fR:
 124 .sp
 125 .if n \{\
 126 .RS 4
 127 .\}
 128 .nf
 129 CREATE CONVERSION myconv FOR \*(AqUTF8\*(Aq TO \*(AqLATIN1\*(Aq FROM myfunc;
 130 .fi
 131 .if n \{\
 132 .RE
 133 .\}
 134 .SH "COMPATIBILITY"
 135 .PP
 136 \fBCREATE CONVERSION\fR
 137 is a
 138 PostgreSQL
 139 extension\&. There is no
 140 \fBCREATE CONVERSION\fR
 141 statement in the SQL standard, but a
 142 \fBCREATE TRANSLATION\fR
 143 statement that is very similar in purpose and syntax\&.
 144 .SH "SEE ALSO"
 145 ALTER CONVERSION (\fBALTER_CONVERSION\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), DROP CONVERSION (\fBDROP_CONVERSION\fR(7))