path: root/doc/src/sgml/man7/ALTER_TYPE.7

'\" 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))