diff options
Diffstat (limited to 'doc/src/sgml/ref/create_domain.sgml')
| -rw-r--r-- | doc/src/sgml/ref/create_domain.sgml | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/create_domain.sgml b/doc/src/sgml/ref/create_domain.sgml new file mode 100644 index 00000000000..f88069bfc20 --- /dev/null +++ b/doc/src/sgml/ref/create_domain.sgml @@ -0,0 +1,231 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.1 2002/03/06 20:34:44 momjian Exp $ +PostgreSQL documentation +--> + +<refentry id="SQL-CREATEDOMAIN"> + <refmeta> + <refentrytitle id="sql-createdomian-title"> + CREATE DOMAIN + </refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + <refnamediv> + <refname> + CREATE DOMAIN + </refname> + <refpurpose> + define a new domain + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <refsynopsisdivinfo> + <date>2002-02-24</date> + </refsynopsisdivinfo> + <synopsis> +CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> <replaceable class="parameter">data_type</replaceable> [ DEFAULT <replaceable>default_expr</> ] [ <replaceable class="PARAMETER">column_constraint</replaceable> [, ... ] ] +[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ] +{ NOT NULL | NULL <!-- | UNIQUE | PRIMARY KEY | + CHECK (<replaceable class="PARAMETER">expression</replaceable>) | + REFERENCES <replaceable class="PARAMETER">reftable</replaceable> [ ( <replaceable class="PARAMETER">refcolumn</replaceable> ) ] [ MATCH FULL | MATCH PARTIAL ] + [ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] --> } +<!-- [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] --> + </synopsis> + + <refsect2 id="R2-SQL-CREATEDOMAIN-1"> + <refsect2info> + <date>2002-02-24</date> + </refsect2info> + <title> + Parameters + </title> + <para> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">domainname</replaceable></term> + <listitem> + <para> + The name of a domain to be created. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">data_type</replaceable></term> + <listitem> + <para> + The data type of the domain. This may include array specifiers. + Refer to the <citetitle>User's Guide</citetitle> for further + information about data types and arrays. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DEFAULT + <replaceable>default_expr</replaceable></literal></term> + <listitem> + <para> + The <literal>DEFAULT</> clause assigns a default data value for + the column whose column definition it appears within. The value + is any variable-free expression (subselects and cross-references + to other columns in the current table are not allowed). The + data type of the default expression must match the data type of the + domain. + </para> + + <para> + The default expression will be used in any insert operation that + does not specify a value for the domain. If there is no default + for a domain, then the default is NULL. + </para> + + <note> + <para> + The default of a column will be tested before that of the domain. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable></literal></term> + <listitem> + <para> + An optional name for a domain. If not specified, + the system generates a name. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>NOT NULL</></term> + <listitem> + <para> + The column is not allowed to contain NULL values. This is + equivalent to the column constraint <literal>CHECK (<replaceable + class="PARAMETER">column</replaceable> NOT NULL)</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>NULL</></term> + <listitem> + <para> + The column is allowed to contain NULL values. This is the default. + </para> + + <para> + This clause is only available for compatibility with + non-standard SQL databases. Its use is discouraged in new + applications. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect2> + + <refsect2 id="R2-SQL-CREATEDOMAIN-2"> + <refsect2info> + <date>2002-02-24</date> + </refsect2info> + <title> + Outputs + </title> + <para> + + <variablelist> + <varlistentry> + <term><computeroutput> +CREATE DOMAIN + </computeroutput></term> + <listitem> + <para> + Message returned if the domain is successfully created. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + </refsynopsisdiv> + + <refsect1 id="R1-SQL-CREATEDOMAIN-1"> + <refsect1info> + <date>2002-02-24</date> + </refsect1info> + <title> + Description + </title> + + <para> + <command>CREATE DOMAIN</command> allows the user to register a new user data + domain with PostgreSQL for use in the current data base. The + user who defines a domain becomes its owner. + <replaceable class="parameter">domainname</replaceable> is + the name of the new type and must be unique within the + types and domains defined for this database. + </para> + + <para> + Domains are useful for abstracting common fields between tables into + a single location for maintenance. An email address column may be used + in several tables, all with the same properties. Define a domain and + use that rather than setting up each tables constraints individually. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + <para> + This example creates the <type>country_code</type> data type and then uses the + type in a table definition: +<programlisting> +CREATE DOMAIN country_code char(2) NOT NULL; +CREATE TABLE countrylist (id INT4, country country_code); +</programlisting> + </para> + </refsect1> + + <refsect1 id="SQL-CREATEDOMAIN-compatibility"> + <title>Compatibility</title> + + <para> + This <command>CREATE DOMAIN</command> command is a + <productname>PostgreSQL</productname> extension. CHECK and FOREIGN KEY + constraints are currently unsupported. + </para> + </refsect1> + + <refsect1 id="SQL-CREATEDOMAIN-see-also"> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-dropdomain"></member> + <member><citetitle>PostgreSQL Programmer's Guide</citetitle></member> + </simplelist> + </refsect1> + +</refentry> + + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> |