begriffs open source - ai-pg/blob - full-docs/html/functions-event-triggers.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>9.30. Event Trigger Functions</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="functions-trigger.html" title="9.29. Trigger Functions" /><link rel="next" href="functions-statistics.html" title="9.31. Statistics Information Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.30. Event Trigger Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-trigger.html" title="9.29. Trigger Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</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="functions-statistics.html" title="9.31. Statistics Information Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-EVENT-TRIGGERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.30. Event Trigger Functions <a href="#FUNCTIONS-EVENT-TRIGGERS" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-event-triggers.html#PG-EVENT-TRIGGER-DDL-COMMAND-END-FUNCTIONS">9.30.1. Capturing Changes at Command End</a></span></dt><dt><span class="sect2"><a href="functions-event-triggers.html#PG-EVENT-TRIGGER-SQL-DROP-FUNCTIONS">9.30.2. Processing Objects Dropped by a DDL Command</a></span></dt><dt><span class="sect2"><a href="functions-event-triggers.html#PG-EVENT-TRIGGER-TABLE-REWRITE-FUNCTIONS">9.30.3. Handling a Table Rewrite Event</a></span></dt></dl></div><p>
   3     <span class="productname">PostgreSQL</span> provides these helper functions
   4     to retrieve information from event triggers.
   5    </p><p>
   6     For more information about event triggers,
   7     see <a class="xref" href="event-triggers.html" title="Chapter 38. Event Triggers">Chapter 38</a>.
   8    </p><div class="sect2" id="PG-EVENT-TRIGGER-DDL-COMMAND-END-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">9.30.1. Capturing Changes at Command End <a href="#PG-EVENT-TRIGGER-DDL-COMMAND-END-FUNCTIONS" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.36.4.2" class="indexterm"></a><pre class="synopsis">
   9 <code class="function">pg_event_trigger_ddl_commands</code> () → <code class="returnvalue">setof record</code>
  10 </pre><p>
  11     <code class="function">pg_event_trigger_ddl_commands</code> returns a list of
  12     <acronym class="acronym">DDL</acronym> commands executed by each user action,
  13     when invoked in a function attached to a
  14     <code class="literal">ddl_command_end</code> event trigger.  If called in any other
  15     context, an error is raised.
  16     <code class="function">pg_event_trigger_ddl_commands</code> returns one row for each
  17     base command executed; some commands that are a single SQL sentence
  18     may return more than one row.  This function returns the following
  19     columns:
  20
  21     </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">classid</code></td><td><code class="type">oid</code></td><td>OID of catalog the object belongs in</td></tr><tr><td><code class="literal">objid</code></td><td><code class="type">oid</code></td><td>OID of the object itself</td></tr><tr><td><code class="literal">objsubid</code></td><td><code class="type">integer</code></td><td>Sub-object ID (e.g., attribute number for a column)</td></tr><tr><td><code class="literal">command_tag</code></td><td><code class="type">text</code></td><td>Command tag</td></tr><tr><td><code class="literal">object_type</code></td><td><code class="type">text</code></td><td>Type of the object</td></tr><tr><td><code class="literal">schema_name</code></td><td><code class="type">text</code></td><td>
  22          Name of the schema the object belongs in, if any; otherwise <code class="literal">NULL</code>.
  23          No quoting is applied.
  24         </td></tr><tr><td><code class="literal">object_identity</code></td><td><code class="type">text</code></td><td>
  25          Text rendering of the object identity, schema-qualified. Each
  26          identifier included in the identity is quoted if necessary.
  27         </td></tr><tr><td><code class="literal">in_extension</code></td><td><code class="type">boolean</code></td><td>True if the command is part of an extension script</td></tr><tr><td><code class="literal">command</code></td><td><code class="type">pg_ddl_command</code></td><td>
  28          A complete representation of the command, in internal format.
  29          This cannot be output directly, but it can be passed to other
  30          functions to obtain different pieces of information about the
  31          command.
  32         </td></tr></tbody></table></div><p>
  33    </p></div><div class="sect2" id="PG-EVENT-TRIGGER-SQL-DROP-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">9.30.2. Processing Objects Dropped by a DDL Command <a href="#PG-EVENT-TRIGGER-SQL-DROP-FUNCTIONS" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.36.5.2" class="indexterm"></a><pre class="synopsis">
  34 <code class="function">pg_event_trigger_dropped_objects</code> () → <code class="returnvalue">setof record</code>
  35 </pre><p>
  36     <code class="function">pg_event_trigger_dropped_objects</code> returns a list of all objects
  37     dropped by the command in whose <code class="literal">sql_drop</code> event it is called.
  38     If called in any other context, an error is raised.
  39     This function returns the following columns:
  40
  41     </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">classid</code></td><td><code class="type">oid</code></td><td>OID of catalog the object belonged in</td></tr><tr><td><code class="literal">objid</code></td><td><code class="type">oid</code></td><td>OID of the object itself</td></tr><tr><td><code class="literal">objsubid</code></td><td><code class="type">integer</code></td><td>Sub-object ID (e.g., attribute number for a column)</td></tr><tr><td><code class="literal">original</code></td><td><code class="type">boolean</code></td><td>True if this was one of the root object(s) of the deletion</td></tr><tr><td><code class="literal">normal</code></td><td><code class="type">boolean</code></td><td>
  42          True if there was a normal dependency relationship
  43          in the dependency graph leading to this object
  44         </td></tr><tr><td><code class="literal">is_temporary</code></td><td><code class="type">boolean</code></td><td>
  45          True if this was a temporary object
  46         </td></tr><tr><td><code class="literal">object_type</code></td><td><code class="type">text</code></td><td>Type of the object</td></tr><tr><td><code class="literal">schema_name</code></td><td><code class="type">text</code></td><td>
  47          Name of the schema the object belonged in, if any; otherwise <code class="literal">NULL</code>.
  48          No quoting is applied.
  49         </td></tr><tr><td><code class="literal">object_name</code></td><td><code class="type">text</code></td><td>
  50          Name of the object, if the combination of schema and name can be
  51          used as a unique identifier for the object; otherwise <code class="literal">NULL</code>.
  52          No quoting is applied, and name is never schema-qualified.
  53         </td></tr><tr><td><code class="literal">object_identity</code></td><td><code class="type">text</code></td><td>
  54          Text rendering of the object identity, schema-qualified. Each
  55          identifier included in the identity is quoted if necessary.
  56         </td></tr><tr><td><code class="literal">address_names</code></td><td><code class="type">text[]</code></td><td>
  57          An array that, together with <code class="literal">object_type</code> and
  58          <code class="literal">address_args</code>, can be used by
  59          the <code class="function">pg_get_object_address</code> function to
  60          recreate the object address in a remote server containing an
  61          identically named object of the same kind.
  62         </td></tr><tr><td><code class="literal">address_args</code></td><td><code class="type">text[]</code></td><td>
  63          Complement for <code class="literal">address_names</code>
  64         </td></tr></tbody></table></div><p>
  65    </p><p>
  66     The <code class="function">pg_event_trigger_dropped_objects</code> function can be used
  67     in an event trigger like this:
  68 </p><pre class="programlisting">
  69 CREATE FUNCTION test_event_trigger_for_drops()
  70         RETURNS event_trigger LANGUAGE plpgsql AS $$
  71 DECLARE
  72     obj record;
  73 BEGIN
  74     FOR obj IN SELECT * FROM pg_event_trigger_dropped_objects()
  75     LOOP
  76         RAISE NOTICE '% dropped object: % %.% %',
  77                      tg_tag,
  78                      obj.object_type,
  79                      obj.schema_name,
  80                      obj.object_name,
  81                      obj.object_identity;
  82     END LOOP;
  83 END;
  84 $$;
  85 CREATE EVENT TRIGGER test_event_trigger_for_drops
  86    ON sql_drop
  87    EXECUTE FUNCTION test_event_trigger_for_drops();
  88 </pre><p>
  89     </p></div><div class="sect2" id="PG-EVENT-TRIGGER-TABLE-REWRITE-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">9.30.3. Handling a Table Rewrite Event <a href="#PG-EVENT-TRIGGER-TABLE-REWRITE-FUNCTIONS" class="id_link">#</a></h3></div></div></div><p>
  90     The functions shown in
  91     <a class="xref" href="functions-event-triggers.html#FUNCTIONS-EVENT-TRIGGER-TABLE-REWRITE" title="Table 9.111. Table Rewrite Information Functions">Table 9.111</a>
  92     provide information about a table for which a
  93     <code class="literal">table_rewrite</code> event has just been called.
  94     If called in any other context, an error is raised.
  95    </p><div class="table" id="FUNCTIONS-EVENT-TRIGGER-TABLE-REWRITE"><p class="title"><strong>Table 9.111. Table Rewrite Information Functions</strong></p><div class="table-contents"><table class="table" summary="Table Rewrite Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
  96         Function
  97        </p>
  98        <p>
  99         Description
 100        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
 101         <a id="id-1.5.8.36.6.3.2.2.1.1.1.1" class="indexterm"></a>
 102         <code class="function">pg_event_trigger_table_rewrite_oid</code> ()
 103         → <code class="returnvalue">oid</code>
 104        </p>
 105        <p>
 106         Returns the OID of the table about to be rewritten.
 107        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 108         <a id="id-1.5.8.36.6.3.2.2.2.1.1.1" class="indexterm"></a>
 109         <code class="function">pg_event_trigger_table_rewrite_reason</code> ()
 110         → <code class="returnvalue">integer</code>
 111        </p>
 112        <p>
 113         Returns a code explaining the reason(s) for rewriting. The value is
 114         a bitmap built from the following values: <code class="literal">1</code>
 115         (the table has changed its persistence), <code class="literal">2</code>
 116         (default value of a column has changed), <code class="literal">4</code>
 117         (a column has a new data type) and <code class="literal">8</code>
 118         (the table access method has changed).
 119        </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
 120     These functions can be used in an event trigger like this:
 121 </p><pre class="programlisting">
 122 CREATE FUNCTION test_event_trigger_table_rewrite_oid()
 123  RETURNS event_trigger
 124  LANGUAGE plpgsql AS
 125 $$
 126 BEGIN
 127   RAISE NOTICE 'rewriting table % for reason %',
 128                 pg_event_trigger_table_rewrite_oid()::regclass,
 129                 pg_event_trigger_table_rewrite_reason();
 130 END;
 131 $$;
 132
 133 CREATE EVENT TRIGGER test_table_rewrite_oid
 134                   ON table_rewrite
 135    EXECUTE FUNCTION test_event_trigger_table_rewrite_oid();
 136 </pre><p>
 137     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-trigger.html" title="9.29. Trigger Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-statistics.html" title="9.31. Statistics Information Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.29. Trigger Functions </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"> 9.31. Statistics Information Functions</td></tr></table></div></body></html>