2002-03-19 03:18:25 +01:00
|
|
|
<!--
|
2007-02-01 01:28:19 +01:00
|
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.31 2007/02/01 00:28:18 momjian Exp $
|
2002-03-19 03:18:25 +01:00
|
|
|
PostgreSQL documentation
|
|
|
|
-->
|
|
|
|
|
|
|
|
<refentry id="SQL-CREATEDOMAIN">
|
|
|
|
<refmeta>
|
2003-04-22 12:08:08 +02:00
|
|
|
<refentrytitle id="sql-createdomain-title">CREATE DOMAIN</refentrytitle>
|
2002-03-19 03:18:25 +01:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
2002-03-19 03:18:25 +01:00
|
|
|
<refnamediv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<refname>CREATE DOMAIN</refname>
|
|
|
|
<refpurpose>define a new domain</refpurpose>
|
2002-03-19 03:18:25 +01:00
|
|
|
</refnamediv>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="sql-createdomain">
|
|
|
|
<primary>CREATE DOMAIN</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2002-03-19 03:18:25 +01:00
|
|
|
<refsynopsisdiv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<synopsis>
|
2005-12-25 02:41:15 +01:00
|
|
|
CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replaceable class="parameter">data_type</replaceable>
|
2003-09-22 02:16:58 +02:00
|
|
|
[ DEFAULT <replaceable>expression</> ]
|
2003-02-13 06:32:42 +01:00
|
|
|
[ <replaceable class="PARAMETER">constraint</replaceable> [ ... ] ]
|
2002-03-20 20:45:13 +01:00
|
|
|
|
|
|
|
where <replaceable class="PARAMETER">constraint</replaceable> is:
|
|
|
|
|
2002-03-19 03:18:25 +01:00
|
|
|
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
|
2002-12-12 21:35:16 +01:00
|
|
|
{ NOT NULL | NULL | CHECK (<replaceable class="PARAMETER">expression</replaceable>) }
|
2003-04-22 12:08:08 +02:00
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
2002-03-19 03:18:25 +01:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
2006-04-06 00:11:58 +02:00
|
|
|
<command>CREATE DOMAIN</command> 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.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If a schema name is given (for example, <literal>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.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2006-04-06 00:11:58 +02:00
|
|
|
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's constraint
|
|
|
|
individually.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
2002-03-19 03:18:25 +01:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2003-09-22 02:16:58 +02:00
|
|
|
<term><replaceable class="parameter">name</replaceable></term>
|
2002-03-19 03:18:25 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2005-01-04 01:39:53 +01:00
|
|
|
The name (optionally schema-qualified) of a domain to be created.
|
2002-03-19 03:18:25 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="PARAMETER">data_type</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
The underlying data type of the domain. This can include array
|
2005-01-04 01:39:53 +01:00
|
|
|
specifiers.
|
2002-03-19 03:18:25 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-09-22 02:16:58 +02:00
|
|
|
<term><literal>DEFAULT <replaceable>expression</replaceable></literal></term>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
2002-03-19 03:18:25 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2002-03-20 20:45:13 +01:00
|
|
|
The <literal>DEFAULT</> clause specifies a default value for
|
2003-04-22 12:08:08 +02:00
|
|
|
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.
|
2002-03-19 03:18:25 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
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.
|
2002-03-19 03:18:25 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable></literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2002-03-20 20:45:13 +01:00
|
|
|
An optional name for a constraint. If not specified,
|
2002-03-19 03:18:25 +01:00
|
|
|
the system generates a name.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>NOT NULL</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
Values of this domain are not allowed to be null.
|
2002-03-19 03:18:25 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>NULL</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
Values of this domain are allowed to be null. This is the default.
|
2002-03-19 03:18:25 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
This clause is only intended for compatibility with
|
|
|
|
nonstandard SQL databases. Its use is discouraged in new
|
2002-03-19 03:18:25 +01:00
|
|
|
applications.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2002-12-12 21:35:16 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><literal>CHECK (<replaceable class="PARAMETER">expression</replaceable>)</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<literal>CHECK</> clauses specify integrity constraints or tests
|
|
|
|
which values of the domain must satisfy.
|
|
|
|
Each constraint must be an expression
|
2006-04-06 00:11:58 +02:00
|
|
|
producing a Boolean result. It should use the key word <literal>VALUE</>
|
2002-12-12 21:35:16 +01:00
|
|
|
to refer to the value being tested.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Currently, <literal>CHECK</literal> expressions cannot contain
|
2003-04-22 12:08:08 +02:00
|
|
|
subqueries nor refer to variables other than <literal>VALUE</>.
|
2002-12-12 21:35:16 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
2002-12-12 21:35:16 +01:00
|
|
|
|
2002-03-19 03:18:25 +01:00
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
2002-03-19 03:18:25 +01:00
|
|
|
<para>
|
2004-08-08 03:49:30 +02:00
|
|
|
This example creates the <type>us_postal_code</type> data type and
|
2004-08-08 04:05:32 +02:00
|
|
|
then uses the type in a table definition. A regular expression test
|
2007-02-01 01:28:19 +01:00
|
|
|
is used to verify that the value looks like a valid US postal code:
|
2004-08-08 03:49:30 +02:00
|
|
|
|
2002-03-19 03:18:25 +01:00
|
|
|
<programlisting>
|
2004-08-08 03:49:30 +02:00
|
|
|
CREATE DOMAIN us_postal_code AS TEXT
|
|
|
|
CHECK(
|
2005-05-01 17:57:59 +02:00
|
|
|
VALUE ~ '^\\d{5}$'
|
|
|
|
OR VALUE ~ '^\\d{5}-\\d{4}$'
|
2004-08-08 03:49:30 +02:00
|
|
|
);
|
|
|
|
|
|
|
|
CREATE TABLE us_snail_addy (
|
2006-04-06 00:11:58 +02:00
|
|
|
address_id SERIAL PRIMARY KEY,
|
|
|
|
street1 TEXT NOT NULL,
|
|
|
|
street2 TEXT,
|
|
|
|
street3 TEXT,
|
|
|
|
city TEXT NOT NULL,
|
|
|
|
postal us_postal_code NOT NULL
|
2004-08-08 03:49:30 +02:00
|
|
|
);
|
2002-03-19 03:18:25 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1 id="SQL-CREATEDOMAIN-compatibility">
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The command <command>CREATE DOMAIN</command> conforms to the SQL
|
|
|
|
standard.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
2002-03-19 03:18:25 +01:00
|
|
|
<refsect1 id="SQL-CREATEDOMAIN-see-also">
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
2005-01-04 01:39:53 +01:00
|
|
|
<member><xref linkend="sql-alterdomain" endterm="sql-alterdomain-title"></member>
|
2002-11-22 00:34:43 +01:00
|
|
|
<member><xref linkend="sql-dropdomain" endterm="sql-dropdomain-title"></member>
|
2002-03-19 03:18:25 +01:00
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
</refentry>
|