diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/event-trigger.sgml | 110 | ||||
| -rw-r--r-- | doc/src/sgml/func.sgml | 113 |
2 files changed, 218 insertions, 5 deletions
diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml index 71241c82245..36928413d15 100644 --- a/doc/src/sgml/event-trigger.sgml +++ b/doc/src/sgml/event-trigger.sgml @@ -27,17 +27,19 @@ <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 events are <literal>ddl_command_start</> - and <literal>ddl_command_end</>. Support for additional events may be - added in future releases. + supported events are + <literal>ddl_command_start</>, + <literal>ddl_command_end</> + and <literal>sql_drop</>. + 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</> command. 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 + 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 @@ -46,6 +48,17 @@ </para> <para> + The <literal>sql_drop</> event occurs just before the + <literal>ddl_command_end</> event trigger for any operation that drops + database objects. To list the objects that have been dropped, use the set + returning function <literal>pg_event_trigger_dropped_objects()</> from your + <literal>sql_drop</> event trigger code (see + <xref linkend="functions-event-triggers">). Note that + the trigger is executed after the objects have been deleted from the + system catalogs, so it's not possible to look them up anymore. + </para> + + <para> Event triggers (like other functions) cannot be executed in an aborted transaction. Thus, if a DDL command fails with an error, any associated <literal>ddl_command_end</> triggers will not be executed. Conversely, @@ -99,6 +112,7 @@ <entry>command tag</entry> <entry><literal>ddl_command_start</literal></entry> <entry><literal>ddl_command_end</literal></entry> + <entry><literal>sql_drop</literal></entry> </row> </thead> <tbody> @@ -106,401 +120,487 @@ <entry align="left"><literal>ALTER AGGREGATE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER COLLATION</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER CONVERSION</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER DOMAIN</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER EXTENSION</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER FOREIGN DATA WRAPPER</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER FOREIGN TABLE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</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> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER LANGUAGE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER OPERATOR</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER OPERATOR CLASS</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER OPERATOR FAMILY</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER SCHEMA</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER SEQUENCE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER SERVER</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER TABLE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</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> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER TEXT SEARCH DICTIONARY</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER TEXT SEARCH PARSER</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER TEXT SEARCH TEMPLATE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER TRIGGER</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER TYPE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER USER MAPPING</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>ALTER VIEW</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE AGGREGATE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE CAST</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE COLLATION</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE CONVERSION</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE DOMAIN</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE EXTENSION</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE FOREIGN DATA WRAPPER</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE FOREIGN TABLE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE FUNCTION</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE INDEX</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE LANGUAGE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE OPERATOR</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE OPERATOR CLASS</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE OPERATOR FAMILY</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE RULE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE SCHEMA</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE SEQUENCE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE SERVER</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE TABLE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE TABLE AS</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE TEXT SEARCH CONFIGURATION</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE TEXT SEARCH DICTIONARY</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE TEXT SEARCH PARSER</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE TEXT SEARCH TEMPLATE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE TRIGGER</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE TYPE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE USER MAPPING</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>CREATE VIEW</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> <row> <entry align="left"><literal>DROP AGGREGATE</literal></entry> <entry align="center"><literal>X</literal></entry> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>X</literal></entry> + </row> + <row> + <entry align="left"><literal>DROP OWNED</literal></entry> + <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</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> <entry align="center"><literal>X</literal></entry> + <entry align="center"><literal>-</literal></entry> </row> </tbody> </tgroup> diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 490d7106435..db4e33f871d 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -15980,4 +15980,117 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger(); <xref linkend="SQL-CREATETRIGGER">. </para> </sect1> + + <sect1 id="functions-event-triggers"> + <title>Event Trigger Functions</title> + + <indexterm> + <primary>pg_event_trigger_dropped_objects</primary> + </indexterm> + + <para> + Currently <productname>PostgreSQL</> provides one built-in event trigger + helper function, <function>pg_event_trigger_dropped_objects</>. + </para> + + <para> + <function>pg_event_trigger_dropped_objects</> returns a list of all object + dropped by the command in whose <literal>sql_drop</> event it is called. + If called in any other context, + <function>pg_event_trigger_dropped_objects</> raises an error. + <function>pg_event_trigger_dropped_objects</> returns the following columns: + + <informaltable> + <tgroup cols="3"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>classid</literal></entry> + <entry><type>Oid</type></entry> + <entry>OID of catalog the object belonged in</entry> + </row> + <row> + <entry><literal>objid</literal></entry> + <entry><type>Oid</type></entry> + <entry>OID the object had within the catalog</entry> + </row> + <row> + <entry><literal>objsubid</literal></entry> + <entry><type>int32</type></entry> + <entry>Object sub-id (e.g. attribute number for columns)</entry> + </row> + <row> + <entry><literal>object_type</literal></entry> + <entry><type>text</type></entry> + <entry>Type of the object</entry> + </row> + <row> + <entry><literal>schema_name</literal></entry> + <entry><type>text</type></entry> + <entry> + Name of the schema the object belonged in, if any; otherwise <literal>NULL</>. + No quoting is applied. + </entry> + </row> + <row> + <entry><literal>object_name</literal></entry> + <entry><type>text</type></entry> + <entry> + Name of the object, if the combination of schema and name can be + used as an unique identifier for the object; otherwise <literal>NULL</>. + No quoting is applied, and name is never schema-qualified. + </entry> + </row> + <row> + <entry><literal>object_identity</literal></entry> + <entry><type>text</type></entry> + <entry> + Text rendering of the object identity, schema-qualified. Each and every + identifier present in the identity is quoted if necessary. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + + <para> + The <function>pg_event_trigger_dropped_objects</> function can be used + in an event trigger like this: +<programlisting> +CREATE FUNCTION test_event_trigger_for_drops() + RETURNS event_trigger LANGUAGE plpgsql AS $$ +DECLARE + obj record; +BEGIN + FOR obj IN SELECT * FROM pg_event_trigger_dropped_objects() + LOOP + RAISE NOTICE '% dropped object: % %.% %', + tg_tag, + obj.object_type, + obj.schema_name, + obj.object_name, + obj.object_identity; + END LOOP; +END +$$; +CREATE EVENT TRIGGER test_event_trigger_for_drops + ON sql_drop + EXECUTE PROCEDURE test_event_trigger_for_drops(); +</programlisting> + </para> + + <para> + For more information about event triggers, + see <xref linkend="event-triggers">. + </para> + </sect1> + </chapter> |