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

   1 '\" t
   2 .\"     Title: ALTER DOMAIN
   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 DOMAIN" "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_DOMAIN \- change the definition of a domain
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 ALTER DOMAIN \fIname\fR
  36     { SET DEFAULT \fIexpression\fR | DROP DEFAULT }
  37 ALTER DOMAIN \fIname\fR
  38     { SET | DROP } NOT NULL
  39 ALTER DOMAIN \fIname\fR
  40     ADD \fIdomain_constraint\fR [ NOT VALID ]
  41 ALTER DOMAIN \fIname\fR
  42     DROP CONSTRAINT [ IF EXISTS ] \fIconstraint_name\fR [ RESTRICT | CASCADE ]
  43 ALTER DOMAIN \fIname\fR
  44      RENAME CONSTRAINT \fIconstraint_name\fR TO \fInew_constraint_name\fR
  45 ALTER DOMAIN \fIname\fR
  46     VALIDATE CONSTRAINT \fIconstraint_name\fR
  47 ALTER DOMAIN \fIname\fR
  48     OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
  49 ALTER DOMAIN \fIname\fR
  50     RENAME TO \fInew_name\fR
  51 ALTER DOMAIN \fIname\fR
  52     SET SCHEMA \fInew_schema\fR
  53
  54 where \fIdomain_constraint\fR is:
  55
  56 [ CONSTRAINT \fIconstraint_name\fR ]
  57 { NOT NULL | CHECK (\fIexpression\fR) }
  58 .fi
  59 .SH "DESCRIPTION"
  60 .PP
  61 \fBALTER DOMAIN\fR
  62 changes the definition of an existing domain\&. There are several sub\-forms:
  63 .PP
  64 SET/DROP DEFAULT
  65 .RS 4
  66 These forms set or remove the default value for a domain\&. Note that defaults only apply to subsequent
  67 \fBINSERT\fR
  68 commands; they do not affect rows already in a table using the domain\&.
  69 .RE
  70 .PP
  71 SET/DROP NOT NULL
  72 .RS 4
  73 These forms change whether a domain is marked to allow NULL values or to reject NULL values\&. You can only
  74 SET NOT NULL
  75 when the columns using the domain contain no null values\&.
  76 .RE
  77 .PP
  78 ADD \fIdomain_constraint\fR [ NOT VALID ]
  79 .RS 4
  80 This form adds a new constraint to a domain\&. When a new constraint is added to a domain, all columns using that domain will be checked against the newly added constraint\&. These checks can be suppressed by adding the new constraint using the
  81 NOT VALID
  82 option; the constraint can later be made valid using
  83 \fBALTER DOMAIN \&.\&.\&. VALIDATE CONSTRAINT\fR\&. Newly inserted or updated rows are always checked against all constraints, even those marked
  84 NOT VALID\&.
  85 NOT VALID
  86 is only accepted for
  87 CHECK
  88 constraints\&.
  89 .RE
  90 .PP
  91 DROP CONSTRAINT [ IF EXISTS ]
  92 .RS 4
  93 This form drops constraints on a domain\&. If
  94 IF EXISTS
  95 is specified and the constraint does not exist, no error is thrown\&. In this case a notice is issued instead\&.
  96 .RE
  97 .PP
  98 RENAME CONSTRAINT
  99 .RS 4
 100 This form changes the name of a constraint on a domain\&.
 101 .RE
 102 .PP
 103 VALIDATE CONSTRAINT
 104 .RS 4
 105 This form validates a constraint previously added as
 106 NOT VALID, that is, it verifies that all values in table columns of the domain type satisfy the specified constraint\&.
 107 .RE
 108 .PP
 109 OWNER
 110 .RS 4
 111 This form changes the owner of the domain to the specified user\&.
 112 .RE
 113 .PP
 114 RENAME
 115 .RS 4
 116 This form changes the name of the domain\&.
 117 .RE
 118 .PP
 119 SET SCHEMA
 120 .RS 4
 121 This form changes the schema of the domain\&. Any constraints associated with the domain are moved into the new schema as well\&.
 122 .RE
 123 .PP
 124 You must own the domain to use
 125 \fBALTER DOMAIN\fR\&. To change the schema of a domain, you must also have
 126 CREATE
 127 privilege on the new schema\&. To alter the owner, you must be able to
 128 SET ROLE
 129 to the new owning role, and that role must have
 130 CREATE
 131 privilege on the domain\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the domain\&. However, a superuser can alter ownership of any domain anyway\&.)
 132 .SH "PARAMETERS"
 133 .PP
 134 .PP
 135 \fIname\fR
 136 .RS 4
 137 The name (possibly schema\-qualified) of an existing domain to alter\&.
 138 .RE
 139 .PP
 140 \fIdomain_constraint\fR
 141 .RS 4
 142 New domain constraint for the domain\&.
 143 .RE
 144 .PP
 145 \fIconstraint_name\fR
 146 .RS 4
 147 Name of an existing constraint to drop or rename\&.
 148 .RE
 149 .PP
 150 NOT VALID
 151 .RS 4
 152 Do not verify existing stored data for constraint validity\&.
 153 .RE
 154 .PP
 155 CASCADE
 156 .RS 4
 157 Automatically drop objects that depend on the constraint, and in turn all objects that depend on those objects (see
 158 Section\ \&5.15)\&.
 159 .RE
 160 .PP
 161 RESTRICT
 162 .RS 4
 163 Refuse to drop the constraint if there are any dependent objects\&. This is the default behavior\&.
 164 .RE
 165 .PP
 166 \fInew_name\fR
 167 .RS 4
 168 The new name for the domain\&.
 169 .RE
 170 .PP
 171 \fInew_constraint_name\fR
 172 .RS 4
 173 The new name for the constraint\&.
 174 .RE
 175 .PP
 176 \fInew_owner\fR
 177 .RS 4
 178 The user name of the new owner of the domain\&.
 179 .RE
 180 .PP
 181 \fInew_schema\fR
 182 .RS 4
 183 The new schema for the domain\&.
 184 .RE
 185 .SH "NOTES"
 186 .PP
 187 Although
 188 \fBALTER DOMAIN ADD CONSTRAINT\fR
 189 attempts to verify that existing stored data satisfies the new constraint, this check is not bulletproof, because the command cannot
 190 \(lqsee\(rq
 191 table rows that are newly inserted or updated and not yet committed\&. If there is a hazard that concurrent operations might insert bad data, the way to proceed is to add the constraint using the
 192 NOT VALID
 193 option, commit that command, wait until all transactions started before that commit have finished, and then issue
 194 \fBALTER DOMAIN VALIDATE CONSTRAINT\fR
 195 to search for data violating the constraint\&. This method is reliable because once the constraint is committed, all new transactions are guaranteed to enforce it against new values of the domain type\&.
 196 .PP
 197 Currently,
 198 \fBALTER DOMAIN ADD CONSTRAINT\fR,
 199 \fBALTER DOMAIN VALIDATE CONSTRAINT\fR, and
 200 \fBALTER DOMAIN SET NOT NULL\fR
 201 will fail if the named domain or any derived domain is used within a container\-type column (a composite, array, or range column) in any table in the database\&. They should eventually be improved to be able to verify the new constraint for such nested values\&.
 202 .SH "EXAMPLES"
 203 .PP
 204 To add a
 205 NOT NULL
 206 constraint to a domain:
 207 .sp
 208 .if n \{\
 209 .RS 4
 210 .\}
 211 .nf
 212 ALTER DOMAIN zipcode SET NOT NULL;
 213 .fi
 214 .if n \{\
 215 .RE
 216 .\}
 217 .sp
 218 To remove a
 219 NOT NULL
 220 constraint from a domain:
 221 .sp
 222 .if n \{\
 223 .RS 4
 224 .\}
 225 .nf
 226 ALTER DOMAIN zipcode DROP NOT NULL;
 227 .fi
 228 .if n \{\
 229 .RE
 230 .\}
 231 .PP
 232 To add a check constraint to a domain:
 233 .sp
 234 .if n \{\
 235 .RS 4
 236 .\}
 237 .nf
 238 ALTER DOMAIN zipcode ADD CONSTRAINT zipchk CHECK (char_length(VALUE) = 5);
 239 .fi
 240 .if n \{\
 241 .RE
 242 .\}
 243 .PP
 244 To remove a check constraint from a domain:
 245 .sp
 246 .if n \{\
 247 .RS 4
 248 .\}
 249 .nf
 250 ALTER DOMAIN zipcode DROP CONSTRAINT zipchk;
 251 .fi
 252 .if n \{\
 253 .RE
 254 .\}
 255 .PP
 256 To rename a check constraint on a domain:
 257 .sp
 258 .if n \{\
 259 .RS 4
 260 .\}
 261 .nf
 262 ALTER DOMAIN zipcode RENAME CONSTRAINT zipchk TO zip_check;
 263 .fi
 264 .if n \{\
 265 .RE
 266 .\}
 267 .PP
 268 To move the domain into a different schema:
 269 .sp
 270 .if n \{\
 271 .RS 4
 272 .\}
 273 .nf
 274 ALTER DOMAIN zipcode SET SCHEMA customers;
 275 .fi
 276 .if n \{\
 277 .RE
 278 .\}
 279 .SH "COMPATIBILITY"
 280 .PP
 281 \fBALTER DOMAIN\fR
 282 conforms to the
 283 SQL
 284 standard, except for the
 285 OWNER,
 286 RENAME,
 287 SET SCHEMA, and
 288 VALIDATE CONSTRAINT
 289 variants, which are
 290 PostgreSQL
 291 extensions\&. The
 292 NOT VALID
 293 clause of the
 294 ADD CONSTRAINT
 295 variant is also a
 296 PostgreSQL
 297 extension\&.
 298 .SH "SEE ALSO"
 299 CREATE DOMAIN (\fBCREATE_DOMAIN\fR(7)), DROP DOMAIN (\fBDROP_DOMAIN\fR(7))