Code review for DOMAIN patch.

4 files changed, 105 insertions, 73 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 451c9dcaa8a..5db408f6d0f 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1,6 +1,6 @@
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
- $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.34 2002/03/19 02:18:10 momjian Exp $
+ $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.35 2002/03/20 19:43:24 tgl Exp $
  -->
 
 <chapter id="catalogs">
@@ -2274,7 +2274,8 @@
    This catalog stores information about datatypes.  Scalar types
    (<quote>base types</>) are created with <command>CREATE TYPE</command>.
    A complex type is also created for each table in the database, to
-   represent the row structure of the table.
+   represent the row structure of the table.  It is also possible to create
+   derived types with <command>CREATE DOMAIN</command>.
   </para>
 
   <table>
@@ -2345,11 +2346,10 @@
       <entry></entry>
       <entry>
        <structfield>typtype</structfield> is <literal>b</literal> for
-       a base type and <literal>c</literal> for a complex type (i.e.,
-       a table's row type).  If <structfield>typtype</structfield> is
-       <literal>c</literal>, <structfield>typrelid</structfield> is
-       the OID of the type's entry in
-       <structname>pg_class</structname>.
+       a base type, <literal>c</literal> for a complex type (i.e.,
+       a table's row type), or <literal>d</literal> for a derived type (i.e.,
+       a domain).  See also <structfield>typrelid</structfield> 
+       and <structfield>typbasetype</structfield>.
       </entry>
      </row>
 
@@ -2382,6 +2382,7 @@
        the <structfield>pg_class</structfield> entry that defines the
        corresponding table. A table could theoretically be used as a
        composite data type, but this is not fully functional.
+       Zero for non-complex types.
       </entry>
      </row>
 
@@ -2511,38 +2512,53 @@
      </row>
 
      <row>
-      <entry>typbasetype</entry>
-      <entry><type>oid</type></entry>
+      <entry>typnotnull</entry>
+      <entry><type>bool</type></entry>
       <entry></entry>
       <entry><para>
-       <structfield>typbasetype</structfield> is the type that this one is based
-       on.  Normally references the domains parent type, and is 0 otherwise.
+       <structfield>typnotnull</structfield> represents a NOT NULL
+       constraint on a type.  Presently used for domains only.
       </para></entry>
      </row>
 
-	 <row>
-	  <entry>typnotnull</entry>
-	  <entry><type>boolean</type></entry>
-	  <entry></entry>
-	  <entry><para>
-	   <structfield>typnotnull</structfield> represents a NOT NULL
-	   constraint on a type.  Used for domains only.
-	  </para></entry>
-	 </row>
+     <row>
+      <entry>typbasetype</entry>
+      <entry><type>oid</type></entry>
+      <entry>pg_type.oid</entry>
+      <entry><para>
+       If this is a derived type (see <structfield>typtype</structfield>),
+       then <structfield>typbasetype</structfield> identifies
+       the type that this one is based on.  Zero if not a derived type.
+      </para></entry>
+     </row>
 
      <row>
-      <entry>typmod</entry>
-      <entry><type>integer</type></entry>
+      <entry>typtypmod</entry>
+      <entry><type>int4</type></entry>
       <entry></entry>
       <entry><para>
-       <structfield>typmod</structfield> records type-specific data
+       <structfield>typtypmod</structfield> records type-specific data
        supplied at table creation time (for example, the maximum
        length of a <type>varchar</type> column).  It is passed to
        type-specific input and output functions as the third
        argument. The value will generally be -1 for types that do not
-       need typmod.  This data is copied to
-       <structfield>pg_attribute.atttypmod</structfield> on creation
-       of a table using a domain as it's field type.
+       need typmod.  This value is copied to
+       <structfield>pg_attribute.atttypmod</structfield> when
+       creating a column of a domain type.
+       </para></entry>
+     </row>
+
+     <row>
+      <entry>typndims</entry>
+      <entry><type>int4</type></entry>
+      <entry></entry>
+      <entry><para>
+       <structfield>typndims</structfield> is the number of array dimensions
+       for a domain that is an array.  (The array element type is
+       typbasetype.)  Zero for non-domains and non-array domains.
+       This value is copied to
+       <structfield>pg_attribute.attndims</structfield> when
+       creating a column of a domain type.
        </para></entry>
      </row>
 
@@ -2551,9 +2567,9 @@
       <entry><type>text</type></entry>
       <entry></entry>
       <entry><para>
-       <structfield>typdefaultbin</structfield> is NULL for types without a
-       default value.  If it's not NULL, it contains the internal string
-       representation of the default expression node.
+       If <structfield>typdefaultbin</> is not NULL, it is the nodeToString
+       representation of a default expression for the type.  Currently this is
+       only used for domains.
       </para></entry>
      </row>
 
@@ -2562,9 +2578,14 @@
       <entry><type>text</type></entry>
       <entry></entry>
       <entry><para>
-       <structfield>typdefault</structfield> is NULL for types without a
-       default value.  If it's not NULL, it contains the external string
-       representation of the type's default value.
+       <structfield>typdefault</> is NULL if the type has no associated
+       default value. If <structfield>typdefaultbin</> is not NULL,
+       <structfield>typdefault</> must contain a human-readable version of the
+       default expression represented by <structfield>typdefaultbin</>.  If
+       <structfield>typdefaultbin</> is NULL and <structfield>typdefault</> is
+       not, then <structfield>typdefault</> is the external representation of
+       the type's default value, which may be fed to the type's input
+       converter to produce a constant.
       </para></entry>
      </row>
     </tbody>
diff --git a/doc/src/sgml/ref/create_domain.sgml b/doc/src/sgml/ref/create_domain.sgml
index 5f79dc63b53..222d49da5d1 100644
--- a/doc/src/sgml/ref/create_domain.sgml
+++ b/doc/src/sgml/ref/create_domain.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.3 2002/03/19 02:18:13 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.4 2002/03/20 19:43:28 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -23,13 +23,14 @@ PostgreSQL documentation
    <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> [, ... ] ]
+CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> [AS] <replaceable class="parameter">data_type</replaceable>
+    [ DEFAULT <replaceable>default_expr</> ]
+    [ <replaceable class="PARAMETER">constraint</replaceable> [, ... ] ]
+
+where <replaceable class="PARAMETER">constraint</replaceable> is:
+
 [ 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 ] -->
+{ NOT NULL | NULL }
   </synopsis>
 
   <refsect2 id="R2-SQL-CREATEDOMAIN-1">
@@ -67,23 +68,26 @@ CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> <replaceab
       <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
+        The <literal>DEFAULT</> clause specifies a default value for
+	columns of the domain data type.  The value
+        is any variable-free expression (but subselects 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
+        does not specify a value for the column.  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.
+         If a default value is specified 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.
         </para>
        </note>
       </listitem>
@@ -93,7 +97,7 @@ CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> <replaceab
       <term><literal>CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable></literal></term>
       <listitem>
        <para>
-        An optional name for a domain.  If not specified,
+        An optional name for a constraint.  If not specified,
         the system generates a name.
        </para>
       </listitem>
@@ -103,7 +107,7 @@ CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> <replaceab
       <term><literal>NOT NULL</></term>
       <listitem>
        <para>
-        The column is not allowed to contain NULL values.  This is
+        Values of this domain are not allowed to be NULL.  This is
         equivalent to the column constraint <literal>CHECK (<replaceable
         class="PARAMETER">column</replaceable> NOT NULL)</literal>.
        </para>
@@ -114,7 +118,7 @@ CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> <replaceab
       <term><literal>NULL</></term>
       <listitem>
        <para>
-        The column is allowed to contain NULL values. This is the default.
+        Values of this domain are allowed to be NULL.  This is the default.
        </para>
 
        <para>
@@ -175,7 +179,7 @@ CREATE DOMAIN
    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.
+   use that rather than setting up each table's constraints individually.
   </para>
  </refsect1>
 
@@ -195,9 +199,9 @@ CREATE TABLE countrylist (id INT4, country country_code);
   <title>Compatibility</title>
 
   <para>
-   This <command>CREATE DOMAIN</command> command is a
-   <productname>PostgreSQL</productname> extension.  CHECK and FOREIGN KEY
-   constraints are currently unsupported.
+   SQL99 defines CREATE DOMAIN, but says that the only allowed constraint
+   type is CHECK constraints.  CHECK constraints for domains are not yet
+   supported by <productname>PostgreSQL</productname>.
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/drop_domain.sgml b/doc/src/sgml/ref/drop_domain.sgml
index e9bc38ad28c..63eb0dc057e 100644
--- a/doc/src/sgml/ref/drop_domain.sgml
+++ b/doc/src/sgml/ref/drop_domain.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_domain.sgml,v 1.3 2002/03/19 02:18:13 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_domain.sgml,v 1.4 2002/03/20 19:43:28 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -23,7 +23,7 @@ PostgreSQL documentation
    <date>1999-07-20</date>
   </refsynopsisdivinfo>
   <synopsis>
-DROP DOMAIN <replaceable class="PARAMETER">domainname</replaceable> [, ...]
+DROP DOMAIN <replaceable class="PARAMETER">domainname</replaceable> [, ...]  [ CASCADE | RESTRICT ]
   </synopsis>
 
   <refsect2 id="R2-SQL-DROPDOMAIN-1">
@@ -43,6 +43,25 @@ DROP DOMAIN <replaceable class="PARAMETER">domainname</replaceable> [, ...]
        </para>
       </listitem>
      </varlistentry>
+
+     <varlistentry>
+      <term><literal>CASCADE</></term>
+      <listitem>
+       <para>
+        Automatically drop objects that depend on the domain.  This
+	behavior is not currently supported.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><literal>RESTRICT</></term>
+      <listitem>
+       <para>
+        Do not drop dependent objects.  This is the default.
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
    </para>
   </refsect2>
@@ -117,7 +136,7 @@ ERROR:  RemoveDomain: type '<replaceable class="parameter">domainname</replaceab
    To remove the <type>box</type> domain:
 
 <programlisting>
-DROP DOMAIN box RESTRICT;
+DROP DOMAIN box;
 </programlisting>
   </para>
  </refsect1>
@@ -134,9 +153,8 @@ DROP DOMAIN box RESTRICT;
 <synopsis>
 DROP DOMAIN <replaceable>name</replaceable> { CASCADE | RESTRICT }
 </synopsis>
-   <productname>PostgreSQL</productname> enforces the existance of
-   RESTRICT or CASCADE but ignores their enforcement against the
-   system tables.
+   <productname>PostgreSQL</productname> accepts only the RESTRICT
+   option, and currently does not check for existence of dependent objects.
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 350128fa724..40ba18716c2 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.64 2002/03/19 02:32:19 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.65 2002/03/20 19:43:30 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -419,21 +419,10 @@ testdb=>
         <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
         <listitem>
         <para>
-        Lists all database domains.
-        </para>
-
-        <para>
-        Descriptions for objects can be generated with the <command>COMMENT ON</command>
-        <acronym>SQL</acronym> command.
-	</para>
-
-        <note>
-        <para>
-        <productname>PostgreSQL</productname> stores the object descriptions in the
-        pg_description system table.
+        Lists all available domains (derived types).
+	If <replaceable class="parameter">pattern</replaceable>
+	(a regular expression) is specified, only matching domains are shown.
         </para>
-        </note>
-
         </listitem>
       </varlistentry>