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