summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/man7/CREATE_EVENT_TRIGGER.7
blob: e1ea71e081ce6a63a64b2ba18be617de1bebcd10 (plain)
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
'\" t
.\"     Title: CREATE EVENT TRIGGER
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2023
.\"    Manual: PostgreSQL 15.5 Documentation
.\"    Source: PostgreSQL 15.5
.\"  Language: English
.\"
.TH "CREATE EVENT TRIGGER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
CREATE_EVENT_TRIGGER \- define a new event trigger
.SH "SYNOPSIS"
.sp
.nf
CREATE EVENT TRIGGER \fIname\fR
    ON \fIevent\fR
    [ WHEN \fIfilter_variable\fR IN (\fIfilter_value\fR [, \&.\&.\&. ]) [ AND \&.\&.\&. ] ]
    EXECUTE { FUNCTION | PROCEDURE } \fIfunction_name\fR()
.fi
.SH "DESCRIPTION"
.PP
\fBCREATE EVENT TRIGGER\fR
creates a new event trigger\&. Whenever the designated event occurs and the
WHEN
condition associated with the trigger, if any, is satisfied, the trigger function will be executed\&. For a general introduction to event triggers, see
Chapter\ \&40\&. The user who creates an event trigger becomes its owner\&.
.SH "PARAMETERS"
.PP
\fIname\fR
.RS 4
The name to give the new trigger\&. This name must be unique within the database\&.
.RE
.PP
\fIevent\fR
.RS 4
The name of the event that triggers a call to the given function\&. See
Section\ \&40.1
for more information on event names\&.
.RE
.PP
\fIfilter_variable\fR
.RS 4
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
\fIfilter_variable\fR
is
TAG\&.
.RE
.PP
\fIfilter_value\fR
.RS 4
A list of values for the associated
\fIfilter_variable\fR
for which the trigger should fire\&. For
TAG, this means a list of command tags (e\&.g\&.,
\*(AqDROP FUNCTION\*(Aq)\&.
.RE
.PP
\fIfunction_name\fR
.RS 4
A user\-supplied function that is declared as taking no argument and returning type
event_trigger\&.
.sp
In the syntax of
CREATE EVENT TRIGGER, the keywords
FUNCTION
and
PROCEDURE
are equivalent, but the referenced function must in any case be a function, not a procedure\&. The use of the keyword
PROCEDURE
here is historical and deprecated\&.
.RE
.SH "NOTES"
.PP
Only superusers can create event triggers\&.
.PP
Event triggers are disabled in single\-user mode (see
\fBpostgres\fR(1))\&. If an erroneous event trigger disables the database so much that you can\*(Aqt even drop the trigger, restart in single\-user mode and you\*(Aqll be able to do that\&.
.SH "EXAMPLES"
.PP
Forbid the execution of any
DDL
command:
.sp
.if n \{\
.RS 4
.\}
.nf
CREATE OR REPLACE FUNCTION abort_any_command()
  RETURNS event_trigger
 LANGUAGE plpgsql
  AS $$
BEGIN
  RAISE EXCEPTION \*(Aqcommand % is disabled\*(Aq, tg_tag;
END;
$$;

CREATE EVENT TRIGGER abort_ddl ON ddl_command_start
   EXECUTE FUNCTION abort_any_command();
.fi
.if n \{\
.RE
.\}
.SH "COMPATIBILITY"
.PP
There is no
\fBCREATE EVENT TRIGGER\fR
statement in the SQL standard\&.
.SH "SEE ALSO"
ALTER EVENT TRIGGER (\fBALTER_EVENT_TRIGGER\fR(7)), DROP EVENT TRIGGER (\fBDROP_EVENT_TRIGGER\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7))