diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml
index cfa7b3d1b2d..1bd9abb6676 100644
--- a/doc/src/sgml/event-trigger.sgml
+++ b/doc/src/sgml/event-trigger.sgml
@@ -26,7 +26,7 @@
An event trigger fires whenever the event with which it is associated
- occurs in the database in which it is defined. Currently, the only
+ occurs in the database in which it is defined. Currently, the
supported events are
login,
ddl_command_start,
@@ -36,6 +36,9 @@
Support for additional events may be added in future releases.
+
+ login
+
The login event occurs when an authenticated user logs
into the system. Any bug in a trigger procedure for this event may
@@ -58,26 +61,58 @@
For an example on how to use the login event trigger,
see .
+
+
+
+ ddl_command_start
The ddl_command_start event occurs just before the
- execution of a CREATE, ALTER, DROP,
- SECURITY LABEL,
- COMMENT, GRANT or REVOKE
- command. No check whether the affected object exists or doesn't exist is
- performed before the event trigger fires.
- As an exception, however, this event does not occur for
- DDL commands targeting shared objects — databases, roles, and tablespaces
- — or for commands targeting event triggers themselves. The event trigger
- mechanism does not support these object types.
- ddl_command_start also occurs just before the execution of a
- SELECT INTO command, since this is equivalent to
- CREATE TABLE AS.
+ execution of a DDL command. DDL commands in this context are:
+
+ CREATE
+ ALTER
+ DROP
+ COMMENT
+ GRANT
+ IMPORT FOREIGN SCHEMA
+ REINDEX
+ REFRESH MATERIALIZED VIEW
+ REVOKE
+ SECURITY LABEL
+
+ ddl_command_start also occurs just before the
+ execution of a SELECT INTO command, since this is
+ equivalent to CREATE TABLE AS.
+
+ As an exception, this event does not occur for DDL commands targeting
+ shared objects:
+
+ databases
+ roles (role definitions and role memberships)
+ tablespaces
+ parameter privileges
+ ALTER SYSTEM
+
+ This event also does not occur for commands targeting event triggers
+ themselves.
+
+
+
+ No check whether the affected object exists or doesn't exist is performed
+ before the event trigger fires.
+
+
+
+
+ ddl_command_end
+
The ddl_command_end event occurs just after the execution of
- this same set of commands. To obtain more details on the DDL
+ the same set of commands as ddl_command_start. To
+ obtain more details on the DDL
operations that took place, use the set-returning function
pg_event_trigger_ddl_commands() from the
ddl_command_end event trigger code (see
@@ -85,17 +120,31 @@
after the actions have taken place (but before the transaction commits),
and thus the system catalogs can be read as already changed.
+
+
+
+ sql_drop
The sql_drop event occurs just before the
ddl_command_end event trigger for any operation that drops
- database objects. To list the objects that have been dropped, use the
+ database objects. Note that besides the obvious DROP
+ commands, some ALTER commands can also trigger an
+ sql_drop event.
+
+
+
+ To list the objects that have been dropped, use the
set-returning function pg_event_trigger_dropped_objects() from the
sql_drop event trigger code (see
). 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.
+
+
+
+ table_rewrite
The table_rewrite event occurs just before a table is
@@ -105,11 +154,15 @@
like CLUSTER and VACUUM,
the table_rewrite event is not triggered by them.
To find the OID of the table that was rewritten, use the function
- pg_event_trigger_table_rewrite_oid() (see
- ). To discover the reason(s)
- for the rewrite, use the function
- pg_event_trigger_table_rewrite_reason().
+ pg_event_trigger_table_rewrite_oid(), to discover the
+ reason(s) for the rewrite, use the function
+ pg_event_trigger_table_rewrite_reason() (see ).
+
+
+
+ Event Triggers in Aborted Transactions
Event triggers (like other functions) cannot be executed in an aborted
@@ -122,11 +175,10 @@
back, just as they would be in any other case where the containing
transaction aborts.
+
-
- For a complete list of commands supported by the event trigger mechanism,
- see .
-
+
+ Creating Event Triggers
Event triggers are created using the command .
@@ -148,935 +200,7 @@
to intercept. A common use of such triggers is to restrict the range of
DDL operations which users may perform.
-
-
-
- Event Trigger Firing Matrix
-
-
- lists all commands
- for which event triggers are supported.
-
-
-
- Event Trigger Support by Command Tag
-
-
-
-
-
-
-
-
-
- Command Tag
- ddl_&zwsp;command_&zwsp;start
- ddl_&zwsp;command_&zwsp;end
- sql_&zwsp;drop
- table_&zwsp;rewrite
- Notes
-
-
-
-
- ALTER AGGREGATE
- X
- X
- -
- -
-
-
-
- ALTER COLLATION
- X
- X
- -
- -
-
-
-
- ALTER CONVERSION
- X
- X
- -
- -
-
-
-
- ALTER DOMAIN
- X
- X
- -
- -
-
-
-
- ALTER DEFAULT PRIVILEGES
- X
- X
- -
- -
-
-
-
- ALTER EXTENSION
- X
- X
- -
- -
-
-
-
- ALTER FOREIGN DATA WRAPPER
- X
- X
- -
- -
-
-
-
- ALTER FOREIGN TABLE
- X
- X
- X
- -
-
-
-
- ALTER FUNCTION
- X
- X
- -
- -
-
-
-
- ALTER LANGUAGE
- X
- X
- -
- -
-
-
-
- ALTER LARGE OBJECT
- X
- X
- -
- -
-
-
-
- ALTER MATERIALIZED VIEW
- X
- X
- -
- X
-
-
-
- ALTER OPERATOR
- X
- X
- -
- -
-
-
-
- ALTER OPERATOR CLASS
- X
- X
- -
- -
-
-
-
- ALTER OPERATOR FAMILY
- X
- X
- -
- -
-
-
-
- ALTER POLICY
- X
- X
- -
- -
-
-
-
- ALTER PROCEDURE
- X
- X
- -
- -
-
-
-
- ALTER PUBLICATION
- X
- X
- -
- -
-
-
-
- ALTER ROUTINE
- X
- X
- -
- -
-
-
-
- ALTER SCHEMA
- X
- X
- -
- -
-
-
-
- ALTER SEQUENCE
- X
- X
- -
- -
-
-
-
- ALTER SERVER
- X
- X
- -
- -
-
-
-
- ALTER STATISTICS
- X
- X
- -
- -
-
-
-
- ALTER SUBSCRIPTION
- X
- X
- -
- -
-
-
-
- ALTER TABLE
- X
- X
- X
- X
-
-
-
- ALTER TEXT SEARCH CONFIGURATION
- X
- X
- -
- -
-
-
-
- ALTER TEXT SEARCH DICTIONARY
- X
- X
- -
- -
-
-
-
- ALTER TEXT SEARCH PARSER
- X
- X
- -
- -
-
-
-
- ALTER TEXT SEARCH TEMPLATE
- X
- X
- -
- -
-
-
-
- ALTER TRIGGER
- X
- X
- -
- -
-
-
-
- ALTER TYPE
- X
- X
- -
- X
-
-
-
- ALTER USER MAPPING
- X
- X
- -
- -
-
-
-
- ALTER VIEW
- X
- X
- -
- -
-
-
-
- COMMENT
- X
- X
- -
- -
- Only for local objects
-
-
- CREATE ACCESS METHOD
- X
- X
- -
- -
-
-
-
- CREATE AGGREGATE
- X
- X
- -
- -
-
-
-
- CREATE CAST
- X
- X
- -
- -
-
-
-
- CREATE COLLATION
- X
- X
- -
- -
-
-
-
- CREATE CONVERSION
- X
- X
- -
- -
-
-
-
- CREATE DOMAIN
- X
- X
- -
- -
-
-
-
- CREATE EXTENSION
- X
- X
- -
- -
-
-
-
- CREATE FOREIGN DATA WRAPPER
- X
- X
- -
- -
-
-
-
- CREATE FOREIGN TABLE
- X
- X
- -
- -
-
-
-
- CREATE FUNCTION
- X
- X
- -
- -
-
-
-
- CREATE INDEX
- X
- X
- -
- -
-
-
-
- CREATE LANGUAGE
- X
- X
- -
- -
-
-
-
- CREATE MATERIALIZED VIEW
- X
- X
- -
- -
-
-
-
- CREATE OPERATOR
- X
- X
- -
- -
-
-
-
- CREATE OPERATOR CLASS
- X
- X
- -
- -
-
-
-
- CREATE OPERATOR FAMILY
- X
- X
- -
- -
-
-
-
- CREATE POLICY
- X
- X
- -
- -
-
-
-
- CREATE PROCEDURE
- X
- X
- -
- -
-
-
-
- CREATE PUBLICATION
- X
- X
- -
- -
-
-
-
- CREATE RULE
- X
- X
- -
- -
-
-
-
- CREATE SCHEMA
- X
- X
- -
- -
-
-
-
- CREATE SEQUENCE
- X
- X
- -
- -
-
-
-
- CREATE SERVER
- X
- X
- -
- -
-
-
-
- CREATE STATISTICS
- X
- X
- -
- -
-
-
-
- CREATE SUBSCRIPTION
- X
- X
- -
- -
-
-
-
- CREATE TABLE
- X
- X
- -
- -
-
-
-
- CREATE TABLE AS
- X
- X
- -
- -
-
-
-
- CREATE TEXT SEARCH CONFIGURATION
- X
- X
- -
- -
-
-
-
- CREATE TEXT SEARCH DICTIONARY
- X
- X
- -
- -
-
-
-
- CREATE TEXT SEARCH PARSER
- X
- X
- -
- -
-
-
-
- CREATE TEXT SEARCH TEMPLATE
- X
- X
- -
- -
-
-
-
- CREATE TRIGGER
- X
- X
- -
- -
-
-
-
- CREATE TYPE
- X
- X
- -
- -
-
-
-
- CREATE USER MAPPING
- X
- X
- -
- -
-
-
-
- CREATE VIEW
- X
- X
- -
- -
-
-
-
- DROP ACCESS METHOD
- X
- X
- X
- -
-
-
-
- DROP AGGREGATE
- X
- X
- X
- -
-
-
-
- DROP CAST
- X
- X
- X
- -
-
-
-
- DROP COLLATION
- X
- X
- X
- -
-
-
-
- DROP CONVERSION
- X
- X
- X
- -
-
-
-
- DROP DOMAIN
- X
- X
- X
- -
-
-
-
- DROP EXTENSION
- X
- X
- X
- -
-
-
-
- DROP FOREIGN DATA WRAPPER
- X
- X
- X
- -
-
-
-
- DROP FOREIGN TABLE
- X
- X
- X
- -
-
-
-
- DROP FUNCTION
- X
- X
- X
- -
-
-
-
- DROP INDEX
- X
- X
- X
- -
-
-
-
- DROP LANGUAGE
- X
- X
- X
- -
-
-
-
- DROP MATERIALIZED VIEW
- X
- X
- X
- -
-
-
-
- DROP OPERATOR
- X
- X
- X
- -
-
-
-
- DROP OPERATOR CLASS
- X
- X
- X
- -
-
-
-
- DROP OPERATOR FAMILY
- X
- X
- X
- -
-
-
-
- DROP OWNED
- X
- X
- X
- -
-
-
-
- DROP POLICY
- X
- X
- X
- -
-
-
-
- DROP PROCEDURE
- X
- X
- X
- -
-
-
-
- DROP PUBLICATION
- X
- X
- X
- -
-
-
-
- DROP ROUTINE
- X
- X
- X
- -
-
-
-
- DROP RULE
- X
- X
- X
- -
-
-
-
- DROP SCHEMA
- X
- X
- X
- -
-
-
-
- DROP SEQUENCE
- X
- X
- X
- -
-
-
-
- DROP SERVER
- X
- X
- X
- -
-
-
-
- DROP STATISTICS
- X
- X
- X
- -
-
-
-
- DROP SUBSCRIPTION
- X
- X
- X
- -
-
-
-
- DROP TABLE
- X
- X
- X
- -
-
-
-
- DROP TEXT SEARCH CONFIGURATION
- X
- X
- X
- -
-
-
-
- DROP TEXT SEARCH DICTIONARY
- X
- X
- X
- -
-
-
-
- DROP TEXT SEARCH PARSER
- X
- X
- X
- -
-
-
-
- DROP TEXT SEARCH TEMPLATE
- X
- X
- X
- -
-
-
-
- DROP TRIGGER
- X
- X
- X
- -
-
-
-
- DROP TYPE
- X
- X
- X
- -
-
-
-
- DROP USER MAPPING
- X
- X
- X
- -
-
-
-
- DROP VIEW
- X
- X
- X
- -
-
-
-
- GRANT
- X
- X
- -
- -
- Only for local objects
-
-
- IMPORT FOREIGN SCHEMA
- X
- X
- -
- -
-
-
-
- REFRESH MATERIALIZED VIEW
- X
- X
- -
- -
-
-
-
- REINDEX
- X
- X
- -
- -
-
-
-
- REVOKE
- X
- X
- -
- -
- Only for local objects
-
-
- SECURITY LABEL
- X
- X
- -
- -
- Only for local objects
-
-
- SELECT INTO
- X
- X
- -
- -
-
-
-
-
-
+
diff --git a/src/backend/commands/event_trigger.c b/src/backend/commands/event_trigger.c
index a586d246ece..dcfc1dbaffd 100644
--- a/src/backend/commands/event_trigger.c
+++ b/src/backend/commands/event_trigger.c
@@ -1123,7 +1123,7 @@ EventTriggerInvoke(List *fn_oid_list, EventTriggerData *trigdata)
/*
* Do event triggers support this object type?
*
- * See also event trigger support matrix in event-trigger.sgml.
+ * See also event trigger documentation in event-trigger.sgml.
*/
bool
EventTriggerSupportsObjectType(ObjectType obtype)
@@ -1147,7 +1147,7 @@ EventTriggerSupportsObjectType(ObjectType obtype)
/*
* Do event triggers support this object class?
*
- * See also event trigger support matrix in event-trigger.sgml.
+ * See also event trigger documentation in event-trigger.sgml.
*/
bool
EventTriggerSupportsObject(const ObjectAddress *object)
diff --git a/src/backend/tcop/utility.c b/src/backend/tcop/utility.c
index b2ea8125c92..f28bf371059 100644
--- a/src/backend/tcop/utility.c
+++ b/src/backend/tcop/utility.c
@@ -535,6 +535,9 @@ ProcessUtility(PlannedStmt *pstmt,
* event trigger code not be invoked when doing START TRANSACTION for
* example, because we might need to refresh the event trigger cache,
* which requires being in a valid transaction.
+ *
+ * When adding or moving utility commands, check that the documentation in
+ * event-trigger.sgml is kept up to date.
*/
void
standard_ProcessUtility(PlannedStmt *pstmt,