Merge docs for CREATE CONSTRAINT TRIGGER and CREATE TRIGGER

diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index f5d67a207876cd40f64f4736575409e06cfa4b4b..a352a431419b8b36722f41a85a716d4f3a21a449 100644 (file)
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -46,7 +46,6 @@ Complete list of usable sgml source files in this directory.
 <!entity copyTable          system "copy.sgml">
 <!entity createAggregate    system "create_aggregate.sgml">
 <!entity createCast         system "create_cast.sgml">
-<!entity createConstraint   system "create_constraint.sgml">
 <!entity createConversion   system "create_conversion.sgml">
 <!entity createDatabase     system "create_database.sgml">
 <!entity createDomain       system "create_domain.sgml">

diff --git a/doc/src/sgml/ref/create_constraint.sgml b/doc/src/sgml/ref/create_constraint.sgml
deleted file mode 100644 (file)
index 3ec3f74..0000000
--- a/doc/src/sgml/ref/create_constraint.sgml
+++ /dev/null
@@ -1,171 +0,0 @@
-<!--
-doc/src/sgml/ref/create_constraint.sgml
-PostgreSQL documentation
--->
-
-<refentry id="SQL-CREATECONSTRAINT">
- <refmeta>
-  <refentrytitle>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
-    [ WHEN ( <replaceable class="parameter">condition</replaceable> ) ]
-    EXECUTE PROCEDURE <replaceable class="parameter">function_name</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">.
-   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">
-      documentation for details of these constraint options.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><replaceable class="parameter">condition</replaceable></term>
-    <listitem>
-     <para>
-      A Boolean expression that determines whether the trigger function
-      will actually be executed.  This acts the same as in <xref
-      linkend="SQL-CREATETRIGGER">.
-      Note in particular that evaluation of the <literal>WHEN</>
-      condition is not deferred, but occurs immediately after the row
-      update operation is performed.  If the condition does not evaluate
-      to <literal>true</> then the trigger is not queued for deferred
-      execution.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><replaceable class="PARAMETER">function_name</replaceable></term>
-    <listitem>
-     <para>
-      The function to call when the trigger is fired. See <xref
-      linkend="SQL-CREATETRIGGER"> 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"> 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"></member>
-   <member><xref linkend="sql-droptrigger"></member>
-   <member><xref linkend="sql-set-constraints"></member>
-  </simplelist>
- </refsect1>
-</refentry>

diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml
index 95d67aad6f5c0db72103967ac218b9e316bdfdca..492611eea8b2c41916cbddf2296435373147a864 100644 (file)
--- a/doc/src/sgml/ref/create_trigger.sgml
+++ b/doc/src/sgml/ref/create_trigger.sgml
@@ -21,8 +21,10 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTER | INSTEAD OF } { <replaceable class="PARAMETER">event</replaceable> [ OR ... ] }
+CREATE [ CONSTRAINT ] TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTER | INSTEAD OF } { <replaceable class="PARAMETER">event</replaceable> [ OR ... ] }
     ON <replaceable class="PARAMETER">table</replaceable> [ FOR [ EACH ] { ROW | STATEMENT } ]
+    [ FROM <replaceable class="parameter">referenced_table_name</replaceable> ]
+    { NOT DEFERRABLE | [ DEFERRABLE ] { INITIALLY IMMEDIATE | INITIALLY DEFERRED } }
     [ WHEN ( <replaceable class="parameter">condition</replaceable> ) ]
     EXECUTE PROCEDURE <replaceable class="PARAMETER">function_name</replaceable> ( <replaceable class="PARAMETER">arguments</replaceable> )
 </synopsis>
@@ -149,6 +151,20 @@ CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTE
    they will be fired in alphabetical order by name.
   </para>
 
+  <para>
+   When the <literal>CONSTRAINT</> option is specified, this 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">.
+   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</>.
+   Constraint triggers are expected to raise an exception when the constraints
+   they implement are violated.
+  </para>
+
   <para>
    <command>SELECT</command> does not modify any rows so you cannot
    create <command>SELECT</command> triggers. Rules and views are more
@@ -170,6 +186,10 @@ CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTE
      <para>
       The name to give the new trigger.  This must be distinct from
       the name of any other trigger for the same table.
+      The name cannot be schema-qualified &mdash; the trigger inherits the
+      schema of its table.  For a constraint trigger, this is also the name to
+      use when modifying the trigger's behavior using
+      <command>SET CONSTRAINTS</>.
      </para>
     </listitem>
    </varlistentry>
@@ -181,7 +201,8 @@ CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTE
     <listitem>
      <para>
       Determines whether the function is called before, after, or instead of
-      the event.
+      the event.  A constraint trigger can only be specified as
+      <literal>AFTER</>.
      </para>
     </listitem>
    </varlistentry>
@@ -222,6 +243,33 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</
     </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.  This can only be specified for
+      constraint triggers.
+     </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"> documentation for details of
+      these constraint options.  This can only be specified for constraint
+      triggers.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><literal>FOR EACH ROW</literal></term>
     <term><literal>FOR EACH STATEMENT</literal></term>
@@ -231,7 +279,8 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</
       This specifies whether the trigger procedure should be fired
       once for every row affected by the trigger event, or just once
       per SQL statement. If neither is specified, <literal>FOR EACH
-      STATEMENT</literal> is the default.
+      STATEMENT</literal> is the default.  Constraint triggers can only
+      be specified <literal>FOR EACH ROW</>.
      </para>
     </listitem>
    </varlistentry>
@@ -263,6 +312,13 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</
       Currently, <literal>WHEN</literal> expressions cannot contain
       subqueries.
      </para>
+
+     <para>
+      Note that for constraint triggers, evaluation of the <literal>WHEN</>
+      condition is not deferred, but occurs immediately after the row update
+      operation is performed. If the condition does not evaluate to true then
+      the trigger is not queued for deferred execution.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -481,6 +537,12 @@ CREATE TRIGGER view_insert
    ability to define statement-level triggers on views.
   </para>
 
+  <para>
+   <command>CREATE CONSTRAINT TRIGGER</command> is a
+   <productname>PostgreSQL</productname> extension of the <acronym>SQL</>
+   standard.
+  </para>
+
  </refsect1>
 
  <refsect1>
@@ -490,6 +552,7 @@ CREATE TRIGGER view_insert
    <member><xref linkend="sql-createfunction"></member>
    <member><xref linkend="sql-altertrigger"></member>
    <member><xref linkend="sql-droptrigger"></member>
+   <member><xref linkend="sql-set-constraints"></member>
   </simplelist>
  </refsect1>
 </refentry>

diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index 463746cda3a0553cb43c3ef76623aaa055fd7327..13de002792538595d0a7c23a9b79f19144dc328f 100644 (file)
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -74,7 +74,6 @@
    &copyTable;
    &createAggregate;
    &createCast;
-   &createConstraint;
    &createConversion;
    &createDatabase;
    &createDomain;