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

   1
   2 37.3. Writing Trigger Functions in C #
   3
   4    This section describes the low-level details of the interface to a
   5    trigger function. This information is only needed when writing trigger
   6    functions in C. If you are using a higher-level language then these
   7    details are handled for you. In most cases you should consider using a
   8    procedural language before writing your triggers in C. The
   9    documentation of each procedural language explains how to write a
  10    trigger in that language.
  11
  12    Trigger functions must use the “version 1” function manager interface.
  13
  14    When a function is called by the trigger manager, it is not passed any
  15    normal arguments, but it is passed a “context” pointer pointing to a
  16    TriggerData structure. C functions can check whether they were called
  17    from the trigger manager or not by executing the macro:
  18 CALLED_AS_TRIGGER(fcinfo)
  19
  20    which expands to:
  21 ((fcinfo)->context != NULL && IsA((fcinfo)->context, TriggerData))
  22
  23    If this returns true, then it is safe to cast fcinfo->context to type
  24    TriggerData * and make use of the pointed-to TriggerData structure. The
  25    function must not alter the TriggerData structure or any of the data it
  26    points to.
  27
  28    struct TriggerData is defined in commands/trigger.h:
  29 typedef struct TriggerData
  30 {
  31     NodeTag          type;
  32     TriggerEvent     tg_event;
  33     Relation         tg_relation;
  34     HeapTuple        tg_trigtuple;
  35     HeapTuple        tg_newtuple;
  36     Trigger         *tg_trigger;
  37     TupleTableSlot  *tg_trigslot;
  38     TupleTableSlot  *tg_newslot;
  39     Tuplestorestate *tg_oldtable;
  40     Tuplestorestate *tg_newtable;
  41     const Bitmapset *tg_updatedcols;
  42 } TriggerData;
  43
  44    where the members are defined as follows:
  45
  46    type
  47           Always T_TriggerData.
  48
  49    tg_event
  50           Describes the event for which the function is called. You can
  51           use the following macros to examine tg_event:
  52
  53         TRIGGER_FIRED_BEFORE(tg_event)
  54                 Returns true if the trigger fired before the operation.
  55
  56         TRIGGER_FIRED_AFTER(tg_event)
  57                 Returns true if the trigger fired after the operation.
  58
  59         TRIGGER_FIRED_INSTEAD(tg_event)
  60                 Returns true if the trigger fired instead of the
  61                 operation.
  62
  63         TRIGGER_FIRED_FOR_ROW(tg_event)
  64                 Returns true if the trigger fired for a row-level event.
  65
  66         TRIGGER_FIRED_FOR_STATEMENT(tg_event)
  67                 Returns true if the trigger fired for a statement-level
  68                 event.
  69
  70         TRIGGER_FIRED_BY_INSERT(tg_event)
  71                 Returns true if the trigger was fired by an INSERT
  72                 command.
  73
  74         TRIGGER_FIRED_BY_UPDATE(tg_event)
  75                 Returns true if the trigger was fired by an UPDATE
  76                 command.
  77
  78         TRIGGER_FIRED_BY_DELETE(tg_event)
  79                 Returns true if the trigger was fired by a DELETE command.
  80
  81         TRIGGER_FIRED_BY_TRUNCATE(tg_event)
  82                 Returns true if the trigger was fired by a TRUNCATE
  83                 command.
  84
  85    tg_relation
  86           A pointer to a structure describing the relation that the
  87           trigger fired for. Look at utils/rel.h for details about this
  88           structure. The most interesting things are tg_relation->rd_att
  89           (descriptor of the relation tuples) and
  90           tg_relation->rd_rel->relname (relation name; the type is not
  91           char* but NameData; use SPI_getrelname(tg_relation) to get a
  92           char* if you need a copy of the name).
  93
  94    tg_trigtuple
  95           A pointer to the row for which the trigger was fired. This is
  96           the row being inserted, updated, or deleted. If this trigger was
  97           fired for an INSERT or DELETE then this is what you should
  98           return from the function if you don't want to replace the row
  99           with a different one (in the case of INSERT) or skip the
 100           operation. For triggers on foreign tables, values of system
 101           columns herein are unspecified.
 102
 103    tg_newtuple
 104           A pointer to the new version of the row, if the trigger was
 105           fired for an UPDATE, and NULL if it is for an INSERT or a
 106           DELETE. This is what you have to return from the function if the
 107           event is an UPDATE and you don't want to replace this row by a
 108           different one or skip the operation. For triggers on foreign
 109           tables, values of system columns herein are unspecified.
 110
 111    tg_trigger
 112           A pointer to a structure of type Trigger, defined in
 113           utils/reltrigger.h:
 114
 115 typedef struct Trigger
 116 {
 117     Oid         tgoid;
 118     char       *tgname;
 119     Oid         tgfoid;
 120     int16       tgtype;
 121     char        tgenabled;
 122     bool        tgisinternal;
 123     bool        tgisclone;
 124     Oid         tgconstrrelid;
 125     Oid         tgconstrindid;
 126     Oid         tgconstraint;
 127     bool        tgdeferrable;
 128     bool        tginitdeferred;
 129     int16       tgnargs;
 130     int16       tgnattr;
 131     int16      *tgattr;
 132     char      **tgargs;
 133     char       *tgqual;
 134     char       *tgoldtable;
 135     char       *tgnewtable;
 136 } Trigger;
 137
 138           where tgname is the trigger's name, tgnargs is the number of
 139           arguments in tgargs, and tgargs is an array of pointers to the
 140           arguments specified in the CREATE TRIGGER statement. The other
 141           members are for internal use only.
 142
 143    tg_trigslot
 144           The slot containing tg_trigtuple, or a NULL pointer if there is
 145           no such tuple.
 146
 147    tg_newslot
 148           The slot containing tg_newtuple, or a NULL pointer if there is
 149           no such tuple.
 150
 151    tg_oldtable
 152           A pointer to a structure of type Tuplestorestate containing zero
 153           or more rows in the format specified by tg_relation, or a NULL
 154           pointer if there is no OLD TABLE transition relation.
 155
 156    tg_newtable
 157           A pointer to a structure of type Tuplestorestate containing zero
 158           or more rows in the format specified by tg_relation, or a NULL
 159           pointer if there is no NEW TABLE transition relation.
 160
 161    tg_updatedcols
 162           For UPDATE triggers, a bitmap set indicating the columns that
 163           were updated by the triggering command. Generic trigger
 164           functions can use this to optimize actions by not having to deal
 165           with columns that were not changed.
 166
 167           As an example, to determine whether a column with attribute
 168           number attnum (1-based) is a member of this bitmap set, call
 169           bms_is_member(attnum - FirstLowInvalidHeapAttributeNumber,
 170           trigdata->tg_updatedcols)).
 171
 172           For triggers other than UPDATE triggers, this will be NULL.
 173
 174    To allow queries issued through SPI to reference transition tables, see
 175    SPI_register_trigger_data.
 176
 177    A trigger function must return either a HeapTuple pointer or a NULL
 178    pointer (not an SQL null value, that is, do not set isNull true). Be
 179    careful to return either tg_trigtuple or tg_newtuple, as appropriate,
 180    if you don't want to modify the row being operated on.