diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/catalogs.sgml | 87 | ||||
| -rw-r--r-- | doc/src/sgml/event-trigger.sgml | 415 | ||||
| -rw-r--r-- | doc/src/sgml/filelist.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/postgres.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/ref/allfiles.sgml | 3 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_event_trigger.sgml | 105 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_extension.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/ref/comment.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_event_trigger.sgml | 162 | ||||
| -rw-r--r-- | doc/src/sgml/ref/drop_event_trigger.sgml | 113 | ||||
| -rw-r--r-- | doc/src/sgml/ref/psql-ref.sgml | 14 | ||||
| -rw-r--r-- | doc/src/sgml/ref/security_label.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/reference.sgml | 3 |
13 files changed, 907 insertions, 0 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index fbd6d0d025d..b100a426e48 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -144,6 +144,11 @@ </row> <row> + <entry><link linkend="catalog-pg-event-trigger"><structname>pg_event_trigger</structname></link></entry> + <entry>event triggers</entry> + </row> + + <row> <entry><link linkend="catalog-pg-extension"><structname>pg_extension</structname></link></entry> <entry>installed extensions</entry> </row> @@ -1857,6 +1862,88 @@ </para> </sect1> + <sect1 id="catalog-pg-event-trigger"> + <title><structname>pg_event_trigger</structname></title> + + <indexterm zone="catalog-pg-event-trigger"> + <primary>pg_event_trigger</primary> + </indexterm> + + <para> + The catalog <structname>pg_event_trigger</structname> stores event triggers. + See <xref linkend="event-triggers"> for more information. + </para> + + <table> + <title><structname>pg_event_trigger</> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>evtname</structfield></entry> + <entry><type>name</type></entry> + <entry></entry> + <entry>Trigger name (must be unique)</entry> + </row> + + <row> + <entry><structfield>evtevent</structfield></entry> + <entry><type>name</type></entry> + <entry></entry> + <entry>Identifies the event for which this trigger fires</entry> + </row> + + <row> + <entry><structfield>evtowner</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry> + <entry>Owner of the event trigger</entry> + </row> + + <row> + <entry><structfield>evtfoid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> + <entry>The function to be called</entry> + </row> + + <row> + <entry><structfield>evtenabled</structfield></entry> + <entry><type>char</type></entry> + <entry></entry> + <entry> + Controls in which <xref linkend="guc-session-replication-role"> modes + the event trigger fires. + <literal>O</> = trigger fires in <quote>origin</> and <quote>local</> modes, + <literal>D</> = trigger is disabled, + <literal>R</> = trigger fires in <quote>replica</> mode, + <literal>A</> = trigger fires always. + </entry> + </row> + + <row> + <entry><structfield>evttags</structfield></entry> + <entry><type>text[]</type></entry> + <entry></entry> + <entry> + Command tags for which this trigger will fire. If NULL, the firing + of this trigger is not restricted on the basis of the command tag. + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="catalog-pg-constraint"> <title><structname>pg_constraint</structname></title> diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml new file mode 100644 index 00000000000..dc4e7614990 --- /dev/null +++ b/doc/src/sgml/event-trigger.sgml @@ -0,0 +1,415 @@ +<!-- 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</> 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 only + supported event is <literal>ddl_command_start</>. Support for + additional events may be added in future releases. + </para> + + <para> + The <literal>ddl_command_start</> event occurs just before the + execution of a <literal>CREATE</>, <literal>ALTER</>, or <literal>DROP</> + commmand. As an exception, however, this event does not occur for + DDL commands targeting shared objects - databases, roles, and tablespaces + - or for command targeting event triggers themselves. The event trigger + mechanism does not support these object types. + <literal>ddl_command_start</> 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> + For a complete list of commands supported by the event trigger mechanism, + see <xref linkend="event-trigger-matrix">. + </para> + + <para> + In order to create an event trigger, you must first create a function with + the special return type <literal>event_trigger</literal>. This function + need not (and may not) return a value; the return type serves merely as + a signal that the function is to be invoked as an event trigger. + </para> + + <para> + If more than one event trigger is defined for a particular event, they will + fire in alphabetical order by trigger name. + </para> + + <para> + A trigger definition can also specify a <literal>WHEN</literal> + condition so that, for example, a <literal>ddl_command_start</literal> + trigger can be fired only for particular commands which the user wishes + to intercept. A common use of such triggers is to restrict the range of + DDL operations which users may perform. + </para> + </sect1> + + <sect1 id="event-trigger-matrix"> + <title>Event Trigger Firing Matrix</title> + + <para> + <xref linkend="event-trigger-by-command-tag"> lists all commands + for which event triggers are supported. + </para> + + <table id="event-trigger-by-command-tag"> + <title>Event Trigger Support by Command Tag</title> + <tgroup cols="2"> + <thead> + <row> + <entry>command tag</entry> + <entry><literal>ddl_command_start</literal></entry> + </row> + </thead> + <tbody> + <row> + <entry align="left"><literal>ALTER AGGREGATE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER COLLATION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER CONVERSION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER DOMAIN</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER EXTENSION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER FOREIGN DATA WRAPPER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER FOREIGN TABLE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER FUNCTION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER LANGUAGE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER OPERATOR</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER OPERATOR CLASS</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER OPERATOR FAMILY</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER SCHEMA</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER SEQUENCE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER SERVER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER TABLE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER TEXT SEARCH CONFIGURATION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER TEXT SEARCH DICTIONARY</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER TEXT SEARCH PARSER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER TEXT SEARCH TEMPLATE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER TRIGGER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER TYPE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER USER MAPPING</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>ALTER VIEW</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE AGGREGATE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE CAST</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE COLLATION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE CONVERSION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE DOMAIN</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE EXTENSION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE FOREIGN DATA WRAPPER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE FOREIGN TABLE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE FUNCTION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE INDEX</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE LANGUAGE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE OPERATOR</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE OPERATOR CLASS</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE OPERATOR FAMILY</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE RULE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE SCHEMA</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE SEQUENCE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE SERVER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE TABLE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE TABLE AS</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE TEXT SEARCH CONFIGURATION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE TEXT SEARCH DICTIONARY</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE TEXT SEARCH PARSER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE TEXT SEARCH TEMPLATE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE TRIGGER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE TYPE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE USER MAPPING</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>CREATE VIEW</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP AGGREGATE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP CAST</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP COLLATION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP CONVERSION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP DOMAIN</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP EXTENSION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP FOREIGN DATA WRAPPER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP FOREIGN TABLE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP FUNCTION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP INDEX</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP LANGUAGE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP OPERATOR</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP OPERATOR CLASS</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP OPERATOR FAMILY</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP RULE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP SCHEMA</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP SEQUENCE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP SERVER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP TABLE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP TEXT SEARCH CONFIGURATION</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP TEXT SEARCH DICTIONARY</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP TEXT SEARCH PARSER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP TEXT SEARCH TEMPLATE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP TRIGGER</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP TYPE</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP USER MAPPING</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP VIEW</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>SELECT INTO</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + +</chapter> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 82b9e394aa5..db4cc3a3fba 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -61,6 +61,7 @@ <!ENTITY rules SYSTEM "rules.sgml"> <!ENTITY spi SYSTEM "spi.sgml"> <!ENTITY trigger SYSTEM "trigger.sgml"> +<!ENTITY event-trigger SYSTEM "event-trigger.sgml"> <!ENTITY xaggr SYSTEM "xaggr.sgml"> <!ENTITY xfunc SYSTEM "xfunc.sgml"> <!ENTITY xindex SYSTEM "xindex.sgml"> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 7e80265eb35..4ef1fc1a6e6 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -208,6 +208,7 @@ &extend; &trigger; + &event-trigger; &rules; &xplang; diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index 382d297bdb2..df84054bcee 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -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"> diff --git a/doc/src/sgml/ref/alter_event_trigger.sgml b/doc/src/sgml/ref/alter_event_trigger.sgml new file mode 100644 index 00000000000..f53b0228bc9 --- /dev/null +++ b/doc/src/sgml/ref/alter_event_trigger.sgml @@ -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> diff --git a/doc/src/sgml/ref/alter_extension.sgml b/doc/src/sgml/ref/alter_extension.sgml index 6916da3f9d8..60bc747269c 100644 --- a/doc/src/sgml/ref/alter_extension.sgml +++ b/doc/src/sgml/ref/alter_extension.sgml @@ -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> [, ...] ] ) | diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index 1c8b37c8328..a03f15cd569 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -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> [, ...] ] ) | diff --git a/doc/src/sgml/ref/create_event_trigger.sgml b/doc/src/sgml/ref/create_event_trigger.sgml new file mode 100644 index 00000000000..56c7b52a59c --- /dev/null +++ b/doc/src/sgml/ref/create_event_trigger.sgml @@ -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> diff --git a/doc/src/sgml/ref/drop_event_trigger.sgml b/doc/src/sgml/ref/drop_event_trigger.sgml new file mode 100644 index 00000000000..86f9628fd8c --- /dev/null +++ b/doc/src/sgml/ref/drop_event_trigger.sgml @@ -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> diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 54890a1db53..b6bf6a3ba8e 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1456,6 +1456,20 @@ testdb=> </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> <listitem> diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml index 8f52664afc0..d946b92e19d 100644 --- a/doc/src/sgml/ref/security_label.sgml +++ b/doc/src/sgml/ref/security_label.sgml @@ -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> | diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index f856819ba5a..08721684074 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -41,6 +41,7 @@ &alterDefaultPrivileges; &alterDomain; &alterExtension; + &alterEventTrigger; &alterForeignDataWrapper; &alterForeignTable; &alterFunction; @@ -82,6 +83,7 @@ &createDatabase; &createDomain; &createExtension; + &createEventTrigger; &createForeignDataWrapper; &createForeignTable; &createFunction; @@ -120,6 +122,7 @@ &dropDatabase; &dropDomain; &dropExtension; + &dropEventTrigger; &dropForeignDataWrapper; &dropForeignTable; &dropFunction; |