postgresql/doc/src/sgml/ref/create_constraint.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_constraint.sgml,v 1.19 2008/11/14 10:22:46 petere Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CREATECONSTRAINT">
 <refmeta>
  <refentrytitle id="sql-createconstraint-title">CREATE CONSTRAINT TRIGGER</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE CONSTRAINT TRIGGER</refname>
  <refpurpose>define a new constraint trigger</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createconstraint">
  <primary>CREATE CONSTRAINT TRIGGER</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
    AFTER <replaceable class="parameter">event</replaceable> [ OR ... ]
    ON <replaceable class="parameter">table_name</replaceable>
    [ FROM <replaceable class="parameter">referenced_table_name</replaceable> ]
    { NOT DEFERRABLE | [ DEFERRABLE ] { INITIALLY IMMEDIATE | INITIALLY DEFERRED } }
    FOR EACH ROW
    EXECUTE PROCEDURE <replaceable class="parameter">funcname</replaceable> ( <replaceable class="parameter">arguments</replaceable> )
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>CREATE CONSTRAINT TRIGGER</command> creates a
   <firstterm>constraint trigger</>.  This is the same as a regular trigger
   except that the timing of the trigger firing can be adjusted using
   <xref linkend="SQL-SET-CONSTRAINTS" endterm="SQL-SET-CONSTRAINTS-TITLE">.
   Constraint triggers must be <literal>AFTER ROW</> triggers.  They can
   be fired either at the end of the statement causing the triggering event,
   or at the end of the containing transaction; in the latter case they are
   said to be <firstterm>deferred</>.  A pending deferred-trigger firing can
   also be forced to happen immediately by using <command>SET CONSTRAINTS</>.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="PARAMETER">name</replaceable></term>
    <listitem>
     <para>
      The name of the constraint trigger.  This is also the name to use
      when modifying the trigger's behavior using <command>SET CONSTRAINTS</>.
      The name cannot be schema-qualified &mdash; the trigger inherits the
      schema of its table.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">event</replaceable></term>
    <listitem>
     <para>
      One of <literal>INSERT</literal>, <literal>UPDATE</literal>, or
      <literal>DELETE</literal>; this specifies the event that will fire the
      trigger. Multiple events can be specified using <literal>OR</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">table_name</replaceable></term>
    <listitem>
     <para>
      The (possibly schema-qualified) name of the table in which
      the triggering events occur.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">referenced_table_name</replaceable></term>
    <listitem>
     <para>
      The (possibly schema-qualified) name of another table referenced by the
      constraint.  This option is used for foreign-key constraints and is not
      recommended for general use.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>DEFERRABLE</literal></term>
    <term><literal>NOT DEFERRABLE</literal></term>
    <term><literal>INITIALLY IMMEDIATE</literal></term>
    <term><literal>INITIALLY DEFERRED</literal></term>
    <listitem>
     <para>
      The default timing of the trigger.
      See the <xref linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-TITLE">
      documentation for details of these constraint options.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">funcname</replaceable></term>
    <listitem>
     <para>
      The function to call when the trigger is fired. See <xref
      linkend="SQL-CREATETRIGGER" endterm="SQL-CREATETRIGGER-TITLE"> for
      details.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">arguments</replaceable></term>
    <listitem>
     <para>
      Optional argument strings to pass to the trigger function. See <xref
      linkend="SQL-CREATETRIGGER" endterm="SQL-CREATETRIGGER-TITLE"> for
      details.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
  </refsect1>

 <refsect1>
  <title>Compatibility</title>
  <para>
   <command>CREATE CONSTRAINT TRIGGER</command> is a
   <productname>PostgreSQL</productname> extension of the <acronym>SQL</>
   standard.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-createtrigger" endterm="sql-createtrigger-title"></member>
   <member><xref linkend="sql-droptrigger" endterm="sql-droptrigger-title"></member>
   <member><xref linkend="sql-set-constraints" endterm="sql-set-constraints-title"></member>
  </simplelist>
 </refsect1>
</refentry>