begriffs open source - ai-pg/blob - full-docs/txt/event-trigger-definition.txt

   1
   2 38.1. Overview of Event Trigger Behavior #
   3
   4    38.1.1. login
   5    38.1.2. ddl_command_start
   6    38.1.3. ddl_command_end
   7    38.1.4. sql_drop
   8    38.1.5. table_rewrite
   9    38.1.6. Event Triggers in Aborted Transactions
  10    38.1.7. Creating Event Triggers
  11
  12    An event trigger fires whenever the event with which it is associated
  13    occurs in the database in which it is defined. Currently, the supported
  14    events are login, ddl_command_start, ddl_command_end, table_rewrite and
  15    sql_drop. Support for additional events may be added in future
  16    releases.
  17
  18 38.1.1. login #
  19
  20    The login event occurs when an authenticated user logs into the system.
  21    Any bug in a trigger procedure for this event may prevent successful
  22    login to the system. Such bugs may be worked around by setting
  23    event_triggers to false either in a connection string or configuration
  24    file. Alternatively, you can restart the system in single-user mode (as
  25    event triggers are disabled in this mode). See the postgres reference
  26    page for details about using single-user mode. The login event will
  27    also fire on standby servers. To prevent servers from becoming
  28    inaccessible, such triggers must avoid writing anything to the database
  29    when running on a standby. Also, it's recommended to avoid long-running
  30    queries in login event triggers. Note that, for instance, canceling a
  31    connection in psql will not cancel the in-progress login trigger.
  32
  33    For an example on how to use the login event trigger, see Section 38.5.
  34
  35 38.1.2. ddl_command_start #
  36
  37    The ddl_command_start event occurs just before the execution of a DDL
  38    command. DDL commands in this context are:
  39      * CREATE
  40      * ALTER
  41      * DROP
  42      * COMMENT
  43      * GRANT
  44      * IMPORT FOREIGN SCHEMA
  45      * REINDEX
  46      * REFRESH MATERIALIZED VIEW
  47      * REVOKE
  48      * SECURITY LABEL
  49
  50    ddl_command_start also occurs just before the execution of a SELECT
  51    INTO command, since this is equivalent to CREATE TABLE AS.
  52
  53    As an exception, this event does not occur for DDL commands targeting
  54    shared objects:
  55      * databases
  56      * roles (role definitions and role memberships)
  57      * tablespaces
  58      * parameter privileges
  59      * ALTER SYSTEM
  60
  61    This event also does not occur for commands targeting event triggers
  62    themselves.
  63
  64    No check whether the affected object exists or doesn't exist is
  65    performed before the event trigger fires.
  66
  67 38.1.3. ddl_command_end #
  68
  69    The ddl_command_end event occurs just after the execution of the same
  70    set of commands as ddl_command_start. To obtain more details on the DDL
  71    operations that took place, use the set-returning function
  72    pg_event_trigger_ddl_commands() from the ddl_command_end event trigger
  73    code (see Section 9.30). Note that the trigger fires after the actions
  74    have taken place (but before the transaction commits), and thus the
  75    system catalogs can be read as already changed.
  76
  77 38.1.4. sql_drop #
  78
  79    The sql_drop event occurs just before the ddl_command_end event trigger
  80    for any operation that drops database objects. Note that besides the
  81    obvious DROP commands, some ALTER commands can also trigger an sql_drop
  82    event.
  83
  84    To list the objects that have been dropped, use the set-returning
  85    function pg_event_trigger_dropped_objects() from the sql_drop event
  86    trigger code (see Section 9.30). Note that the trigger is executed
  87    after the objects have been deleted from the system catalogs, so it's
  88    not possible to look them up anymore.
  89
  90 38.1.5. table_rewrite #
  91
  92    The table_rewrite event occurs just before a table is rewritten by some
  93    actions of the commands ALTER TABLE and ALTER TYPE. While other control
  94    statements are available to rewrite a table, like CLUSTER and VACUUM,
  95    the table_rewrite event is not triggered by them. To find the OID of
  96    the table that was rewritten, use the function
  97    pg_event_trigger_table_rewrite_oid(), to discover the reason(s) for the
  98    rewrite, use the function pg_event_trigger_table_rewrite_reason() (see
  99    Section 9.30).
 100
 101 38.1.6. Event Triggers in Aborted Transactions #
 102
 103    Event triggers (like other functions) cannot be executed in an aborted
 104    transaction. Thus, if a DDL command fails with an error, any associated
 105    ddl_command_end triggers will not be executed. Conversely, if a
 106    ddl_command_start trigger fails with an error, no further event
 107    triggers will fire, and no attempt will be made to execute the command
 108    itself. Similarly, if a ddl_command_end trigger fails with an error,
 109    the effects of the DDL statement will be rolled back, just as they
 110    would be in any other case where the containing transaction aborts.
 111
 112 38.1.7. Creating Event Triggers #
 113
 114    Event triggers are created using the command CREATE EVENT TRIGGER. In
 115    order to create an event trigger, you must first create a function with
 116    the special return type event_trigger. This function need not (and may
 117    not) return a value; the return type serves merely as a signal that the
 118    function is to be invoked as an event trigger.
 119
 120    If more than one event trigger is defined for a particular event, they
 121    will fire in alphabetical order by trigger name.
 122
 123    A trigger definition can also specify a WHEN condition so that, for
 124    example, a ddl_command_start trigger can be fired only for particular
 125    commands which the user wishes to intercept. A common use of such
 126    triggers is to restrict the range of DDL operations which users may
 127    perform.