From 53eff471c69dc8b0c01f046d3fdcc460eb90d0e5 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Thu, 21 Aug 2025 09:15:55 +0200
Subject: PL/Python: Add event trigger support

Allow event triggers to be written in PL/Python.  It provides a TD
dictionary with some information about the event trigger.

Author: Euler Taveira <euler@eulerto.com>
Co-authored-by: Dimitri Fontaine <dimitri@2ndQuadrant.fr>
Reviewed-by: Pavel Stehule <pavel.stehule@gmail.com>
Discussion: https://www.postgresql.org/message-id/flat/03f03515-2068-4f5b-b357-8fb540883c38%40app.fastmail.com
---
 doc/src/sgml/plpython.sgml | 76 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

(limited to 'doc/src')

diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index cb065bf5f88..27c4467ba7d 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -662,6 +662,14 @@ $$ LANGUAGE plpython3u;
    <secondary>in PL/Python</secondary>
   </indexterm>
 
+  <para>
+   <application>PL/Python</application> can be used to define trigger
+   functions.
+   <productname>PostgreSQL</productname> requires that a function that is to
+   be called as a trigger must be declared as a function with no arguments and
+   a return type of <literal>trigger</literal>.
+  </para>
+
   <para>
    When a function is used as a trigger, the dictionary
    <literal>TD</literal> contains trigger-related values:
@@ -769,6 +777,74 @@ $$ LANGUAGE plpython3u;
   </para>
  </sect1>
 
+ <sect1 id="plpython-event-trigger">
+  <title>Event Trigger Functions</title>
+
+  <indexterm zone="plpython-event-trigger">
+   <primary>event trigger</primary>
+   <secondary>in PL/Python</secondary>
+  </indexterm>
+
+  <para>
+   <application>PL/Python</application> can be used to define event triggers
+   (see also <xref linkend="event-triggers"/>).
+   <productname>PostgreSQL</productname> requires that a function that is to
+   be called as an event trigger must be declared as a function with no
+   arguments and a return type of <literal>event_trigger</literal>.
+  </para>
+
+  <para>
+   When a function is used as an event trigger, the dictionary
+   <literal>TD</literal> contains trigger-related values:
+
+   <variablelist>
+    <varlistentry>
+     <term><varname>TD["event"]</varname></term>
+     <listitem>
+      <para>
+       The event the trigger was fired for, as a string, for example
+       <literal>ddl_command_start</literal>.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><varname>TD["tag"]</varname></term>
+     <listitem>
+      <para>
+       The command tag for which the trigger was fired, as a string, for
+       example <literal>DROP TABLE</literal>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+
+  <para>
+   <xref linkend="plpython-event-trigger-example"/> shows an example of an
+   event trigger function in <application>PL/Python</application>.
+  </para>
+
+  <example id="plpython-event-trigger-example">
+   <title>A <application>PL/Python</application> Event Trigger Function</title>
+
+   <para>
+    This example trigger simply raises a <literal>NOTICE</literal> message
+    each time a supported command is executed.
+   </para>
+
+<programlisting>
+CREATE OR REPLACE FUNCTION pysnitch() RETURNS event_trigger
+LANGUAGE plpython3u
+AS $$
+  plpy.notice("TD[event] => " + TD["event"] + " ; TD[tag] => " + TD["tag"]);
+$$;
+
+CREATE EVENT TRIGGER pysnitch ON ddl_command_start EXECUTE FUNCTION pysnitch();
+</programlisting>
+  </example>
+ </sect1>
+
  <sect1 id="plpython-database">
   <title>Database Access</title>
 
-- 
cgit v1.2.3