codekingpro/portable-devtools

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>40.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 40. Event Triggers" /><link rel="next" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">40.1. Overview of Event Trigger Behavior</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="event-triggers.html" title="Chapter 40. Event Triggers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><th width="60%" align="center">Chapter 40. Event Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix">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">40.1. Overview of Event Trigger Behavior <a href="#EVENT-TRIGGER-DEFINITION" class="id_link">#</a></h2></div></div></div><p>3     An event trigger fires whenever the event with which it is associated4     occurs in the database in which it is defined. Currently, the only5     supported events are6     <code class="literal">ddl_command_start</code>,7     <code class="literal">ddl_command_end</code>,8     <code class="literal">table_rewrite</code>9     and <code class="literal">sql_drop</code>.10     Support for additional events may be added in future releases.11   </p><p>12     The <code class="literal">ddl_command_start</code> event occurs just before the13     execution of a <code class="literal">CREATE</code>, <code class="literal">ALTER</code>, <code class="literal">DROP</code>,14     <code class="literal">SECURITY LABEL</code>,15     <code class="literal">COMMENT</code>, <code class="literal">GRANT</code> or <code class="literal">REVOKE</code>16     command.  No check whether the affected object exists or doesn't exist is17     performed before the event trigger fires.18     As an exception, however, this event does not occur for19     DDL commands targeting shared objects — databases, roles, and tablespaces20     — or for commands targeting event triggers themselves.  The event trigger21     mechanism does not support these object types.22     <code class="literal">ddl_command_start</code> also occurs just before the execution of a23     <code class="literal">SELECT INTO</code> command, since this is equivalent to24     <code class="literal">CREATE TABLE AS</code>.25   </p><p>26    The <code class="literal">ddl_command_end</code> event occurs just after the execution of27    this same set of commands.  To obtain more details on the <acronym class="acronym">DDL</acronym>28    operations that took place, use the set-returning function29    <code class="literal">pg_event_trigger_ddl_commands()</code> from the30    <code class="literal">ddl_command_end</code> event trigger code (see31    <a class="xref" href="functions-event-triggers.html" title="9.29. Event Trigger Functions">Section 9.29</a>).  Note that the trigger fires32    after the actions have taken place (but before the transaction commits),33    and thus the system catalogs can be read as already changed.34   </p><p>35    The <code class="literal">sql_drop</code> event occurs just before the36    <code class="literal">ddl_command_end</code> event trigger for any operation that drops37    database objects.  To list the objects that have been dropped, use the38    set-returning function <code class="literal">pg_event_trigger_dropped_objects()</code> from the39    <code class="literal">sql_drop</code> event trigger code (see40    <a class="xref" href="functions-event-triggers.html" title="9.29. Event Trigger Functions">Section 9.29</a>). Note that41    the trigger is executed after the objects have been deleted from the42    system catalogs, so it's not possible to look them up anymore.43   </p><p>44    The <code class="literal">table_rewrite</code> event occurs just before a table is45    rewritten by some actions of the commands <code class="literal">ALTER TABLE</code> and46    <code class="literal">ALTER TYPE</code>.  While other47    control statements are available to rewrite a table,48    like <code class="literal">CLUSTER</code> and <code class="literal">VACUUM</code>,49    the <code class="literal">table_rewrite</code> event is not triggered by them.50   </p><p>51     Event triggers (like other functions) cannot be executed in an aborted52     transaction.  Thus, if a DDL command fails with an error, any associated53     <code class="literal">ddl_command_end</code> triggers will not be executed.  Conversely,54     if a <code class="literal">ddl_command_start</code> trigger fails with an error, no55     further event triggers will fire, and no attempt will be made to execute56     the command itself.  Similarly, if a <code class="literal">ddl_command_end</code> trigger57     fails with an error, the effects of the DDL statement will be rolled58     back, just as they would be in any other case where the containing59     transaction aborts.60   </p><p>61     For a complete list of commands supported by the event trigger mechanism,62     see <a class="xref" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix">Section 40.2</a>.63   </p><p>64     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>.65     In order to create an event trigger, you must first create a function with66     the special return type <code class="literal">event_trigger</code>.  This function67     need not (and may not) return a value; the return type serves merely as68     a signal that the function is to be invoked as an event trigger.69   </p><p>70     If more than one event trigger is defined for a particular event, they will71     fire in alphabetical order by trigger name.72   </p><p>73     A trigger definition can also specify a <code class="literal">WHEN</code>74     condition so that, for example, a <code class="literal">ddl_command_start</code>75     trigger can be fired only for particular commands which the user wishes76     to intercept. A common use of such triggers is to restrict the range of77     DDL operations which users may perform.78   </p></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 40. Event Triggers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 40. Event Triggers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 40.2. Event Trigger Firing Matrix</td></tr></table></div></body></html>