1<!-- doc/src/sgml/event-trigger.sgml -->
2
3 <chapter id="event-triggers">
4  <title>Event Triggers</title>
5
6  <indexterm zone="event-triggers">
7   <primary>event trigger</primary>
8  </indexterm>
9
10  <para>
11   To supplement the trigger mechanism discussed in <xref linkend="triggers"/>,
12   <productname>PostgreSQL</productname> also provides event triggers.  Unlike regular
13   triggers, which are attached to a single table and capture only DML events,
14   event triggers are global to a particular database and are capable of
15   capturing DDL events.
16  </para>
17
18  <para>
19   Like regular triggers, event triggers can be written in any procedural
20   language that includes event trigger support, or in C, but not in plain
21   SQL.
22  </para>
23
24  <sect1 id="event-trigger-definition">
25   <title>Overview of Event Trigger Behavior</title>
26
27   <para>
28     An event trigger fires whenever the event with which it is associated
29     occurs in the database in which it is defined. Currently, the only
30     supported events are
31     <literal>ddl_command_start</literal>,
32     <literal>ddl_command_end</literal>,
33     <literal>table_rewrite</literal>
34     and <literal>sql_drop</literal>.
35     Support for additional events may be added in future releases.
36   </para>
37
38   <para>
39     The <literal>ddl_command_start</literal> event occurs just before the
40     execution of a <literal>CREATE</literal>, <literal>ALTER</literal>, <literal>DROP</literal>,
41     <literal>SECURITY LABEL</literal>,
42     <literal>COMMENT</literal>, <literal>GRANT</literal> or <literal>REVOKE</literal>
43     command.  No check whether the affected object exists or doesn't exist is
44     performed before the event trigger fires.
45     As an exception, however, this event does not occur for
46     DDL commands targeting shared objects &mdash; databases, roles, and tablespaces
47     &mdash; or for commands targeting event triggers themselves.  The event trigger
48     mechanism does not support these object types.
49     <literal>ddl_command_start</literal> also occurs just before the execution of a
50     <literal>SELECT INTO</literal> command, since this is equivalent to
51     <literal>CREATE TABLE AS</literal>.
52   </para>
53
54   <para>
55    The <literal>ddl_command_end</literal> event occurs just after the execution of
56    this same set of commands.  To obtain more details on the <acronym>DDL</acronym>
57    operations that took place, use the set-returning function
58    <literal>pg_event_trigger_ddl_commands()</literal> from the
59    <literal>ddl_command_end</literal> event trigger code (see
60    <xref linkend="functions-event-triggers"/>).  Note that the trigger fires
61    after the actions have taken place (but before the transaction commits),
62    and thus the system catalogs can be read as already changed.
63   </para>
64
65   <para>
66    The <literal>sql_drop</literal> event occurs just before the
67    <literal>ddl_command_end</literal> event trigger for any operation that drops
68    database objects.  To list the objects that have been dropped, use the
69    set-returning function <literal>pg_event_trigger_dropped_objects()</literal> from the
70    <literal>sql_drop</literal> event trigger code (see
71    <xref linkend="functions-event-triggers"/>). Note that
72    the trigger is executed after the objects have been deleted from the
73    system catalogs, so it's not possible to look them up anymore.
74   </para>
75
76   <para>
77    The <literal>table_rewrite</literal> event occurs just before a table is
78    rewritten by some actions of the commands <literal>ALTER TABLE</literal> and
79    <literal>ALTER TYPE</literal>.  While other
80    control statements are available to rewrite a table,
81    like <literal>CLUSTER</literal> and <literal>VACUUM</literal>,
82    the <literal>table_rewrite</literal> event is not triggered by them.
83   </para>
84
85   <para>
86     Event triggers (like other functions) cannot be executed in an aborted
87     transaction.  Thus, if a DDL command fails with an error, any associated
88     <literal>ddl_command_end</literal> triggers will not be executed.  Conversely,
89     if a <literal>ddl_command_start</literal> trigger fails with an error, no
90     further event triggers will fire, and no attempt will be made to execute
91     the command itself.  Similarly, if a <literal>ddl_command_end</literal> trigger
92     fails with an error, the effects of the DDL statement will be rolled
93     back, just as they would be in any other case where the containing
94     transaction aborts.
95   </para>
96
97   <para>
98     For a complete list of commands supported by the event trigger mechanism,
99     see <xref linkend="event-trigger-matrix"/>.
100   </para>
101
102   <para>
103     Event triggers are created using the command <xref linkend="sql-createeventtrigger"/>.
104     In order to create an event trigger, you must first create a function with
105     the special return type <literal>event_trigger</literal>.  This function
106     need not (and may not) return a value; the return type serves merely as
107     a signal that the function is to be invoked as an event trigger.
108   </para>
109
110   <para>
111     If more than one event trigger is defined for a particular event, they will
112     fire in alphabetical order by trigger name.
113   </para>
114
115   <para>
116     A trigger definition can also specify a <literal>WHEN</literal>
117     condition so that, for example, a <literal>ddl_command_start</literal>
118     trigger can be fired only for particular commands which the user wishes
119     to intercept. A common use of such triggers is to restrict the range of
120     DDL operations which users may perform.
121   </para>
122  </sect1>
123
124  <sect1 id="event-trigger-matrix">
125   <title>Event Trigger Firing Matrix</title>
126
127   <para>
128     <xref linkend="event-trigger-by-command-tag"/> lists all commands
129     for which event triggers are supported.
130   </para>
131
132   <table id="event-trigger-by-command-tag">
133     <title>Event Trigger Support by Command Tag</title>
134     <tgroup cols="6">
135      <colspec colname="col1" colwidth="2*"/>
136      <colspec colname="col2" colwidth="1*"/>
137      <colspec colname="col3" colwidth="1*"/>
138      <colspec colname="col4" colwidth="1*"/>
139      <colspec colname="col5" colwidth="1*"/>
140      <colspec colname="col6" colwidth="1*"/>
141      <thead>
142       <row>
143        <entry>Command Tag</entry>
144        <entry><literal>ddl_&zwsp;command_&zwsp;start</literal></entry>
145        <entry><literal>ddl_&zwsp;command_&zwsp;end</literal></entry>
146        <entry><literal>sql_&zwsp;drop</literal></entry>
147        <entry><literal>table_&zwsp;rewrite</literal></entry>
148        <entry>Notes</entry>
149       </row>
150      </thead>
151      <tbody>
152       <row>
153        <entry align="left"><literal>ALTER AGGREGATE</literal></entry>
154        <entry align="center"><literal>X</literal></entry>
155        <entry align="center"><literal>X</literal></entry>
156        <entry align="center"><literal>-</literal></entry>
157        <entry align="center"><literal>-</literal></entry>
158        <entry align="left"></entry>
159       </row>
160       <row>
161        <entry align="left"><literal>ALTER COLLATION</literal></entry>
162        <entry align="center"><literal>X</literal></entry>
163        <entry align="center"><literal>X</literal></entry>
164        <entry align="center"><literal>-</literal></entry>
165        <entry align="center"><literal>-</literal></entry>
166        <entry align="left"></entry>
167       </row>
168       <row>
169        <entry align="left"><literal>ALTER CONVERSION</literal></entry>
170        <entry align="center"><literal>X</literal></entry>
171        <entry align="center"><literal>X</literal></entry>
172        <entry align="center"><literal>-</literal></entry>
173        <entry align="center"><literal>-</literal></entry>
174        <entry align="left"></entry>
175       </row>
176       <row>
177        <entry align="left"><literal>ALTER DOMAIN</literal></entry>
178        <entry align="center"><literal>X</literal></entry>
179        <entry align="center"><literal>X</literal></entry>
180        <entry align="center"><literal>-</literal></entry>
181        <entry align="center"><literal>-</literal></entry>
182        <entry align="left"></entry>
183       </row>
184       <row>
185        <entry align="left"><literal>ALTER DEFAULT PRIVILEGES</literal></entry>
186        <entry align="center"><literal>X</literal></entry>
187        <entry align="center"><literal>X</literal></entry>
188        <entry align="center"><literal>-</literal></entry>
189        <entry align="center"><literal>-</literal></entry>
190        <entry align="left"></entry>
191       </row>
192       <row>
193        <entry align="left"><literal>ALTER EXTENSION</literal></entry>
194        <entry align="center"><literal>X</literal></entry>
195        <entry align="center"><literal>X</literal></entry>
196        <entry align="center"><literal>-</literal></entry>
197        <entry align="center"><literal>-</literal></entry>
198        <entry align="left"></entry>
199       </row>
200       <row>
201        <entry align="left"><literal>ALTER FOREIGN DATA WRAPPER</literal></entry>
202        <entry align="center"><literal>X</literal></entry>
203        <entry align="center"><literal>X</literal></entry>
204        <entry align="center"><literal>-</literal></entry>
205        <entry align="center"><literal>-</literal></entry>
206        <entry align="left"></entry>
207       </row>
208       <row>
209        <entry align="left"><literal>ALTER FOREIGN TABLE</literal></entry>
210        <entry align="center"><literal>X</literal></entry>
211        <entry align="center"><literal>X</literal></entry>
212        <entry align="center"><literal>X</literal></entry>
213        <entry align="center"><literal>-</literal></entry>
214        <entry align="left"></entry>
215       </row>
216       <row>
217        <entry align="left"><literal>ALTER FUNCTION</literal></entry>
218        <entry align="center"><literal>X</literal></entry>
219        <entry align="center"><literal>X</literal></entry>
220        <entry align="center"><literal>-</literal></entry>
221        <entry align="center"><literal>-</literal></entry>
222        <entry align="left"></entry>
223       </row>
224       <row>
225        <entry align="left"><literal>ALTER LANGUAGE</literal></entry>
226        <entry align="center"><literal>X</literal></entry>
227        <entry align="center"><literal>X</literal></entry>
228        <entry align="center"><literal>-</literal></entry>
229        <entry align="center"><literal>-</literal></entry>
230        <entry align="left"></entry>
231       </row>
232       <row>
233        <entry align="left"><literal>ALTER LARGE OBJECT</literal></entry>
234        <entry align="center"><literal>X</literal></entry>
235        <entry align="center"><literal>X</literal></entry>
236        <entry align="center"><literal>-</literal></entry>
237        <entry align="center"><literal>-</literal></entry>
238        <entry align="left"></entry>
239       </row>
240       <row>
241        <entry align="left"><literal>ALTER MATERIALIZED VIEW</literal></entry>
242        <entry align="center"><literal>X</literal></entry>
243        <entry align="center"><literal>X</literal></entry>
244        <entry align="center"><literal>-</literal></entry>
245        <entry align="center"><literal>-</literal></entry>
246        <entry align="left"></entry>
247       </row>
248       <row>
249        <entry align="left"><literal>ALTER OPERATOR</literal></entry>
250        <entry align="center"><literal>X</literal></entry>
251        <entry align="center"><literal>X</literal></entry>
252        <entry align="center"><literal>-</literal></entry>
253        <entry align="center"><literal>-</literal></entry>
254        <entry align="left"></entry>
255       </row>
256       <row>
257        <entry align="left"><literal>ALTER OPERATOR CLASS</literal></entry>
258        <entry align="center"><literal>X</literal></entry>
259        <entry align="center"><literal>X</literal></entry>
260        <entry align="center"><literal>-</literal></entry>
261        <entry align="center"><literal>-</literal></entry>
262        <entry align="left"></entry>
263       </row>
264       <row>
265        <entry align="left"><literal>ALTER OPERATOR FAMILY</literal></entry>
266        <entry align="center"><literal>X</literal></entry>
267        <entry align="center"><literal>X</literal></entry>
268        <entry align="center"><literal>-</literal></entry>
269        <entry align="center"><literal>-</literal></entry>
270        <entry align="left"></entry>
271       </row>
272       <row>
273        <entry align="left"><literal>ALTER POLICY</literal></entry>
274        <entry align="center"><literal>X</literal></entry>
275        <entry align="center"><literal>X</literal></entry>
276        <entry align="center"><literal>-</literal></entry>
277        <entry align="center"><literal>-</literal></entry>
278        <entry align="left"></entry>
279       </row>
280       <row>
281        <entry align="left"><literal>ALTER PROCEDURE</literal></entry>
282        <entry align="center"><literal>X</literal></entry>
283        <entry align="center"><literal>X</literal></entry>
284        <entry align="center"><literal>-</literal></entry>
285        <entry align="center"><literal>-</literal></entry>
286        <entry align="left"></entry>
287       </row>
288       <row>
289        <entry align="left"><literal>ALTER PUBLICATION</literal></entry>
290        <entry align="center"><literal>X</literal></entry>
291        <entry align="center"><literal>X</literal></entry>
292        <entry align="center"><literal>-</literal></entry>
293        <entry align="center"><literal>-</literal></entry>
294        <entry align="left"></entry>
295       </row>
296       <row>
297        <entry align="left"><literal>ALTER SCHEMA</literal></entry>
298        <entry align="center"><literal>X</literal></entry>
299        <entry align="center"><literal>X</literal></entry>
300        <entry align="center"><literal>-</literal></entry>
301        <entry align="center"><literal>-</literal></entry>
302        <entry align="left"></entry>
303       </row>
304       <row>
305        <entry align="left"><literal>ALTER SEQUENCE</literal></entry>
306        <entry align="center"><literal>X</literal></entry>
307        <entry align="center"><literal>X</literal></entry>
308        <entry align="center"><literal>-</literal></entry>
309        <entry align="center"><literal>-</literal></entry>
310        <entry align="left"></entry>
311       </row>
312       <row>
313        <entry align="left"><literal>ALTER SERVER</literal></entry>
314        <entry align="center"><literal>X</literal></entry>
315        <entry align="center"><literal>X</literal></entry>
316        <entry align="center"><literal>-</literal></entry>
317        <entry align="center"><literal>-</literal></entry>
318        <entry align="left"></entry>
319       </row>
320       <row>
321        <entry align="left"><literal>ALTER STATISTICS</literal></entry>
322        <entry align="center"><literal>X</literal></entry>
323        <entry align="center"><literal>X</literal></entry>
324        <entry align="center"><literal>-</literal></entry>
325        <entry align="center"><literal>-</literal></entry>
326        <entry align="left"></entry>
327       </row>
328       <row>
329        <entry align="left"><literal>ALTER SUBSCRIPTION</literal></entry>
330        <entry align="center"><literal>X</literal></entry>
331        <entry align="center"><literal>X</literal></entry>
332        <entry align="center"><literal>-</literal></entry>
333        <entry align="center"><literal>-</literal></entry>
334        <entry align="left"></entry>
335       </row>
336       <row>
337        <entry align="left"><literal>ALTER TABLE</literal></entry>
338        <entry align="center"><literal>X</literal></entry>
339        <entry align="center"><literal>X</literal></entry>
340        <entry align="center"><literal>X</literal></entry>
341        <entry align="center"><literal>X</literal></entry>
342        <entry align="left"></entry>
343       </row>
344       <row>
345        <entry align="left"><literal>ALTER TEXT SEARCH CONFIGURATION</literal></entry>
346        <entry align="center"><literal>X</literal></entry>
347        <entry align="center"><literal>X</literal></entry>
348        <entry align="center"><literal>-</literal></entry>
349        <entry align="center"><literal>-</literal></entry>
350        <entry align="left"></entry>
351       </row>
352       <row>
353        <entry align="left"><literal>ALTER TEXT SEARCH DICTIONARY</literal></entry>
354        <entry align="center"><literal>X</literal></entry>
355        <entry align="center"><literal>X</literal></entry>
356        <entry align="center"><literal>-</literal></entry>
357        <entry align="center"><literal>-</literal></entry>
358        <entry align="left"></entry>
359       </row>
360       <row>
361        <entry align="left"><literal>ALTER TEXT SEARCH PARSER</literal></entry>
362        <entry align="center"><literal>X</literal></entry>
363        <entry align="center"><literal>X</literal></entry>
364        <entry align="center"><literal>-</literal></entry>
365        <entry align="center"><literal>-</literal></entry>
366        <entry align="left"></entry>
367       </row>
368       <row>
369        <entry align="left"><literal>ALTER TEXT SEARCH TEMPLATE</literal></entry>
370        <entry align="center"><literal>X</literal></entry>
371        <entry align="center"><literal>X</literal></entry>
372        <entry align="center"><literal>-</literal></entry>
373        <entry align="center"><literal>-</literal></entry>
374        <entry align="left"></entry>
375       </row>
376       <row>
377        <entry align="left"><literal>ALTER TRIGGER</literal></entry>
378        <entry align="center"><literal>X</literal></entry>
379        <entry align="center"><literal>X</literal></entry>
380        <entry align="center"><literal>-</literal></entry>
381        <entry align="center"><literal>-</literal></entry>
382        <entry align="left"></entry>
383       </row>
384       <row>
385        <entry align="left"><literal>ALTER TYPE</literal></entry>
386        <entry align="center"><literal>X</literal></entry>
387        <entry align="center"><literal>X</literal></entry>
388        <entry align="center"><literal>-</literal></entry>
389        <entry align="center"><literal>X</literal></entry>
390        <entry align="left"></entry>
391       </row>
392       <row>
393        <entry align="left"><literal>ALTER USER MAPPING</literal></entry>
394        <entry align="center"><literal>X</literal></entry>
395        <entry align="center"><literal>X</literal></entry>
396        <entry align="center"><literal>-</literal></entry>
397        <entry align="center"><literal>-</literal></entry>
398        <entry align="left"></entry>
399       </row>
400       <row>
401        <entry align="left"><literal>ALTER VIEW</literal></entry>
402        <entry align="center"><literal>X</literal></entry>
403        <entry align="center"><literal>X</literal></entry>
404        <entry align="center"><literal>-</literal></entry>
405        <entry align="center"><literal>-</literal></entry>
406        <entry align="left"></entry>
407       </row>
408       <row>
409        <entry align="left"><literal>COMMENT</literal></entry>
410        <entry align="center"><literal>X</literal></entry>
411        <entry align="center"><literal>X</literal></entry>
412        <entry align="center"><literal>-</literal></entry>
413        <entry align="center"><literal>-</literal></entry>
414        <entry align="left">Only for local objects</entry>
415       </row>
416       <row>
417        <entry align="left"><literal>CREATE ACCESS METHOD</literal></entry>
418        <entry align="center"><literal>X</literal></entry>
419        <entry align="center"><literal>X</literal></entry>
420        <entry align="center"><literal>-</literal></entry>
421        <entry align="center"><literal>-</literal></entry>
422        <entry align="left"></entry>
423       </row>
424       <row>
425        <entry align="left"><literal>CREATE AGGREGATE</literal></entry>
426        <entry align="center"><literal>X</literal></entry>
427        <entry align="center"><literal>X</literal></entry>
428        <entry align="center"><literal>-</literal></entry>
429        <entry align="center"><literal>-</literal></entry>
430        <entry align="left"></entry>
431       </row>
432       <row>
433        <entry align="left"><literal>CREATE CAST</literal></entry>
434        <entry align="center"><literal>X</literal></entry>
435        <entry align="center"><literal>X</literal></entry>
436        <entry align="center"><literal>-</literal></entry>
437        <entry align="center"><literal>-</literal></entry>
438        <entry align="left"></entry>
439       </row>
440       <row>
441        <entry align="left"><literal>CREATE COLLATION</literal></entry>
442        <entry align="center"><literal>X</literal></entry>
443        <entry align="center"><literal>X</literal></entry>
444        <entry align="center"><literal>-</literal></entry>
445        <entry align="center"><literal>-</literal></entry>
446        <entry align="left"></entry>
447       </row>
448       <row>
449        <entry align="left"><literal>CREATE CONVERSION</literal></entry>
450        <entry align="center"><literal>X</literal></entry>
451        <entry align="center"><literal>X</literal></entry>
452        <entry align="center"><literal>-</literal></entry>
453        <entry align="center"><literal>-</literal></entry>
454        <entry align="left"></entry>
455       </row>
456       <row>
457        <entry align="left"><literal>CREATE DOMAIN</literal></entry>
458        <entry align="center"><literal>X</literal></entry>
459        <entry align="center"><literal>X</literal></entry>
460        <entry align="center"><literal>-</literal></entry>
461        <entry align="center"><literal>-</literal></entry>
462        <entry align="left"></entry>
463       </row>
464       <row>
465        <entry align="left"><literal>CREATE EXTENSION</literal></entry>
466        <entry align="center"><literal>X</literal></entry>
467        <entry align="center"><literal>X</literal></entry>
468        <entry align="center"><literal>-</literal></entry>
469        <entry align="center"><literal>-</literal></entry>
470        <entry align="left"></entry>
471       </row>
472       <row>
473        <entry align="left"><literal>CREATE FOREIGN DATA WRAPPER</literal></entry>
474        <entry align="center"><literal>X</literal></entry>
475        <entry align="center"><literal>X</literal></entry>
476        <entry align="center"><literal>-</literal></entry>
477        <entry align="center"><literal>-</literal></entry>
478        <entry align="left"></entry>
479       </row>
480       <row>
481        <entry align="left"><literal>CREATE FOREIGN TABLE</literal></entry>
482        <entry align="center"><literal>X</literal></entry>
483        <entry align="center"><literal>X</literal></entry>
484        <entry align="center"><literal>-</literal></entry>
485        <entry align="center"><literal>-</literal></entry>
486        <entry align="left"></entry>
487       </row>
488       <row>
489        <entry align="left"><literal>CREATE FUNCTION</literal></entry>
490        <entry align="center"><literal>X</literal></entry>
491        <entry align="center"><literal>X</literal></entry>
492        <entry align="center"><literal>-</literal></entry>
493        <entry align="center"><literal>-</literal></entry>
494        <entry align="left"></entry>
495       </row>
496       <row>
497        <entry align="left"><literal>CREATE INDEX</literal></entry>
498        <entry align="center"><literal>X</literal></entry>
499        <entry align="center"><literal>X</literal></entry>
500        <entry align="center"><literal>-</literal></entry>
501        <entry align="center"><literal>-</literal></entry>
502        <entry align="left"></entry>
503       </row>
504       <row>
505        <entry align="left"><literal>CREATE LANGUAGE</literal></entry>
506        <entry align="center"><literal>X</literal></entry>
507        <entry align="center"><literal>X</literal></entry>
508        <entry align="center"><literal>-</literal></entry>
509        <entry align="center"><literal>-</literal></entry>
510        <entry align="left"></entry>
511       </row>
512       <row>
513        <entry align="left"><literal>CREATE MATERIALIZED VIEW</literal></entry>
514        <entry align="center"><literal>X</literal></entry>
515        <entry align="center"><literal>X</literal></entry>
516        <entry align="center"><literal>-</literal></entry>
517        <entry align="center"><literal>-</literal></entry>
518        <entry align="left"></entry>
519       </row>
520       <row>
521        <entry align="left"><literal>CREATE OPERATOR</literal></entry>
522        <entry align="center"><literal>X</literal></entry>
523        <entry align="center"><literal>X</literal></entry>
524        <entry align="center"><literal>-</literal></entry>
525        <entry align="center"><literal>-</literal></entry>
526        <entry align="left"></entry>
527       </row>
528       <row>
529        <entry align="left"><literal>CREATE OPERATOR CLASS</literal></entry>
530        <entry align="center"><literal>X</literal></entry>
531        <entry align="center"><literal>X</literal></entry>
532        <entry align="center"><literal>-</literal></entry>
533        <entry align="center"><literal>-</literal></entry>
534        <entry align="left"></entry>
535       </row>
536       <row>
537        <entry align="left"><literal>CREATE OPERATOR FAMILY</literal></entry>
538        <entry align="center"><literal>X</literal></entry>
539        <entry align="center"><literal>X</literal></entry>
540        <entry align="center"><literal>-</literal></entry>
541        <entry align="center"><literal>-</literal></entry>
542        <entry align="left"></entry>
543       </row>
544       <row>
545        <entry align="left"><literal>CREATE POLICY</literal></entry>
546        <entry align="center"><literal>X</literal></entry>
547        <entry align="center"><literal>X</literal></entry>
548        <entry align="center"><literal>-</literal></entry>
549        <entry align="center"><literal>-</literal></entry>
550        <entry align="left"></entry>
551       </row>
552       <row>
553        <entry align="left"><literal>CREATE PROCEDURE</literal></entry>
554        <entry align="center"><literal>X</literal></entry>
555        <entry align="center"><literal>X</literal></entry>
556        <entry align="center"><literal>-</literal></entry>
557        <entry align="center"><literal>-</literal></entry>
558        <entry align="left"></entry>
559       </row>
560       <row>
561        <entry align="left"><literal>CREATE PUBLICATION</literal></entry>
562        <entry align="center"><literal>X</literal></entry>
563        <entry align="center"><literal>X</literal></entry>
564        <entry align="center"><literal>-</literal></entry>
565        <entry align="center"><literal>-</literal></entry>
566        <entry align="left"></entry>
567       </row>
568       <row>
569        <entry align="left"><literal>CREATE RULE</literal></entry>
570        <entry align="center"><literal>X</literal></entry>
571        <entry align="center"><literal>X</literal></entry>
572        <entry align="center"><literal>-</literal></entry>
573        <entry align="center"><literal>-</literal></entry>
574        <entry align="left"></entry>
575       </row>
576       <row>
577        <entry align="left"><literal>CREATE SCHEMA</literal></entry>
578        <entry align="center"><literal>X</literal></entry>
579        <entry align="center"><literal>X</literal></entry>
580        <entry align="center"><literal>-</literal></entry>
581        <entry align="center"><literal>-</literal></entry>
582        <entry align="left"></entry>
583       </row>
584       <row>
585        <entry align="left"><literal>CREATE SEQUENCE</literal></entry>
586        <entry align="center"><literal>X</literal></entry>
587        <entry align="center"><literal>X</literal></entry>
588        <entry align="center"><literal>-</literal></entry>
589        <entry align="center"><literal>-</literal></entry>
590        <entry align="left"></entry>
591       </row>
592       <row>
593        <entry align="left"><literal>CREATE SERVER</literal></entry>
594        <entry align="center"><literal>X</literal></entry>
595        <entry align="center"><literal>X</literal></entry>
596        <entry align="center"><literal>-</literal></entry>
597        <entry align="center"><literal>-</literal></entry>
598        <entry align="left"></entry>
599       </row>
600       <row>
601        <entry align="left"><literal>CREATE STATISTICS</literal></entry>
602        <entry align="center"><literal>X</literal></entry>
603        <entry align="center"><literal>X</literal></entry>
604        <entry align="center"><literal>-</literal></entry>
605        <entry align="center"><literal>-</literal></entry>
606        <entry align="left"></entry>
607       </row>
608       <row>
609        <entry align="left"><literal>CREATE SUBSCRIPTION</literal></entry>
610        <entry align="center"><literal>X</literal></entry>
611        <entry align="center"><literal>X</literal></entry>
612        <entry align="center"><literal>-</literal></entry>
613        <entry align="center"><literal>-</literal></entry>
614        <entry align="left"></entry>
615       </row>
616       <row>
617        <entry align="left"><literal>CREATE TABLE</literal></entry>
618        <entry align="center"><literal>X</literal></entry>
619        <entry align="center"><literal>X</literal></entry>
620        <entry align="center"><literal>-</literal></entry>
621        <entry align="center"><literal>-</literal></entry>
622        <entry align="left"></entry>
623       </row>
624       <row>
625        <entry align="left"><literal>CREATE TABLE AS</literal></entry>
626        <entry align="center"><literal>X</literal></entry>
627        <entry align="center"><literal>X</literal></entry>
628        <entry align="center"><literal>-</literal></entry>
629        <entry align="center"><literal>-</literal></entry>
630        <entry align="left"></entry>
631       </row>
632       <row>
633        <entry align="left"><literal>CREATE TEXT SEARCH CONFIGURATION</literal></entry>
634        <entry align="center"><literal>X</literal></entry>
635        <entry align="center"><literal>X</literal></entry>
636        <entry align="center"><literal>-</literal></entry>
637        <entry align="center"><literal>-</literal></entry>
638        <entry align="left"></entry>
639       </row>
640       <row>
641        <entry align="left"><literal>CREATE TEXT SEARCH DICTIONARY</literal></entry>
642        <entry align="center"><literal>X</literal></entry>
643        <entry align="center"><literal>X</literal></entry>
644        <entry align="center"><literal>-</literal></entry>
645        <entry align="center"><literal>-</literal></entry>
646        <entry align="left"></entry>
647       </row>
648       <row>
649        <entry align="left"><literal>CREATE TEXT SEARCH PARSER</literal></entry>
650        <entry align="center"><literal>X</literal></entry>
651        <entry align="center"><literal>X</literal></entry>
652        <entry align="center"><literal>-</literal></entry>
653        <entry align="center"><literal>-</literal></entry>
654        <entry align="left"></entry>
655       </row>
656       <row>
657        <entry align="left"><literal>CREATE TEXT SEARCH TEMPLATE</literal></entry>
658        <entry align="center"><literal>X</literal></entry>
659        <entry align="center"><literal>X</literal></entry>
660        <entry align="center"><literal>-</literal></entry>
661        <entry align="center"><literal>-</literal></entry>
662        <entry align="left"></entry>
663       </row>
664       <row>
665        <entry align="left"><literal>CREATE TRIGGER</literal></entry>
666        <entry align="center"><literal>X</literal></entry>
667        <entry align="center"><literal>X</literal></entry>
668        <entry align="center"><literal>-</literal></entry>
669        <entry align="center"><literal>-</literal></entry>
670        <entry align="left"></entry>
671       </row>
672       <row>
673        <entry align="left"><literal>CREATE TYPE</literal></entry>
674        <entry align="center"><literal>X</literal></entry>
675        <entry align="center"><literal>X</literal></entry>
676        <entry align="center"><literal>-</literal></entry>
677        <entry align="center"><literal>-</literal></entry>
678        <entry align="left"></entry>
679       </row>
680       <row>
681        <entry align="left"><literal>CREATE USER MAPPING</literal></entry>
682        <entry align="center"><literal>X</literal></entry>
683        <entry align="center"><literal>X</literal></entry>
684        <entry align="center"><literal>-</literal></entry>
685        <entry align="center"><literal>-</literal></entry>
686        <entry align="left"></entry>
687       </row>
688       <row>
689        <entry align="left"><literal>CREATE VIEW</literal></entry>
690        <entry align="center"><literal>X</literal></entry>
691        <entry align="center"><literal>X</literal></entry>
692        <entry align="center"><literal>-</literal></entry>
693        <entry align="center"><literal>-</literal></entry>
694        <entry align="left"></entry>
695       </row>
696       <row>
697        <entry align="left"><literal>DROP ACCESS METHOD</literal></entry>
698        <entry align="center"><literal>X</literal></entry>
699        <entry align="center"><literal>X</literal></entry>
700        <entry align="center"><literal>X</literal></entry>
701        <entry align="center"><literal>-</literal></entry>
702        <entry align="left"></entry>
703       </row>
704       <row>
705        <entry align="left"><literal>DROP AGGREGATE</literal></entry>
706        <entry align="center"><literal>X</literal></entry>
707        <entry align="center"><literal>X</literal></entry>
708        <entry align="center"><literal>X</literal></entry>
709        <entry align="center"><literal>-</literal></entry>
710        <entry align="left"></entry>
711       </row>
712       <row>
713        <entry align="left"><literal>DROP CAST</literal></entry>
714        <entry align="center"><literal>X</literal></entry>
715        <entry align="center"><literal>X</literal></entry>
716        <entry align="center"><literal>X</literal></entry>
717        <entry align="center"><literal>-</literal></entry>
718        <entry align="left"></entry>
719       </row>
720       <row>
721        <entry align="left"><literal>DROP COLLATION</literal></entry>
722        <entry align="center"><literal>X</literal></entry>
723        <entry align="center"><literal>X</literal></entry>
724        <entry align="center"><literal>X</literal></entry>
725        <entry align="center"><literal>-</literal></entry>
726        <entry align="left"></entry>
727       </row>
728       <row>
729        <entry align="left"><literal>DROP CONVERSION</literal></entry>
730        <entry align="center"><literal>X</literal></entry>
731        <entry align="center"><literal>X</literal></entry>
732        <entry align="center"><literal>X</literal></entry>
733        <entry align="center"><literal>-</literal></entry>
734        <entry align="left"></entry>
735       </row>
736       <row>
737        <entry align="left"><literal>DROP DOMAIN</literal></entry>
738        <entry align="center"><literal>X</literal></entry>
739        <entry align="center"><literal>X</literal></entry>
740        <entry align="center"><literal>X</literal></entry>
741        <entry align="center"><literal>-</literal></entry>
742        <entry align="left"></entry>
743       </row>
744       <row>
745        <entry align="left"><literal>DROP EXTENSION</literal></entry>
746        <entry align="center"><literal>X</literal></entry>
747        <entry align="center"><literal>X</literal></entry>
748        <entry align="center"><literal>X</literal></entry>
749        <entry align="center"><literal>-</literal></entry>
750        <entry align="left"></entry>
751       </row>
752       <row>
753        <entry align="left"><literal>DROP FOREIGN DATA WRAPPER</literal></entry>
754        <entry align="center"><literal>X</literal></entry>
755        <entry align="center"><literal>X</literal></entry>
756        <entry align="center"><literal>X</literal></entry>
757        <entry align="center"><literal>-</literal></entry>
758        <entry align="left"></entry>
759       </row>
760       <row>
761        <entry align="left"><literal>DROP FOREIGN TABLE</literal></entry>
762        <entry align="center"><literal>X</literal></entry>
763        <entry align="center"><literal>X</literal></entry>
764        <entry align="center"><literal>X</literal></entry>
765        <entry align="center"><literal>-</literal></entry>
766        <entry align="left"></entry>
767       </row>
768       <row>
769        <entry align="left"><literal>DROP FUNCTION</literal></entry>
770        <entry align="center"><literal>X</literal></entry>
771        <entry align="center"><literal>X</literal></entry>
772        <entry align="center"><literal>X</literal></entry>
773        <entry align="center"><literal>-</literal></entry>
774        <entry align="left"></entry>
775       </row>
776       <row>
777        <entry align="left"><literal>DROP INDEX</literal></entry>
778        <entry align="center"><literal>X</literal></entry>
779        <entry align="center"><literal>X</literal></entry>
780        <entry align="center"><literal>X</literal></entry>
781        <entry align="center"><literal>-</literal></entry>
782        <entry align="left"></entry>
783       </row>
784       <row>
785        <entry align="left"><literal>DROP LANGUAGE</literal></entry>
786        <entry align="center"><literal>X</literal></entry>
787        <entry align="center"><literal>X</literal></entry>
788        <entry align="center"><literal>X</literal></entry>
789        <entry align="center"><literal>-</literal></entry>
790        <entry align="left"></entry>
791       </row>
792       <row>
793        <entry align="left"><literal>DROP MATERIALIZED VIEW</literal></entry>
794        <entry align="center"><literal>X</literal></entry>
795        <entry align="center"><literal>X</literal></entry>
796        <entry align="center"><literal>X</literal></entry>
797        <entry align="center"><literal>-</literal></entry>
798        <entry align="left"></entry>
799       </row>
800       <row>
801        <entry align="left"><literal>DROP OPERATOR</literal></entry>
802        <entry align="center"><literal>X</literal></entry>
803        <entry align="center"><literal>X</literal></entry>
804        <entry align="center"><literal>X</literal></entry>
805        <entry align="center"><literal>-</literal></entry>
806        <entry align="left"></entry>
807       </row>
808       <row>
809        <entry align="left"><literal>DROP OPERATOR CLASS</literal></entry>
810        <entry align="center"><literal>X</literal></entry>
811        <entry align="center"><literal>X</literal></entry>
812        <entry align="center"><literal>X</literal></entry>
813        <entry align="center"><literal>-</literal></entry>
814        <entry align="left"></entry>
815       </row>
816       <row>
817        <entry align="left"><literal>DROP OPERATOR FAMILY</literal></entry>
818        <entry align="center"><literal>X</literal></entry>
819        <entry align="center"><literal>X</literal></entry>
820        <entry align="center"><literal>X</literal></entry>
821        <entry align="center"><literal>-</literal></entry>
822        <entry align="left"></entry>
823       </row>
824       <row>
825        <entry align="left"><literal>DROP OWNED</literal></entry>
826        <entry align="center"><literal>X</literal></entry>
827        <entry align="center"><literal>X</literal></entry>
828        <entry align="center"><literal>X</literal></entry>
829        <entry align="center"><literal>-</literal></entry>
830        <entry align="left"></entry>
831       </row>
832       <row>
833        <entry align="left"><literal>DROP POLICY</literal></entry>
834        <entry align="center"><literal>X</literal></entry>
835        <entry align="center"><literal>X</literal></entry>
836        <entry align="center"><literal>X</literal></entry>
837        <entry align="center"><literal>-</literal></entry>
838        <entry align="left"></entry>
839       </row>
840       <row>
841        <entry align="left"><literal>DROP PROCEDURE</literal></entry>
842        <entry align="center"><literal>X</literal></entry>
843        <entry align="center"><literal>X</literal></entry>
844        <entry align="center"><literal>X</literal></entry>
845        <entry align="center"><literal>-</literal></entry>
846        <entry align="left"></entry>
847       </row>
848       <row>
849        <entry align="left"><literal>DROP PUBLICATION</literal></entry>
850        <entry align="center"><literal>X</literal></entry>
851        <entry align="center"><literal>X</literal></entry>
852        <entry align="center"><literal>X</literal></entry>
853        <entry align="center"><literal>-</literal></entry>
854        <entry align="left"></entry>
855       </row>
856       <row>
857        <entry align="left"><literal>DROP RULE</literal></entry>
858        <entry align="center"><literal>X</literal></entry>
859        <entry align="center"><literal>X</literal></entry>
860        <entry align="center"><literal>X</literal></entry>
861        <entry align="center"><literal>-</literal></entry>
862        <entry align="left"></entry>
863       </row>
864       <row>
865        <entry align="left"><literal>DROP SCHEMA</literal></entry>
866        <entry align="center"><literal>X</literal></entry>
867        <entry align="center"><literal>X</literal></entry>
868        <entry align="center"><literal>X</literal></entry>
869        <entry align="center"><literal>-</literal></entry>
870        <entry align="left"></entry>
871       </row>
872       <row>
873        <entry align="left"><literal>DROP SEQUENCE</literal></entry>
874        <entry align="center"><literal>X</literal></entry>
875        <entry align="center"><literal>X</literal></entry>
876        <entry align="center"><literal>X</literal></entry>
877        <entry align="center"><literal>-</literal></entry>
878        <entry align="left"></entry>
879       </row>
880       <row>
881        <entry align="left"><literal>DROP SERVER</literal></entry>
882        <entry align="center"><literal>X</literal></entry>
883        <entry align="center"><literal>X</literal></entry>
884        <entry align="center"><literal>X</literal></entry>
885        <entry align="center"><literal>-</literal></entry>
886        <entry align="left"></entry>
887       </row>
888       <row>
889        <entry align="left"><literal>DROP STATISTICS</literal></entry>
890        <entry align="center"><literal>X</literal></entry>
891        <entry align="center"><literal>X</literal></entry>
892        <entry align="center"><literal>X</literal></entry>
893        <entry align="center"><literal>-</literal></entry>
894        <entry align="left"></entry>
895       </row>
896       <row>
897        <entry align="left"><literal>DROP SUBSCRIPTION</literal></entry>
898        <entry align="center"><literal>X</literal></entry>
899        <entry align="center"><literal>X</literal></entry>
900        <entry align="center"><literal>X</literal></entry>
901        <entry align="center"><literal>-</literal></entry>
902        <entry align="left"></entry>
903       </row>
904       <row>
905        <entry align="left"><literal>DROP TABLE</literal></entry>
906        <entry align="center"><literal>X</literal></entry>
907        <entry align="center"><literal>X</literal></entry>
908        <entry align="center"><literal>X</literal></entry>
909        <entry align="center"><literal>-</literal></entry>
910        <entry align="left"></entry>
911       </row>
912       <row>
913        <entry align="left"><literal>DROP TEXT SEARCH CONFIGURATION</literal></entry>
914        <entry align="center"><literal>X</literal></entry>
915        <entry align="center"><literal>X</literal></entry>
916        <entry align="center"><literal>X</literal></entry>
917        <entry align="center"><literal>-</literal></entry>
918        <entry align="left"></entry>
919       </row>
920       <row>
921        <entry align="left"><literal>DROP TEXT SEARCH DICTIONARY</literal></entry>
922        <entry align="center"><literal>X</literal></entry>
923        <entry align="center"><literal>X</literal></entry>
924        <entry align="center"><literal>X</literal></entry>
925        <entry align="center"><literal>-</literal></entry>
926        <entry align="left"></entry>
927       </row>
928       <row>
929        <entry align="left"><literal>DROP TEXT SEARCH PARSER</literal></entry>
930        <entry align="center"><literal>X</literal></entry>
931        <entry align="center"><literal>X</literal></entry>
932        <entry align="center"><literal>X</literal></entry>
933        <entry align="center"><literal>-</literal></entry>
934        <entry align="left"></entry>
935       </row>
936       <row>
937        <entry align="left"><literal>DROP TEXT SEARCH TEMPLATE</literal></entry>
938        <entry align="center"><literal>X</literal></entry>
939        <entry align="center"><literal>X</literal></entry>
940        <entry align="center"><literal>X</literal></entry>
941        <entry align="center"><literal>-</literal></entry>
942        <entry align="left"></entry>
943       </row>
944       <row>
945        <entry align="left"><literal>DROP TRIGGER</literal></entry>
946        <entry align="center"><literal>X</literal></entry>
947        <entry align="center"><literal>X</literal></entry>
948        <entry align="center"><literal>X</literal></entry>
949        <entry align="center"><literal>-</literal></entry>
950        <entry align="left"></entry>
951       </row>
952       <row>
953        <entry align="left"><literal>DROP TYPE</literal></entry>
954        <entry align="center"><literal>X</literal></entry>
955        <entry align="center"><literal>X</literal></entry>
956        <entry align="center"><literal>X</literal></entry>
957        <entry align="center"><literal>-</literal></entry>
958        <entry align="left"></entry>
959       </row>
960       <row>
961        <entry align="left"><literal>DROP USER MAPPING</literal></entry>
962        <entry align="center"><literal>X</literal></entry>
963        <entry align="center"><literal>X</literal></entry>
964        <entry align="center"><literal>X</literal></entry>
965        <entry align="center"><literal>-</literal></entry>
966        <entry align="left"></entry>
967       </row>
968       <row>
969        <entry align="left"><literal>DROP VIEW</literal></entry>
970        <entry align="center"><literal>X</literal></entry>
971        <entry align="center"><literal>X</literal></entry>
972        <entry align="center"><literal>X</literal></entry>
973        <entry align="center"><literal>-</literal></entry>
974        <entry align="left"></entry>
975       </row>
976       <row>
977        <entry align="left"><literal>GRANT</literal></entry>
978        <entry align="center"><literal>X</literal></entry>
979        <entry align="center"><literal>X</literal></entry>
980        <entry align="center"><literal>-</literal></entry>
981        <entry align="center"><literal>-</literal></entry>
982        <entry align="left">Only for local objects</entry>
983       </row>
984       <row>
985        <entry align="left"><literal>IMPORT FOREIGN SCHEMA</literal></entry>
986        <entry align="center"><literal>X</literal></entry>
987        <entry align="center"><literal>X</literal></entry>
988        <entry align="center"><literal>-</literal></entry>
989        <entry align="center"><literal>-</literal></entry>
990        <entry align="left"></entry>
991       </row>
992       <row>
993        <entry align="left"><literal>REFRESH MATERIALIZED VIEW</literal></entry>
994        <entry align="center"><literal>X</literal></entry>
995        <entry align="center"><literal>X</literal></entry>
996        <entry align="center"><literal>-</literal></entry>
997        <entry align="center"><literal>-</literal></entry>
998        <entry align="left"></entry>
999       </row>
1000       <row>
1001        <entry align="left"><literal>REVOKE</literal></entry>
1002        <entry align="center"><literal>X</literal></entry>
1003        <entry align="center"><literal>X</literal></entry>
1004        <entry align="center"><literal>-</literal></entry>
1005        <entry align="center"><literal>-</literal></entry>
1006        <entry align="left">Only for local objects</entry>
1007       </row>
1008       <row>
1009        <entry align="left"><literal>SECURITY LABEL</literal></entry>
1010        <entry align="center"><literal>X</literal></entry>
1011        <entry align="center"><literal>X</literal></entry>
1012        <entry align="center"><literal>-</literal></entry>
1013        <entry align="center"><literal>-</literal></entry>
1014        <entry align="left">Only for local objects</entry>
1015       </row>
1016       <row>
1017        <entry align="left"><literal>SELECT INTO</literal></entry>
1018        <entry align="center"><literal>X</literal></entry>
1019        <entry align="center"><literal>X</literal></entry>
1020        <entry align="center"><literal>-</literal></entry>
1021        <entry align="center"><literal>-</literal></entry>
1022        <entry align="left"></entry>
1023       </row>
1024      </tbody>
1025     </tgroup>
1026   </table>
1027  </sect1>
1028
1029  <sect1 id="event-trigger-interface">
1030   <title>Writing Event Trigger Functions in C</title>
1031
1032   <indexterm zone="event-trigger-interface">
1033    <primary>event trigger</primary>
1034    <secondary>in C</secondary>
1035   </indexterm>
1036
1037   <para>
1038    This section describes the low-level details of the interface to an
1039    event trigger function. This information is only needed when writing
1040    event trigger functions in C. If you are using a higher-level language
1041    then these details are handled for you. In most cases you should
1042    consider using a procedural language before writing your event triggers
1043    in C. The documentation of each procedural language explains how to
1044    write an event trigger in that language.
1045   </para>
1046
1047   <para>
1048    Event trigger functions must use the <quote>version 1</quote> function
1049    manager interface.
1050   </para>
1051
1052   <para>
1053    When a function is called by the event trigger manager, it is not passed
1054    any normal arguments, but it is passed a <quote>context</quote> pointer
1055    pointing to a <structname>EventTriggerData</structname> structure. C functions can
1056    check whether they were called from the event trigger manager or not by
1057    executing the macro:
1058<programlisting>
1059CALLED_AS_EVENT_TRIGGER(fcinfo)
1060</programlisting>
1061    which expands to:
1062<programlisting>
1063((fcinfo)-&gt;context != NULL &amp;&amp; IsA((fcinfo)-&gt;context, EventTriggerData))
1064</programlisting>
1065    If this returns true, then it is safe to cast
1066    <literal>fcinfo-&gt;context</literal> to type <literal>EventTriggerData
1067    *</literal> and make use of the pointed-to
1068    <structname>EventTriggerData</structname> structure.  The function must
1069    <emphasis>not</emphasis> alter the <structname>EventTriggerData</structname>
1070    structure or any of the data it points to.
1071   </para>
1072
1073   <para>
1074    <structname>struct EventTriggerData</structname> is defined in
1075    <filename>commands/event_trigger.h</filename>:
1076
1077<programlisting>
1078typedef struct EventTriggerData
1079{
1080    NodeTag     type;
1081    const char *event;      /* event name */
1082    Node       *parsetree;  /* parse tree */
1083    CommandTag  tag;        /* command tag */
1084} EventTriggerData;
1085</programlisting>
1086
1087    where the members are defined as follows:
1088
1089    <variablelist>
1090     <varlistentry>
1091      <term><structfield>type</structfield></term>
1092      <listitem>
1093       <para>
1094        Always <literal>T_EventTriggerData</literal>.
1095       </para>
1096      </listitem>
1097     </varlistentry>
1098
1099     <varlistentry>
1100      <term><structfield>event</structfield></term>
1101      <listitem>
1102       <para>
1103        Describes the event for which the function is called, one of
1104        <literal>"ddl_command_start"</literal>, <literal>"ddl_command_end"</literal>,
1105        <literal>"sql_drop"</literal>, <literal>"table_rewrite"</literal>.
1106        See <xref linkend="event-trigger-definition"/> for the meaning of these
1107        events.
1108       </para>
1109      </listitem>
1110     </varlistentry>
1111
1112     <varlistentry>
1113      <term><structfield>parsetree</structfield></term>
1114      <listitem>
1115       <para>
1116        A pointer to the parse tree of the command.  Check the PostgreSQL
1117        source code for details.  The parse tree structure is subject to change
1118        without notice.
1119       </para>
1120      </listitem>
1121     </varlistentry>
1122
1123     <varlistentry>
1124      <term><structfield>tag</structfield></term>
1125      <listitem>
1126       <para>
1127        The command tag associated with the event for which the event trigger
1128        is run, for example <literal>"CREATE FUNCTION"</literal>.
1129       </para>
1130      </listitem>
1131     </varlistentry>
1132    </variablelist>
1133   </para>
1134
1135   <para>
1136    An event trigger function must return a <symbol>NULL</symbol> pointer
1137    (<emphasis>not</emphasis> an SQL null value, that is, do not
1138    set <parameter>isNull</parameter> true).
1139   </para>
1140  </sect1>
1141
1142  <sect1 id="event-trigger-example">
1143   <title>A Complete Event Trigger Example</title>
1144
1145   <para>
1146    Here is a very simple example of an event trigger function written in C.
1147    (Examples of triggers written in procedural languages can be found in
1148    the documentation of the procedural languages.)
1149   </para>
1150
1151   <para>
1152    The function <function>noddl</function> raises an exception each time it is called.
1153    The event trigger definition associated the function with
1154    the <literal>ddl_command_start</literal> event.  The effect is that all DDL
1155    commands (with the exceptions mentioned
1156    in <xref linkend="event-trigger-definition"/>) are prevented from running.
1157   </para>
1158
1159   <para>
1160    This is the source code of the trigger function:
1161<programlisting><![CDATA[
1162#include "postgres.h"
1163#include "commands/event_trigger.h"
1164
1165
1166PG_MODULE_MAGIC;
1167
1168PG_FUNCTION_INFO_V1(noddl);
1169
1170Datum
1171noddl(PG_FUNCTION_ARGS)
1172{
1173    EventTriggerData *trigdata;
1174
1175    if (!CALLED_AS_EVENT_TRIGGER(fcinfo))  /* internal error */
1176        elog(ERROR, "not fired by event trigger manager");
1177
1178    trigdata = (EventTriggerData *) fcinfo->context;
1179
1180    ereport(ERROR,
1181        (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
1182                 errmsg("command \"%s\" denied", trigdata->tag)));
1183
1184    PG_RETURN_NULL();
1185}
1186]]></programlisting>
1187   </para>
1188
1189   <para>
1190    After you have compiled the source code (see <xref linkend="dfunc"/>),
1191    declare the function and the triggers:
1192<programlisting>
1193CREATE FUNCTION noddl() RETURNS event_trigger
1194    AS 'noddl' LANGUAGE C;
1195
1196CREATE EVENT TRIGGER noddl ON ddl_command_start
1197    EXECUTE FUNCTION noddl();
1198</programlisting>
1199   </para>
1200
1201   <para>
1202    Now you can test the operation of the trigger:
1203<screen>
1204=# \dy
1205                     List of event triggers
1206 Name  |       Event       | Owner | Enabled | Function | Tags
1207-------+-------------------+-------+---------+----------+------
1208 noddl | ddl_command_start | dim   | enabled | noddl    |
1209(1 row)
1210
1211=# CREATE TABLE foo(id serial);
1212ERROR:  command "CREATE TABLE" denied
1213</screen>
1214   </para>
1215
1216   <para>
1217    In this situation, in order to be able to run some DDL commands when you
1218    need to do so, you have to either drop the event trigger or disable it.  It
1219    can be convenient to disable the trigger for only the duration of a
1220    transaction:
1221<programlisting>
1222BEGIN;
1223ALTER EVENT TRIGGER noddl DISABLE;
1224CREATE TABLE foo (id serial);
1225ALTER EVENT TRIGGER noddl ENABLE;
1226COMMIT;
1227</programlisting>
1228    (Recall that DDL commands on event triggers themselves are not affected by
1229    event triggers.)
1230   </para>
1231  </sect1>
1232
1233  <sect1 id="event-trigger-table-rewrite-example">
1234   <title>A Table Rewrite Event Trigger Example</title>
1235
1236   <para>
1237    Thanks to the <literal>table_rewrite</literal> event, it is possible to implement
1238    a table rewriting policy only allowing the rewrite in maintenance windows.
1239   </para>
1240
1241   <para>
1242    Here's an example implementing such a policy.
1243<programlisting>
1244CREATE OR REPLACE FUNCTION no_rewrite()
1245 RETURNS event_trigger
1246 LANGUAGE plpgsql AS
1247$$
1248---
1249--- Implement local Table Rewriting policy:
1250---   public.foo is not allowed rewriting, ever
1251---   other tables are only allowed rewriting between 1am and 6am
1252---   unless they have more than 100 blocks
1253---
1254DECLARE
1255  table_oid oid := pg_event_trigger_table_rewrite_oid();
1256  current_hour integer := extract('hour' from current_time);
1257  pages integer;
1258  max_pages integer := 100;
1259BEGIN
1260  IF pg_event_trigger_table_rewrite_oid() = 'public.foo'::regclass
1261  THEN
1262        RAISE EXCEPTION 'you''re not allowed to rewrite the table %',
1263                        table_oid::regclass;
1264  END IF;
1265
1266  SELECT INTO pages relpages FROM pg_class WHERE oid = table_oid;
1267  IF pages > max_pages
1268  THEN
1269        RAISE EXCEPTION 'rewrites only allowed for table with less than % pages',
1270                        max_pages;
1271  END IF;
1272
1273  IF current_hour NOT BETWEEN 1 AND 6
1274  THEN
1275        RAISE EXCEPTION 'rewrites only allowed between 1am and 6am';
1276  END IF;
1277END;
1278$$;
1279
1280CREATE EVENT TRIGGER no_rewrite_allowed
1281                  ON table_rewrite
1282   EXECUTE FUNCTION no_rewrite();
1283</programlisting>
1284   </para>
1285 </sect1>
1286</chapter>
1287