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

   1 '\" t
   2 .\"     Title: CREATE 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 "CREATE 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 CREATE_DOMAIN \- define a new domain
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE DOMAIN \fIname\fR [ AS ] \fIdata_type\fR
  36     [ COLLATE \fIcollation\fR ]
  37     [ DEFAULT \fIexpression\fR ]
  38     [ \fIdomain_constraint\fR [ \&.\&.\&. ] ]
  39
  40 where \fIdomain_constraint\fR is:
  41
  42 [ CONSTRAINT \fIconstraint_name\fR ]
  43 { NOT NULL | NULL | CHECK (\fIexpression\fR) }
  44 .fi
  45 .SH "DESCRIPTION"
  46 .PP
  47 \fBCREATE DOMAIN\fR
  48 creates a new domain\&. A domain is essentially a data type with optional constraints (restrictions on the allowed set of values)\&. The user who defines a domain becomes its owner\&.
  49 .PP
  50 If a schema name is given (for example,
  51 CREATE DOMAIN myschema\&.mydomain \&.\&.\&.) then the domain is created in the specified schema\&. Otherwise it is created in the current schema\&. The domain name must be unique among the types and domains existing in its schema\&.
  52 .PP
  53 Domains are useful for abstracting common constraints on fields into a single location for maintenance\&. For example, several tables might contain email address columns, all requiring the same CHECK constraint to verify the address syntax\&. Define a domain rather than setting up each table\*(Aqs constraint individually\&.
  54 .PP
  55 To be able to create a domain, you must have
  56 USAGE
  57 privilege on the underlying type\&.
  58 .SH "PARAMETERS"
  59 .PP
  60 \fIname\fR
  61 .RS 4
  62 The name (optionally schema\-qualified) of a domain to be created\&.
  63 .RE
  64 .PP
  65 \fIdata_type\fR
  66 .RS 4
  67 The underlying data type of the domain\&. This can include array specifiers\&.
  68 .RE
  69 .PP
  70 \fIcollation\fR
  71 .RS 4
  72 An optional collation for the domain\&. If no collation is specified, the domain has the same collation behavior as its underlying data type\&. The underlying type must be collatable if
  73 COLLATE
  74 is specified\&.
  75 .RE
  76 .PP
  77 DEFAULT \fIexpression\fR
  78 .RS 4
  79 The
  80 DEFAULT
  81 clause specifies a default value for columns of the domain data type\&. The value is any variable\-free expression (but subqueries are not allowed)\&. The data type of the default expression must match the data type of the domain\&. If no default value is specified, then the default value is the null value\&.
  82 .sp
  83 The default expression will be used in any insert operation that does not specify a value for the column\&. If a default value is defined for a particular column, it overrides any default associated with the domain\&. In turn, the domain default overrides any default value associated with the underlying data type\&.
  84 .RE
  85 .PP
  86 CONSTRAINT \fIconstraint_name\fR
  87 .RS 4
  88 An optional name for a constraint\&. If not specified, the system generates a name\&.
  89 .RE
  90 .PP
  91 NOT NULL
  92 .RS 4
  93 Values of this domain are prevented from being null (but see notes below)\&.
  94 .RE
  95 .PP
  96 NULL
  97 .RS 4
  98 Values of this domain are allowed to be null\&. This is the default\&.
  99 .sp
 100 This clause is only intended for compatibility with nonstandard SQL databases\&. Its use is discouraged in new applications\&.
 101 .RE
 102 .PP
 103 CHECK (\fIexpression\fR)
 104 .RS 4
 105 CHECK
 106 clauses specify integrity constraints or tests which values of the domain must satisfy\&. Each constraint must be an expression producing a Boolean result\&. It should use the key word
 107 VALUE
 108 to refer to the value being tested\&. Expressions evaluating to TRUE or UNKNOWN succeed\&. If the expression produces a FALSE result, an error is reported and the value is not allowed to be converted to the domain type\&.
 109 .sp
 110 Currently,
 111 CHECK
 112 expressions cannot contain subqueries nor refer to variables other than
 113 VALUE\&.
 114 .sp
 115 When a domain has multiple
 116 CHECK
 117 constraints, they will be tested in alphabetical order by name\&. (PostgreSQL
 118 versions before 9\&.5 did not honor any particular firing order for
 119 CHECK
 120 constraints\&.)
 121 .RE
 122 .SH "NOTES"
 123 .PP
 124 Domain constraints, particularly
 125 NOT NULL, are checked when converting a value to the domain type\&. It is possible for a column that is nominally of the domain type to read as null despite there being such a constraint\&. For example, this can happen in an outer\-join query, if the domain column is on the nullable side of the outer join\&. A more subtle example is
 126 .sp
 127 .if n \{\
 128 .RS 4
 129 .\}
 130 .nf
 131 INSERT INTO tab (domcol) VALUES ((SELECT domcol FROM tab WHERE false));
 132 .fi
 133 .if n \{\
 134 .RE
 135 .\}
 136 .sp
 137 The empty scalar sub\-SELECT will produce a null value that is considered to be of the domain type, so no further constraint checking is applied to it, and the insertion will succeed\&.
 138 .PP
 139 It is very difficult to avoid such problems, because of SQL\*(Aqs general assumption that a null value is a valid value of every data type\&. Best practice therefore is to design a domain\*(Aqs constraints so that a null value is allowed, and then to apply column
 140 NOT NULL
 141 constraints to columns of the domain type as needed, rather than directly to the domain type\&.
 142 .PP
 143 PostgreSQL
 144 assumes that
 145 CHECK
 146 constraints\*(Aq conditions are immutable, that is, they will always give the same result for the same input value\&. This assumption is what justifies examining
 147 CHECK
 148 constraints only when a value is first converted to be of a domain type, and not at other times\&. (This is essentially the same as the treatment of table
 149 CHECK
 150 constraints, as described in
 151 Section\ \&5.5.1\&.)
 152 .PP
 153 An example of a common way to break this assumption is to reference a user\-defined function in a
 154 CHECK
 155 expression, and then change the behavior of that function\&.
 156 PostgreSQL
 157 does not disallow that, but it will not notice if there are stored values of the domain type that now violate the
 158 CHECK
 159 constraint\&. That would cause a subsequent database dump and restore to fail\&. The recommended way to handle such a change is to drop the constraint (using
 160 \fBALTER DOMAIN\fR), adjust the function definition, and re\-add the constraint, thereby rechecking it against stored data\&.
 161 .PP
 162 It\*(Aqs also good practice to ensure that domain
 163 CHECK
 164 expressions will not throw errors\&.
 165 .SH "EXAMPLES"
 166 .PP
 167 This example creates the
 168 us_postal_code
 169 data type and then uses the type in a table definition\&. A regular expression test is used to verify that the value looks like a valid US postal code:
 170 .sp
 171 .if n \{\
 172 .RS 4
 173 .\}
 174 .nf
 175 CREATE DOMAIN us_postal_code AS TEXT
 176 CHECK(
 177    VALUE ~ \*(Aq^\ed{5}$\*(Aq
 178 OR VALUE ~ \*(Aq^\ed{5}\-\ed{4}$\*(Aq
 179 );
 180
 181 CREATE TABLE us_snail_addy (
 182   address_id SERIAL PRIMARY KEY,
 183   street1 TEXT NOT NULL,
 184   street2 TEXT,
 185   street3 TEXT,
 186   city TEXT NOT NULL,
 187   postal us_postal_code NOT NULL
 188 );
 189 .fi
 190 .if n \{\
 191 .RE
 192 .\}
 193 .SH "COMPATIBILITY"
 194 .PP
 195 The command
 196 \fBCREATE DOMAIN\fR
 197 conforms to the SQL standard\&.
 198 .PP
 199 The syntax
 200 NOT NULL
 201 in this command is a
 202 PostgreSQL
 203 extension\&. (A standard\-conforming way to write the same for non\-composite data types would be
 204 CHECK (VALUE IS NOT NULL)\&. However, per
 205 the section called \(lqNOTES\(rq, such constraints are best avoided in practice anyway\&.) The
 206 NULL
 207 \(lqconstraint\(rq
 208 is a
 209 PostgreSQL
 210 extension (see also
 211 Compatibility)\&.
 212 .SH "SEE ALSO"
 213 ALTER DOMAIN (\fBALTER_DOMAIN\fR(7)), DROP DOMAIN (\fBDROP_DOMAIN\fR(7))