<!-- doc/src/sgml/event-trigger.sgml -->

 <chapter id="event-triggers">
  <title>Event Triggers</title>

  <indexterm zone="event-triggers">
   <primary>event trigger</primary>
  </indexterm>

  <para>
   To supplement the trigger mechanism discussed in <xref linkend="triggers"/>,
   <productname>PostgreSQL</productname> also provides event triggers.  Unlike regular
   triggers, which are attached to a single table and capture only DML events,
   event triggers are global to a particular database and are capable of
   capturing DDL events.
  </para>

  <para>
   Like regular triggers, event triggers can be written in any procedural
   language that includes event trigger support, or in C, but not in plain
   SQL.
  </para>

  <sect1 id="event-trigger-definition">
   <title>Overview of Event Trigger Behavior</title>

   <para>
     An event trigger fires whenever the event with which it is associated
     occurs in the database in which it is defined. Currently, the
     supported events are
     <literal>login</literal>,
     <literal>ddl_command_start</literal>,
     <literal>ddl_command_end</literal>,
     <literal>table_rewrite</literal>
     and <literal>sql_drop</literal>.
     Support for additional events may be added in future releases.
   </para>

   <sect2 id="event-trigger-login">
    <title>login</title>

   <para>
     The <literal>login</literal> event occurs when an authenticated user logs
     into the system. Any bug in a trigger procedure for this event may
     prevent successful login to the system. Such bugs may be worked around by
     setting <xref linkend="guc-event-triggers"/> to <literal>false</literal>
     either in a connection string or configuration file. Alternatively, you can
     restart the system in single-user mode (as event triggers are
     disabled in this mode). See the <xref linkend="app-postgres"/> reference
     page for details about using single-user mode.
     The <literal>login</literal> event will also fire on standby servers.
     To prevent servers from becoming inaccessible, such triggers must avoid
     writing anything to the database when running on a standby.
     Also, it's recommended to avoid long-running queries in
     <literal>login</literal> event triggers.  Note that, for instance,
     canceling a connection in <application>psql</application> will not cancel
     the in-progress <literal>login</literal> trigger.
   </para>

   <para>
     For an example on how to use the <literal>login</literal> event trigger,
     see <xref linkend="event-trigger-database-login-example"/>.
   </para>
   </sect2>

   <sect2 id="event-trigger-ddl_command_start">
    <title>ddl_command_start</title>

   <para>
     The <literal>ddl_command_start</literal> event occurs just before the
     execution of a DDL command.  DDL commands in this context are:
     <itemizedlist>
      <listitem><para><literal>CREATE</literal></para></listitem>
      <listitem><para><literal>ALTER</literal></para></listitem>
      <listitem><para><literal>DROP</literal></para></listitem>
      <listitem><para><literal>COMMENT</literal></para></listitem>
      <listitem><para><literal>GRANT</literal></para></listitem>
      <listitem><para><literal>IMPORT FOREIGN SCHEMA</literal></para></listitem>
      <listitem><para><literal>REINDEX</literal></para></listitem>
      <listitem><para><literal>REFRESH MATERIALIZED VIEW</literal></para></listitem>
      <listitem><para><literal>REVOKE</literal></para></listitem>
      <listitem><para><literal>SECURITY LABEL</literal></para></listitem>
     </itemizedlist>
     <literal>ddl_command_start</literal> also occurs just before the
     execution of a <literal>SELECT INTO</literal> command, since this is
     equivalent to <literal>CREATE TABLE AS</literal>.
   </para>

   <para>
     As an exception, this event does not occur for DDL commands targeting
     shared objects:
     <itemizedlist>
      <listitem><para>databases</para></listitem>
      <listitem><para>roles