<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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>39.3. Writing Trigger Functions in C</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="trigger-datachanges.html" title="39.2. Visibility of Data Changes" /><link rel="next" href="trigger-example.html" title="39.4. A Complete Trigger Example" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">39.3. Writing Trigger Functions in C</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="trigger-datachanges.html" title="39.2. Visibility of Data Changes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="triggers.html" title="Chapter 39. Triggers">Up</a></td><th width="60%" align="center">Chapter 39. Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 11.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="trigger-example.html" title="39.4. A Complete Trigger Example">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="TRIGGER-INTERFACE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">39.3. Writing Trigger Functions in C</h2></div></div></div><a id="id-1.8.4.7.2" class="indexterm"></a><a id="id-1.8.4.7.3" class="indexterm"></a><p>
This section describes the low-level details of the interface to a
trigger function. This information is only needed when writing
trigger functions in C. If you are using a higher-level language then
these details are handled for you. In most cases you should consider
using a procedural language before writing your triggers in C. The
documentation of each procedural language explains how to write a
trigger in that language.
</p><p>
Trigger functions must use the <span class="quote">“<span class="quote">version 1</span>”</span> function manager
interface.
</p><p>
When a function is called by the trigger manager, it is not passed
any normal arguments, but it is passed a <span class="quote">“<span class="quote">context</span>”</span>
pointer pointing to a <code class="structname">TriggerData</code> structure. C
functions can check whether they were called from the trigger
manager or not by executing the macro:
</p><pre class="programlisting">
CALLED_AS_TRIGGER(fcinfo)
</pre><p>
which expands to:
</p><pre class="programlisting">
((fcinfo)->context != NULL && IsA((fcinfo)->context, TriggerData))
</pre><p>
If this returns true, then it is safe to cast
<code class="literal">fcinfo->context</code> to type <code class="literal">TriggerData
*</code> and make use of the pointed-to
<code class="structname">TriggerData</code> structure. The function must
<span class="emphasis"><em>not</em></span> alter the <code class="structname">TriggerData</code>
structure or any of the data it points to.
</p><p>
<code class="structname">struct TriggerData</code> is defined in
<code class="filename">commands/trigger.h</code>:
</p><pre class="programlisting">
typedef struct TriggerData
{
NodeTag type;
TriggerEvent tg_event;
Relation tg_relation;
HeapTuple tg_trigtuple;
HeapTuple tg_newtuple;
Trigger *tg_trigger;
Buffer tg_trigtuplebuf;
Buffer tg_newtuplebuf;
Tuplestorestate *tg_oldtable;
Tuplestorestate *tg_newtable;
} TriggerData;
</pre><p>
where the members are defined as follows:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="structfield">type</code></span></dt><dd><p>
Always <code class="literal">T_TriggerData</code>.
</p></dd><dt><span class="term"><code class="structfield">tg_event</code></span></dt><dd><p>
Describes the event for which the function is called. You can use the
following macros to examine <code class="literal">tg_event</code>:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TRIGGER_FIRED_BEFORE(tg_event)</code></span></dt><dd><p>
Returns true if the trigger fired before the operation.
</p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_AFTER(tg_event)</code></span></dt><dd><p>
Returns true if the trigger fired after the operation.
</p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_INSTEAD(tg_event)</code></span></dt><dd><p>
Returns true if the trigger fired instead of the operation.
</p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_FOR_ROW(tg_event)</code></span></dt><dd><p>
Returns true if the trigger fired for a row-level event.
</p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_FOR_STATEMENT(tg_event)</code></span></dt><dd><p>
Returns true if the trigger fired for a statement-level event.
</p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_BY_INSERT(tg_event)</code></span></dt><dd><p>
Returns true if the trigger was fired by an <code class="command">INSERT</code> command.
</p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_BY_UPDATE(tg_event)</code></span></dt><dd><p>
Returns true if the trigger was fired by an <code class="command">UPDATE</code> command.
</p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_BY_DELETE(tg_event)</code></span></dt><dd><p>
Returns true if the trigger was fired by a <code class="command">DELETE</code> command.
</p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_BY_TRUNCATE(tg_event)</code></span></dt><dd><p>
Returns true if the trigger was fired by a <code class="command">TRUNCATE</code> command.
</p></dd></dl></div><p>
</p></dd><dt><span class="term"><code class="structfield">tg_relation</code></span></dt><dd><p>
A pointer to a structure describing the relation that the trigger fired for.
Look at <code class="filename">utils/rel.h</code> for details about
this structure. The most interesting things are
<code class="literal">tg_relation->rd_att</code> (descriptor of the relation
tuples) and <code class="literal">tg_relation->rd_rel->relname</code>
(relation name; the type is not <code class="type">char*</code> but
<code class="type">NameData</code>; use
<code class="literal">SPI_getrelname(tg_relation)</code> to get a <code class="type">char*</code> if you
need a copy of the name).
</p></dd><dt><span class="term"><code class="structfield">tg_trigtuple</code></span></dt><dd><p>
A pointer to the row for which the trigger was fired. This is
the row being inserted, updated, or deleted. If this trigger
was fired for an <code class="command">INSERT</code> or
<code class="command">DELETE</code> then this is what you should return
from the function if you don't want to replace the row with
a different one (in the case of <code class="command">INSERT</code>) or
skip the operation. For triggers on foreign tables, values of system
columns herein are unspecified.
</p></dd><dt><span class="term"><code class="structfield">tg_newtuple</code></span></dt><dd><p>
A pointer to the new version of the row, if the trigger was
fired for an <code class="command">UPDATE</code>, and <code class="symbol">NULL</code> if
it is for an <code class="command">INSERT</code> or a
<code class="command">DELETE</code>. This is what you have to return
from the function if the event is an <code class="command">UPDATE</code>
and you don't want to replace this row by a different one or
skip the operation. For triggers on foreign tables, values of system
columns herein are unspecified.
</p></dd><dt><span class="term"><code class="structfield">tg_trigger</code></span></dt><dd><p>
A pointer to a structure of type <code class="structname">Trigger</code>,
defined in <code class="filename">utils/reltrigger.h</code>:
</p><pre class="programlisting">
typedef struct Trigger
{
Oid tgoid;
char *tgname;
Oid tgfoid;
int16 tgtype;
char tgenabled;
bool tgisinternal;
Oid tgconstrrelid;
Oid tgconstrindid;
Oid tgconstraint;
bool tgdeferrable;
bool tginitdeferred;
int16 tgnargs;
int16 tgnattr;
int16 *tgattr;
char **tgargs;
char *tgqual;
char *tgoldtable;
char *tgnewtable;
} Trigger;
</pre><p>
where <code class="structfield">tgname</code> is the trigger's name,
<code class="structfield">tgnargs</code> is the number of arguments in
<code class="structfield">tgargs</code>, and <code class="structfield">tgargs</code> is an array of
pointers to the arguments specified in the <code class="command">CREATE
TRIGGER</code> statement. The other members are for internal use
only.
</p></dd><dt><span class="term"><code class="structfield">tg_trigtuplebuf</code></span></dt><dd><p>
The buffer containing <code class="structfield">tg_trigtuple</code>, or <code class="symbol">InvalidBuffer</code> if there
is no such tuple or it is not stored in a disk buffer.
</p></dd><dt><span class="term"><code class="structfield">tg_newtuplebuf</code></span></dt><dd><p>
The buffer containing <code class="structfield">tg_newtuple</code>, or <code class="symbol">InvalidBuffer</code> if there
is no such tuple or it is not stored in a disk buffer.
</p></dd><dt><span class="term"><code class="structfield">tg_oldtable</code></span></dt><dd><p>
A pointer to a structure of type <code class="structname">Tuplestorestate</code>
containing zero or more rows in the format specified by
<code class="structfield">tg_relation</code>, or a <code class="symbol">NULL</code> pointer
if there is no <code class="literal">OLD TABLE</code> transition relation.
</p></dd><dt><span class="term"><code class="structfield">tg_newtable</code></span></dt><dd><p>
A pointer to a structure of type <code class="structname">Tuplestorestate</code>
containing zero or more rows in the format specified by
<code class="structfield">tg_relation</code>, or a <code class="symbol">NULL</code> pointer
if there is no <code class="literal">NEW TABLE</code> transition relation.
</p></dd></dl></div><p>
</p><p>
To allow queries issued through SPI to reference transition tables, see
<a class="xref" href="spi-spi-register-trigger-data.html" title="SPI_register_trigger_data"><span class="refentrytitle">SPI_register_trigger_data</span></a>.
</p><p>
A trigger function must return either a
<code class="structname">HeapTuple</code> pointer or a <code class="symbol">NULL</code> pointer
(<span class="emphasis"><em>not</em></span> an SQL null value, that is, do not set <em class="parameter"><code>isNull</code></em> true).
Be careful to return either
<code class="structfield">tg_trigtuple</code> or <code class="structfield">tg_newtuple</code>,
as appropriate, if you don't want to modify the row being operated on.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="trigger-datachanges.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="triggers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="trigger-example.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">39.2. Visibility of Data Changes </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 39.4. A Complete Trigger Example</td></tr></table></div></body></html>
