Debian Codegraph @

doc/src/sgml/ref/create_event_trigger.sgml

raw
1 <!--
2 doc/src/sgml/ref/create_event_trigger.sgml
3 PostgreSQL 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>
24 CREATE 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"/>) as well as when
125 <xref linkend="guc-event-triggers"/> is set to <literal>false</literal>.
126 If an erroneous event trigger disables the database so much that you can't
127 even drop the trigger, restart with <xref linkend="guc-event-triggers"/>
128 set to <literal>false</literal> to temporarily disable event triggers, or
129 in single-user mode, and you'll be able to do that.
130 </para>
131 </refsect1>
132
133 <refsect1 id="sql-createeventtrigger-examples">
134 <title>Examples</title>
135
136 <para>
137 Forbid the execution of any <link linkend="ddl">DDL</link> command:
138
139 <programlisting>
140 CREATE OR REPLACE FUNCTION abort_any_command()
141 RETURNS event_trigger
142 LANGUAGE plpgsql
143 AS $$
144 BEGIN
145 RAISE EXCEPTION 'command % is disabled', tg_tag;
146 END;
147 $$;
148
149 CREATE EVENT TRIGGER abort_ddl ON ddl_command_start
150 EXECUTE FUNCTION abort_any_command();
151 </programlisting></para>
152 </refsect1>
153
154 <refsect1 id="sql-createeventtrigger-compatibility">
155 <title>Compatibility</title>
156
157 <para>
158 There is no <command>CREATE EVENT TRIGGER</command> statement in the
159 SQL standard.
160 </para>
161
162 </refsect1>
163
164 <refsect1>
165 <title>See Also</title>
166
167 <simplelist type="inline">
168 <member><xref linkend="sql-altereventtrigger"/></member>
169 <member><xref linkend="sql-dropeventtrigger"/></member>
170 <member><xref linkend="sql-createfunction"/></member>
171 </simplelist>
172 </refsect1>
173 </refentry>