postgres/doc/src/sgml/ref/alter_domain.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_domain.sgml,v 1.10 2003/09/22 00:16:57 petere Exp $
PostgreSQL documentation
-->

<refentry id="SQL-ALTERDOMAIN">
 <refmeta>
  <refentrytitle id="sql-alterdomain-title">ALTER DOMAIN</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>
   ALTER DOMAIN
  </refname>
  <refpurpose>
   change the definition of a domain
  </refpurpose>
 </refnamediv>

 <indexterm zone="sql-alterdomain">
  <primary>ALTER DOMAIN</primary>
 </indexterm>

 <refsynopsisdiv>
  <synopsis>
ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
    { SET DEFAULT <replaceable class="PARAMETER">expression</replaceable> | DROP DEFAULT }
ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
    { SET | DROP } NOT NULL
ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
    ADD <replaceable class="PARAMETER">domain_constraint</replaceable>
ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
    DROP CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> [ RESTRICT | CASCADE ]
ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
    OWNER TO <replaceable class="PARAMETER">new_owner</replaceable> 
  </synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>ALTER DOMAIN</command> changes the definition of an existing domain.
   There are several sub-forms:
  </para>

  <variablelist>
   <varlistentry>
    <term>SET/DROP DEFAULT</term>
    <listitem>
     <para>
      These forms set or remove the default value for a domain. Note
      that defaults only apply to subsequent <command>INSERT</command>
      commands; they do not affect rows already in a table using the domain.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>SET/DROP NOT NULL</term>
    <listitem>
     <para>
      These forms change whether a domain is marked to allow NULL
      values or to reject NULL values.  You may only <literal>SET NOT NULL</>
      when the columns using the domain contain no null values.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>ADD <replaceable class="PARAMETER">domain_constraint</replaceable></term>
    <listitem>
     <para>
      This form adds a new constraint to a domain using the same syntax as
      <xref linkend="SQL-CREATEDOMAIN" endterm="SQL-CREATEDOMAIN-TITLE">.
      This will only succeed if all columns using the domain satisfy the
      new constraint.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>DROP CONSTRAINT</term>
    <listitem>
     <para>
      This form drops constraints on a domain.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>OWNER</term>
    <listitem>
     <para>
      This form changes the owner of the domain to the specified user.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   You must own the domain to use <command>ALTER DOMAIN</>; except for
   <command>ALTER DOMAIN OWNER</>, which may only be executed by a superuser.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

   <para>
    <variablelist>
     <varlistentry>
      <term><replaceable class="PARAMETER">name</replaceable></term>
      <listitem>
       <para>
	The name (possibly schema-qualified) of an existing domain to
	alter.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="PARAMETER">domain_constraint</replaceable></term>
      <listitem>
       <para>
	New domain constraint for the domain.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
      <listitem>
       <para>
	Name of an existing constraint to drop.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>CASCADE</term>
      <listitem>
       <para>
        Automatically drop objects that depend on the constraint.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>RESTRICT</term>
      <listitem>
       <para>
        Refuse to drop the constraint if there are any dependent
	objects. This is the default behavior.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="PARAMETER">new_owner</replaceable></term>
      <listitem>
       <para>
	The user name of the new owner of the domain.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
  </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   To add a NOT NULL constraint to a domain:
   <programlisting>
ALTER DOMAIN zipcode SET NOT NULL;
   </programlisting>
   To remove a NOT NULL constraint from a domain:
   <programlisting>
ALTER DOMAIN zipcode DROP NOT NULL;
   </programlisting>
  </para>

  <para> 
   To add a check constraint to a domain:
   <programlisting>
ALTER DOMAIN zipcode ADD CONSTRAINT zipchk CHECK (char_length(VALUE) = 5);
   </programlisting>
  </para>

  <para> 
   To remove a check constraint from a domain:
   <programlisting>
ALTER DOMAIN zipcode DROP CONSTRAINT zipchk;
   </programlisting>
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>
    
  <para>
   The <command>ALTER DOMAIN</command> statement is compatible with SQL99,
   except for the <literal>OWNER</> variant, which is a
   <productname>PostgreSQL</productname> extension.
  </para>
 </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:
-->