mirror of
https://github.com/postgres/postgres.git
synced 2025-12-22 17:42:17 +03:00
Syntax support and documentation for event triggers.
They don't actually do anything yet; that will get fixed in a follow-on commit. But this gets the basic infrastructure in place, including CREATE/ALTER/DROP EVENT TRIGGER; support for COMMENT, SECURITY LABEL, and ALTER EXTENSION .. ADD/DROP EVENT TRIGGER; pg_dump and psql support; and documentation for the anticipated initial feature set. Dimitri Fontaine, with review and a bunch of additional hacking by me. Thom Brown extensively reviewed earlier versions of this patch set, but there's not a whole lot of that code left in this commit, as it turns out.
This commit is contained in:
Robert Haas
@@ -12,6 +12,7 @@ Complete list of usable sgml source files in this directory.
|
||||
<!ENTITY alterDatabase SYSTEM "alter_database.sgml">
|
||||
<!ENTITY alterDefaultPrivileges SYSTEM "alter_default_privileges.sgml">
|
||||
<!ENTITY alterDomain SYSTEM "alter_domain.sgml">
|
||||
<!ENTITY alterEventTrigger SYSTEM "alter_event_trigger.sgml">
|
||||
<!ENTITY alterExtension SYSTEM "alter_extension.sgml">
|
||||
<!ENTITY alterForeignDataWrapper SYSTEM "alter_foreign_data_wrapper.sgml">
|
||||
<!ENTITY alterForeignTable SYSTEM "alter_foreign_table.sgml">
|
||||
@@ -53,6 +54,7 @@ Complete list of usable sgml source files in this directory.
|
||||
<!ENTITY createConversion SYSTEM "create_conversion.sgml">
|
||||
<!ENTITY createDatabase SYSTEM "create_database.sgml">
|
||||
<!ENTITY createDomain SYSTEM "create_domain.sgml">
|
||||
<!ENTITY createEventTrigger SYSTEM "create_event_trigger.sgml">
|
||||
<!ENTITY createExtension SYSTEM "create_extension.sgml">
|
||||
<!ENTITY createForeignDataWrapper SYSTEM "create_foreign_data_wrapper.sgml">
|
||||
<!ENTITY createForeignTable SYSTEM "create_foreign_table.sgml">
|
||||
@@ -91,6 +93,7 @@ Complete list of usable sgml source files in this directory.
|
||||
<!ENTITY dropConversion SYSTEM "drop_conversion.sgml">
|
||||
<!ENTITY dropDatabase SYSTEM "drop_database.sgml">
|
||||
<!ENTITY dropDomain SYSTEM "drop_domain.sgml">
|
||||
<!ENTITY dropEventTrigger SYSTEM "drop_event_trigger.sgml">
|
||||
<!ENTITY dropExtension SYSTEM "drop_extension.sgml">
|
||||
<!ENTITY dropForeignDataWrapper SYSTEM "drop_foreign_data_wrapper.sgml">
|
||||
<!ENTITY dropForeignTable SYSTEM "drop_foreign_table.sgml">
|
||||
|
||||
105
doc/src/sgml/ref/alter_event_trigger.sgml
Normal file
105
doc/src/sgml/ref/alter_event_trigger.sgml
Normal file
@@ -0,0 +1,105 @@
|
||||
<!--
|
||||
doc/src/sgml/ref/alter_event_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 an event trigger</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<indexterm zone="sql-altereventtrigger">
|
||||
<primary>ALTER EVENT TRIGGER</primary>
|
||||
</indexterm>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<synopsis>
|
||||
ALTER EVENT TRIGGER <replaceable class="PARAMETER">name</replaceable> DISABLE
|
||||
ALTER EVENT TRIGGER <replaceable class="PARAMETER">name</replaceable> ENABLE [ REPLICA | ALWAYS ]
|
||||
ALTER EVENT TRIGGER <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceable class="PARAMETER">new_owner</replaceable>
|
||||
ALTER EVENT TRIGGER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable class="PARAMETER">new_name</replaceable>
|
||||
</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 an 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">new_owner</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The user name of the new owner of the event trigger.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><replaceable class="PARAMETER">new_name</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The new name of the event trigger.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>DISABLE</literal>/<literal>ENABLE [ REPLICA | ALWAYS ] TRIGGER</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
These forms configure the firing of event triggers. A disabled trigger
|
||||
is still known to the system, but is not executed when its triggering
|
||||
event occurs. See also <xref linkend="guc-session-replication-role">.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="sql-alterventtrigger-compatibility">
|
||||
<title>Compatibility</title>
|
||||
|
||||
<para>
|
||||
There is no <command>ALTER EVENT TRIGGER</command> statement in 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>
|
||||
@@ -35,6 +35,7 @@ ALTER EXTENSION <replaceable class="PARAMETER">name</replaceable> DROP <replacea
|
||||
COLLATION <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
CONVERSION <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
DOMAIN <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
EVENT TRIGGER <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
FOREIGN DATA WRAPPER <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) |
|
||||
|
||||
@@ -32,6 +32,7 @@ COMMENT ON
|
||||
DATABASE <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
DOMAIN <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
EXTENSION <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
EVENT TRIGGER <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
FOREIGN DATA WRAPPER <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) |
|
||||
|
||||
162
doc/src/sgml/ref/create_event_trigger.sgml
Normal file
162
doc/src/sgml/ref/create_event_trigger.sgml
Normal file
@@ -0,0 +1,162 @@
|
||||
<!--
|
||||
doc/src/sgml/ref/create_event_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 event trigger</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<indexterm zone="sql-createeventtrigger">
|
||||
<primary>CREATE EVENT TRIGGER</primary>
|
||||
</indexterm>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<synopsis>
|
||||
CREATE EVENT TRIGGER <replaceable class="PARAMETER">name</replaceable>
|
||||
ON <replaceable class="PARAMETER">event</replaceable>
|
||||
[ WHEN <replaceable class="PARAMETER">filter_variable</replaceable> IN (filter_value [ AND ... ] ) ]
|
||||
EXECUTE PROCEDURE <replaceable class="PARAMETER">function_name</replaceable>()
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>CREATE EVENT TRIGGER</command> creates a new event trigger.
|
||||
Whenever the designated event occurs and the <literal>WHEN</> condition
|
||||
associated with the trigger, if any, is satisfied, the trigger function
|
||||
will be executed. For a general introduction to event triggers, see
|
||||
<xref linkend="event-triggers">. The user who creates an event trigger
|
||||
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.
|
||||
See <xref linkend="event-trigger-definition"> for more information
|
||||
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>
|
||||
for which the trigger should fire. For <literal>TAG</>, this means a
|
||||
list of command tags (e.g. <literal>'DROP FUNCTION'</>).
|
||||
</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>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="sql-createeventtrigger-examples">
|
||||
<title>Examples</title>
|
||||
|
||||
<para>
|
||||
Forbid the execution of any <link linkend="ddl">ddl</link> 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 ON ddl_command_start
|
||||
EXECUTE PROCEDURE abort_any_command();
|
||||
</programlisting>
|
||||
</para>
|
||||
</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">
|
||||
<member><xref linkend="sql-createfunction"></member>
|
||||
<member><xref linkend="sql-altereventtrigger"></member>
|
||||
<member><xref linkend="sql-dropeventtrigger"></member>
|
||||
</simplelist>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
113
doc/src/sgml/ref/drop_event_trigger.sgml
Normal file
113
doc/src/sgml/ref/drop_event_trigger.sgml
Normal file
@@ -0,0 +1,113 @@
|
||||
<!--
|
||||
doc/src/sgml/ref/drop_event_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 an 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 event trigger.
|
||||
To execute this command, the current user must be the owner of the event
|
||||
trigger.
|
||||
</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>
|
||||
There is no <command>DROP EVENT TRIGGER</command> statement in the
|
||||
SQL standard.
|
||||
</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>
|
||||
@@ -1455,6 +1455,20 @@ testdb=>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>\dy[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Lists event triggers.
|
||||
If <replaceable class="parameter">pattern</replaceable>
|
||||
is specified, only those event triggers whose names match the pattern
|
||||
are listed.
|
||||
If <literal>+</literal> is appended to the command name, each object
|
||||
is listed with its associated description.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>\e</literal> or <literal>\edit</> <literal> <optional> <replaceable class="parameter">filename</> </optional> <optional> <replaceable class="parameter">line_number</> </optional> </literal></term>
|
||||
|
||||
|
||||
@@ -28,6 +28,7 @@ SECURITY LABEL [ FOR <replaceable class="PARAMETER">provider</replaceable> ] ON
|
||||
AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> (<replaceable class="PARAMETER">agg_type</replaceable> [, ...] ) |
|
||||
DATABASE <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
DOMAIN <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
EVENT TRIGGER <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable>
|
||||
FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) |
|
||||
LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> |
|
||||
|
||||
Reference in New Issue
Block a user