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

   1 '\" t
   2 .\"     Title: ALTER 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 "ALTER 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 ALTER_COLLATION \- change the definition of a collation
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 ALTER COLLATION \fIname\fR REFRESH VERSION
  36
  37 ALTER COLLATION \fIname\fR RENAME TO \fInew_name\fR
  38 ALTER COLLATION \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
  39 ALTER COLLATION \fIname\fR SET SCHEMA \fInew_schema\fR
  40 .fi
  41 .SH "DESCRIPTION"
  42 .PP
  43 \fBALTER COLLATION\fR
  44 changes the definition of a collation\&.
  45 .PP
  46 You must own the collation to use
  47 \fBALTER COLLATION\fR\&. To alter the owner, you must be able to
  48 SET ROLE
  49 to the new owning role, and that role must have
  50 CREATE
  51 privilege on the collation\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the collation\&. However, a superuser can alter ownership of any collation anyway\&.)
  52 .SH "PARAMETERS"
  53 .PP
  54 \fIname\fR
  55 .RS 4
  56 The name (optionally schema\-qualified) of an existing collation\&.
  57 .RE
  58 .PP
  59 \fInew_name\fR
  60 .RS 4
  61 The new name of the collation\&.
  62 .RE
  63 .PP
  64 \fInew_owner\fR
  65 .RS 4
  66 The new owner of the collation\&.
  67 .RE
  68 .PP
  69 \fInew_schema\fR
  70 .RS 4
  71 The new schema for the collation\&.
  72 .RE
  73 .PP
  74 REFRESH VERSION
  75 .RS 4
  76 Update the collation\*(Aqs version\&. See
  77 Notes
  78 below\&.
  79 .RE
  80 .SH "NOTES"
  81 .PP
  82 When a collation object is created, the provider\-specific version of the collation is recorded in the system catalog\&. When the collation is used, the current version is checked against the recorded version, and a warning is issued when there is a mismatch, for example:
  83 .sp
  84 .if n \{\
  85 .RS 4
  86 .\}
  87 .nf
  88 WARNING:  collation "xx\-x\-icu" has version mismatch
  89 DETAIL:  The collation in the database was created using version 1\&.2\&.3\&.4, but the operating system provides version 2\&.3\&.4\&.5\&.
  90 HINT:  Rebuild all objects affected by this collation and run ALTER COLLATION pg_catalog\&."xx\-x\-icu" REFRESH VERSION, or build PostgreSQL with the right library version\&.
  91 .fi
  92 .if n \{\
  93 .RE
  94 .\}
  95 .sp
  96 A change in collation definitions can lead to corrupt indexes and other problems because the database system relies on stored objects having a certain sort order\&. Generally, this should be avoided, but it can happen in legitimate circumstances, such as when upgrading the operating system to a new major version or when using
  97 \fBpg_upgrade\fR
  98 to upgrade to server binaries linked with a newer version of ICU\&. When this happens, all objects depending on the collation should be rebuilt, for example, using
  99 \fBREINDEX\fR\&. When that is done, the collation version can be refreshed using the command
 100 ALTER COLLATION \&.\&.\&. REFRESH VERSION\&. This will update the system catalog to record the current collation version and will make the warning go away\&. Note that this does not actually check whether all affected objects have been rebuilt correctly\&.
 101 .PP
 102 When using collations provided by
 103 libc, version information is recorded on systems using the GNU C library (most Linux systems), FreeBSD and Windows\&. When using collations provided by ICU, the version information is provided by the ICU library and is available on all platforms\&.
 104 .if n \{\
 105 .sp
 106 .\}
 107 .RS 4
 108 .it 1 an-trap
 109 .nr an-no-space-flag 1
 110 .nr an-break-flag 1
 111 .br
 112 .ps +1
 113 \fBNote\fR
 114 .ps -1
 115 .br
 116 .PP
 117 When using the GNU C library for collations, the C library\*(Aqs version is used as a proxy for the collation version\&. Many Linux distributions change collation definitions only when upgrading the C library, but this approach is imperfect as maintainers are free to back\-port newer collation definitions to older C library releases\&.
 118 .PP
 119 When using Windows for collations, version information is only available for collations defined with BCP 47 language tags such as
 120 en\-US\&.
 121 .sp .5v
 122 .RE
 123 .PP
 124 For the database default collation, there is an analogous command
 125 ALTER DATABASE \&.\&.\&. REFRESH COLLATION VERSION\&.
 126 .PP
 127 The following query can be used to identify all collations in the current database that need to be refreshed and the objects that depend on them:
 128 .sp
 129 .if n \{\
 130 .RS 4
 131 .\}
 132 .nf
 133 SELECT pg_describe_object(refclassid, refobjid, refobjsubid) AS "Collation",
 134        pg_describe_object(classid, objid, objsubid) AS "Object"
 135   FROM pg_depend d JOIN pg_collation c
 136        ON refclassid = \*(Aqpg_collation\*(Aq::regclass AND refobjid = c\&.oid
 137   WHERE c\&.collversion <> pg_collation_actual_version(c\&.oid)
 138   ORDER BY 1, 2;
 139 .fi
 140 .if n \{\
 141 .RE
 142 .\}
 143 .SH "EXAMPLES"
 144 .PP
 145 To rename the collation
 146 de_DE
 147 to
 148 german:
 149 .sp
 150 .if n \{\
 151 .RS 4
 152 .\}
 153 .nf
 154 ALTER COLLATION "de_DE" RENAME TO german;
 155 .fi
 156 .if n \{\
 157 .RE
 158 .\}
 159 .PP
 160 To change the owner of the collation
 161 en_US
 162 to
 163 joe:
 164 .sp
 165 .if n \{\
 166 .RS 4
 167 .\}
 168 .nf
 169 ALTER COLLATION "en_US" OWNER TO joe;
 170 .fi
 171 .if n \{\
 172 .RE
 173 .\}
 174 .SH "COMPATIBILITY"
 175 .PP
 176 There is no
 177 \fBALTER COLLATION\fR
 178 statement in the SQL standard\&.
 179 .SH "SEE ALSO"
 180 CREATE COLLATION (\fBCREATE_COLLATION\fR(7)), DROP COLLATION (\fBDROP_COLLATION\fR(7))