suppress_redundant_updates_trigger function.

1 files changed, 52 insertions, 1 deletions

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7cfb1219889..0aaf4c1b480 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.452 2008/11/03 17:51:12 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.453 2008/11/03 20:17:20 adunstan Exp $ -->
 
  <chapter id="functions">
   <title>Functions and Operators</title>
@@ -12846,4 +12846,55 @@ SELECT (pg_stat_file('filename')).modification;
 
   </sect1>
 
+  <sect1 id="functions-trigger">
+   <title>Trigger Functions</title>
+
+   <indexterm>
+     <primary>suppress_redundant_updates_trigger</primary>
+   </indexterm>
+
+   <para>
+      Currently <productname>PostgreSQL</> provides one built in trigger
+	  function, <function>suppress_redundant_updates_trigger</>, 
+	  which will prevent any update
+	  that does not actually change the data in the row from taking place, in
+	  contrast to the normal behaviour which always performs the update
+	  regardless of whether or not the data has changed. (This normal behaviour
+	  makes updates run faster, since no checking is required, and is also
+	  useful in certain cases.)
+    </para>
+
+	<para>
+	  Ideally, you should normally avoid running updates that don't actually
+	  change the data in the record. Redundant updates can cost considerable
+	  unnecessary time, especially if there are lots of indexes to alter,
+	  and space in dead rows that will eventually have to be vacuumed.
+	  However, detecting such situations in client code is not
+	  always easy, or even possible, and writing expressions to detect
+	  them can be error-prone. An alternative is to use 
+	  <function>suppress_redundant_updates_trigger</>, which will skip
+	  updates that don't change the data. You should use this with care,
+	  however. The trigger takes a small but non-trivial time for each record, 
+	  so if most of the records affected by an update are actually changed,
+	  use of this trigger will actually make the update run slower.
+    </para>
+
+    <para>
+      The <function>suppress_redundant_updates_trigger</> function can be 
+	  added to a table like this:
+<programlisting>
+CREATE TRIGGER z_min_update 
+BEFORE UPDATE ON tablename
+FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger();
+</programlisting>
+      In most cases, you would want to fire this trigger last for each row.
+	  Bearing in mind that triggers fire in name order, you would then
+	  choose a trigger name that comes after the name of any other trigger
+      you might have on the table.
+    </para>
+	<para>
+       For more information about creating triggers, see
+	    <xref linkend="SQL-CREATETRIGGER">.
+    </para>
+  </sect1>
 </chapter>