Home Explore Blog CI



postgresql

5th chunk of `doc/src/sgml/trigger.sgml`
d722b104ba97d681535c06dada4b8b9440a0d02ef34338c90000000100000fa6
 trigger function to modify the
       row being inserted or updated.
      </para>
     </listitem>
    </itemizedlist>

    A row-level <literal>BEFORE</literal> trigger that does not intend to cause
    either of these behaviors must be careful to return as its result the same
    row that was passed in (that is, the <varname>NEW</varname> row
    for <command>INSERT</command> and <command>UPDATE</command>
    triggers, the <varname>OLD</varname> row for
    <command>DELETE</command> triggers).
   </para>

   <para>
    A row-level <literal>INSTEAD OF</literal> trigger should either return
    <symbol>NULL</symbol> to indicate that it did not modify any data from
    the view's underlying base tables, or it should return the view
    row that was passed in (the <varname>NEW</varname> row
    for <command>INSERT</command> and <command>UPDATE</command>
    operations, or the <varname>OLD</varname> row for
    <command>DELETE</command> operations). A nonnull return value is
    used to signal that the trigger performed the necessary data
    modifications in the view.  This will cause the count of the number
    of rows affected by the command to be incremented. For
    <command>INSERT</command> and <command>UPDATE</command> operations only, the trigger
    may modify the <varname>NEW</varname> row before returning it.  This will
    change the data returned by
    <command>INSERT RETURNING</command> or <command>UPDATE RETURNING</command>,
    and is useful when the view will not show exactly the same data
    that was provided.
   </para>

   <para>
    The return value is ignored for row-level triggers fired after an
    operation, and so they can return <symbol>NULL</symbol>.
   </para>

   <para>
    Some considerations apply for generated
    columns.<indexterm><primary>generated column</primary><secondary>in
    triggers</secondary></indexterm>  Stored generated columns are computed after
    <literal>BEFORE</literal> triggers and before <literal>AFTER</literal>
    triggers.  Therefore, the generated value can be inspected in
    <literal>AFTER</literal> triggers.  In <literal>BEFORE</literal> triggers,
    the <literal>OLD</literal> row contains the old generated value, as one
    would expect, but the <literal>NEW</literal> row does not yet contain the
    new generated value and should not be accessed.  In the C language
    interface, the content of the column is undefined at this point; a
    higher-level programming language should prevent access to a stored
    generated column in the <literal>NEW</literal> row in a
    <literal>BEFORE</literal> trigger.  Changes to the value of a generated
    column in a <literal>BEFORE</literal> trigger are ignored and will be
    overwritten.
    Virtual generated columns are never computed when triggers fire.  In the C
    language interface, their content is undefined in a trigger function.
    Higher-level programming languages should prevent access to virtual
    generated columns in triggers.
   </para>

   <para>
    If more than one trigger is defined for the same event on the same
    relation, the triggers will be fired in alphabetical order by
    trigger name.  In the case of <literal>BEFORE</literal> and
    <literal>INSTEAD OF</literal> triggers, the possibly-modified row returned by
    each trigger becomes the input to the next trigger.  If any
    <literal>BEFORE</literal> or <literal>INSTEAD OF</literal> trigger returns
    <symbol>NULL</symbol>, the operation is abandoned for that row and subsequent
    triggers are not fired (for that row).
   </para>

   <para>
    A trigger definition can also specify a Boolean <literal>WHEN</literal>
    condition, which will be tested to see whether the trigger should
    be fired.  In row-level triggers the <literal>WHEN</literal> condition can
    examine the old and/or new values of columns of the row.  (Statement-level
    triggers can also have <literal>WHEN</literal> conditions, although the feature
    is not so useful

Title: Trigger Behavior and Execution Rules
Summary
This section describes the rules governing trigger behavior, including return values, generated columns, trigger ordering, and conditional trigger firing, and explains how triggers can modify rows, abandon operations, and interact with each other, as well as the use of WHEN conditions to control trigger firing based on old and new column values.