← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/create_domain.sgml

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/create_domain.sgml
 
1
<!--
 
2
$PostgreSQL: pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.20.4.1 2005-05-02 01:56:16 neilc 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-alterdomain" endterm="sql-alterdomain-title"></member>
 
200
   <member><xref linkend="sql-dropdomain" endterm="sql-dropdomain-title"></member>
 
201
  </simplelist>
 
202
 </refsect1>
 
203
 
 
204
</refentry>
 
205
 
 
206
 
 
207
<!-- Keep this comment at the end of the file
 
208
Local variables:
 
209
mode: sgml
 
210
sgml-omittag:nil
 
211
sgml-shorttag:t
 
212
sgml-minimize-attributes:nil
 
213
sgml-always-quote-attributes:t
 
214
sgml-indent-step:1
 
215
sgml-indent-data:t
 
216
sgml-parent-document:nil
 
217
sgml-default-dtd-file:"../reference.ced"
 
218
sgml-exposed-tags:nil
 
219
sgml-local-catalogs:"/usr/lib/sgml/catalog"
 
220
sgml-local-ecat-files:nil
 
221
End:
 
222
-->