begriffs open source - ai-pg/blob - full-docs/man7/CREATE_COLLATION.7

   1 '\" t
   2 .\"     Title: CREATE COLLATION
   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 COLLATION" "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_COLLATION \- define a new collation
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE COLLATION [ IF NOT EXISTS ] \fIname\fR (
  36     [ LOCALE = \fIlocale\fR, ]
  37     [ LC_COLLATE = \fIlc_collate\fR, ]
  38     [ LC_CTYPE = \fIlc_ctype\fR, ]
  39     [ PROVIDER = \fIprovider\fR, ]
  40     [ DETERMINISTIC = \fIboolean\fR, ]
  41     [ RULES = \fIrules\fR, ]
  42     [ VERSION = \fIversion\fR ]
  43 )
  44 CREATE COLLATION [ IF NOT EXISTS ] \fIname\fR FROM \fIexisting_collation\fR
  45 .fi
  46 .SH "DESCRIPTION"
  47 .PP
  48 \fBCREATE COLLATION\fR
  49 defines a new collation using the specified operating system locale settings, or by copying an existing collation\&.
  50 .PP
  51 To be able to create a collation, you must have
  52 CREATE
  53 privilege on the destination schema\&.
  54 .SH "PARAMETERS"
  55 .PP
  56 IF NOT EXISTS
  57 .RS 4
  58 Do not throw an error if a collation with the same name already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing collation is anything like the one that would have been created\&.
  59 .RE
  60 .PP
  61 \fIname\fR
  62 .RS 4
  63 The name of the collation\&. The collation name can be schema\-qualified\&. If it is not, the collation is defined in the current schema\&. The collation name must be unique within that schema\&. (The system catalogs can contain collations with the same name for other encodings, but these are ignored if the database encoding does not match\&.)
  64 .RE
  65 .PP
  66 \fIlocale\fR
  67 .RS 4
  68 The locale name for this collation\&. See
  69 Section\ \&23.2.2.3.1
  70 and
  71 Section\ \&23.2.2.3.2
  72 for details\&.
  73 .sp
  74 If
  75 \fIprovider\fR
  76 is
  77 libc, this is a shortcut for setting
  78 LC_COLLATE
  79 and
  80 LC_CTYPE
  81 at once\&. If you specify
  82 \fIlocale\fR, you cannot specify either of those parameters\&.
  83 .sp
  84 If
  85 \fIprovider\fR
  86 is
  87 builtin, then
  88 \fIlocale\fR
  89 must be specified and set to either
  90 C,
  91 C\&.UTF\-8
  92 or
  93 PG_UNICODE_FAST\&.
  94 .RE
  95 .PP
  96 \fIlc_collate\fR
  97 .RS 4
  98 If
  99 \fIprovider\fR
 100 is
 101 libc, use the specified operating system locale for the
 102 LC_COLLATE
 103 locale category\&.
 104 .RE
 105 .PP
 106 \fIlc_ctype\fR
 107 .RS 4
 108 If
 109 \fIprovider\fR
 110 is
 111 libc, use the specified operating system locale for the
 112 LC_CTYPE
 113 locale category\&.
 114 .RE
 115 .PP
 116 \fIprovider\fR
 117 .RS 4
 118 Specifies the provider to use for locale services associated with this collation\&. Possible values are
 119 builtin,
 120 icu
 121 (if the server was built with ICU support) or
 122 libc\&.
 123 libc
 124 is the default\&. See
 125 Section\ \&23.1.4
 126 for details\&.
 127 .RE
 128 .PP
 129 DETERMINISTIC
 130 .RS 4
 131 Specifies whether the collation should use deterministic comparisons\&. The default is true\&. A deterministic comparison considers strings that are not byte\-wise equal to be unequal even if they are considered logically equal by the comparison\&. PostgreSQL breaks ties using a byte\-wise comparison\&. Comparison that is not deterministic can make the collation be, say, case\- or accent\-insensitive\&. For that, you need to choose an appropriate
 132 LOCALE
 133 setting
 134 \fIand\fR
 135 set the collation to not deterministic here\&.
 136 .sp
 137 Nondeterministic collations are only supported with the ICU provider\&.
 138 .RE
 139 .PP
 140 \fIrules\fR
 141 .RS 4
 142 Specifies additional collation rules to customize the behavior of the collation\&. This is supported for ICU only\&. See
 143 Section\ \&23.2.3.4
 144 for details\&.
 145 .RE
 146 .PP
 147 \fIversion\fR
 148 .RS 4
 149 Specifies the version string to store with the collation\&. Normally, this should be omitted, which will cause the version to be computed from the actual version of the collation as provided by the operating system\&. This option is intended to be used by
 150 \fBpg_upgrade\fR
 151 for copying the version from an existing installation\&.
 152 .sp
 153 See also
 154 ALTER COLLATION (\fBALTER_COLLATION\fR(7))
 155 for how to handle collation version mismatches\&.
 156 .RE
 157 .PP
 158 \fIexisting_collation\fR
 159 .RS 4
 160 The name of an existing collation to copy\&. The new collation will have the same properties as the existing one, but it will be an independent object\&.
 161 .RE
 162 .SH "NOTES"
 163 .PP
 164 \fBCREATE COLLATION\fR
 165 takes a
 166 SHARE ROW EXCLUSIVE
 167 lock, which is self\-conflicting, on the
 168 pg_collation
 169 system catalog, so only one
 170 \fBCREATE COLLATION\fR
 171 command can run at a time\&.
 172 .PP
 173 Use
 174 \fBDROP COLLATION\fR
 175 to remove user\-defined collations\&.
 176 .PP
 177 See
 178 Section\ \&23.2.2.3
 179 for more information on how to create collations\&.
 180 .PP
 181 When using the
 182 libc
 183 collation provider, the locale must be applicable to the current database encoding\&. See
 184 CREATE DATABASE (\fBCREATE_DATABASE\fR(7))
 185 for the precise rules\&.
 186 .SH "EXAMPLES"
 187 .PP
 188 To create a collation from the operating system locale
 189 fr_FR\&.utf8
 190 (assuming the current database encoding is
 191 UTF8):
 192 .sp
 193 .if n \{\
 194 .RS 4
 195 .\}
 196 .nf
 197 CREATE COLLATION french (locale = \*(Aqfr_FR\&.utf8\*(Aq);
 198 .fi
 199 .if n \{\
 200 .RE
 201 .\}
 202 .PP
 203 To create a collation using the ICU provider using German phone book sort order:
 204 .sp
 205 .if n \{\
 206 .RS 4
 207 .\}
 208 .nf
 209 CREATE COLLATION german_phonebook (provider = icu, locale = \*(Aqde\-u\-co\-phonebk\*(Aq);
 210 .fi
 211 .if n \{\
 212 .RE
 213 .\}
 214 .PP
 215 To create a collation using the ICU provider, based on the root ICU locale, with custom rules:
 216 .sp
 217 .if n \{\
 218 .RS 4
 219 .\}
 220 .nf
 221 CREATE COLLATION custom (provider = icu, locale = \*(Aqund\*(Aq, rules = \*(Aq&V << w <<< W\*(Aq);
 222 .fi
 223 .if n \{\
 224 .RE
 225 .\}
 226 .sp
 227 See
 228 Section\ \&23.2.3.4
 229 for further details and examples on the rules syntax\&.
 230 .PP
 231 To create a collation from an existing collation:
 232 .sp
 233 .if n \{\
 234 .RS 4
 235 .\}
 236 .nf
 237 CREATE COLLATION german FROM "de_DE";
 238 .fi
 239 .if n \{\
 240 .RE
 241 .\}
 242 .sp
 243 This can be convenient to be able to use operating\-system\-independent collation names in applications\&.
 244 .SH "COMPATIBILITY"
 245 .PP
 246 There is a
 247 \fBCREATE COLLATION\fR
 248 statement in the SQL standard, but it is limited to copying an existing collation\&. The syntax to create a new collation is a
 249 PostgreSQL
 250 extension\&.
 251 .SH "SEE ALSO"
 252 ALTER COLLATION (\fBALTER_COLLATION\fR(7)), DROP COLLATION (\fBDROP_COLLATION\fR(7))