postgres/doc/src/sgml/func/func-trigger.sgml

  <sect1 id="functions-trigger">
   <title>Trigger Functions</title>

  <para>
   While many uses of triggers involve user-written trigger functions,
   <productname>PostgreSQL</productname> provides a few built-in trigger
   functions that can be used directly in user-defined triggers.  These
   are summarized in <xref linkend="builtin-triggers-table"/>.
   (Additional built-in trigger functions exist, which implement foreign
   key constraints and deferred index constraints.  Those are not documented
   here since users need not use them directly.)
  </para>

  <para>
   For more information about creating triggers, see
   <xref linkend="sql-createtrigger"/>.
  </para>

   <table id="builtin-triggers-table">
    <title>Built-In Trigger Functions</title>
    <tgroup cols="1">
     <thead>
      <row>
       <entry role="func_table_entry"><para role="func_signature">
        Function
       </para>
       <para>
        Description
       </para>
       <para>
        Example Usage
       </para></entry>
      </row>
     </thead>

     <tbody>
       <row>
       <entry role="func_table_entry"><para role="func_signature">
        <indexterm>
         <primary>suppress_redundant_updates_trigger</primary>
        </indexterm>
        <function>suppress_redundant_updates_trigger</function> ( )
        <returnvalue>trigger</returnvalue>
       </para>
       <para>
        Suppresses do-nothing update operations.  See below for details.
       </para>
       <para>
        <literal>CREATE TRIGGER ... suppress_redundant_updates_trigger()</literal>
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <indexterm>
         <primary>tsvector_update_trigger</primary>
        </indexterm>
        <function>tsvector_update_trigger</function> ( )
        <returnvalue>trigger</returnvalue>
       </para>
       <para>
        Automatically updates a <type>tsvector</type> column from associated
        plain-text document column(s).  The text search configuration to use
        is specified by name as a trigger argument.  See
        <xref linkend="textsearch-update-triggers"/> for details.
       </para>
       <para>
        <literal>CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)</literal>
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <indexterm>
         <primary>tsvector_update_trigger_column</primary>
        </indexterm>
        <function>tsvector_update_trigger_column</function> ( )
        <returnvalue>trigger</returnvalue>
       </para>
       <para>
        Automatically updates a <type>tsvector</type> column from associated
        plain-text document column(s).  The text search configuration to use
        is taken from a <type>regconfig</type> column of the table.  See
        <xref linkend="textsearch-update-triggers"/> for details.
       </para>
       <para>
        <literal>CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, tsconfigcol, title, body)</literal>
       </para></entry>
      </row>
     </tbody>
    </tgroup>
   </table>

   <para>
      The <function>suppress_redundant_updates_trigger</function> function,
      when applied as a row-level <literal>BEFORE UPDATE</literal> trigger,
      will prevent any update that does not actually change the data in the
      row from taking place.  This overrides the normal behavior which always
      performs a physical row update
      regardless of whether or not the data has changed. (This normal behavior
      makes updates run faster, since no checking is required, and is also
      useful in certain cases.)
    </para>

    <para>
      Ideally, you should 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</function>, 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 updates do actually change,
      use of this trigger will make updates run slower on average.
    </para>

    <para>
      The <function>suppress_redundant_updates_trigger</function> function can be
      added to a table like this:
<programlisting>
CREATE TRIGGER z_min_update
BEFORE UPDATE ON tablename
FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
</programlisting>
      In most cases, you need to fire this trigger last for each row, so that
      it does not override other triggers that might wish to alter the row.
      Bearing in mind that triggers fire in name order, you would therefore
      choose a trigger name that comes after the name of any other trigger
      you might have on the table.  (Hence the <quote>z</quote> prefix in the
      example.)
    </para>
  </sect1>