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

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>42.6. Trigger Functions in PL/Tcl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-dbaccess.html" title="42.5. Database Access from PL/Tcl" /><link rel="next" href="pltcl-event-trigger.html" title="42.7. Event Trigger Functions in PL/Tcl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">42.6. Trigger Functions in PL/Tcl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-dbaccess.html" title="42.5. Database Access from PL/Tcl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 42. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 42. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-event-trigger.html" title="42.7. Event Trigger Functions in PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-TRIGGER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">42.6. Trigger Functions in PL/Tcl <a href="#PLTCL-TRIGGER" class="id_link">#</a></h2></div></div></div><a id="id-1.8.9.10.2" class="indexterm"></a><p>
   3      Trigger functions can be written in PL/Tcl.
   4      <span class="productname">PostgreSQL</span> requires that a function that is to be called
   5      as a trigger must be declared as a function with no arguments
   6      and a return type of <code class="literal">trigger</code>.
   7     </p><p>
   8      The information from the trigger manager is passed to the function body
   9      in the following variables:
  10
  11      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">$TG_name</code></span></dt><dd><p>
  12          The name of the trigger from the <code class="command">CREATE TRIGGER</code> statement.
  13         </p></dd><dt><span class="term"><code class="varname">$TG_relid</code></span></dt><dd><p>
  14          The object ID of the table that caused the trigger function
  15          to be invoked.
  16         </p></dd><dt><span class="term"><code class="varname">$TG_table_name</code></span></dt><dd><p>
  17          The name of the table that caused the trigger function
  18          to be invoked.
  19         </p></dd><dt><span class="term"><code class="varname">$TG_table_schema</code></span></dt><dd><p>
  20          The schema of the table that caused the trigger function
  21          to be invoked.
  22         </p></dd><dt><span class="term"><code class="varname">$TG_relatts</code></span></dt><dd><p>
  23          A Tcl list of the table column names, prefixed with an empty list
  24          element. So looking up a column name in the list with <span class="application">Tcl</span>'s
  25          <code class="function">lsearch</code> command returns the element's number starting
  26          with 1 for the first column, the same way the columns are customarily
  27          numbered in <span class="productname">PostgreSQL</span>.  (Empty list
  28          elements also appear in the positions of columns that have been
  29          dropped, so that the attribute numbering is correct for columns
  30          to their right.)
  31         </p></dd><dt><span class="term"><code class="varname">$TG_when</code></span></dt><dd><p>
  32          The string <code class="literal">BEFORE</code>, <code class="literal">AFTER</code>, or
  33          <code class="literal">INSTEAD OF</code>, depending on the type of trigger event.
  34         </p></dd><dt><span class="term"><code class="varname">$TG_level</code></span></dt><dd><p>
  35          The string <code class="literal">ROW</code> or <code class="literal">STATEMENT</code> depending on the
  36          type of trigger event.
  37         </p></dd><dt><span class="term"><code class="varname">$TG_op</code></span></dt><dd><p>
  38          The string <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
  39          <code class="literal">DELETE</code>, or <code class="literal">TRUNCATE</code> depending on the type of
  40          trigger event.
  41         </p></dd><dt><span class="term"><code class="varname">$NEW</code></span></dt><dd><p>
  42          An associative array containing the values of the new table
  43          row for <code class="command">INSERT</code> or <code class="command">UPDATE</code> actions, or
  44          empty for <code class="command">DELETE</code>.  The array is indexed by column
  45          name.  Columns that are null will not appear in the array.
  46          This is not set for statement-level triggers.
  47         </p></dd><dt><span class="term"><code class="varname">$OLD</code></span></dt><dd><p>
  48          An associative array containing the values of the old table
  49          row for <code class="command">UPDATE</code> or <code class="command">DELETE</code> actions, or
  50          empty for <code class="command">INSERT</code>.  The array is indexed by column
  51          name.  Columns that are null will not appear in the array.
  52          This is not set for statement-level triggers.
  53         </p></dd><dt><span class="term"><code class="varname">$args</code></span></dt><dd><p>
  54          A Tcl list of the arguments to the function as given in the
  55          <code class="command">CREATE TRIGGER</code> statement. These arguments are also accessible as
  56          <code class="literal">$1</code> ... <code class="literal">$<em class="replaceable"><code>n</code></em></code> in the function body.
  57         </p></dd></dl></div><p>
  58     </p><p>
  59      The return value from a trigger function can be one of the strings
  60      <code class="literal">OK</code> or <code class="literal">SKIP</code>, or a list of column name/value pairs.
  61      If the return value is <code class="literal">OK</code>,
  62      the operation (<code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code>)
  63      that fired the trigger will proceed
  64      normally. <code class="literal">SKIP</code> tells the trigger manager to silently suppress
  65      the operation for this row. If a list is returned, it tells PL/Tcl to
  66      return a modified row to the trigger manager; the contents of the
  67      modified row are specified by the column names and values in the list.
  68      Any columns not mentioned in the list are set to null.
  69      Returning a modified row is only meaningful
  70      for row-level <code class="literal">BEFORE</code> <code class="command">INSERT</code> or <code class="command">UPDATE</code>
  71      triggers, for which the modified row will be inserted instead of the one
  72      given in <code class="varname">$NEW</code>; or for row-level <code class="literal">INSTEAD OF</code>
  73      <code class="command">INSERT</code> or <code class="command">UPDATE</code> triggers where the returned row
  74      is used as the source data for <code class="command">INSERT RETURNING</code> or
  75      <code class="command">UPDATE RETURNING</code> clauses.
  76      In row-level <code class="literal">BEFORE</code> <code class="command">DELETE</code> or <code class="literal">INSTEAD
  77      OF</code> <code class="command">DELETE</code> triggers, returning a modified row has the same
  78      effect as returning <code class="literal">OK</code>, that is the operation proceeds.
  79      The trigger return value is ignored for all other types of triggers.
  80     </p><div class="tip"><h3 class="title">Tip</h3><p>
  81       The result list can be made from an array representation of the
  82       modified tuple with the <code class="literal">array get</code> Tcl command.
  83      </p></div><p>
  84      Here's a little example trigger function that forces an integer value
  85      in a table to keep track of the number of updates that are performed on the
  86      row. For new rows inserted, the value is initialized to 0 and then
  87      incremented on every update operation.
  88
  89 </p><pre class="programlisting">
  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 </pre><p>
 111
 112      Notice that the trigger function itself does not know the column
 113      name; that's supplied from the trigger arguments.  This lets the
 114      trigger function be reused with different tables.
 115     </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-dbaccess.html" title="42.5. Database Access from PL/Tcl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 42. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-event-trigger.html" title="42.7. Event Trigger Functions in PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">42.5. Database Access from PL/Tcl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 42.7. Event Trigger Functions in PL/Tcl</td></tr></table></div></body></html>