create_event_trigger.sgml 4.95 KB
Newer Older
1 2 3 4 5
<!--
doc/src/sgml/ref/create_event_trigger.sgml
PostgreSQL documentation
-->

6
<refentry id="sql-createeventtrigger">
7 8 9 10
 <indexterm zone="sql-createeventtrigger">
  <primary>CREATE EVENT TRIGGER</primary>
 </indexterm>

11 12 13 14 15 16 17 18 19 20 21 22 23
 <refmeta>
  <refentrytitle>CREATE EVENT TRIGGER</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE EVENT TRIGGER</refname>
  <refpurpose>define a new event trigger</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
24 25
CREATE EVENT TRIGGER <replaceable class="parameter">name</replaceable>
    ON <replaceable class="parameter">event</replaceable>
26
    [ WHEN <replaceable class="parameter">filter_variable</replaceable> IN (<replaceable class="parameter">filter_value</replaceable> [, ... ]) [ AND ... ] ]
27
    EXECUTE { FUNCTION | PROCEDURE } <replaceable class="parameter">function_name</replaceable>()
28 29 30 31 32 33 34 35
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>CREATE EVENT TRIGGER</command> creates a new event trigger.
36
   Whenever the designated event occurs and the <literal>WHEN</literal> condition
37 38
   associated with the trigger, if any, is satisfied, the trigger function
   will be executed.  For a general introduction to event triggers, see
39
   <xref linkend="event-triggers"/>.  The user who creates an event trigger
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
   becomes its owner.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="parameter">name</replaceable></term>
    <listitem>
     <para>
      The name to give the new trigger.  This name must be unique within
      the database.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">event</replaceable></term>
    <listitem>
     <para>
      The name of the event that triggers a call to the given function.
63
      See <xref linkend="event-trigger-definition"/> for more information
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
      on event names.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">filter_variable</replaceable></term>
    <listitem>
     <para>
      The name of a variable used to filter events.  This makes it possible
      to restrict the firing of the trigger to a subset of the cases in which
      it is supported.  Currently the only supported
      <replaceable class="parameter">filter_variable</replaceable>
      is <literal>TAG</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">filter_value</replaceable></term>
    <listitem>
     <para>
      A list of values for the
      associated <replaceable class="parameter">filter_variable</replaceable>
88
      for which the trigger should fire.  For <literal>TAG</literal>, this means a
89
      list of command tags (e.g., <literal>'DROP FUNCTION'</literal>).
90 91 92 93 94 95 96 97 98 99 100
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">function_name</replaceable></term>
    <listitem>
     <para>
      A user-supplied function that is declared as taking no argument and
      returning type <literal>event_trigger</literal>.
     </para>
101 102 103 104 105 106 107 108

     <para>
      In the syntax of <literal>CREATE EVENT TRIGGER</literal>, the keywords
      <literal>FUNCTION</literal> and <literal>PROCEDURE</literal> are
      equivalent, but the referenced function must in any case be a function,
      not a procedure.  The use of the keyword <literal>PROCEDURE</literal>
      here is historical and deprecated.
     </para>
109 110 111 112 113 114 115 116 117 118
    </listitem>
   </varlistentry>

  </variablelist>
 </refsect1>

 <refsect1 id="sql-createeventtrigger-notes">
  <title>Notes</title>

  <para>
119 120 121 122 123
   Only superusers can create event triggers.
  </para>

  <para>
   Event triggers are disabled in single-user mode (see <xref
124
   linkend="app-postgres"/>).  If an erroneous event trigger disables the
125 126
   database so much that you can't even drop the trigger, restart in
   single-user mode and you'll be able to do that.
127 128 129 130 131 132 133
  </para>
 </refsect1>

 <refsect1 id="sql-createeventtrigger-examples">
  <title>Examples</title>

  <para>
134
   Forbid the execution of any <link linkend="ddl">DDL</link> command:
135 136 137 138 139 140 141 142 143 144 145 146

<programlisting>
CREATE OR REPLACE FUNCTION abort_any_command()
  RETURNS event_trigger
 LANGUAGE plpgsql
  AS $$
BEGIN
  RAISE EXCEPTION 'command % is disabled', tg_tag;
END;
$$;

CREATE EVENT TRIGGER abort_ddl ON ddl_command_start
147
   EXECUTE FUNCTION abort_any_command();
148
</programlisting></para>
149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
 </refsect1>

 <refsect1 id="sql-createeventtrigger-compatibility">
  <title>Compatibility</title>

  <para>
   There is no <command>CREATE EVENT TRIGGER</command> statement in the
   SQL standard.
  </para>

 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
165 166 167
   <member><xref linkend="sql-altereventtrigger"/></member>
   <member><xref linkend="sql-dropeventtrigger"/></member>
   <member><xref linkend="sql-createfunction"/></member>
168 169 170
  </simplelist>
 </refsect1>
</refentry>