granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/create_domain.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.19 2004/08/08 02:05:32 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEDOMAIN">
   7  <refmeta>
   8   <refentrytitle id="sql-createdomain-title">CREATE DOMAIN</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CREATE DOMAIN</refname>
  14   <refpurpose>define a new domain</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-createdomain">
  18   <primary>CREATE DOMAIN</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CREATE DOMAIN <replaceable class="parameter">name</replaceable> [AS] <replaceable class="parameter">data_type</replaceable>
  24     [ DEFAULT <replaceable>expression</> ]
  25     [ <replaceable class="PARAMETER">constraint</replaceable> [ ... ] ]
  26
  27 where <replaceable class="PARAMETER">constraint</replaceable> is:
  28
  29 [ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
  30 { NOT NULL | NULL | CHECK (<replaceable class="PARAMETER">expression</replaceable>) }
  31 </synopsis>
  32  </refsynopsisdiv>
  33
  34  <refsect1>
  35   <title>Description</title>
  36
  37   <para>
  38    <command>CREATE DOMAIN</command> creates a new data domain.  The
  39    user who defines a domain becomes its owner.
  40   </para>
  41
  42   <para>
  43    If a schema name is given (for example, <literal>CREATE DOMAIN
  44    myschema.mydomain ...</>) then the domain is created in the
  45    specified schema.  Otherwise it is created in the current schema.
  46    The domain name must be unique among the types and domains existing
  47    in its schema.
  48   </para>
  49
  50   <para>
  51    Domains are useful for abstracting common fields between tables into
  52    a single location for maintenance.  For example, an email address column may be used
  53    in several tables, all with the same properties.  Define a domain and
  54    use that rather than setting up each table's constraints individually.
  55   </para>
  56  </refsect1>
  57
  58  <refsect1>
  59   <title>Parameters</title>
  60
  61     <variablelist>
  62      <varlistentry>
  63       <term><replaceable class="parameter">name</replaceable></term>
  64       <listitem>
  65        <para>
  66         The name (optionally schema-qualified) of a domain to be created.
  67        </para>
  68       </listitem>
  69      </varlistentry>
  70
  71      <varlistentry>
  72       <term><replaceable class="PARAMETER">data_type</replaceable></term>
  73       <listitem>
  74        <para>
  75         The underlying data type of the domain. This may include array
  76         specifiers.
  77        </para>
  78       </listitem>
  79      </varlistentry>
  80
  81      <varlistentry>
  82       <term><literal>DEFAULT <replaceable>expression</replaceable></literal></term>
  83
  84       <listitem>
  85        <para>
  86         The <literal>DEFAULT</> clause specifies a default value for
  87         columns of the domain data type.  The value is any
  88         variable-free expression (but subqueries are not allowed).
  89         The data type of the default expression must match the data
  90         type of the domain.  If no default value is specified, then
  91         the default value is the null value.
  92        </para>
  93
  94        <para>
  95         The default expression will be used in any insert operation
  96         that does not specify a value for the column.  If a default
  97         value is defined for a particular column, it overrides any
  98         default associated with the domain.  In turn, the domain
  99         default overrides any default value associated with the
 100         underlying data type.
 101        </para>
 102       </listitem>
 103      </varlistentry>
 104
 105      <varlistentry>
 106       <term><literal>CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable></literal></term>
 107       <listitem>
 108        <para>
 109         An optional name for a constraint.  If not specified,
 110         the system generates a name.
 111        </para>
 112       </listitem>
 113      </varlistentry>
 114
 115      <varlistentry>
 116       <term><literal>NOT NULL</></term>
 117       <listitem>
 118        <para>
 119         Values of this domain are not allowed to be null.
 120        </para>
 121       </listitem>
 122      </varlistentry>
 123
 124      <varlistentry>
 125       <term><literal>NULL</></term>
 126       <listitem>
 127        <para>
 128         Values of this domain are allowed to be null.  This is the default.
 129        </para>
 130
 131        <para>
 132         This clause is only intended for compatibility with
 133         nonstandard SQL databases.  Its use is discouraged in new
 134         applications.
 135        </para>
 136       </listitem>
 137      </varlistentry>
 138
 139    <varlistentry>
 140     <term><literal>CHECK (<replaceable class="PARAMETER">expression</replaceable>)</literal></term>
 141     <listitem>
 142      <para>
 143       <literal>CHECK</> clauses specify integrity constraints or tests
 144       which values of the domain must satisfy.
 145       Each constraint must be an expression
 146       producing a Boolean result.  It should use the name <literal>VALUE</>
 147       to refer to the value being tested.
 148      </para>
 149
 150      <para>
 151       Currently, <literal>CHECK</literal> expressions cannot contain
 152       subqueries nor refer to variables other than <literal>VALUE</>.
 153      </para>
 154     </listitem>
 155    </varlistentry>
 156   </variablelist>
 157  </refsect1>
 158
 159  <refsect1>
 160   <title>Examples</title>
 161
 162   <para>
 163    This example creates the <type>us_postal_code</type> data type and
 164    then uses the type in a table definition.  A regular expression test
 165    is used to verify that the value looks like a valid US postal code.
 166
 167 <programlisting>
 168 CREATE DOMAIN us_postal_code AS TEXT
 169 CHECK(
 170    VALUE ~ '^\d{5}$'
 171 OR VALUE ~ '^\d{5}-\d{4}$'
 172 );
 173
 174 CREATE TABLE us_snail_addy (
 175   address_id SERIAL NOT NULL PRIMARY KEY
 176 , street1 TEXT NOT NULL
 177 , street2 TEXT
 178 , street3 TEXT
 179 , city TEXT NOT NULL
 180 , postal us_postal_code NOT NULL
 181 );
 182 </programlisting>
 183   </para>
 184  </refsect1>
 185
 186  <refsect1 id="SQL-CREATEDOMAIN-compatibility">
 187   <title>Compatibility</title>
 188
 189   <para>
 190    The command <command>CREATE DOMAIN</command> conforms to the SQL
 191    standard.
 192   </para>
 193  </refsect1>
 194
 195  <refsect1 id="SQL-CREATEDOMAIN-see-also">
 196   <title>See Also</title>
 197
 198   <simplelist type="inline">
 199    <member><xref linkend="sql-dropdomain" endterm="sql-dropdomain-title"></member>
 200   </simplelist>
 201  </refsect1>
 202
 203 </refentry>
 204
 205
 206 <!-- Keep this comment at the end of the file
 207 Local variables:
 208 mode: sgml
 209 sgml-omittag:nil
 210 sgml-shorttag:t
 211 sgml-minimize-attributes:nil
 212 sgml-always-quote-attributes:t
 213 sgml-indent-step:1
 214 sgml-indent-data:t
 215 sgml-parent-document:nil
 216 sgml-default-dtd-file:"../reference.ced"
 217 sgml-exposed-tags:nil
 218 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 219 sgml-local-ecat-files:nil
 220 End:
 221 -->