Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.

20 years ago · 130b2dd8ea
parent 249a720ec5
commit 130b2dd8ea
3 changed files with 87 additions and 8 deletions
--- 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
- $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>
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/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>
--- a/doc/src/sgml/ref/alter_trigger.sgml
+++ b/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