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