Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.

Author: tglsfdc

doc/src/sgml/catalogs.sgml

@@ -1,6 +1,6 @@
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.111 2005/08/11 21:11:41 tgl Exp $
+ $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.112 2005/08/24 17:24:17 tgl Exp $
  -->
 
 <chapter id="catalogs">
@@ -3789,9 +3789,7 @@
       <entry><structfield>tgenabled</structfield></entry>
       <entry><type>bool</type></entry>
       <entry></entry>
-      <entry>True if trigger is enabled (not presently checked everywhere
-      it should be, so disabling a trigger by setting this false does not
-      work reliably)</entry>
+      <entry>True if trigger is enabled</entry>
      </row>
 
      <row>

doc/src/sgml/ref/alter_table.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.80 2005/08/22 21:32:01 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.81 2005/08/24 17:24:19 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -41,6 +41,8 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }
     ADD <replaceable class="PARAMETER">table_constraint</replaceable>
     DROP CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> [ RESTRICT | CASCADE ]
+    DISABLE TRIGGER [ <replaceable class="PARAMETER">trigger_name</replaceable> | ALL | USER ]
+    ENABLE TRIGGER [ <replaceable class="PARAMETER">trigger_name</replaceable> | ALL | USER ]
     CLUSTER ON <replaceable class="PARAMETER">index_name</replaceable>
     SET WITHOUT CLUSTER
     SET WITHOUT OIDS
@@ -189,6 +191,25 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><literal>DISABLE</literal>/<literal>ENABLE TRIGGER</literal></term>
+    <listitem>
+     <para>
+      These forms disable or enable trigger(s) belonging to the table.
+      A disabled trigger is still known to the system, but is not executed
+      when its triggering event occurs.  For a deferred trigger, the enable
+      status is checked when the event occurs, not when the trigger function
+      is actually executed.  One may disable or enable a single
+      trigger specified by name, or all triggers on the table, or only
+      user triggers (this option excludes triggers that are used to implement
+      foreign key constraints).  Disabling or enabling constraint triggers
+      requires superuser privileges; it should be done with caution since
+      of course the integrity of the constraint cannot be guaranteed if the
+      triggers are not executed.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><literal>CLUSTER</literal></term>
     <listitem>
@@ -292,8 +313,11 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
    You must own the table to use <command>ALTER TABLE</>.
    To change the schema of a table, you must also have
    <literal>CREATE</literal> privilege on the new schema.
-   To alter the owner, the new owner must have
-   <literal>CREATE</literal> privilege on the schema.
+   To alter the owner, you must also be a direct or indirect member of the new
+   owning role, and that role must have <literal>CREATE</literal> privilege on
+   the table's schema.  (These restrictions enforce that altering the owner
+   doesn't do anything you couldn't do by dropping and recreating the table.
+   However, a superuser can alter ownership of any table anyway.)
   </para>
  </refsect1>
 
@@ -394,6 +418,36 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><replaceable class="PARAMETER">trigger_name</replaceable></term>
+      <listitem>
+       <para>
+        Name of a single trigger to disable or enable.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><literal>ALL</literal></term>
+      <listitem>
+       <para>
+        Disable or enable all triggers belonging to the table.
+        (This requires superuser privilege if any of the triggers are for
+        foreign key constraints.)
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><literal>USER</literal></term>
+      <listitem>
+       <para>
+        Disable or enable all triggers belonging to the table except for
+        foreign key constraint triggers.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><replaceable class="PARAMETER">index_name</replaceable></term>
       <listitem>
@@ -524,6 +578,13 @@ ALTER TABLE table ALTER COLUMN anycol TYPE anytype;
     instead marks them as independently defined rather than inherited.
    </para>
 
+   <para>
+    The <literal>TRIGGER</>, <literal>CLUSTER</>, <literal>OWNER</>,
+    and <literal>TABLESPACE</> actions never recurse to descendant tables;
+    that is, they always act as though <literal>ONLY</> were specified.
+    Adding a constraint can recurse only for <literal>CHECK</> constraints.
+   </para>
+
    <para>
     Changing any part of a system catalog table is not permitted.
    </para>

doc/src/sgml/ref/alter_trigger.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_trigger.sgml,v 1.8 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_trigger.sgml,v 1.9 2005/08/24 17:24:19 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -72,6 +72,18 @@ ALTER TRIGGER <replaceable class="PARAMETER">name</replaceable> ON <replaceable
   </variablelist>
  </refsect1>
 
+ <refsect1>
+  <title>Notes</title>
+
+   <para>
+    The ability to temporarily enable or disable a trigger is provided by
+    <xref linkend="SQL-ALTERTABLE" endterm="SQL-ALTERTABLE-TITLE">, not by
+    <command>ALTER TRIGGER</>, because <command>ALTER TRIGGER</> has no
+    convenient way to express the option of enabling or disabling all of
+    a table's triggers at once.
+   </para>
+ </refsect1>
+
  <refsect1>
   <title>Examples</title>
 
@@ -91,6 +103,14 @@ ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs;
    extension of the SQL standard.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-altertable" endterm="sql-altertable-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file