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

   1
   2 ALTER DOMAIN
   3
   4    ALTER DOMAIN — change the definition of a domain
   5
   6 Synopsis
   7
   8 ALTER DOMAIN name
   9     { SET DEFAULT expression | DROP DEFAULT }
  10 ALTER DOMAIN name
  11     { SET | DROP } NOT NULL
  12 ALTER DOMAIN name
  13     ADD domain_constraint [ NOT VALID ]
  14 ALTER DOMAIN name
  15     DROP CONSTRAINT [ IF EXISTS ] constraint_name [ RESTRICT | CASCADE ]
  16 ALTER DOMAIN name
  17      RENAME CONSTRAINT constraint_name TO new_constraint_name
  18 ALTER DOMAIN name
  19     VALIDATE CONSTRAINT constraint_name
  20 ALTER DOMAIN name
  21     OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
  22 ALTER DOMAIN name
  23     RENAME TO new_name
  24 ALTER DOMAIN name
  25     SET SCHEMA new_schema
  26
  27 where domain_constraint is:
  28
  29 [ CONSTRAINT constraint_name ]
  30 { NOT NULL | CHECK (expression) }
  31
  32 Description
  33
  34    ALTER DOMAIN changes the definition of an existing domain. There are
  35    several sub-forms:
  36
  37    SET/DROP DEFAULT
  38           These forms set or remove the default value for a domain. Note
  39           that defaults only apply to subsequent INSERT commands; they do
  40           not affect rows already in a table using the domain.
  41
  42    SET/DROP NOT NULL
  43           These forms change whether a domain is marked to allow NULL
  44           values or to reject NULL values. You can only SET NOT NULL when
  45           the columns using the domain contain no null values.
  46
  47    ADD domain_constraint [ NOT VALID ]
  48           This form adds a new constraint to a domain. When a new
  49           constraint is added to a domain, all columns using that domain
  50           will be checked against the newly added constraint. These checks
  51           can be suppressed by adding the new constraint using the NOT
  52           VALID option; the constraint can later be made valid using ALTER
  53           DOMAIN ... VALIDATE CONSTRAINT. Newly inserted or updated rows
  54           are always checked against all constraints, even those marked
  55           NOT VALID. NOT VALID is only accepted for CHECK constraints.
  56
  57    DROP CONSTRAINT [ IF EXISTS ]
  58           This form drops constraints on a domain. If IF EXISTS is
  59           specified and the constraint does not exist, no error is thrown.
  60           In this case a notice is issued instead.
  61
  62    RENAME CONSTRAINT
  63           This form changes the name of a constraint on a domain.
  64
  65    VALIDATE CONSTRAINT
  66           This form validates a constraint previously added as NOT VALID,
  67           that is, it verifies that all values in table columns of the
  68           domain type satisfy the specified constraint.
  69
  70    OWNER
  71           This form changes the owner of the domain to the specified user.
  72
  73    RENAME
  74           This form changes the name of the domain.
  75
  76    SET SCHEMA
  77           This form changes the schema of the domain. Any constraints
  78           associated with the domain are moved into the new schema as
  79           well.
  80
  81    You must own the domain to use ALTER DOMAIN. To change the schema of a
  82    domain, you must also have CREATE privilege on the new schema. To alter
  83    the owner, you must be able to SET ROLE to the new owning role, and
  84    that role must have CREATE privilege on the domain's schema. (These
  85    restrictions enforce that altering the owner doesn't do anything you
  86    couldn't do by dropping and recreating the domain. However, a superuser
  87    can alter ownership of any domain anyway.)
  88
  89 Parameters
  90
  91    name
  92           The name (possibly schema-qualified) of an existing domain to
  93           alter.
  94
  95    domain_constraint
  96           New domain constraint for the domain.
  97
  98    constraint_name
  99           Name of an existing constraint to drop or rename.
 100
 101    NOT VALID
 102           Do not verify existing stored data for constraint validity.
 103
 104    CASCADE
 105           Automatically drop objects that depend on the constraint, and in
 106           turn all objects that depend on those objects (see
 107           Section 5.15).
 108
 109    RESTRICT
 110           Refuse to drop the constraint if there are any dependent
 111           objects. This is the default behavior.
 112
 113    new_name
 114           The new name for the domain.
 115
 116    new_constraint_name
 117           The new name for the constraint.
 118
 119    new_owner
 120           The user name of the new owner of the domain.
 121
 122    new_schema
 123           The new schema for the domain.
 124
 125 Notes
 126
 127    Although ALTER DOMAIN ADD CONSTRAINT attempts to verify that existing
 128    stored data satisfies the new constraint, this check is not
 129    bulletproof, because the command cannot “see” table rows that are newly
 130    inserted or updated and not yet committed. If there is a hazard that
 131    concurrent operations might insert bad data, the way to proceed is to
 132    add the constraint using the NOT VALID option, commit that command,
 133    wait until all transactions started before that commit have finished,
 134    and then issue ALTER DOMAIN VALIDATE CONSTRAINT to search for data
 135    violating the constraint. This method is reliable because once the
 136    constraint is committed, all new transactions are guaranteed to enforce
 137    it against new values of the domain type.
 138
 139    Currently, ALTER DOMAIN ADD CONSTRAINT, ALTER DOMAIN VALIDATE
 140    CONSTRAINT, and ALTER DOMAIN SET NOT NULL will fail if the named domain
 141    or any derived domain is used within a container-type column (a
 142    composite, array, or range column) in any table in the database. They
 143    should eventually be improved to be able to verify the new constraint
 144    for such nested values.
 145
 146 Examples
 147
 148    To add a NOT NULL constraint to a domain:
 149 ALTER DOMAIN zipcode SET NOT NULL;
 150
 151    To remove a NOT NULL constraint from a domain:
 152 ALTER DOMAIN zipcode DROP NOT NULL;
 153
 154    To add a check constraint to a domain:
 155 ALTER DOMAIN zipcode ADD CONSTRAINT zipchk CHECK (char_length(VALUE) = 5);
 156
 157    To remove a check constraint from a domain:
 158 ALTER DOMAIN zipcode DROP CONSTRAINT zipchk;
 159
 160    To rename a check constraint on a domain:
 161 ALTER DOMAIN zipcode RENAME CONSTRAINT zipchk TO zip_check;
 162
 163    To move the domain into a different schema:
 164 ALTER DOMAIN zipcode SET SCHEMA customers;
 165
 166 Compatibility
 167
 168    ALTER DOMAIN conforms to the SQL standard, except for the OWNER,
 169    RENAME, SET SCHEMA, and VALIDATE CONSTRAINT variants, which are
 170    PostgreSQL extensions. The NOT VALID clause of the ADD CONSTRAINT
 171    variant is also a PostgreSQL extension.
 172
 173 See Also
 174
 175    CREATE DOMAIN, DROP DOMAIN