begriffs open source - ai-pg/blob - full-docs/txt/trigger-definition.txt

   1
   2 37.1. Overview of Trigger Behavior #
   3
   4    A trigger is a specification that the database should automatically
   5    execute a particular function whenever a certain type of operation is
   6    performed. Triggers can be attached to tables (partitioned or not),
   7    views, and foreign tables.
   8
   9    On tables and foreign tables, triggers can be defined to execute either
  10    before or after any INSERT, UPDATE, or DELETE operation, either once
  11    per modified row, or once per SQL statement. UPDATE triggers can
  12    moreover be set to fire only if certain columns are mentioned in the
  13    SET clause of the UPDATE statement. Triggers can also fire for TRUNCATE
  14    statements. If a trigger event occurs, the trigger's function is called
  15    at the appropriate time to handle the event.
  16
  17    On views, triggers can be defined to execute instead of INSERT, UPDATE,
  18    or DELETE operations. Such INSTEAD OF triggers are fired once for each
  19    row that needs to be modified in the view. It is the responsibility of
  20    the trigger's function to perform the necessary modifications to the
  21    view's underlying base table(s) and, where appropriate, return the
  22    modified row as it will appear in the view. Triggers on views can also
  23    be defined to execute once per SQL statement, before or after INSERT,
  24    UPDATE, or DELETE operations. However, such triggers are fired only if
  25    there is also an INSTEAD OF trigger on the view. Otherwise, any
  26    statement targeting the view must be rewritten into a statement
  27    affecting its underlying base table(s), and then the triggers that will
  28    be fired are the ones attached to the base table(s).
  29
  30    The trigger function must be defined before the trigger itself can be
  31    created. The trigger function must be declared as a function taking no
  32    arguments and returning type trigger. (The trigger function receives
  33    its input through a specially-passed TriggerData structure, not in the
  34    form of ordinary function arguments.)
  35
  36    Once a suitable trigger function has been created, the trigger is
  37    established with CREATE TRIGGER. The same trigger function can be used
  38    for multiple triggers.
  39
  40    PostgreSQL offers both per-row triggers and per-statement triggers.
  41    With a per-row trigger, the trigger function is invoked once for each
  42    row that is affected by the statement that fired the trigger. In
  43    contrast, a per-statement trigger is invoked only once when an
  44    appropriate statement is executed, regardless of the number of rows
  45    affected by that statement. In particular, a statement that affects
  46    zero rows will still result in the execution of any applicable
  47    per-statement triggers. These two types of triggers are sometimes
  48    called row-level triggers and statement-level triggers, respectively.
  49    Triggers on TRUNCATE may only be defined at statement level, not
  50    per-row.
  51
  52    Triggers are also classified according to whether they fire before,
  53    after, or instead of the operation. These are referred to as BEFORE
  54    triggers, AFTER triggers, and INSTEAD OF triggers respectively.
  55    Statement-level BEFORE triggers naturally fire before the statement
  56    starts to do anything, while statement-level AFTER triggers fire at the
  57    very end of the statement. These types of triggers may be defined on
  58    tables, views, or foreign tables. Row-level BEFORE triggers fire
  59    immediately before a particular row is operated on, while row-level
  60    AFTER triggers fire at the end of the statement (but before any
  61    statement-level AFTER triggers). These types of triggers may only be
  62    defined on tables and foreign tables, not views. INSTEAD OF triggers
  63    may only be defined on views, and only at row level; they fire
  64    immediately as each row in the view is identified as needing to be
  65    operated on.
  66
  67    The execution of an AFTER trigger can be deferred to the end of the
  68    transaction, rather than the end of the statement, if it was defined as
  69    a constraint trigger. In all cases, a trigger is executed as part of
  70    the same transaction as the statement that triggered it, so if either
  71    the statement or the trigger causes an error, the effects of both will
  72    be rolled back. Also, the trigger will always run as the role that
  73    queued the trigger event, unless the trigger function is marked as
  74    SECURITY DEFINER, in which case it will run as the function owner.
  75
  76    If an INSERT contains an ON CONFLICT DO UPDATE clause, it is possible
  77    for row-level BEFORE INSERT and then BEFORE UPDATE triggers to be
  78    executed on triggered rows. Such interactions can be complex if the
  79    triggers are not idempotent because change made by BEFORE INSERT
  80    triggers will be seen by BEFORE UPDATE triggers, including changes to
  81    EXCLUDED columns.
  82
  83    Note that statement-level UPDATE triggers are executed when ON CONFLICT
  84    DO UPDATE is specified, regardless of whether or not any rows were
  85    affected by the UPDATE (and regardless of whether the alternative
  86    UPDATE path was ever taken). An INSERT with an ON CONFLICT DO UPDATE
  87    clause will execute statement-level BEFORE INSERT triggers first, then
  88    statement-level BEFORE UPDATE triggers, followed by statement-level
  89    AFTER UPDATE triggers and finally statement-level AFTER INSERT
  90    triggers.
  91
  92    A statement that targets a parent table in an inheritance or
  93    partitioning hierarchy does not cause the statement-level triggers of
  94    affected child tables to be fired; only the parent table's
  95    statement-level triggers are fired. However, row-level triggers of any
  96    affected child tables will be fired.
  97
  98    If an UPDATE on a partitioned table causes a row to move to another
  99    partition, it will be performed as a DELETE from the original partition
 100    followed by an INSERT into the new partition. In this case, all
 101    row-level BEFORE UPDATE triggers and all row-level BEFORE DELETE
 102    triggers are fired on the original partition. Then all row-level BEFORE
 103    INSERT triggers are fired on the destination partition. The possibility
 104    of surprising outcomes should be considered when all these triggers
 105    affect the row being moved. As far as AFTER ROW triggers are concerned,
 106    AFTER DELETE and AFTER INSERT triggers are applied; but AFTER UPDATE
 107    triggers are not applied because the UPDATE has been converted to a
 108    DELETE and an INSERT. As far as statement-level triggers are concerned,
 109    none of the DELETE or INSERT triggers are fired, even if row movement
 110    occurs; only the UPDATE triggers defined on the target table used in
 111    the UPDATE statement will be fired.
 112
 113    No separate triggers are defined for MERGE. Instead, statement-level or
 114    row-level UPDATE, DELETE, and INSERT triggers are fired depending on
 115    (for statement-level triggers) what actions are specified in the MERGE
 116    query and (for row-level triggers) what actions are performed.
 117
 118    While running a MERGE command, statement-level BEFORE and AFTER
 119    triggers are fired for events specified in the actions of the MERGE
 120    command, irrespective of whether or not the action is ultimately
 121    performed. This is the same as an UPDATE statement that updates no
 122    rows, yet statement-level triggers are fired. The row-level triggers
 123    are fired only when a row is actually updated, inserted or deleted. So
 124    it's perfectly legal that while statement-level triggers are fired for
 125    certain types of action, no row-level triggers are fired for the same
 126    kind of action.
 127
 128    Trigger functions invoked by per-statement triggers should always
 129    return NULL. Trigger functions invoked by per-row triggers can return a
 130    table row (a value of type HeapTuple) to the calling executor, if they
 131    choose. A row-level trigger fired before an operation has the following
 132    choices:
 133      * It can return NULL to skip the operation for the current row. This
 134        instructs the executor to not perform the row-level operation that
 135        invoked the trigger (the insertion, modification, or deletion of a
 136        particular table row).
 137      * For row-level INSERT and UPDATE triggers only, the returned row
 138        becomes the row that will be inserted or will replace the row being
 139        updated. This allows the trigger function to modify the row being
 140        inserted or updated.
 141
 142    A row-level BEFORE trigger that does not intend to cause either of
 143    these behaviors must be careful to return as its result the same row
 144    that was passed in (that is, the NEW row for INSERT and UPDATE
 145    triggers, the OLD row for DELETE triggers).
 146
 147    A row-level INSTEAD OF trigger should either return NULL to indicate
 148    that it did not modify any data from the view's underlying base tables,
 149    or it should return the view row that was passed in (the NEW row for
 150    INSERT and UPDATE operations, or the OLD row for DELETE operations). A
 151    nonnull return value is used to signal that the trigger performed the
 152    necessary data modifications in the view. This will cause the count of
 153    the number of rows affected by the command to be incremented. For
 154    INSERT and UPDATE operations only, the trigger may modify the NEW row
 155    before returning it. This will change the data returned by INSERT
 156    RETURNING or UPDATE RETURNING, and is useful when the view will not
 157    show exactly the same data that was provided.
 158
 159    The return value is ignored for row-level triggers fired after an
 160    operation, and so they can return NULL.
 161
 162    Some considerations apply for generated columns. Stored generated
 163    columns are computed after BEFORE triggers and before AFTER triggers.
 164    Therefore, the generated value can be inspected in AFTER triggers. In
 165    BEFORE triggers, the OLD row contains the old generated value, as one
 166    would expect, but the NEW row does not yet contain the new generated
 167    value and should not be accessed. In the C language interface, the
 168    content of the column is undefined at this point; a higher-level
 169    programming language should prevent access to a stored generated column
 170    in the NEW row in a BEFORE trigger. Changes to the value of a generated
 171    column in a BEFORE trigger are ignored and will be overwritten. Virtual
 172    generated columns are never computed when triggers fire. In the C
 173    language interface, their content is undefined in a trigger function.
 174    Higher-level programming languages should prevent access to virtual
 175    generated columns in triggers.
 176
 177    If more than one trigger is defined for the same event on the same
 178    relation, the triggers will be fired in alphabetical order by trigger
 179    name. In the case of BEFORE and INSTEAD OF triggers, the
 180    possibly-modified row returned by each trigger becomes the input to the
 181    next trigger. If any BEFORE or INSTEAD OF trigger returns NULL, the
 182    operation is abandoned for that row and subsequent triggers are not
 183    fired (for that row).
 184
 185    A trigger definition can also specify a Boolean WHEN condition, which
 186    will be tested to see whether the trigger should be fired. In row-level
 187    triggers the WHEN condition can examine the old and/or new values of
 188    columns of the row. (Statement-level triggers can also have WHEN
 189    conditions, although the feature is not so useful for them.) In a
 190    BEFORE trigger, the WHEN condition is evaluated just before the
 191    function is or would be executed, so using WHEN is not materially
 192    different from testing the same condition at the beginning of the
 193    trigger function. However, in an AFTER trigger, the WHEN condition is
 194    evaluated just after the row update occurs, and it determines whether
 195    an event is queued to fire the trigger at the end of statement. So when
 196    an AFTER trigger's WHEN condition does not return true, it is not
 197    necessary to queue an event nor to re-fetch the row at end of
 198    statement. This can result in significant speedups in statements that
 199    modify many rows, if the trigger only needs to be fired for a few of
 200    the rows. INSTEAD OF triggers do not support WHEN conditions.
 201
 202    Typically, row-level BEFORE triggers are used for checking or modifying
 203    the data that will be inserted or updated. For example, a BEFORE
 204    trigger might be used to insert the current time into a timestamp
 205    column, or to check that two elements of the row are consistent.
 206    Row-level AFTER triggers are most sensibly used to propagate the
 207    updates to other tables, or make consistency checks against other
 208    tables. The reason for this division of labor is that an AFTER trigger
 209    can be certain it is seeing the final value of the row, while a BEFORE
 210    trigger cannot; there might be other BEFORE triggers firing after it.
 211    If you have no specific reason to make a trigger BEFORE or AFTER, the
 212    BEFORE case is more efficient, since the information about the
 213    operation doesn't have to be saved until end of statement.
 214
 215    If a trigger function executes SQL commands then these commands might
 216    fire triggers again. This is known as cascading triggers. There is no
 217    direct limitation on the number of cascade levels. It is possible for
 218    cascades to cause a recursive invocation of the same trigger; for
 219    example, an INSERT trigger might execute a command that inserts an
 220    additional row into the same table, causing the INSERT trigger to be
 221    fired again. It is the trigger programmer's responsibility to avoid
 222    infinite recursion in such scenarios.
 223
 224    If a foreign key constraint specifies referential actions (that is,
 225    cascading updates or deletes), those actions are performed via ordinary
 226    SQL UPDATE or DELETE commands on the referencing table. In particular,
 227    any triggers that exist on the referencing table will be fired for
 228    those changes. If such a trigger modifies or blocks the effect of one
 229    of these commands, the end result could be to break referential
 230    integrity. It is the trigger programmer's responsibility to avoid that.
 231
 232    When a trigger is being defined, arguments can be specified for it. The
 233    purpose of including arguments in the trigger definition is to allow
 234    different triggers with similar requirements to call the same function.
 235    As an example, there could be a generalized trigger function that takes
 236    as its arguments two column names and puts the current user in one and
 237    the current time stamp in the other. Properly written, this trigger
 238    function would be independent of the specific table it is triggering
 239    on. So the same function could be used for INSERT events on any table
 240    with suitable columns, to automatically track creation of records in a
 241    transaction table for example. It could also be used to track
 242    last-update events if defined as an UPDATE trigger.
 243
 244    Each programming language that supports triggers has its own method for
 245    making the trigger input data available to the trigger function. This
 246    input data includes the type of trigger event (e.g., INSERT or UPDATE)
 247    as well as any arguments that were listed in CREATE TRIGGER. For a
 248    row-level trigger, the input data also includes the NEW row for INSERT
 249    and UPDATE triggers, and/or the OLD row for UPDATE and DELETE triggers.
 250
 251    By default, statement-level triggers do not have any way to examine the
 252    individual row(s) modified by the statement. But an AFTER STATEMENT
 253    trigger can request that transition tables be created to make the sets
 254    of affected rows available to the trigger. AFTER ROW triggers can also
 255    request transition tables, so that they can see the total changes in
 256    the table as well as the change in the individual row they are
 257    currently being fired for. The method for examining the transition
 258    tables again depends on the programming language that is being used,
 259    but the typical approach is to make the transition tables act like
 260    read-only temporary tables that can be accessed by SQL commands issued
 261    within the trigger function.