Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Add reference documentation for new Event Triggers commands (somehow …

…missed'em).
  • Loading branch information...
commit 25eac1a3edbc77fdeb3ab8051668597a6092ad5f 1 parent 5c71e38
@dimitri authored
View
103 doc/src/sgml/ref/alter_event_trigger.sgml
@@ -0,0 +1,103 @@
+<!--
+doc/src/sgml/ref/alter_trigger.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="SQL-ALTEREVENTTRIGGER">
+ <refmeta>
+ <refentrytitle>ALTER EVENT TRIGGER</refentrytitle>
+ <manvolnum>7</manvolnum>
+ <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>ALTER EVENT TRIGGER</refname>
+ <refpurpose>change the definition of a trigger</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="sql-altereventtrigger">
+ <primary>ALTER EVENT TRIGGER</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+<synopsis>
+ALTER EVENT TRIGGER <replaceable class="PARAMETER">name</replaceable> <replaceable class="parameter">enabled</replaceable>
+ALTER EVENT TRIGGER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable class="PARAMETER">newname</replaceable>
+
+<phrase>where <replaceable class="parameter">enabled</replaceable> can be one of:</phrase>
+
+ ENABLE
+ ENABLE ALWAYS
+ ENABLE REPLICA
+ DISABLE
+
+<phrase>and where <replaceable class="parameter">command</replaceable> can be one of the same list as in <xref linkend="sql-createeventtrigger">.</phrase>
+
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ <command>ALTER EVENT TRIGGER</command> changes properties of an
+ existing event trigger.
+ </para>
+
+ <para>
+ You must be superuser to alter a event trigger.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Parameters</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><replaceable class="PARAMETER">name</replaceable></term>
+ <listitem>
+ <para>
+ The name of an existing trigger to alter.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="PARAMETER">newname</replaceable></term>
+ <listitem>
+ <para>
+ The new name of the event trigger.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="PARAMETER">enabled</replaceable></term>
+ <listitem>
+ <para>
+ When to enable this trigger. See
+ the <literal>session_replication_role</literal> parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Compatibility</title>
+
+ <para>
+ <command>ALTER EVENT TRIGGER</command> is a <productname>PostgreSQL</>
+ extension of the SQL standard.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-createeventtrigger"></member>
+ <member><xref linkend="sql-dropeventtrigger"></member>
+ </simplelist>
+ </refsect1>
+</refentry>
View
321 doc/src/sgml/ref/create_event_trigger.sgml
@@ -0,0 +1,321 @@
+<!--
+doc/src/sgml/ref/create_trigger.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="SQL-CREATEEVENTTRIGGER">
+ <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 trigger</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="sql-createeventtrigger">
+ <primary>CREATE EVENT TRIGGER</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+<synopsis>
+CREATE EVENT TRIGGER <replaceable class="PARAMETER">name</replaceable>
+ { BEFORE | INSTEAD OF } <replaceable class="PARAMETER">event</replaceable>
+ [ WHEN <replaceable class="PARAMETER">variable</replaceable> IN (tag [, tag [, ...] ] ) ]
+ EXECUTE PROCEDURE <replaceable class="PARAMETER">function_name</replaceable> ()
+
+<phrase>where <replaceable class="parameter">event</replaceable> can be one of:</phrase>
+
+ command_start
+
+<phrase>where <replaceable class="parameter">tag</replaceable> can be one of:</phrase>
+
+ ALTER AGGREGATE
+ ALTER COLLATION
+ ALTER CONVERSION
+ ALTER DOMAIN
+ ALTER EXTENSION
+ ALTER FOREIGN DATA WRAPPER
+ ALTER FOREIGN TABLE
+ ALTER FUNCTION
+ ALTER LANGUAGE
+ ALTER OPERATOR
+ ALTER OPERATOR CLASS
+ ALTER OPERATOR FAMILY
+ ALTER SCHEMA
+ ALTER SEQUENCE
+ ALTER SERVER
+ ALTER TABLE
+ ALTER TEXT SEARCH CONFIGURATION
+ ALTER TEXT SEARCH DICTIONARY
+ ALTER TEXT SEARCH PARSER
+ ALTER TEXT SEARCH TEMPLATE
+ ALTER TRIGGER
+ ALTER TYPE
+ ALTER USER MAPPING
+ ALTER VIEW
+ CLUSTER
+ CREATE AGGREGATE
+ CREATE CAST
+ CREATE COLLATION
+ CREATE CONVERSION
+ CREATE DOMAIN
+ CREATE EXTENSION
+ CREATE FOREIGN DATA WRAPPER
+ CREATE FOREIGN TABLE
+ CREATE FUNCTION
+ CREATE INDEX
+ CREATE LANGUAGE
+ CREATE OPERATOR
+ CREATE OPERATOR CLASS
+ CREATE OPERATOR FAMILY
+ CREATE RULE
+ CREATE SCHEMA
+ CREATE SEQUENCE
+ CREATE SERVER
+ CREATE TABLE
+ CREATE TABLE AS
+ CREATE TEXT SEARCH CONFIGURATION
+ CREATE TEXT SEARCH DICTIONARY
+ CREATE TEXT SEARCH PARSER
+ CREATE TEXT SEARCH TEMPLATE
+ CREATE TRIGGER
+ CREATE TYPE
+ CREATE USER MAPPING
+ CREATE VIEW
+ DROP AGGREGATE
+ DROP CAST
+ DROP COLLATION
+ DROP CONVERSION
+ DROP DOMAIN
+ DROP EXTENSION
+ DROP FOREIGN DATA WRAPPER
+ DROP FOREIGN TABLE
+ DROP FUNCTION
+ DROP INDEX
+ DROP LANGUAGE
+ DROP OPERATOR
+ DROP OPERATOR CLASS
+ DROP OPERATOR FAMILY
+ DROP RULE
+ DROP SCHEMA
+ DROP SEQUENCE
+ DROP SERVER
+ DROP TABLE
+ DROP TEXT SEARCH CONFIGURATION
+ DROP TEXT SEARCH DICTIONARY
+ DROP TEXT SEARCH PARSER
+ DROP TEXT SEARCH TEMPLATE
+ DROP TRIGGER
+ DROP TYPE
+ DROP USER MAPPING
+ DROP VIEW
+ LOAD
+ REINDEX
+ SELECT INTO
+ VACUUM
+
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ <command>CREATE EVENT TRIGGER</command> creates a new event trigger.
+ The trigger will be associated with the specified event and will
+ execute the specified
+ function <replaceable class="parameter">function_name</replaceable> when
+ that event is run.
+ </para>
+
+ <para>
+ The command trigger gives a procedure to fire before the event is
+ executed. In some cases the procedure can be fired instead of the event
+ code PostgreSQL would run itself. A command trigger's function must
+ return <literal>event_trigger</literal> data type. It can then only
+ abort the execution of the command by raising an exception.
+ </para>
+
+ <para>
+ If multiple triggers of the same kind are defined for the same event,
+ they will be fired in alphabetical order by name.
+ </para>
+
+ <para>
+ Note that objects dropped by the effect of <literal>DROP
+ CASCADE</literal> will not result in a event trigger firing, only the
+ top-level event for the main object will fire a event trigger. That
+ also applies to other dependencies following, as in <literal>DROP OWNED
+ BY</literal>.
+ </para>
+
+ <para>
+ Refer to <xref linkend="triggers"> for more information about triggers.
+ </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 must be distinct from the name
+ of any other trigger for the same table. The name cannot be
+ schema-qualified.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="parameter">tag</replaceable></term>
+ <listitem>
+ <para>
+ The tag of the command the trigger is for. Supported commands are
+ mainly those acting on database objects, plus some more facilities.
+ That leaves out the following list of non supported commands.
+ </para>
+ <para>
+ Commands that refer to global objects, such as databases, tablespaces
+ and roles, are not supported.
+ </para>
+ <para>
+ Commands that exercise their own transaction control are only
+ supported in <literal>BEFORE</literal> command triggers. This is the
+ case for <literal>VACUUM</literal>, <literal>CLUSTER</literal>,
+ <literal>CREATE INDEX CONCURRENTLY</literal>, and <literal>REINDEX
+ DATABASE</literal>.
+ </para>
+ <para>
+ The command <literal>ALTER TYPE ... ADD VALUE ...</literal> prevents
+ transaction control entirely, thus no command trigger will get fired
+ when it's used.
+ </para>
+ <para>
+ Commands that are related to transaction control (such
+ as <literal>BEGIN</literal> or <literal>COMMIT</literal>), related to
+ prepared plans
+ (e.g. <literal>PREPARE</literal>, <literal>DEALLOCATE</literal>),
+ cursors management
+ (e.g. <literal>DECLARE</literal>, <literal>FETCH</literal>), setting
+ variables (<literal>SET</literal>), the <literal>LISTEN</literal>
+ feature, and security are not supported either.
+ </para>
+ <para>
+ Event triggers on <literal>CREATE EVENT
+ TRIGGER</literal>, <literal>ALTER EVENT TRIGGER</literal>
+ and <literal>DROP EVENT TRIGGER</literal> are not supported so as
+ not to be able to take over control from a superuser.
+ </para>
+ <para>
+ Triggers on <literal>ANY</literal> command support more commands than
+ just this list, and will only provide the <literal>command
+ tag</literal> argument as <literal>NOT NULL</literal>. Supporting more
+ commands is made so that you can actually block <xref linkend="ddl">
+ commands in one go.
+ </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>
+ <para>
+ If your event trigger is implemented in <literal>C</literal> then it
+ will be called with an argument, of
+ type <literal>internal</literal>, which is a pointer to
+ the <literal>Node *</literal> parse tree.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="SQL-CREATEEVENTTRIGGER-notes">
+ <title>Notes</title>
+
+ <para>
+ To create a trigger on a event, the user must be superuser.
+ </para>
+
+ <para>
+ Use <xref linkend="sql-dropeventtrigger"> to remove a event trigger.
+ </para>
+ </refsect1>
+
+ <refsect1 id="SQL-CREATEEVENTTRIGGER-examples">
+ <title>Examples</title>
+
+ <para>
+ Forbids the execution of any DDL command:
+
+<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
+ BEFORE command_start
+ EXECUTE PROCEDURE abort_any_command();
+</programlisting>
+
+ Execute the function <function>enforce_local_style</> each time
+ a <literal>CREATE TABLE</literal> command is run:
+
+<programlisting>
+CREATE OR REPLACE FUNCTION enforce_local_style()
+ RETURNS event_trigger
+ LANGUAGE plpgsql
+ AS $$
+BEGIN
+ IF substring(tg_objectname, 0, 4) NOT IN ('ab_', 'cz_', 'fr_')
+ THEN
+ RAISE EXCEPTION 'invalid relation name: %', tg_objectname;
+ END IF;
+END;
+$$;
+
+ CREATE EVENT TRIGGER check_style
+ BEFORE command_start
+ WHEN tag IN (CREATE TABLE)
+ EXECUTE PROCEDURE enforce_local_style();
+</programlisting>
+ </para>
+ </refsect1>
+
+ <refsect1 id="SQL-CREATEEVENTTRIGGER-compatibility">
+ <title>Compatibility</title>
+
+ <para>
+ <command>CREATE EVENT TRIGGER</command> is a
+ <productname>PostgreSQL</productname> extension of the <acronym>SQL</>
+ standard.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-createfunction"></member>
+ <member><xref linkend="sql-altereventtrigger"></member>
+ <member><xref linkend="sql-dropeventtrigger"></member>
+ </simplelist>
+ </refsect1>
+</refentry>
View
111 doc/src/sgml/ref/drop_event_trigger.sgml
@@ -0,0 +1,111 @@
+<!--
+doc/src/sgml/ref/drop_trigger.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="SQL-DROPEVENTTRIGGER">
+ <refmeta>
+ <refentrytitle>DROP EVENT TRIGGER</refentrytitle>
+ <manvolnum>7</manvolnum>
+ <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>DROP EVENT TRIGGER</refname>
+ <refpurpose>remove a event trigger</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="sql-dropeventtrigger">
+ <primary>DROP EVENT TRIGGER</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+<synopsis>
+DROP EVENT TRIGGER [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [ CASCADE | RESTRICT ]
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ <command>DROP EVENT TRIGGER</command> removes an existing trigger definition.
+ To execute this command, the current user must be superuser.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Parameters</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><literal>IF EXISTS</literal></term>
+ <listitem>
+ <para>
+ Do not throw an error if the event trigger does not exist. A notice
+ is issued in this case.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="PARAMETER">name</replaceable></term>
+ <listitem>
+ <para>
+ The name of the event trigger to remove.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>CASCADE</literal></term>
+ <listitem>
+ <para>
+ Automatically drop objects that depend on the trigger.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>RESTRICT</literal></term>
+ <listitem>
+ <para>
+ Refuse to drop the trigger if any objects depend on it. This is
+ the default.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="SQL-DROPEVENTTRIGGER-examples">
+ <title>Examples</title>
+
+ <para>
+ Destroy the trigger <literal>snitch</literal>:
+
+<programlisting>
+DROP EVENT TRIGGER snitch;
+</programlisting></para>
+ </refsect1>
+
+ <refsect1 id="SQL-DROPEVENTTRIGGER-compatibility">
+ <title>Compatibility</title>
+
+ <para>
+ The <command>DROP EVENT TRIGGER</command> statement is a
+ <productname>PostgreSQL</productname> extension.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-createeventtrigger"></member>
+ <member><xref linkend="sql-altereventtrigger"></member>
+ </simplelist>
+ </refsect1>
+
+</refentry>
Please sign in to comment.
Something went wrong with that request. Please try again.