granicus.if.org Git - postgresql/blob - doc/src/sgml/event-trigger.sgml

   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</> 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</>,
  32      <literal>ddl_command_end</>
  33      and <literal>sql_drop</>.
  34      Support for additional events may be added in future releases.
  35    </para>
  36
  37    <para>
  38      The <literal>ddl_command_start</> event occurs just before the
  39      execution of a <literal>CREATE</>, <literal>ALTER</>, or <literal>DROP</>
  40      command.  No check whether the affected object exists or doesn't exist is
  41      performed before the event trigger fires.
  42      As an exception, however, this event does not occur for
  43      DDL commands targeting shared objects &mdash; databases, roles, and tablespaces
  44      &mdash; or for commands targeting event triggers themselves.  The event trigger
  45      mechanism does not support these object types.
  46      <literal>ddl_command_start</> also occurs just before the execution of a
  47      <literal>SELECT INTO</literal> command, since this is equivalent to
  48      <literal>CREATE TABLE AS</literal>.
  49    </para>
  50
  51    <para>
  52     The <literal>ddl_command_end</> event occurs just after the execution of
  53     this same set of commands.
  54    </para>
  55
  56    <para>
  57     The <literal>sql_drop</> event occurs just before the
  58     <literal>ddl_command_end</> event trigger for any operation that drops
  59     database objects.  To list the objects that have been dropped, use the
  60     set-returning function <literal>pg_event_trigger_dropped_objects()</> from the
  61     <literal>sql_drop</> event trigger code (see
  62     <xref linkend="functions-event-triggers">). Note that
  63     the trigger is executed after the objects have been deleted from the
  64     system catalogs, so it's not possible to look them up anymore.
  65    </para>
  66
  67    <para>
  68      Event triggers (like other functions) cannot be executed in an aborted
  69      transaction.  Thus, if a DDL command fails with an error, any associated
  70      <literal>ddl_command_end</> triggers will not be executed.  Conversely,
  71      if a <literal>ddl_command_start</> trigger fails with an error, no
  72      further event triggers will fire, and no attempt will be made to execute
  73      the command itself.  Similarly, if a <literal>ddl_command_end</> trigger
  74      fails with an error, the effects of the DDL statement will be rolled
  75      back, just as they would be in any other case where the containing
  76      transaction aborts.
  77    </para>
  78
  79    <para>
  80      For a complete list of commands supported by the event trigger mechanism,
  81      see <xref linkend="event-trigger-matrix">.
  82    </para>
  83
  84    <para>
  85      Event triggers are created using the command <xref linkend="sql-createeventtrigger">.
  86      In order to create an event trigger, you must first create a function with
  87      the special return type <literal>event_trigger</literal>.  This function
  88      need not (and may not) return a value; the return type serves merely as
  89      a signal that the function is to be invoked as an event trigger.
  90    </para>
  91
  92    <para>
  93      If more than one event trigger is defined for a particular event, they will
  94      fire in alphabetical order by trigger name.
  95    </para>
  96
  97    <para>
  98      A trigger definition can also specify a <literal>WHEN</literal>
  99      condition so that, for example, a <literal>ddl_command_start</literal>
 100      trigger can be fired only for particular commands which the user wishes
 101      to intercept. A common use of such triggers is to restrict the range of
 102      DDL operations which users may perform.
 103    </para>
 104   </sect1>
 105
 106   <sect1 id="event-trigger-matrix">
 107    <title>Event Trigger Firing Matrix</title>
 108
 109    <para>
 110      <xref linkend="event-trigger-by-command-tag"> lists all commands
 111      for which event triggers are supported.
 112    </para>
 113
 114    <table id="event-trigger-by-command-tag">
 115      <title>Event Trigger Support by Command Tag</title>
 116      <tgroup cols="4">
 117       <thead>
 118        <row>
 119         <entry>command tag</entry>
 120         <entry><literal>ddl_command_start</literal></entry>
 121         <entry><literal>ddl_command_end</literal></entry>
 122         <entry><literal>sql_drop</literal></entry>
 123        </row>
 124       </thead>
 125       <tbody>
 126        <row>
 127         <entry align="left"><literal>ALTER AGGREGATE</literal></entry>
 128         <entry align="center"><literal>X</literal></entry>
 129         <entry align="center"><literal>X</literal></entry>
 130         <entry align="center"><literal>-</literal></entry>
 131        </row>
 132        <row>
 133         <entry align="left"><literal>ALTER COLLATION</literal></entry>
 134         <entry align="center"><literal>X</literal></entry>
 135         <entry align="center"><literal>X</literal></entry>
 136         <entry align="center"><literal>-</literal></entry>
 137        </row>
 138        <row>
 139         <entry align="left"><literal>ALTER CONVERSION</literal></entry>
 140         <entry align="center"><literal>X</literal></entry>
 141         <entry align="center"><literal>X</literal></entry>
 142         <entry align="center"><literal>-</literal></entry>
 143        </row>
 144        <row>
 145         <entry align="left"><literal>ALTER DOMAIN</literal></entry>
 146         <entry align="center"><literal>X</literal></entry>
 147         <entry align="center"><literal>X</literal></entry>
 148         <entry align="center"><literal>-</literal></entry>
 149        </row>
 150        <row>
 151         <entry align="left"><literal>ALTER EXTENSION</literal></entry>
 152         <entry align="center"><literal>X</literal></entry>
 153         <entry align="center"><literal>X</literal></entry>
 154         <entry align="center"><literal>-</literal></entry>
 155        </row>
 156        <row>
 157         <entry align="left"><literal>ALTER FOREIGN DATA WRAPPER</literal></entry>
 158         <entry align="center"><literal>X</literal></entry>
 159         <entry align="center"><literal>X</literal></entry>
 160         <entry align="center"><literal>-</literal></entry>
 161        </row>
 162        <row>
 163         <entry align="left"><literal>ALTER FOREIGN TABLE</literal></entry>
 164         <entry align="center"><literal>X</literal></entry>
 165         <entry align="center"><literal>X</literal></entry>
 166         <entry align="center"><literal>X</literal></entry>
 167        </row>
 168        <row>
 169         <entry align="left"><literal>ALTER FUNCTION</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        </row>
 174        <row>
 175         <entry align="left"><literal>ALTER LANGUAGE</literal></entry>
 176         <entry align="center"><literal>X</literal></entry>
 177         <entry align="center"><literal>X</literal></entry>
 178         <entry align="center"><literal>-</literal></entry>
 179        </row>
 180        <row>
 181         <entry align="left"><literal>ALTER OPERATOR</literal></entry>
 182         <entry align="center"><literal>X</literal></entry>
 183         <entry align="center"><literal>X</literal></entry>
 184         <entry align="center"><literal>-</literal></entry>
 185        </row>
 186        <row>
 187         <entry align="left"><literal>ALTER OPERATOR CLASS</literal></entry>
 188         <entry align="center"><literal>X</literal></entry>
 189         <entry align="center"><literal>X</literal></entry>
 190         <entry align="center"><literal>-</literal></entry>
 191        </row>
 192        <row>
 193         <entry align="left"><literal>ALTER OPERATOR FAMILY</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        </row>
 198        <row>
 199         <entry align="left"><literal>ALTER SCHEMA</literal></entry>
 200         <entry align="center"><literal>X</literal></entry>
 201         <entry align="center"><literal>X</literal></entry>
 202         <entry align="center"><literal>-</literal></entry>
 203        </row>
 204        <row>
 205         <entry align="left"><literal>ALTER SEQUENCE</literal></entry>
 206         <entry align="center"><literal>X</literal></entry>
 207         <entry align="center"><literal>X</literal></entry>
 208         <entry align="center"><literal>-</literal></entry>
 209        </row>
 210        <row>
 211         <entry align="left"><literal>ALTER SERVER</literal></entry>
 212         <entry align="center"><literal>X</literal></entry>
 213         <entry align="center"><literal>X</literal></entry>
 214         <entry align="center"><literal>-</literal></entry>
 215        </row>
 216        <row>
 217         <entry align="left"><literal>ALTER TABLE</literal></entry>
 218         <entry align="center"><literal>X</literal></entry>
 219         <entry align="center"><literal>X</literal></entry>
 220         <entry align="center"><literal>X</literal></entry>
 221        </row>
 222        <row>
 223         <entry align="left"><literal>ALTER TEXT SEARCH CONFIGURATION</literal></entry>
 224         <entry align="center"><literal>X</literal></entry>
 225         <entry align="center"><literal>X</literal></entry>
 226         <entry align="center"><literal>-</literal></entry>
 227        </row>
 228        <row>
 229         <entry align="left"><literal>ALTER TEXT SEARCH DICTIONARY</literal></entry>
 230         <entry align="center"><literal>X</literal></entry>
 231         <entry align="center"><literal>X</literal></entry>
 232         <entry align="center"><literal>-</literal></entry>
 233        </row>
 234        <row>
 235         <entry align="left"><literal>ALTER TEXT SEARCH PARSER</literal></entry>
 236         <entry align="center"><literal>X</literal></entry>
 237         <entry align="center"><literal>X</literal></entry>
 238         <entry align="center"><literal>-</literal></entry>
 239        </row>
 240        <row>
 241         <entry align="left"><literal>ALTER TEXT SEARCH TEMPLATE</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        </row>
 246        <row>
 247         <entry align="left"><literal>ALTER TRIGGER</literal></entry>
 248         <entry align="center"><literal>X</literal></entry>
 249         <entry align="center"><literal>X</literal></entry>
 250         <entry align="center"><literal>-</literal></entry>
 251        </row>
 252        <row>
 253         <entry align="left"><literal>ALTER TYPE</literal></entry>
 254         <entry align="center"><literal>X</literal></entry>
 255         <entry align="center"><literal>X</literal></entry>
 256         <entry align="center"><literal>-</literal></entry>
 257        </row>
 258        <row>
 259         <entry align="left"><literal>ALTER USER MAPPING</literal></entry>
 260         <entry align="center"><literal>X</literal></entry>
 261         <entry align="center"><literal>X</literal></entry>
 262         <entry align="center"><literal>-</literal></entry>
 263        </row>
 264        <row>
 265         <entry align="left"><literal>ALTER VIEW</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        </row>
 270        <row>
 271         <entry align="left"><literal>CREATE AGGREGATE</literal></entry>
 272         <entry align="center"><literal>X</literal></entry>
 273         <entry align="center"><literal>X</literal></entry>
 274         <entry align="center"><literal>-</literal></entry>
 275        </row>
 276        <row>
 277         <entry align="left"><literal>CREATE CAST</literal></entry>
 278         <entry align="center"><literal>X</literal></entry>
 279         <entry align="center"><literal>X</literal></entry>
 280         <entry align="center"><literal>-</literal></entry>
 281        </row>
 282        <row>
 283         <entry align="left"><literal>CREATE COLLATION</literal></entry>
 284         <entry align="center"><literal>X</literal></entry>
 285         <entry align="center"><literal>X</literal></entry>
 286         <entry align="center"><literal>-</literal></entry>
 287        </row>
 288        <row>
 289         <entry align="left"><literal>CREATE CONVERSION</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        </row>
 294        <row>
 295         <entry align="left"><literal>CREATE DOMAIN</literal></entry>
 296         <entry align="center"><literal>X</literal></entry>
 297         <entry align="center"><literal>X</literal></entry>
 298         <entry align="center"><literal>-</literal></entry>
 299        </row>
 300        <row>
 301         <entry align="left"><literal>CREATE EXTENSION</literal></entry>
 302         <entry align="center"><literal>X</literal></entry>
 303         <entry align="center"><literal>X</literal></entry>
 304         <entry align="center"><literal>-</literal></entry>
 305        </row>
 306        <row>
 307         <entry align="left"><literal>CREATE FOREIGN DATA WRAPPER</literal></entry>
 308         <entry align="center"><literal>X</literal></entry>
 309         <entry align="center"><literal>X</literal></entry>
 310         <entry align="center"><literal>-</literal></entry>
 311        </row>
 312        <row>
 313         <entry align="left"><literal>CREATE FOREIGN TABLE</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        </row>
 318        <row>
 319         <entry align="left"><literal>CREATE FUNCTION</literal></entry>
 320         <entry align="center"><literal>X</literal></entry>
 321         <entry align="center"><literal>X</literal></entry>
 322         <entry align="center"><literal>-</literal></entry>
 323        </row>
 324        <row>
 325         <entry align="left"><literal>CREATE INDEX</literal></entry>
 326         <entry align="center"><literal>X</literal></entry>
 327         <entry align="center"><literal>X</literal></entry>
 328         <entry align="center"><literal>-</literal></entry>
 329        </row>
 330        <row>
 331         <entry align="left"><literal>CREATE LANGUAGE</literal></entry>
 332         <entry align="center"><literal>X</literal></entry>
 333         <entry align="center"><literal>X</literal></entry>
 334         <entry align="center"><literal>-</literal></entry>
 335        </row>
 336        <row>
 337         <entry align="left"><literal>CREATE OPERATOR</literal></entry>
 338         <entry align="center"><literal>X</literal></entry>
 339         <entry align="center"><literal>X</literal></entry>
 340         <entry align="center"><literal>-</literal></entry>
 341        </row>
 342        <row>
 343         <entry align="left"><literal>CREATE OPERATOR CLASS</literal></entry>
 344         <entry align="center"><literal>X</literal></entry>
 345         <entry align="center"><literal>X</literal></entry>
 346         <entry align="center"><literal>-</literal></entry>
 347        </row>
 348        <row>
 349         <entry align="left"><literal>CREATE OPERATOR FAMILY</literal></entry>
 350         <entry align="center"><literal>X</literal></entry>
 351         <entry align="center"><literal>X</literal></entry>
 352         <entry align="center"><literal>-</literal></entry>
 353        </row>
 354        <row>
 355         <entry align="left"><literal>CREATE RULE</literal></entry>
 356         <entry align="center"><literal>X</literal></entry>
 357         <entry align="center"><literal>X</literal></entry>
 358         <entry align="center"><literal>-</literal></entry>
 359        </row>
 360        <row>
 361         <entry align="left"><literal>CREATE SCHEMA</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        </row>
 366        <row>
 367         <entry align="left"><literal>CREATE SEQUENCE</literal></entry>
 368         <entry align="center"><literal>X</literal></entry>
 369         <entry align="center"><literal>X</literal></entry>
 370         <entry align="center"><literal>-</literal></entry>
 371        </row>
 372        <row>
 373         <entry align="left"><literal>CREATE SERVER</literal></entry>
 374         <entry align="center"><literal>X</literal></entry>
 375         <entry align="center"><literal>X</literal></entry>
 376         <entry align="center"><literal>-</literal></entry>
 377        </row>
 378        <row>
 379         <entry align="left"><literal>CREATE TABLE</literal></entry>
 380         <entry align="center"><literal>X</literal></entry>
 381         <entry align="center"><literal>X</literal></entry>
 382         <entry align="center"><literal>-</literal></entry>
 383        </row>
 384        <row>
 385         <entry align="left"><literal>CREATE TABLE AS</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        </row>
 390        <row>
 391         <entry align="left"><literal>CREATE TEXT SEARCH CONFIGURATION</literal></entry>
 392         <entry align="center"><literal>X</literal></entry>
 393         <entry align="center"><literal>X</literal></entry>
 394         <entry align="center"><literal>-</literal></entry>
 395        </row>
 396        <row>
 397         <entry align="left"><literal>CREATE TEXT SEARCH DICTIONARY</literal></entry>
 398         <entry align="center"><literal>X</literal></entry>
 399         <entry align="center"><literal>X</literal></entry>
 400         <entry align="center"><literal>-</literal></entry>
 401        </row>
 402        <row>
 403         <entry align="left"><literal>CREATE TEXT SEARCH PARSER</literal></entry>
 404         <entry align="center"><literal>X</literal></entry>
 405         <entry align="center"><literal>X</literal></entry>
 406         <entry align="center"><literal>-</literal></entry>
 407        </row>
 408        <row>
 409         <entry align="left"><literal>CREATE TEXT SEARCH TEMPLATE</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        </row>
 414        <row>
 415         <entry align="left"><literal>CREATE TRIGGER</literal></entry>
 416         <entry align="center"><literal>X</literal></entry>
 417         <entry align="center"><literal>X</literal></entry>
 418         <entry align="center"><literal>-</literal></entry>
 419        </row>
 420        <row>
 421         <entry align="left"><literal>CREATE TYPE</literal></entry>
 422         <entry align="center"><literal>X</literal></entry>
 423         <entry align="center"><literal>X</literal></entry>
 424         <entry align="center"><literal>-</literal></entry>
 425        </row>
 426        <row>
 427         <entry align="left"><literal>CREATE USER MAPPING</literal></entry>
 428         <entry align="center"><literal>X</literal></entry>
 429         <entry align="center"><literal>X</literal></entry>
 430         <entry align="center"><literal>-</literal></entry>
 431        </row>
 432        <row>
 433         <entry align="left"><literal>CREATE VIEW</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        </row>
 438        <row>
 439         <entry align="left"><literal>DROP AGGREGATE</literal></entry>
 440         <entry align="center"><literal>X</literal></entry>
 441         <entry align="center"><literal>X</literal></entry>
 442         <entry align="center"><literal>X</literal></entry>
 443        </row>
 444        <row>
 445         <entry align="left"><literal>DROP CAST</literal></entry>
 446         <entry align="center"><literal>X</literal></entry>
 447         <entry align="center"><literal>X</literal></entry>
 448         <entry align="center"><literal>X</literal></entry>
 449        </row>
 450        <row>
 451         <entry align="left"><literal>DROP COLLATION</literal></entry>
 452         <entry align="center"><literal>X</literal></entry>
 453         <entry align="center"><literal>X</literal></entry>
 454         <entry align="center"><literal>X</literal></entry>
 455        </row>
 456        <row>
 457         <entry align="left"><literal>DROP CONVERSION</literal></entry>
 458         <entry align="center"><literal>X</literal></entry>
 459         <entry align="center"><literal>X</literal></entry>
 460         <entry align="center"><literal>X</literal></entry>
 461        </row>
 462        <row>
 463         <entry align="left"><literal>DROP DOMAIN</literal></entry>
 464         <entry align="center"><literal>X</literal></entry>
 465         <entry align="center"><literal>X</literal></entry>
 466         <entry align="center"><literal>X</literal></entry>
 467        </row>
 468        <row>
 469         <entry align="left"><literal>DROP EXTENSION</literal></entry>
 470         <entry align="center"><literal>X</literal></entry>
 471         <entry align="center"><literal>X</literal></entry>
 472         <entry align="center"><literal>X</literal></entry>
 473        </row>
 474        <row>
 475         <entry align="left"><literal>DROP FOREIGN DATA WRAPPER</literal></entry>
 476         <entry align="center"><literal>X</literal></entry>
 477         <entry align="center"><literal>X</literal></entry>
 478         <entry align="center"><literal>X</literal></entry>
 479        </row>
 480        <row>
 481         <entry align="left"><literal>DROP 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>X</literal></entry>
 485        </row>
 486        <row>
 487         <entry align="left"><literal>DROP FUNCTION</literal></entry>
 488         <entry align="center"><literal>X</literal></entry>
 489         <entry align="center"><literal>X</literal></entry>
 490         <entry align="center"><literal>X</literal></entry>
 491        </row>
 492        <row>
 493         <entry align="left"><literal>DROP INDEX</literal></entry>
 494         <entry align="center"><literal>X</literal></entry>
 495         <entry align="center"><literal>X</literal></entry>
 496         <entry align="center"><literal>X</literal></entry>
 497        </row>
 498        <row>
 499         <entry align="left"><literal>DROP LANGUAGE</literal></entry>
 500         <entry align="center"><literal>X</literal></entry>
 501         <entry align="center"><literal>X</literal></entry>
 502         <entry align="center"><literal>X</literal></entry>
 503        </row>
 504        <row>
 505         <entry align="left"><literal>DROP OPERATOR</literal></entry>
 506         <entry align="center"><literal>X</literal></entry>
 507         <entry align="center"><literal>X</literal></entry>
 508         <entry align="center"><literal>X</literal></entry>
 509        </row>
 510        <row>
 511         <entry align="left"><literal>DROP OPERATOR CLASS</literal></entry>
 512         <entry align="center"><literal>X</literal></entry>
 513         <entry align="center"><literal>X</literal></entry>
 514         <entry align="center"><literal>X</literal></entry>
 515        </row>
 516        <row>
 517         <entry align="left"><literal>DROP OPERATOR FAMILY</literal></entry>
 518         <entry align="center"><literal>X</literal></entry>
 519         <entry align="center"><literal>X</literal></entry>
 520         <entry align="center"><literal>X</literal></entry>
 521        </row>
 522        <row>
 523         <entry align="left"><literal>DROP OWNED</literal></entry>
 524         <entry align="center"><literal>X</literal></entry>
 525         <entry align="center"><literal>X</literal></entry>
 526         <entry align="center"><literal>X</literal></entry>
 527        </row>
 528        <row>
 529         <entry align="left"><literal>DROP RULE</literal></entry>
 530         <entry align="center"><literal>X</literal></entry>
 531         <entry align="center"><literal>X</literal></entry>
 532         <entry align="center"><literal>X</literal></entry>
 533        </row>
 534        <row>
 535         <entry align="left"><literal>DROP SCHEMA</literal></entry>
 536         <entry align="center"><literal>X</literal></entry>
 537         <entry align="center"><literal>X</literal></entry>
 538         <entry align="center"><literal>X</literal></entry>
 539        </row>
 540        <row>
 541         <entry align="left"><literal>DROP SEQUENCE</literal></entry>
 542         <entry align="center"><literal>X</literal></entry>
 543         <entry align="center"><literal>X</literal></entry>
 544         <entry align="center"><literal>X</literal></entry>
 545        </row>
 546        <row>
 547         <entry align="left"><literal>DROP SERVER</literal></entry>
 548         <entry align="center"><literal>X</literal></entry>
 549         <entry align="center"><literal>X</literal></entry>
 550         <entry align="center"><literal>X</literal></entry>
 551        </row>
 552        <row>
 553         <entry align="left"><literal>DROP TABLE</literal></entry>
 554         <entry align="center"><literal>X</literal></entry>
 555         <entry align="center"><literal>X</literal></entry>
 556         <entry align="center"><literal>X</literal></entry>
 557        </row>
 558        <row>
 559         <entry align="left"><literal>DROP TEXT SEARCH CONFIGURATION</literal></entry>
 560         <entry align="center"><literal>X</literal></entry>
 561         <entry align="center"><literal>X</literal></entry>
 562         <entry align="center"><literal>X</literal></entry>
 563        </row>
 564        <row>
 565         <entry align="left"><literal>DROP TEXT SEARCH DICTIONARY</literal></entry>
 566         <entry align="center"><literal>X</literal></entry>
 567         <entry align="center"><literal>X</literal></entry>
 568         <entry align="center"><literal>X</literal></entry>
 569        </row>
 570        <row>
 571         <entry align="left"><literal>DROP TEXT SEARCH PARSER</literal></entry>
 572         <entry align="center"><literal>X</literal></entry>
 573         <entry align="center"><literal>X</literal></entry>
 574         <entry align="center"><literal>X</literal></entry>
 575        </row>
 576        <row>
 577         <entry align="left"><literal>DROP TEXT SEARCH TEMPLATE</literal></entry>
 578         <entry align="center"><literal>X</literal></entry>
 579         <entry align="center"><literal>X</literal></entry>
 580         <entry align="center"><literal>X</literal></entry>
 581        </row>
 582        <row>
 583         <entry align="left"><literal>DROP TRIGGER</literal></entry>
 584         <entry align="center"><literal>X</literal></entry>
 585         <entry align="center"><literal>X</literal></entry>
 586         <entry align="center"><literal>X</literal></entry>
 587        </row>
 588        <row>
 589         <entry align="left"><literal>DROP TYPE</literal></entry>
 590         <entry align="center"><literal>X</literal></entry>
 591         <entry align="center"><literal>X</literal></entry>
 592         <entry align="center"><literal>X</literal></entry>
 593        </row>
 594        <row>
 595         <entry align="left"><literal>DROP USER MAPPING</literal></entry>
 596         <entry align="center"><literal>X</literal></entry>
 597         <entry align="center"><literal>X</literal></entry>
 598         <entry align="center"><literal>X</literal></entry>
 599        </row>
 600        <row>
 601         <entry align="left"><literal>DROP VIEW</literal></entry>
 602         <entry align="center"><literal>X</literal></entry>
 603         <entry align="center"><literal>X</literal></entry>
 604         <entry align="center"><literal>X</literal></entry>
 605        </row>
 606        <row>
 607         <entry align="left"><literal>IMPORT FOREIGN SCHEMA</literal></entry>
 608         <entry align="center"><literal>X</literal></entry>
 609         <entry align="center"><literal>X</literal></entry>
 610         <entry align="center"><literal>-</literal></entry>
 611        </row>
 612        <row>
 613         <entry align="left"><literal>SELECT INTO</literal></entry>
 614         <entry align="center"><literal>X</literal></entry>
 615         <entry align="center"><literal>X</literal></entry>
 616         <entry align="center"><literal>-</literal></entry>
 617        </row>
 618       </tbody>
 619      </tgroup>
 620    </table>
 621   </sect1>
 622
 623   <sect1 id="event-trigger-interface">
 624    <title>Writing Event Trigger Functions in C</title>
 625
 626    <indexterm zone="event-trigger-interface">
 627     <primary>event trigger</primary>
 628     <secondary>in C</secondary>
 629    </indexterm>
 630
 631    <para>
 632     This section describes the low-level details of the interface to an
 633     event trigger function. This information is only needed when writing
 634     event trigger functions in C. If you are using a higher-level language
 635     then these details are handled for you. In most cases you should
 636     consider using a procedural language before writing your event triggers
 637     in C. The documentation of each procedural language explains how to
 638     write an event trigger in that language.
 639    </para>
 640
 641    <para>
 642     Event trigger functions must use the <quote>version 1</> function
 643     manager interface.
 644    </para>
 645
 646    <para>
 647     When a function is called by the event trigger manager, it is not passed
 648     any normal arguments, but it is passed a <quote>context</> pointer
 649     pointing to a <structname>EventTriggerData</> structure. C functions can
 650     check whether they were called from the event trigger manager or not by
 651     executing the macro:
 652 <programlisting>
 653 CALLED_AS_EVENT_TRIGGER(fcinfo)
 654 </programlisting>
 655     which expands to:
 656 <programlisting>
 657 ((fcinfo)-&gt;context != NULL &amp;&amp; IsA((fcinfo)-&gt;context, EventTriggerData))
 658 </programlisting>
 659     If this returns true, then it is safe to cast
 660     <literal>fcinfo-&gt;context</> to type <literal>EventTriggerData
 661     *</literal> and make use of the pointed-to
 662     <structname>EventTriggerData</> structure.  The function must
 663     <emphasis>not</emphasis> alter the <structname>EventTriggerData</>
 664     structure or any of the data it points to.
 665    </para>
 666
 667    <para>
 668     <structname>struct EventTriggerData</structname> is defined in
 669     <filename>commands/event_trigger.h</filename>:
 670
 671 <programlisting>
 672 typedef struct EventTriggerData
 673 {
 674     NodeTag     type;
 675     const char *event;      /* event name */
 676     Node       *parsetree;  /* parse tree */
 677     const char *tag;        /* command tag */
 678 } EventTriggerData;
 679 </programlisting>
 680
 681     where the members are defined as follows:
 682
 683     <variablelist>
 684      <varlistentry>
 685       <term><structfield>type</></term>
 686       <listitem>
 687        <para>
 688         Always <literal>T_EventTriggerData</literal>.
 689        </para>
 690       </listitem>
 691      </varlistentry>
 692
 693      <varlistentry>
 694       <term><structfield>event</></term>
 695       <listitem>
 696        <para>
 697         Describes the event for which the function is called, one of
 698         <literal>"ddl_command_start"</literal>, <literal>"ddl_command_end"</literal>,
 699         <literal>"sql_drop"</literal>.
 700         See <xref linkend="event-trigger-definition"> for the meaning of these
 701         events.
 702        </para>
 703       </listitem>
 704      </varlistentry>
 705
 706      <varlistentry>
 707       <term><structfield>parsetree</></term>
 708       <listitem>
 709        <para>
 710         A pointer to the parse tree of the command.  Check the PostgreSQL
 711         source code for details.  The parse tree structure is subject to change
 712         without notice.
 713        </para>
 714       </listitem>
 715      </varlistentry>
 716
 717      <varlistentry>
 718       <term><structfield>tag</></term>
 719       <listitem>
 720        <para>
 721         The command tag associated with the event for which the event trigger
 722         is run, for example <literal>"CREATE FUNCTION"</literal>.
 723        </para>
 724       </listitem>
 725      </varlistentry>
 726     </variablelist>
 727    </para>
 728
 729    <para>
 730     An event trigger function must return a <symbol>NULL</> pointer
 731     (<emphasis>not</> an SQL null value, that is, do not
 732     set <parameter>isNull</parameter> true).
 733    </para>
 734   </sect1>
 735
 736   <sect1 id="event-trigger-example">
 737    <title>A Complete Event Trigger Example</title>
 738
 739    <para>
 740     Here is a very simple example of an event trigger function written in C.
 741     (Examples of triggers written in procedural languages can be found in
 742     the documentation of the procedural languages.)
 743    </para>
 744
 745    <para>
 746     The function <function>noddl</> raises an exception each time it is called.
 747     The event trigger definition associated the function with
 748     the <literal>ddl_command_start</literal> event.  The effect is that all DDL
 749     commands (with the exceptions mentioned
 750     in <xref linkend="event-trigger-definition">) are prevented from running.
 751    </para>
 752
 753    <para>
 754     This is the source code of the trigger function:
 755 <programlisting><![CDATA[
 756 #include "postgres.h"
 757 #include "commands/event_trigger.h"
 758
 759
 760 PG_MODULE_MAGIC;
 761
 762 Datum noddl(PG_FUNCTION_ARGS);
 763
 764 PG_FUNCTION_INFO_V1(noddl);
 765
 766 Datum
 767 noddl(PG_FUNCTION_ARGS)
 768 {
 769     EventTriggerData *trigdata;
 770
 771     if (!CALLED_AS_EVENT_TRIGGER(fcinfo))  /* internal error */
 772         elog(ERROR, "not fired by event trigger manager");
 773
 774     trigdata = (EventTriggerData *) fcinfo->context;
 775
 776     ereport(ERROR,
 777         (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
 778                  errmsg("command \"%s\" denied", trigdata->tag)));
 779
 780     PG_RETURN_NULL();
 781 }
 782 ]]></programlisting>
 783    </para>
 784
 785    <para>
 786     After you have compiled the source code (see <xref linkend="dfunc">),
 787     declare the function and the triggers:
 788 <programlisting>
 789 CREATE FUNCTION noddl() RETURNS event_trigger
 790     AS 'noddl' LANGUAGE C;
 791
 792 CREATE EVENT TRIGGER noddl ON ddl_command_start
 793     EXECUTE PROCEDURE noddl();
 794 </programlisting>
 795    </para>
 796
 797    <para>
 798     Now you can test the operation of the trigger:
 799 <screen>
 800 =# \dy
 801                      List of event triggers
 802  Name  |       Event       | Owner | Enabled | Procedure | Tags
 803 -------+-------------------+-------+---------+-----------+------
 804  noddl | ddl_command_start | dim   | enabled | noddl     |
 805 (1 row)
 806
 807 =# CREATE TABLE foo(id serial);
 808 ERROR:  command "CREATE TABLE" denied
 809 </screen>
 810    </para>
 811
 812    <para>
 813     In this situation, in order to be able to run some DDL commands when you
 814     need to do so, you have to either drop the event trigger or disable it.  It
 815     can be convenient to disable the trigger for only the duration of a
 816     transaction:
 817 <programlisting>
 818 BEGIN;
 819 ALTER EVENT TRIGGER noddl DISABLE;
 820 CREATE TABLE foo (id serial);
 821 ALTER EVENT TRIGGER noddl ENABLE;
 822 COMMIT;
 823 </programlisting>
 824     (Recall that DDL commands on event triggers themselves are not affected by
 825     event triggers.)
 826    </para>
 827   </sect1>
 828 </chapter>