diff options
Diffstat (limited to 'doc/src/sgml/man7/ALTER_TYPE.7')
| -rw-r--r-- | doc/src/sgml/man7/ALTER_TYPE.7 | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/doc/src/sgml/man7/ALTER_TYPE.7 b/doc/src/sgml/man7/ALTER_TYPE.7 new file mode 100644 index 0000000..58becdb --- /dev/null +++ b/doc/src/sgml/man7/ALTER_TYPE.7 @@ -0,0 +1,424 @@ +'\" t +.\" Title: ALTER TYPE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER TYPE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 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" +ALTER_TYPE \- change the definition of a type +.SH "SYNOPSIS" +.sp +.nf +ALTER TYPE \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER TYPE \fIname\fR RENAME TO \fInew_name\fR +ALTER TYPE \fIname\fR SET SCHEMA \fInew_schema\fR +ALTER TYPE \fIname\fR RENAME ATTRIBUTE \fIattribute_name\fR TO \fInew_attribute_name\fR [ CASCADE | RESTRICT ] +ALTER TYPE \fIname\fR \fIaction\fR [, \&.\&.\&. ] +ALTER TYPE \fIname\fR ADD VALUE [ IF NOT EXISTS ] \fInew_enum_value\fR [ { BEFORE | AFTER } \fIneighbor_enum_value\fR ] +ALTER TYPE \fIname\fR RENAME VALUE \fIexisting_enum_value\fR TO \fInew_enum_value\fR +ALTER TYPE \fIname\fR SET ( \fIproperty\fR = \fIvalue\fR [, \&.\&.\&. ] ) + +where \fIaction\fR is one of: + + ADD ATTRIBUTE \fIattribute_name\fR \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ CASCADE | RESTRICT ] + DROP ATTRIBUTE [ IF EXISTS ] \fIattribute_name\fR [ CASCADE | RESTRICT ] + ALTER ATTRIBUTE \fIattribute_name\fR [ SET DATA ] TYPE \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBALTER TYPE\fR +changes the definition of an existing type\&. There are several subforms: +.PP +OWNER +.RS 4 +This form changes the owner of the type\&. +.RE +.PP +RENAME +.RS 4 +This form changes the name of the type\&. +.RE +.PP +SET SCHEMA +.RS 4 +This form moves the type into another schema\&. +.RE +.PP +RENAME ATTRIBUTE +.RS 4 +This form is only usable with composite types\&. It changes the name of an individual attribute of the type\&. +.RE +.PP +ADD ATTRIBUTE +.RS 4 +This form adds a new attribute to a composite type, using the same syntax as +\fBCREATE TYPE\fR\&. +.RE +.PP +DROP ATTRIBUTE [ IF EXISTS ] +.RS 4 +This form drops an attribute from a composite type\&. If +IF EXISTS +is specified and the attribute does not exist, no error is thrown\&. In this case a notice is issued instead\&. +.RE +.PP +ALTER ATTRIBUTE \&.\&.\&. SET DATA TYPE +.RS 4 +This form changes the type of an attribute of a composite type\&. +.RE +.PP +ADD VALUE [ IF NOT EXISTS ] [ BEFORE | AFTER ] +.RS 4 +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 +BEFORE +or +AFTER +one of the existing values\&. Otherwise, the new item is added at the end of the list of values\&. +.sp +If +IF NOT EXISTS +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\&. +.RE +.PP +RENAME VALUE +.RS 4 +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\&. +.RE +.PP +SET ( \fIproperty\fR = \fIvalue\fR [, \&.\&.\&. ] ) +.RS 4 +This form is only applicable to base types\&. It allows adjustment of a subset of the base\-type properties that can be set in +\fBCREATE TYPE\fR\&. Specifically, these properties can be changed: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +RECEIVE +can be set to the name of a binary input function, or +NONE +to remove the type\*(Aqs binary input function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SEND +can be set to the name of a binary output function, or +NONE +to remove the type\*(Aqs binary output function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TYPMOD_IN +can be set to the name of a type modifier input function, or +NONE +to remove the type\*(Aqs type modifier input function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TYPMOD_OUT +can be set to the name of a type modifier output function, or +NONE +to remove the type\*(Aqs type modifier output function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ANALYZE +can be set to the name of a type\-specific statistics collection function, or +NONE +to remove the type\*(Aqs statistics collection function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SUBSCRIPT +can be set to the name of a type\-specific subscripting handler function, or +NONE +to remove the type\*(Aqs subscripting handler function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +STORAGE +can be set to +plain, +extended, +external, or +main +(see +Section\ \&73.2 +for more information about what these mean)\&. However, changing from +plain +to another setting requires superuser privilege (because it requires that the type\*(Aqs C functions all be TOAST\-ready), and changing to +plain +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 +ALTER TABLE (\fBALTER_TABLE\fR(7)) +to change the TOAST strategy for existing table columns\&. +.RE +.sp +See +CREATE TYPE (\fBCREATE_TYPE\fR(7)) +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\&. +.RE +.PP +The +ADD ATTRIBUTE, +DROP ATTRIBUTE, and +ALTER ATTRIBUTE +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\&. +.PP +You must own the type to use +\fBALTER TYPE\fR\&. To change the schema of a type, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +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 +USAGE +privilege on the attribute\*(Aqs data type\&. +.SH "PARAMETERS" +.PP +.PP +\fIname\fR +.RS 4 +The name (possibly schema\-qualified) of an existing type to alter\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the type\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the type\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the type\&. +.RE +.PP +\fIattribute_name\fR +.RS 4 +The name of the attribute to add, alter, or drop\&. +.RE +.PP +\fInew_attribute_name\fR +.RS 4 +The new name of the attribute to be renamed\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The data type of the attribute to add, or the new type of the attribute to alter\&. +.RE +.PP +\fInew_enum_value\fR +.RS 4 +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\&. +.RE +.PP +\fIneighbor_enum_value\fR +.RS 4 +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\&. +.RE +.PP +\fIexisting_enum_value\fR +.RS 4 +The existing enum value that should be renamed\&. Like all enum literals, it needs to be quoted\&. +.RE +.PP +\fIproperty\fR +.RS 4 +The name of a base\-type property to be modified; see above for possible values\&. +.RE +.PP +CASCADE +.RS 4 +Automatically propagate the operation to typed tables of the type being altered, and their descendants\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse the operation if the type being altered is the type of a typed table\&. This is the default\&. +.RE +.SH "NOTES" +.PP +If +\fBALTER TYPE \&.\&.\&. ADD VALUE\fR +(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\&. +.PP +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 +BEFORE +or +AFTER +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 +\(lqwrapped around\(rq +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\&. +.SH "EXAMPLES" +.PP +To rename a data type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE electronic_mail RENAME TO email; +.fi +.if n \{\ +.RE +.\} +.PP +To change the owner of the type +email +to +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE email OWNER TO joe; +.fi +.if n \{\ +.RE +.\} +.PP +To change the schema of the type +email +to +customers: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE email SET SCHEMA customers; +.fi +.if n \{\ +.RE +.\} +.PP +To add a new attribute to a composite type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE compfoo ADD ATTRIBUTE f3 int; +.fi +.if n \{\ +.RE +.\} +.PP +To add a new value to an enum type in a particular sort position: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE colors ADD VALUE \*(Aqorange\*(Aq AFTER \*(Aqred\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +To rename an enum value: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE colors RENAME VALUE \*(Aqpurple\*(Aq TO \*(Aqmauve\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +To create binary I/O functions for an existing base type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION mytypesend(mytype) RETURNS bytea \&.\&.\&.; +CREATE FUNCTION mytyperecv(internal, oid, integer) RETURNS mytype \&.\&.\&.; +ALTER TYPE mytype SET ( + SEND = mytypesend, + RECEIVE = mytyperecv +); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The variants to add and drop attributes are part of the SQL standard; the other variants are PostgreSQL extensions\&. +.SH "SEE ALSO" +CREATE TYPE (\fBCREATE_TYPE\fR(7)), DROP TYPE (\fBDROP_TYPE\fR(7)) |