1<!-- 2doc/src/sgml/ref/create_event_trigger.sgml 3PostgreSQL documentation 4--> 5 6<refentry id="sql-createeventtrigger"> 7 <indexterm zone="sql-createeventtrigger"> 8 <primary>CREATE EVENT TRIGGER</primary> 9 </indexterm> 10 11 <refmeta> 12 <refentrytitle>CREATE EVENT TRIGGER</refentrytitle> 13 <manvolnum>7</manvolnum> 14 <refmiscinfo>SQL - Language Statements</refmiscinfo> 15 </refmeta> 16 17 <refnamediv> 18 <refname>CREATE EVENT TRIGGER</refname> 19 <refpurpose>define a new event trigger</refpurpose> 20 </refnamediv> 21 22 <refsynopsisdiv> 23<synopsis> 24CREATE EVENT TRIGGER <replaceable class="parameter">name</replaceable> 25 ON <replaceable class="parameter">event</replaceable> 26 [ WHEN <replaceable class="parameter">filter_variable</replaceable> IN (<replaceable class="parameter">filter_value</replaceable> [, ... ]) [ AND ... ] ] 27 EXECUTE { FUNCTION | PROCEDURE } <replaceable class="parameter">function_name</replaceable>() 28</synopsis> 29 </refsynopsisdiv> 30 31 <refsect1> 32 <title>Description</title> 33 34 <para> 35 <command>CREATE EVENT TRIGGER</command> creates a new event trigger. 36 Whenever the designated event occurs and the <literal>WHEN</literal> condition 37 associated with the trigger, if any, is satisfied, the trigger function 38 will be executed. For a general introduction to event triggers, see 39 <xref linkend="event-triggers"/>. The user who creates an event trigger 40 becomes its owner. 41 </para> 42 </refsect1> 43 44 <refsect1> 45 <title>Parameters</title> 46 47 <variablelist> 48 <varlistentry> 49 <term><replaceable class="parameter">name</replaceable></term> 50 <listitem> 51 <para> 52 The name to give the new trigger. This name must be unique within 53 the database. 54 </para> 55 </listitem> 56 </varlistentry> 57 58 <varlistentry> 59 <term><replaceable class="parameter">event</replaceable></term> 60 <listitem> 61 <para> 62 The name of the event that triggers a call to the given function. 63 See <xref linkend="event-trigger-definition"/> for more information 64 on event names. 65 </para> 66 </listitem> 67 </varlistentry> 68 69 <varlistentry> 70 <term><replaceable class="parameter">filter_variable</replaceable></term> 71 <listitem> 72 <para> 73 The name of a variable used to filter events. This makes it possible 74 to restrict the firing of the trigger to a subset of the cases in which 75 it is supported. Currently the only supported 76 <replaceable class="parameter">filter_variable</replaceable> 77 is <literal>TAG</literal>. 78 </para> 79 </listitem> 80 </varlistentry> 81 82 <varlistentry> 83 <term><replaceable class="parameter">filter_value</replaceable></term> 84 <listitem> 85 <para> 86 A list of values for the 87 associated <replaceable class="parameter">filter_variable</replaceable> 88 for which the trigger should fire. For <literal>TAG</literal>, this means a 89 list of command tags (e.g., <literal>'DROP FUNCTION'</literal>). 90 </para> 91 </listitem> 92 </varlistentry> 93 94 <varlistentry> 95 <term><replaceable class="parameter">function_name</replaceable></term> 96 <listitem> 97 <para> 98 A user-supplied function that is declared as taking no argument and 99 returning type <literal>event_trigger</literal>. 100 </para> 101 102 <para> 103 In the syntax of <literal>CREATE EVENT TRIGGER</literal>, the keywords 104 <literal>FUNCTION</literal> and <literal>PROCEDURE</literal> are 105 equivalent, but the referenced function must in any case be a function, 106 not a procedure. The use of the keyword <literal>PROCEDURE</literal> 107 here is historical and deprecated. 108 </para> 109 </listitem> 110 </varlistentry> 111 112 </variablelist> 113 </refsect1> 114 115 <refsect1 id="sql-createeventtrigger-notes"> 116 <title>Notes</title> 117 118 <para> 119 Only superusers can create event triggers. 120 </para> 121 122 <para> 123 Event triggers are disabled in single-user mode (see <xref 124 linkend="app-postgres"/>). If an erroneous event trigger disables the 125 database so much that you can't even drop the trigger, restart in 126 single-user mode and you'll be able to do that. 127 </para> 128 </refsect1> 129 130 <refsect1 id="sql-createeventtrigger-examples"> 131 <title>Examples</title> 132 133 <para> 134 Forbid the execution of any <link linkend="ddl">DDL</link> command: 135 136<programlisting> 137CREATE OR REPLACE FUNCTION abort_any_command() 138 RETURNS event_trigger 139 LANGUAGE plpgsql 140 AS $$ 141BEGIN 142 RAISE EXCEPTION 'command % is disabled', tg_tag; 143END; 144$$; 145 146CREATE EVENT TRIGGER abort_ddl ON ddl_command_start 147 EXECUTE FUNCTION abort_any_command(); 148</programlisting></para> 149 </refsect1> 150 151 <refsect1 id="sql-createeventtrigger-compatibility"> 152 <title>Compatibility</title> 153 154 <para> 155 There is no <command>CREATE EVENT TRIGGER</command> statement in the 156 SQL standard. 157 </para> 158 159 </refsect1> 160 161 <refsect1> 162 <title>See Also</title> 163 164 <simplelist type="inline"> 165 <member><xref linkend="sql-altereventtrigger"/></member> 166 <member><xref linkend="sql-dropeventtrigger"/></member> 167 <member><xref linkend="sql-createfunction"/></member> 168 </simplelist> 169 </refsect1> 170</refentry> 171