begriffs open source - ai-pg/blob - full-docs/src/sgml/html/event-trigger-definition.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>38.1. Overview of Event Trigger Behavior</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="event-triggers.html" title="Chapter 38. Event Triggers" /><link rel="next" href="event-trigger-interface.html" title="38.2. Writing Event Trigger Functions in C" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.1. Overview of Event Trigger Behavior</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="event-triggers.html" title="Chapter 38. Event Triggers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="event-triggers.html" title="Chapter 38. Event Triggers">Up</a></td><th width="60%" align="center">Chapter 38. Event Triggers</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="event-trigger-interface.html" title="38.2. Writing Event Trigger Functions in C">Next</a></td></tr></table><hr /></div><div class="sect1" id="EVENT-TRIGGER-DEFINITION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.1. Overview of Event Trigger Behavior <a href="#EVENT-TRIGGER-DEFINITION" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="event-trigger-definition.html#EVENT-TRIGGER-LOGIN">38.1.1. login</a></span></dt><dt><span class="sect2"><a href="event-trigger-definition.html#EVENT-TRIGGER-DDL_COMMAND_START">38.1.2. ddl_command_start</a></span></dt><dt><span class="sect2"><a href="event-trigger-definition.html#EVENT-TRIGGER-DDL_COMMAND_END">38.1.3. ddl_command_end</a></span></dt><dt><span class="sect2"><a href="event-trigger-definition.html#EVENT-TRIGGER-SQL_DROP">38.1.4. sql_drop</a></span></dt><dt><span class="sect2"><a href="event-trigger-definition.html#EVENT-TRIGGER-TABLE_REWRITE">38.1.5. table_rewrite</a></span></dt><dt><span class="sect2"><a href="event-trigger-definition.html#EVENT-TRIGGER-ABORTED-TRANSACTIONS">38.1.6. Event Triggers in Aborted Transactions</a></span></dt><dt><span class="sect2"><a href="event-trigger-definition.html#EVENT-TRIGGER-CREATING">38.1.7. Creating Event Triggers</a></span></dt></dl></div><p>
   3      An event trigger fires whenever the event with which it is associated
   4      occurs in the database in which it is defined. Currently, the
   5      supported events are
   6      <code class="literal">login</code>,
   7      <code class="literal">ddl_command_start</code>,
   8      <code class="literal">ddl_command_end</code>,
   9      <code class="literal">table_rewrite</code>
  10      and <code class="literal">sql_drop</code>.
  11      Support for additional events may be added in future releases.
  12    </p><div class="sect2" id="EVENT-TRIGGER-LOGIN"><div class="titlepage"><div><div><h3 class="title">38.1.1. login <a href="#EVENT-TRIGGER-LOGIN" class="id_link">#</a></h3></div></div></div><p>
  13      The <code class="literal">login</code> event occurs when an authenticated user logs
  14      into the system. Any bug in a trigger procedure for this event may
  15      prevent successful login to the system. Such bugs may be worked around by
  16      setting <a class="xref" href="runtime-config-client.html#GUC-EVENT-TRIGGERS">event_triggers</a> to <code class="literal">false</code>
  17      either in a connection string or configuration file. Alternatively, you can
  18      restart the system in single-user mode (as event triggers are
  19      disabled in this mode). See the <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a> reference
  20      page for details about using single-user mode.
  21      The <code class="literal">login</code> event will also fire on standby servers.
  22      To prevent servers from becoming inaccessible, such triggers must avoid
  23      writing anything to the database when running on a standby.
  24      Also, it's recommended to avoid long-running queries in
  25      <code class="literal">login</code> event triggers.  Note that, for instance,
  26      canceling a connection in <span class="application">psql</span> will not cancel
  27      the in-progress <code class="literal">login</code> trigger.
  28    </p><p>
  29      For an example on how to use the <code class="literal">login</code> event trigger,
  30      see <a class="xref" href="event-trigger-database-login-example.html" title="38.5. A Database Login Event Trigger Example">Section 38.5</a>.
  31    </p></div><div class="sect2" id="EVENT-TRIGGER-DDL_COMMAND_START"><div class="titlepage"><div><div><h3 class="title">38.1.2. ddl_command_start <a href="#EVENT-TRIGGER-DDL_COMMAND_START" class="id_link">#</a></h3></div></div></div><p>
  32      The <code class="literal">ddl_command_start</code> event occurs just before the
  33      execution of a DDL command.  DDL commands in this context are:
  34      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">CREATE</code></p></li><li class="listitem"><p><code class="literal">ALTER</code></p></li><li class="listitem"><p><code class="literal">DROP</code></p></li><li class="listitem"><p><code class="literal">COMMENT</code></p></li><li class="listitem"><p><code class="literal">GRANT</code></p></li><li class="listitem"><p><code class="literal">IMPORT FOREIGN SCHEMA</code></p></li><li class="listitem"><p><code class="literal">REINDEX</code></p></li><li class="listitem"><p><code class="literal">REFRESH MATERIALIZED VIEW</code></p></li><li class="listitem"><p><code class="literal">REVOKE</code></p></li><li class="listitem"><p><code class="literal">SECURITY LABEL</code></p></li></ul></div><p>
  35      <code class="literal">ddl_command_start</code> also occurs just before the
  36      execution of a <code class="literal">SELECT INTO</code> command, since this is
  37      equivalent to <code class="literal">CREATE TABLE AS</code>.
  38    </p><p>
  39      As an exception, this event does not occur for DDL commands targeting
  40      shared objects:
  41      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>databases</p></li><li class="listitem"><p>roles (role definitions and role memberships)</p></li><li class="listitem"><p>tablespaces</p></li><li class="listitem"><p>parameter privileges</p></li><li class="listitem"><p><code class="command">ALTER SYSTEM</code></p></li></ul></div><p>
  42      This event also does not occur for commands targeting event triggers
  43      themselves.
  44    </p><p>
  45      No check whether the affected object exists or doesn't exist is performed
  46      before the event trigger fires.
  47    </p></div><div class="sect2" id="EVENT-TRIGGER-DDL_COMMAND_END"><div class="titlepage"><div><div><h3 class="title">38.1.3. ddl_command_end <a href="#EVENT-TRIGGER-DDL_COMMAND_END" class="id_link">#</a></h3></div></div></div><p>
  48     The <code class="literal">ddl_command_end</code> event occurs just after the execution of
  49     the same set of commands as <code class="literal">ddl_command_start</code>.  To
  50     obtain more details on the <acronym class="acronym">DDL</acronym>
  51     operations that took place, use the set-returning function
  52     <code class="literal">pg_event_trigger_ddl_commands()</code> from the
  53     <code class="literal">ddl_command_end</code> event trigger code (see
  54     <a class="xref" href="functions-event-triggers.html" title="9.30. Event Trigger Functions">Section 9.30</a>).  Note that the trigger fires
  55     after the actions have taken place (but before the transaction commits),
  56     and thus the system catalogs can be read as already changed.
  57    </p></div><div class="sect2" id="EVENT-TRIGGER-SQL_DROP"><div class="titlepage"><div><div><h3 class="title">38.1.4. sql_drop <a href="#EVENT-TRIGGER-SQL_DROP" class="id_link">#</a></h3></div></div></div><p>
  58     The <code class="literal">sql_drop</code> event occurs just before the
  59     <code class="literal">ddl_command_end</code> event trigger for any operation that drops
  60     database objects.  Note that besides the obvious <code class="literal">DROP</code>
  61     commands, some <code class="literal">ALTER</code> commands can also trigger an
  62     <code class="literal">sql_drop</code> event.
  63    </p><p>
  64     To list the objects that have been dropped, use the
  65     set-returning function <code class="literal">pg_event_trigger_dropped_objects()</code> from the
  66     <code class="literal">sql_drop</code> event trigger code (see
  67     <a class="xref" href="functions-event-triggers.html" title="9.30. Event Trigger Functions">Section 9.30</a>). Note that
  68     the trigger is executed after the objects have been deleted from the
  69     system catalogs, so it's not possible to look them up anymore.
  70    </p></div><div class="sect2" id="EVENT-TRIGGER-TABLE_REWRITE"><div class="titlepage"><div><div><h3 class="title">38.1.5. table_rewrite <a href="#EVENT-TRIGGER-TABLE_REWRITE" class="id_link">#</a></h3></div></div></div><p>
  71     The <code class="literal">table_rewrite</code> event occurs just before a table is
  72     rewritten by some actions of the commands <code class="literal">ALTER TABLE</code> and
  73     <code class="literal">ALTER TYPE</code>.  While other
  74     control statements are available to rewrite a table,
  75     like <code class="literal">CLUSTER</code> and <code class="literal">VACUUM</code>,
  76     the <code class="literal">table_rewrite</code> event is not triggered by them.
  77     To find the OID of the table that was rewritten, use the function
  78     <code class="literal">pg_event_trigger_table_rewrite_oid()</code>, to discover the
  79     reason(s) for the rewrite, use the function
  80     <code class="literal">pg_event_trigger_table_rewrite_reason()</code> (see <a class="xref" href="functions-event-triggers.html" title="9.30. Event Trigger Functions">Section 9.30</a>).
  81    </p></div><div class="sect2" id="EVENT-TRIGGER-ABORTED-TRANSACTIONS"><div class="titlepage"><div><div><h3 class="title">38.1.6. Event Triggers in Aborted Transactions <a href="#EVENT-TRIGGER-ABORTED-TRANSACTIONS" class="id_link">#</a></h3></div></div></div><p>
  82      Event triggers (like other functions) cannot be executed in an aborted
  83      transaction.  Thus, if a DDL command fails with an error, any associated
  84      <code class="literal">ddl_command_end</code> triggers will not be executed.  Conversely,
  85      if a <code class="literal">ddl_command_start</code> trigger fails with an error, no
  86      further event triggers will fire, and no attempt will be made to execute
  87      the command itself.  Similarly, if a <code class="literal">ddl_command_end</code> trigger
  88      fails with an error, the effects of the DDL statement will be rolled
  89      back, just as they would be in any other case where the containing
  90      transaction aborts.
  91    </p></div><div class="sect2" id="EVENT-TRIGGER-CREATING"><div class="titlepage"><div><div><h3 class="title">38.1.7. Creating Event Triggers <a href="#EVENT-TRIGGER-CREATING" class="id_link">#</a></h3></div></div></div><p>
  92      Event triggers are created using the command <a class="xref" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER"><span class="refentrytitle">CREATE EVENT TRIGGER</span></a>.
  93      In order to create an event trigger, you must first create a function with
  94      the special return type <code class="literal">event_trigger</code>.  This function
  95      need not (and may not) return a value; the return type serves merely as
  96      a signal that the function is to be invoked as an event trigger.
  97    </p><p>
  98      If more than one event trigger is defined for a particular event, they will
  99      fire in alphabetical order by trigger name.
 100    </p><p>
 101      A trigger definition can also specify a <code class="literal">WHEN</code>
 102      condition so that, for example, a <code class="literal">ddl_command_start</code>
 103      trigger can be fired only for particular commands which the user wishes
 104      to intercept. A common use of such triggers is to restrict the range of
 105      DDL operations which users may perform.
 106    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="event-triggers.html" title="Chapter 38. Event Triggers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="event-triggers.html" title="Chapter 38. Event Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="event-trigger-interface.html" title="38.2. Writing Event Trigger Functions in C">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 38. Event Triggers </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"> 38.2. Writing Event Trigger Functions in C</td></tr></table></div></body></html>