<!-- doc/src/sgml/trigger.sgml -->

 <chapter id="triggers">
  <title>Triggers</title>

  <indexterm zone="triggers">
   <primary>trigger</primary>
  </indexterm>

  <para>
   This chapter provides general information about writing trigger functions.
   Trigger functions can be written in most of the available procedural
   languages, including
   <application>PL/pgSQL</application> (<xref linkend="plpgsql"/>),
   <application>PL/Tcl</application> (<xref linkend="pltcl"/>),
   <application>PL/Perl</application> (<xref linkend="plperl"/>), and
   <application>PL/Python</application> (<xref linkend="plpython"/>).
   After reading this chapter, you should consult the chapter for
   your favorite procedural language to find out the language-specific
   details of writing a trigger in it.
  </para>

  <para>
   It is also possible to write a trigger function in C, although
   most people find it easier to use one of the procedural languages.
   It is not currently possible to write a trigger function in the
   plain SQL function language.
  </para>

  <sect1 id="trigger-definition">
   <title>Overview of Trigger Behavior</title>

   <para>
    A trigger is a specification that the database should automatically
    execute a particular function whenever a certain type of operation is
    performed.  Triggers can be attached to tables (partitioned or not),
    views, and foreign tables.
  </para>

  <para>
    On tables and foreign tables, triggers can be defined to execute either
    before or after any <command>INSERT</command>, <command>UPDATE</command>,
    or <command>DELETE</command> operation, either once per modified row,
    or once per <acronym>SQL</acronym> statement.
    <command>UPDATE</command> triggers can moreover be set to fire only if
    certain columns are mentioned in the <literal>SET</literal> clause of
    the <command>UPDATE</command> statement.  Triggers can also fire
    for <command>TRUNCATE</command> statements.  If a trigger event occurs,
    the trigger's function is called at the appropriate time to handle the
    event.
   </para>

   <para>
    On views, triggers can be defined to execute instead of
    <command>INSERT</command>, <command>UPDATE</command>, or
    <command>DELETE</command> operations.
    Such <literal>INSTEAD OF</literal> triggers
    are fired once for each row that needs to be modified in the view.
    It is the responsibility of the
    trigger's function to perform the necessary modifications to the view's
    underlying base table(s) and, where appropriate, return the modified
    row as it will appear in the view.  Triggers on views can also be defined
    to execute once per <acronym>SQL</acronym> statement, before or after
    <command>INSERT</command>, <command>UPDATE</command>, or
    <command>DELETE</command> operations.
    However, such triggers are fired only if there is also
    an <literal>INSTEAD OF</literal> trigger on the view.  Otherwise,
    any statement targeting the view must be rewritten into a statement
    affecting its underlying base table(s), and then the triggers
    that will be fired are the ones attached to the base table(s).
   </para>

   <para>
    The trigger function must be defined before the trigger itself can be
    created.  The trigger function must be declared as a
    function taking no arguments and returning type <literal>trigger</literal>.
    (The trigger function receives its input through a specially-passed
    <structname>TriggerData</structname> structure, not in the form of ordinary function
    arguments.)
   </para>

   <para>
    Once a suitable trigger function has been created, the trigger is
    established with
    <xref linkend="sql-createtrigger"/>.
    The same trigger function can be used for multiple triggers.
   </para>

   <para>
    <productname>PostgreSQL</productname> offers both <firstterm>per-row</firstterm>
    triggers and <firstterm>per-statement</firstterm> triggers.  With a per-row
    trigger, the trigger function