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

   1
   2 42.6. Trigger Functions in PL/Tcl #
   3
   4    Trigger functions can be written in PL/Tcl. PostgreSQL requires that a
   5    function that is to be called as a trigger must be declared as a
   6    function with no arguments and a return type of trigger.
   7
   8    The information from the trigger manager is passed to the function body
   9    in the following variables:
  10
  11    $TG_name
  12           The name of the trigger from the CREATE TRIGGER statement.
  13
  14    $TG_relid
  15           The object ID of the table that caused the trigger function to
  16           be invoked.
  17
  18    $TG_table_name
  19           The name of the table that caused the trigger function to be
  20           invoked.
  21
  22    $TG_table_schema
  23           The schema of the table that caused the trigger function to be
  24           invoked.
  25
  26    $TG_relatts
  27           A Tcl list of the table column names, prefixed with an empty
  28           list element. So looking up a column name in the list with Tcl's
  29           lsearch command returns the element's number starting with 1 for
  30           the first column, the same way the columns are customarily
  31           numbered in PostgreSQL. (Empty list elements also appear in the
  32           positions of columns that have been dropped, so that the
  33           attribute numbering is correct for columns to their right.)
  34
  35    $TG_when
  36           The string BEFORE, AFTER, or INSTEAD OF, depending on the type
  37           of trigger event.
  38
  39    $TG_level
  40           The string ROW or STATEMENT depending on the type of trigger
  41           event.
  42
  43    $TG_op
  44           The string INSERT, UPDATE, DELETE, or TRUNCATE depending on the
  45           type of trigger event.
  46
  47    $NEW
  48           An associative array containing the values of the new table row
  49           for INSERT or UPDATE actions, or empty for DELETE. The array is
  50           indexed by column name. Columns that are null will not appear in
  51           the array. This is not set for statement-level triggers.
  52
  53    $OLD
  54           An associative array containing the values of the old table row
  55           for UPDATE or DELETE actions, or empty for INSERT. The array is
  56           indexed by column name. Columns that are null will not appear in
  57           the array. This is not set for statement-level triggers.
  58
  59    $args
  60           A Tcl list of the arguments to the function as given in the
  61           CREATE TRIGGER statement. These arguments are also accessible as
  62           $1 ... $n in the function body.
  63
  64    The return value from a trigger function can be one of the strings OK
  65    or SKIP, or a list of column name/value pairs. If the return value is
  66    OK, the operation (INSERT/UPDATE/DELETE) that fired the trigger will
  67    proceed normally. SKIP tells the trigger manager to silently suppress
  68    the operation for this row. If a list is returned, it tells PL/Tcl to
  69    return a modified row to the trigger manager; the contents of the
  70    modified row are specified by the column names and values in the list.
  71    Any columns not mentioned in the list are set to null. Returning a
  72    modified row is only meaningful for row-level BEFORE INSERT or UPDATE
  73    triggers, for which the modified row will be inserted instead of the
  74    one given in $NEW; or for row-level INSTEAD OF INSERT or UPDATE
  75    triggers where the returned row is used as the source data for INSERT
  76    RETURNING or UPDATE RETURNING clauses. In row-level BEFORE DELETE or
  77    INSTEAD OF DELETE triggers, returning a modified row has the same
  78    effect as returning OK, that is the operation proceeds. The trigger
  79    return value is ignored for all other types of triggers.
  80
  81 Tip
  82
  83    The result list can be made from an array representation of the
  84    modified tuple with the array get Tcl command.
  85
  86    Here's a little example trigger function that forces an integer value
  87    in a table to keep track of the number of updates that are performed on
  88    the row. For new rows inserted, the value is initialized to 0 and then
  89    incremented on every update operation.
  90 CREATE FUNCTION trigfunc_modcount() RETURNS trigger AS $$
  91     switch $TG_op {
  92         INSERT {
  93             set NEW($1) 0
  94         }
  95         UPDATE {
  96             set NEW($1) $OLD($1)
  97             incr NEW($1)
  98         }
  99         default {
 100             return OK
 101         }
 102     }
 103     return [array get NEW]
 104 $$ LANGUAGE pltcl;
 105
 106 CREATE TABLE mytab (num integer, description text, modcnt integer);
 107
 108 CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
 109     FOR EACH ROW EXECUTE FUNCTION trigfunc_modcount('modcnt');
 110
 111    Notice that the trigger function itself does not know the column name;
 112    that's supplied from the trigger arguments. This lets the trigger
 113    function be reused with different tables.