begriffs open source - ai-pg/blob - full-docs/txt/sql-altertype.txt

   1
   2 ALTER TYPE
   3
   4    ALTER TYPE — change the definition of a type
   5
   6 Synopsis
   7
   8 ALTER TYPE name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USE
   9 R }
  10 ALTER TYPE name RENAME TO new_name
  11 ALTER TYPE name SET SCHEMA new_schema
  12 ALTER TYPE name RENAME ATTRIBUTE attribute_name TO new_attribute_name [ CASCADE
  13 | RESTRICT ]
  14 ALTER TYPE name action [, ... ]
  15 ALTER TYPE name ADD VALUE [ IF NOT EXISTS ] new_enum_value [ { BEFORE | AFTER }
  16 neighbor_enum_value ]
  17 ALTER TYPE name RENAME VALUE existing_enum_value TO new_enum_value
  18 ALTER TYPE name SET ( property = value [, ... ] )
  19
  20 where action is one of:
  21
  22     ADD ATTRIBUTE attribute_name data_type [ COLLATE collation ] [ CASCADE | RES
  23 TRICT ]
  24     DROP ATTRIBUTE [ IF EXISTS ] attribute_name [ CASCADE | RESTRICT ]
  25     ALTER ATTRIBUTE attribute_name [ SET DATA ] TYPE data_type [ COLLATE collati
  26 on ] [ CASCADE | RESTRICT ]
  27
  28 Description
  29
  30    ALTER TYPE changes the definition of an existing type. There are
  31    several subforms:
  32
  33    OWNER
  34           This form changes the owner of the type.
  35
  36    RENAME
  37           This form changes the name of the type.
  38
  39    SET SCHEMA
  40           This form moves the type into another schema.
  41
  42    RENAME ATTRIBUTE
  43           This form is only usable with composite types. It changes the
  44           name of an individual attribute of the type.
  45
  46    ADD ATTRIBUTE
  47           This form adds a new attribute to a composite type, using the
  48           same syntax as CREATE TYPE.
  49
  50    DROP ATTRIBUTE [ IF EXISTS ]
  51           This form drops an attribute from a composite type. If IF EXISTS
  52           is specified and the attribute does not exist, no error is
  53           thrown. In this case a notice is issued instead.
  54
  55    ALTER ATTRIBUTE ... SET DATA TYPE
  56           This form changes the type of an attribute of a composite type.
  57
  58    ADD VALUE [ IF NOT EXISTS ] [ BEFORE | AFTER ]
  59           This form adds a new value to an enum type. The new value's
  60           place in the enum's ordering can be specified as being BEFORE or
  61           AFTER one of the existing values. Otherwise, the new item is
  62           added at the end of the list of values.
  63
  64           If IF NOT EXISTS is specified, it is not an error if the type
  65           already contains the new value: a notice is issued but no other
  66           action is taken. Otherwise, an error will occur if the new value
  67           is already present.
  68
  69    RENAME VALUE
  70           This form renames a value of an enum type. The value's place in
  71           the enum's ordering is not affected. An error will occur if the
  72           specified value is not present or the new name is already
  73           present.
  74
  75    SET ( property = value [, ... ] )
  76           This form is only applicable to base types. It allows adjustment
  77           of a subset of the base-type properties that can be set in
  78           CREATE TYPE. Specifically, these properties can be changed:
  79
  80           + RECEIVE can be set to the name of a binary input function, or
  81             NONE to remove the type's binary input function. Using this
  82             option requires superuser privilege.
  83           + SEND can be set to the name of a binary output function, or
  84             NONE to remove the type's binary output function. Using this
  85             option requires superuser privilege.
  86           + TYPMOD_IN can be set to the name of a type modifier input
  87             function, or NONE to remove the type's type modifier input
  88             function. Using this option requires superuser privilege.
  89           + TYPMOD_OUT can be set to the name of a type modifier output
  90             function, or NONE to remove the type's type modifier output
  91             function. Using this option requires superuser privilege.
  92           + ANALYZE can be set to the name of a type-specific statistics
  93             collection function, or NONE to remove the type's statistics
  94             collection function. Using this option requires superuser
  95             privilege.
  96           + SUBSCRIPT can be set to the name of a type-specific
  97             subscripting handler function, or NONE to remove the type's
  98             subscripting handler function. Using this option requires
  99             superuser privilege.
 100           + STORAGE can be set to plain, extended, external, or main (see
 101             Section 66.2 for more information about what these mean).
 102             However, changing from plain to another setting requires
 103             superuser privilege (because it requires that the type's C
 104             functions all be TOAST-ready), and changing to plain from
 105             another setting is not allowed at all (since the type may
 106             already have TOASTed values present in the database). Note
 107             that changing this option doesn't by itself change any stored
 108             data, it just sets the default TOAST strategy to be used for
 109             table columns created in the future. See ALTER TABLE to change
 110             the TOAST strategy for existing table columns.
 111
 112           See CREATE TYPE for more details about these type properties.
 113           Note that where appropriate, a change in these properties for a
 114           base type will be propagated automatically to domains based on
 115           that type.
 116
 117    The ADD ATTRIBUTE, DROP ATTRIBUTE, and ALTER ATTRIBUTE actions can be
 118    combined into a list of multiple alterations to apply in parallel. For
 119    example, it is possible to add several attributes and/or alter the type
 120    of several attributes in a single command.
 121
 122    You must own the type to use ALTER TYPE. To change the schema of a
 123    type, you must also have CREATE privilege on the new schema. To alter
 124    the owner, you must be able to SET ROLE to the new owning role, and
 125    that role must have CREATE privilege on the type's schema. (These
 126    restrictions enforce that altering the owner doesn't do anything you
 127    couldn't do by dropping and recreating the type. However, a superuser
 128    can alter ownership of any type anyway.) To add an attribute or alter
 129    an attribute type, you must also have USAGE privilege on the
 130    attribute's data type.
 131
 132 Parameters
 133
 134    name
 135           The name (possibly schema-qualified) of an existing type to
 136           alter.
 137
 138    new_name
 139           The new name for the type.
 140
 141    new_owner
 142           The user name of the new owner of the type.
 143
 144    new_schema
 145           The new schema for the type.
 146
 147    attribute_name
 148           The name of the attribute to add, alter, or drop.
 149
 150    new_attribute_name
 151           The new name of the attribute to be renamed.
 152
 153    data_type
 154           The data type of the attribute to add, or the new type of the
 155           attribute to alter.
 156
 157    new_enum_value
 158           The new value to be added to an enum type's list of values, or
 159           the new name to be given to an existing value. Like all enum
 160           literals, it needs to be quoted.
 161
 162    neighbor_enum_value
 163           The existing enum value that the new value should be added
 164           immediately before or after in the enum type's sort ordering.
 165           Like all enum literals, it needs to be quoted.
 166
 167    existing_enum_value
 168           The existing enum value that should be renamed. Like all enum
 169           literals, it needs to be quoted.
 170
 171    property
 172           The name of a base-type property to be modified; see above for
 173           possible values.
 174
 175    CASCADE
 176           Automatically propagate the operation to typed tables of the
 177           type being altered, and their descendants.
 178
 179    RESTRICT
 180           Refuse the operation if the type being altered is the type of a
 181           typed table. This is the default.
 182
 183 Notes
 184
 185    If ALTER TYPE ... ADD VALUE (the form that adds a new value to an enum
 186    type) is executed inside a transaction block, the new value cannot be
 187    used until after the transaction has been committed.
 188
 189    Comparisons involving an added enum value will sometimes be slower than
 190    comparisons involving only original members of the enum type. This will
 191    usually only occur if BEFORE or AFTER is used to set the new value's
 192    sort position somewhere other than at the end of the list. However,
 193    sometimes it will happen even though the new value is added at the end
 194    (this occurs if the OID counter “wrapped around” since the original
 195    creation of the enum type). The slowdown is usually insignificant; but
 196    if it matters, optimal performance can be regained by dropping and
 197    recreating the enum type, or by dumping and restoring the database.
 198
 199 Examples
 200
 201    To rename a data type:
 202 ALTER TYPE electronic_mail RENAME TO email;
 203
 204    To change the owner of the type email to joe:
 205 ALTER TYPE email OWNER TO joe;
 206
 207    To change the schema of the type email to customers:
 208 ALTER TYPE email SET SCHEMA customers;
 209
 210    To add a new attribute to a composite type:
 211 ALTER TYPE compfoo ADD ATTRIBUTE f3 int;
 212
 213    To add a new value to an enum type in a particular sort position:
 214 ALTER TYPE colors ADD VALUE 'orange' AFTER 'red';
 215
 216    To rename an enum value:
 217 ALTER TYPE colors RENAME VALUE 'purple' TO 'mauve';
 218
 219    To create binary I/O functions for an existing base type:
 220 CREATE FUNCTION mytypesend(mytype) RETURNS bytea ...;
 221 CREATE FUNCTION mytyperecv(internal, oid, integer) RETURNS mytype ...;
 222 ALTER TYPE mytype SET (
 223     SEND = mytypesend,
 224     RECEIVE = mytyperecv
 225 );
 226
 227 Compatibility
 228
 229    The variants to add and drop attributes are part of the SQL standard;
 230    the other variants are PostgreSQL extensions.
 231
 232 See Also
 233
 234    CREATE TYPE, DROP TYPE