From 8de37230f50b6a47c89fc5f5d0ea1010b635be62 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Tue, 29 Oct 2024 11:58:32 +0100 Subject: [PATCH] doc: Remove event trigger firing matrix This is difficult to maintain accurately, and it was probably already somewhat incorrect, especially in the sql_drop and table_rewrite categories. The prior section already documented which DDL commands are *not* supported (which was also slightly outdated), so let's just rely on that instead of listing out each command in full detail. Discussion: https://www.postgresql.org/message-id/flat/CACJufxE_UAuxcM08BW5oVsg34v0cFWoEt8yBa5xSAoKLmL6LTQ%40mail.gmail.com --- doc/src/sgml/event-trigger.sgml | 1022 ++------------------------ src/backend/commands/event_trigger.c | 4 +- src/backend/tcop/utility.c | 3 + 3 files changed, 79 insertions(+), 950 deletions(-) diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml index cfa7b3d1b2d..2cfe8d4f278 100644 --- a/doc/src/sgml/event-trigger.sgml +++ b/doc/src/sgml/event-trigger.sgml @@ -26,7 +26,7 @@ Overview of Event Trigger Behavior 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 @@ Overview of Event Trigger Behavior 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,57 @@ Overview of Event Trigger Behavior 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 + 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 @@ -86,10 +120,21 @@ Overview of Event Trigger Behavior 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 @@ -97,6 +142,11 @@ Overview of Event Trigger Behavior system catalogs, so it's not possible to look them up anymore. + + + + table_rewrite + The table_rewrite event occurs just before a table is rewritten by some actions of the commands ALTER TABLE and @@ -111,6 +161,11 @@ Overview of Event Trigger Behavior pg_event_trigger_table_rewrite_reason(). + + + + Event Triggers in Aborted Transactions + Event triggers (like other functions) cannot be executed in an aborted transaction. Thus, if a DDL command fails with an error, any associated @@ -122,11 +177,10 @@ Overview of Event Trigger Behavior 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 +202,7 @@ Overview of Event Trigger Behavior 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, base-commit: 4b7bba49e71266ec378e672a1aaa9f16823449c2 -- 2.47.0