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 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</> 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</>, this means a 89 list of command tags (e.g., <literal>'DROP FUNCTION'</>). 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 </listitem> 102 </varlistentry> 103 104 </variablelist> 105 </refsect1> 106 107 <refsect1 id="sql-createeventtrigger-notes"> 108 <title>Notes</title> 109 110 <para> 111 Only superusers can create event triggers. 112 </para> 113 114 <para> 115 Event triggers are disabled in single-user mode (see <xref 116 linkend="app-postgres">). If an erroneous event trigger disables the 117 database so much that you can't even drop the trigger, restart in 118 single-user mode and you'll be able to do that. 119 </para> 120 </refsect1> 121 122 <refsect1 id="sql-createeventtrigger-examples"> 123 <title>Examples</title> 124 125 <para> 126 Forbid the execution of any <link linkend="ddl">DDL</link> command: 127 128<programlisting> 129CREATE OR REPLACE FUNCTION abort_any_command() 130 RETURNS event_trigger 131 LANGUAGE plpgsql 132 AS $$ 133BEGIN 134 RAISE EXCEPTION 'command % is disabled', tg_tag; 135END; 136$$; 137 138CREATE EVENT TRIGGER abort_ddl ON ddl_command_start 139 EXECUTE PROCEDURE abort_any_command(); 140</programlisting></para> 141 </refsect1> 142 143 <refsect1 id="sql-createeventtrigger-compatibility"> 144 <title>Compatibility</title> 145 146 <para> 147 There is no <command>CREATE EVENT TRIGGER</command> statement in the 148 SQL standard. 149 </para> 150 151 </refsect1> 152 153 <refsect1> 154 <title>See Also</title> 155 156 <simplelist type="inline"> 157 <member><xref linkend="sql-altereventtrigger"></member> 158 <member><xref linkend="sql-dropeventtrigger"></member> 159 <member><xref linkend="sql-createfunction"></member> 160 </simplelist> 161 </refsect1> 162</refentry> 163