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

   1 '\" t
   2 .\"     Title: ALTER TYPE
   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 TYPE" "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_TYPE \- change the definition of a type
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 ALTER TYPE \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
  36 ALTER TYPE \fIname\fR RENAME TO \fInew_name\fR
  37 ALTER TYPE \fIname\fR SET SCHEMA \fInew_schema\fR
  38 ALTER TYPE \fIname\fR RENAME ATTRIBUTE \fIattribute_name\fR TO \fInew_attribute_name\fR [ CASCADE | RESTRICT ]
  39 ALTER TYPE \fIname\fR \fIaction\fR [, \&.\&.\&. ]
  40 ALTER TYPE \fIname\fR ADD VALUE [ IF NOT EXISTS ] \fInew_enum_value\fR [ { BEFORE | AFTER } \fIneighbor_enum_value\fR ]
  41 ALTER TYPE \fIname\fR RENAME VALUE \fIexisting_enum_value\fR TO \fInew_enum_value\fR
  42 ALTER TYPE \fIname\fR SET ( \fIproperty\fR = \fIvalue\fR [, \&.\&.\&. ] )
  43
  44 where \fIaction\fR is one of:
  45
  46     ADD ATTRIBUTE \fIattribute_name\fR \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ CASCADE | RESTRICT ]
  47     DROP ATTRIBUTE [ IF EXISTS ] \fIattribute_name\fR [ CASCADE | RESTRICT ]
  48     ALTER ATTRIBUTE \fIattribute_name\fR [ SET DATA ] TYPE \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ CASCADE | RESTRICT ]
  49 .fi
  50 .SH "DESCRIPTION"
  51 .PP
  52 \fBALTER TYPE\fR
  53 changes the definition of an existing type\&. There are several subforms:
  54 .PP
  55 OWNER
  56 .RS 4
  57 This form changes the owner of the type\&.
  58 .RE
  59 .PP
  60 RENAME
  61 .RS 4
  62 This form changes the name of the type\&.
  63 .RE
  64 .PP
  65 SET SCHEMA
  66 .RS 4
  67 This form moves the type into another schema\&.
  68 .RE
  69 .PP
  70 RENAME ATTRIBUTE
  71 .RS 4
  72 This form is only usable with composite types\&. It changes the name of an individual attribute of the type\&.
  73 .RE
  74 .PP
  75 ADD ATTRIBUTE
  76 .RS 4
  77 This form adds a new attribute to a composite type, using the same syntax as
  78 \fBCREATE TYPE\fR\&.
  79 .RE
  80 .PP
  81 DROP ATTRIBUTE [ IF EXISTS ]
  82 .RS 4
  83 This form drops an attribute from a composite type\&. If
  84 IF EXISTS
  85 is specified and the attribute does not exist, no error is thrown\&. In this case a notice is issued instead\&.
  86 .RE
  87 .PP
  88 ALTER ATTRIBUTE \&.\&.\&. SET DATA TYPE
  89 .RS 4
  90 This form changes the type of an attribute of a composite type\&.
  91 .RE
  92 .PP
  93 ADD VALUE [ IF NOT EXISTS ] [ BEFORE | AFTER ]
  94 .RS 4
  95 This form adds a new value to an enum type\&. The new value\*(Aqs place in the enum\*(Aqs ordering can be specified as being
  96 BEFORE
  97 or
  98 AFTER
  99 one of the existing values\&. Otherwise, the new item is added at the end of the list of values\&.
 100 .sp
 101 If
 102 IF NOT EXISTS
 103 is specified, it is not an error if the type already contains the new value: a notice is issued but no other action is taken\&. Otherwise, an error will occur if the new value is already present\&.
 104 .RE
 105 .PP
 106 RENAME VALUE
 107 .RS 4
 108 This form renames a value of an enum type\&. The value\*(Aqs place in the enum\*(Aqs ordering is not affected\&. An error will occur if the specified value is not present or the new name is already present\&.
 109 .RE
 110 .PP
 111 SET ( \fIproperty\fR = \fIvalue\fR [, \&.\&.\&. ] )
 112 .RS 4
 113 This form is only applicable to base types\&. It allows adjustment of a subset of the base\-type properties that can be set in
 114 \fBCREATE TYPE\fR\&. Specifically, these properties can be changed:
 115 .sp
 116 .RS 4
 117 .ie n \{\
 118 \h'-04'\(bu\h'+03'\c
 119 .\}
 120 .el \{\
 121 .sp -1
 122 .IP \(bu 2.3
 123 .\}
 124 RECEIVE
 125 can be set to the name of a binary input function, or
 126 NONE
 127 to remove the type\*(Aqs binary input function\&. Using this option requires superuser privilege\&.
 128 .RE
 129 .sp
 130 .RS 4
 131 .ie n \{\
 132 \h'-04'\(bu\h'+03'\c
 133 .\}
 134 .el \{\
 135 .sp -1
 136 .IP \(bu 2.3
 137 .\}
 138 SEND
 139 can be set to the name of a binary output function, or
 140 NONE
 141 to remove the type\*(Aqs binary output function\&. Using this option requires superuser privilege\&.
 142 .RE
 143 .sp
 144 .RS 4
 145 .ie n \{\
 146 \h'-04'\(bu\h'+03'\c
 147 .\}
 148 .el \{\
 149 .sp -1
 150 .IP \(bu 2.3
 151 .\}
 152 TYPMOD_IN
 153 can be set to the name of a type modifier input function, or
 154 NONE
 155 to remove the type\*(Aqs type modifier input function\&. Using this option requires superuser privilege\&.
 156 .RE
 157 .sp
 158 .RS 4
 159 .ie n \{\
 160 \h'-04'\(bu\h'+03'\c
 161 .\}
 162 .el \{\
 163 .sp -1
 164 .IP \(bu 2.3
 165 .\}
 166 TYPMOD_OUT
 167 can be set to the name of a type modifier output function, or
 168 NONE
 169 to remove the type\*(Aqs type modifier output function\&. Using this option requires superuser privilege\&.
 170 .RE
 171 .sp
 172 .RS 4
 173 .ie n \{\
 174 \h'-04'\(bu\h'+03'\c
 175 .\}
 176 .el \{\
 177 .sp -1
 178 .IP \(bu 2.3
 179 .\}
 180 ANALYZE
 181 can be set to the name of a type\-specific statistics collection function, or
 182 NONE
 183 to remove the type\*(Aqs statistics collection function\&. Using this option requires superuser privilege\&.
 184 .RE
 185 .sp
 186 .RS 4
 187 .ie n \{\
 188 \h'-04'\(bu\h'+03'\c
 189 .\}
 190 .el \{\
 191 .sp -1
 192 .IP \(bu 2.3
 193 .\}
 194 SUBSCRIPT
 195 can be set to the name of a type\-specific subscripting handler function, or
 196 NONE
 197 to remove the type\*(Aqs subscripting handler function\&. Using this option requires superuser privilege\&.
 198 .RE
 199 .sp
 200 .RS 4
 201 .ie n \{\
 202 \h'-04'\(bu\h'+03'\c
 203 .\}
 204 .el \{\
 205 .sp -1
 206 .IP \(bu 2.3
 207 .\}
 208 STORAGE
 209 can be set to
 210 plain,
 211 extended,
 212 external, or
 213 main
 214 (see
 215 Section\ \&66.2
 216 for more information about what these mean)\&. However, changing from
 217 plain
 218 to another setting requires superuser privilege (because it requires that the type\*(Aqs C functions all be TOAST\-ready), and changing to
 219 plain
 220 from another setting is not allowed at all (since the type may already have TOASTed values present in the database)\&. Note that changing this option doesn\*(Aqt by itself change any stored data, it just sets the default TOAST strategy to be used for table columns created in the future\&. See
 221 ALTER TABLE (\fBALTER_TABLE\fR(7))
 222 to change the TOAST strategy for existing table columns\&.
 223 .RE
 224 .sp
 225 See
 226 CREATE TYPE (\fBCREATE_TYPE\fR(7))
 227 for more details about these type properties\&. Note that where appropriate, a change in these properties for a base type will be propagated automatically to domains based on that type\&.
 228 .RE
 229 .PP
 230 The
 231 ADD ATTRIBUTE,
 232 DROP ATTRIBUTE, and
 233 ALTER ATTRIBUTE
 234 actions can be combined into a list of multiple alterations to apply in parallel\&. For example, it is possible to add several attributes and/or alter the type of several attributes in a single command\&.
 235 .PP
 236 You must own the type to use
 237 \fBALTER TYPE\fR\&. To change the schema of a type, you must also have
 238 CREATE
 239 privilege on the new schema\&. To alter the owner, you must be able to
 240 SET ROLE
 241 to the new owning role, and that role must have
 242 CREATE
 243 privilege on the type\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the type\&. However, a superuser can alter ownership of any type anyway\&.) To add an attribute or alter an attribute type, you must also have
 244 USAGE
 245 privilege on the attribute\*(Aqs data type\&.
 246 .SH "PARAMETERS"
 247 .PP
 248 .PP
 249 \fIname\fR
 250 .RS 4
 251 The name (possibly schema\-qualified) of an existing type to alter\&.
 252 .RE
 253 .PP
 254 \fInew_name\fR
 255 .RS 4
 256 The new name for the type\&.
 257 .RE
 258 .PP
 259 \fInew_owner\fR
 260 .RS 4
 261 The user name of the new owner of the type\&.
 262 .RE
 263 .PP
 264 \fInew_schema\fR
 265 .RS 4
 266 The new schema for the type\&.
 267 .RE
 268 .PP
 269 \fIattribute_name\fR
 270 .RS 4
 271 The name of the attribute to add, alter, or drop\&.
 272 .RE
 273 .PP
 274 \fInew_attribute_name\fR
 275 .RS 4
 276 The new name of the attribute to be renamed\&.
 277 .RE
 278 .PP
 279 \fIdata_type\fR
 280 .RS 4
 281 The data type of the attribute to add, or the new type of the attribute to alter\&.
 282 .RE
 283 .PP
 284 \fInew_enum_value\fR
 285 .RS 4
 286 The new value to be added to an enum type\*(Aqs list of values, or the new name to be given to an existing value\&. Like all enum literals, it needs to be quoted\&.
 287 .RE
 288 .PP
 289 \fIneighbor_enum_value\fR
 290 .RS 4
 291 The existing enum value that the new value should be added immediately before or after in the enum type\*(Aqs sort ordering\&. Like all enum literals, it needs to be quoted\&.
 292 .RE
 293 .PP
 294 \fIexisting_enum_value\fR
 295 .RS 4
 296 The existing enum value that should be renamed\&. Like all enum literals, it needs to be quoted\&.
 297 .RE
 298 .PP
 299 \fIproperty\fR
 300 .RS 4
 301 The name of a base\-type property to be modified; see above for possible values\&.
 302 .RE
 303 .PP
 304 CASCADE
 305 .RS 4
 306 Automatically propagate the operation to typed tables of the type being altered, and their descendants\&.
 307 .RE
 308 .PP
 309 RESTRICT
 310 .RS 4
 311 Refuse the operation if the type being altered is the type of a typed table\&. This is the default\&.
 312 .RE
 313 .SH "NOTES"
 314 .PP
 315 If
 316 \fBALTER TYPE \&.\&.\&. ADD VALUE\fR
 317 (the form that adds a new value to an enum type) is executed inside a transaction block, the new value cannot be used until after the transaction has been committed\&.
 318 .PP
 319 Comparisons involving an added enum value will sometimes be slower than comparisons involving only original members of the enum type\&. This will usually only occur if
 320 BEFORE
 321 or
 322 AFTER
 323 is used to set the new value\*(Aqs sort position somewhere other than at the end of the list\&. However, sometimes it will happen even though the new value is added at the end (this occurs if the OID counter
 324 \(lqwrapped around\(rq
 325 since the original creation of the enum type)\&. The slowdown is usually insignificant; but if it matters, optimal performance can be regained by dropping and recreating the enum type, or by dumping and restoring the database\&.
 326 .SH "EXAMPLES"
 327 .PP
 328 To rename a data type:
 329 .sp
 330 .if n \{\
 331 .RS 4
 332 .\}
 333 .nf
 334 ALTER TYPE electronic_mail RENAME TO email;
 335 .fi
 336 .if n \{\
 337 .RE
 338 .\}
 339 .PP
 340 To change the owner of the type
 341 email
 342 to
 343 joe:
 344 .sp
 345 .if n \{\
 346 .RS 4
 347 .\}
 348 .nf
 349 ALTER TYPE email OWNER TO joe;
 350 .fi
 351 .if n \{\
 352 .RE
 353 .\}
 354 .PP
 355 To change the schema of the type
 356 email
 357 to
 358 customers:
 359 .sp
 360 .if n \{\
 361 .RS 4
 362 .\}
 363 .nf
 364 ALTER TYPE email SET SCHEMA customers;
 365 .fi
 366 .if n \{\
 367 .RE
 368 .\}
 369 .PP
 370 To add a new attribute to a composite type:
 371 .sp
 372 .if n \{\
 373 .RS 4
 374 .\}
 375 .nf
 376 ALTER TYPE compfoo ADD ATTRIBUTE f3 int;
 377 .fi
 378 .if n \{\
 379 .RE
 380 .\}
 381 .PP
 382 To add a new value to an enum type in a particular sort position:
 383 .sp
 384 .if n \{\
 385 .RS 4
 386 .\}
 387 .nf
 388 ALTER TYPE colors ADD VALUE \*(Aqorange\*(Aq AFTER \*(Aqred\*(Aq;
 389 .fi
 390 .if n \{\
 391 .RE
 392 .\}
 393 .PP
 394 To rename an enum value:
 395 .sp
 396 .if n \{\
 397 .RS 4
 398 .\}
 399 .nf
 400 ALTER TYPE colors RENAME VALUE \*(Aqpurple\*(Aq TO \*(Aqmauve\*(Aq;
 401 .fi
 402 .if n \{\
 403 .RE
 404 .\}
 405 .PP
 406 To create binary I/O functions for an existing base type:
 407 .sp
 408 .if n \{\
 409 .RS 4
 410 .\}
 411 .nf
 412 CREATE FUNCTION mytypesend(mytype) RETURNS bytea \&.\&.\&.;
 413 CREATE FUNCTION mytyperecv(internal, oid, integer) RETURNS mytype \&.\&.\&.;
 414 ALTER TYPE mytype SET (
 415     SEND = mytypesend,
 416     RECEIVE = mytyperecv
 417 );
 418 .fi
 419 .if n \{\
 420 .RE
 421 .\}
 422 .SH "COMPATIBILITY"
 423 .PP
 424 The variants to add and drop attributes are part of the SQL standard; the other variants are PostgreSQL extensions\&.
 425 .SH "SEE ALSO"
 426 CREATE TYPE (\fBCREATE_TYPE\fR(7)), DROP TYPE (\fBDROP_TYPE\fR(7))