@@ -1891,30 +1892,28 @@
evtnamename
- Trigger name (unique)
+ Trigger name (must be unique)evteventname
- The event this trigger fires for.
+ Identifies the event for which this trigger firesevtowneroidpg_authid.oid
- Owner of the event
+ Owner of the event triggerevtfoidoidpg_proc.oid
-
- The OID of the function called by this event trigger.
-
+ The function to be called
@@ -1935,7 +1934,10 @@
evttagstext[]
- Command tags of the commands this trigger is restricted to.
+
+ 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.
+
diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml
new file mode 100644
index 0000000..4ff93d0
--- /dev/null
+++ b/doc/src/sgml/event-trigger.sgml
@@ -0,0 +1,466 @@
+
+
+
+ Event Triggers
+
+
+ event trigger
+
+
+
+ To supplement the trigger mechanism discussed in ,
+ 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.
+
+
+
+ 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.
+
+
+
+ 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 supported event is command_start. Support for
+ additional events may be added in future releases.
+
+
+
+ The command_start event occurs just before the execution of
+ many SQL commands, most of which can be broadly described as
+ DDL. There are a number of commands that,
+ for various reasons, are specifically excluded from the event trigger
+ system:
+
+
+
+
+ The command_start event does not occur for commands that
+ access or modify data within a particular table, such
+ , ,
+ , , and
+ . This also includes commands related
+ to prepared plans, such as ,
+ , ,
+ and . Ordinary triggers or rules should
+ be used in these cases.
+
+
+
+
+ The command_start event does not occur for commands that
+ create, alter, or drop global objects. Unlike the event trigger, these
+ objects are not part of the current database; they are accessible from
+ all databases in the cluster, and are therefore unaffected by event
+ triggers. Such objects include databases, tablespaces, and roles.
+
+
+
+
+ The command_start event does not occur for commands where
+ firing a trigger might result either result in system instability or
+ interfere with the administrator's ability to regain control of the
+ database. These include transaction control commands, such as
+ or ; configuration
+ commands, such as or ;
+ and commands related to the event trigger mechanism itself, such as
+ ,
+ , and
+ .
+
+
+
+
+
+
+ For a complete list of commands supported by the event trigger mechanism,
+ see .
+
+
+
+ In order to create an event trigger, you must first create a function with
+ the special return type event_trigger. 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.
+
+
+
+ If more than one event trigger is defined for a particular event, they will
+ fire in alphabetical order by trigger name.
+
+
+
+ A trigger definition can also specify a WHEN
+ condition so that, for example, a command_start
+ tag 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.
+
+
+
+
+ Event Trigger Firing Matrix
+
+
+ lists all commands
+ for which event triggers are supported.
+
+
+
+ Event Trigger Support by Command Tag
+
+
+
+ command tag
+ command_start
+
+
+
+
+ ALTER AGGREGATE
+ X
+
+
+ ALTER COLLATION
+ X
+
+
+ ALTER CONVERSION
+ X
+
+
+ ALTER DOMAIN
+ X
+
+
+ ALTER EXTENSION
+ X
+
+
+ ALTER FOREIGN DATA WRAPPER
+ X
+
+
+ ALTER FOREIGN TABLE
+ X
+
+
+ ALTER FUNCTION
+ X
+
+
+ ALTER LANGUAGE
+ X
+
+
+ ALTER OPERATOR
+ X
+
+
+ ALTER OPERATOR CLASS
+ X
+
+
+ ALTER OPERATOR FAMILY
+ X
+
+
+ ALTER SCHEMA
+ X
+
+
+ ALTER SEQUENCE
+ X
+
+
+ ALTER SERVER
+ X
+
+
+ ALTER TABLE
+ X
+
+
+ ALTER TEXT SEARCH CONFIGURATION
+ X
+
+
+ ALTER TEXT SEARCH DICTIONARY
+ X
+
+
+ ALTER TEXT SEARCH PARSER
+ X
+
+
+ ALTER TEXT SEARCH TEMPLATE
+ X
+
+
+ ALTER TRIGGER
+ X
+
+
+ ALTER TYPE
+ X
+
+
+ ALTER USER MAPPING
+ X
+
+
+ ALTER VIEW
+ X
+
+
+ CLUSTER
+ X
+
+
+ CREATE AGGREGATE
+ X
+
+
+ CREATE CAST
+ X
+
+
+ CREATE COLLATION
+ X
+
+
+ CREATE CONVERSION
+ X
+
+
+ CREATE DOMAIN
+ X
+
+
+ CREATE EXTENSION
+ X
+
+
+ CREATE FOREIGN DATA WRAPPER
+ X
+
+
+ CREATE FOREIGN TABLE
+ X
+
+
+ CREATE FUNCTION
+ X
+
+
+ CREATE INDEX
+ X
+
+
+ CREATE LANGUAGE
+ X
+
+
+ CREATE OPERATOR
+ X
+
+
+ CREATE OPERATOR CLASS
+ X
+
+
+ CREATE OPERATOR FAMILY
+ X
+
+
+ CREATE RULE
+ X
+
+
+ CREATE SCHEMA
+ X
+
+
+ CREATE SEQUENCE
+ X
+
+
+ CREATE SERVER
+ X
+
+
+ CREATE TABLE
+ X
+
+
+ CREATE TABLE AS
+ X
+
+
+ CREATE TEXT SEARCH CONFIGURATION
+ X
+
+
+ CREATE TEXT SEARCH DICTIONARY
+ X
+
+
+ CREATE TEXT SEARCH PARSER
+ X
+
+
+ CREATE TEXT SEARCH TEMPLATE
+ X
+
+
+ CREATE TRIGGER
+ X
+
+
+ CREATE TYPE
+ X
+
+
+ CREATE USER MAPPING
+ X
+
+
+ CREATE VIEW
+ X
+
+
+ DROP AGGREGATE
+ X
+
+
+ DROP CAST
+ X
+
+
+ DROP COLLATION
+ X
+
+
+ DROP CONVERSION
+ X
+
+
+ DROP DOMAIN
+ X
+
+
+ DROP EXTENSION
+ X
+
+
+ DROP FOREIGN DATA WRAPPER
+ X
+
+
+ DROP FOREIGN TABLE
+ X
+
+
+ DROP FUNCTION
+ X
+
+
+ DROP INDEX
+ X
+
+
+ DROP LANGUAGE
+ X
+
+
+ DROP OPERATOR
+ X
+
+
+ DROP OPERATOR CLASS
+ X
+
+
+ DROP OPERATOR FAMILY
+ X
+
+
+ DROP RULE
+ X
+
+
+ DROP SCHEMA
+ X
+
+
+ DROP SEQUENCE
+ X
+
+
+ DROP SERVER
+ X
+
+
+ DROP TABLE
+ X
+
+
+ DROP TEXT SEARCH CONFIGURATION
+ X
+
+
+ DROP TEXT SEARCH DICTIONARY
+ X
+
+
+ DROP TEXT SEARCH PARSER
+ X
+
+
+ DROP TEXT SEARCH TEMPLATE
+ X
+
+
+ DROP TRIGGER
+ X
+
+
+ DROP TYPE
+ X
+
+
+ DROP USER MAPPING
+ X
+
+
+ DROP VIEW
+ X
+
+
+ LOAD
+ X
+
+
+ REINDEX
+ X
+
+
+ SELECT INTO
+ X
+
+
+ VACUUM
+ X
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 82b9e39..db4cc3a 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -61,6 +61,7 @@
+
diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index 9ec7a6e..e490086 100644
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -1220,7 +1220,7 @@ CREATE TRIGGER test_valid_id_trig
- Trigger Procedures on Events in PL/Perl
+ Trigger Procedures on Events in PL/Perlevent trigger
@@ -1229,9 +1229,9 @@ CREATE TRIGGER test_valid_id_trig
Event trigger procedures can be written in PL/Perl.
- PostgreSQL requires that a procedure that is to be called
- as a trigger must be declared as a function with no arguments
- and a return type of event_trigger.
+ PostgreSQL requires that a procedure that
+ is to be called as an event trigger must be declared as a function with
+ no arguments and a return type of event_trigger.
@@ -1272,7 +1272,7 @@ CREATE TRIGGER test_valid_id_trig
$_TD->{objectname}
- The name of the objectthat caused the trigger procedure
+ The name of the object that caused the trigger procedure
to be invoked.
@@ -1289,7 +1289,7 @@ CREATE TRIGGER test_valid_id_trig
-
+
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index fadd5d7..a21aaf2 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3378,7 +3378,7 @@ RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
- Triggers on data change
+ Triggers on data changesPL/pgSQL can be used to define trigger
@@ -3930,19 +3930,19 @@ SELECT * FROM sales_summary_bytime;
- Triggers on event
+ Triggers on events
- PL/pgSQL can be used to define command
- trigger procedures. An event trigger procedure is created with the
- CREATE FUNCTION command, declaring it as a function with
- no arguments and a return type of event trigger.
+ PL/pgSQL can be used to define event
+ triggers. PostgreSQL requires that a procedure that
+ is to be called as an event trigger must be declared as a function with
+ no arguments and a return type of event_trigger.
-
- When a PL/pgSQL function is called as a
- event trigger, several special variables are created automatically
- in the top-level block. They are:
+
+ When a PL/pgSQL function is called as a
+ event trigger, several special variables are created automatically
+ in the top-level block. They are:
@@ -3999,10 +3999,6 @@ SELECT * FROM sales_summary_bytime;
-
- The event trigger function's return value is not used.
-
-
shows an example of a
event trigger procedure in PL/pgSQL.
diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index e2a8f41..99ce8f9 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -872,7 +872,7 @@ $$ LANGUAGE plpythonu;
- Trigger Procedures on Events in PL/Python
+ Trigger Procedures on Events in PL/Pythonevent trigger
@@ -881,9 +881,9 @@ $$ LANGUAGE plpythonu;
Event trigger procedures can be written in PL/Python.
- PostgreSQL requires that a procedure that is to be called
- as a trigger must be declared as a function with no arguments
- and a return type of event_trigger.
+ PostgreSQL requires that a procedure that
+ is to be called as an event trigger must be declared as a function with
+ no arguments and a return type of event_trigger.
@@ -924,7 +924,7 @@ $$ LANGUAGE plpythonu;
TD["objectname"]
- The name of the objectthat caused the trigger procedure
+ The name of the object that caused the trigger procedure
to be invoked.
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index c9a4e4c..c932ddb 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -725,9 +725,9 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
Event trigger procedures can be written in PL/Tcl.
- PostgreSQL requires that a procedure that is to be called
- as a trigger must be declared as a function with no arguments
- and a return type of event_trigger.
+ PostgreSQL requires that a procedure that
+ is to be called as an event trigger must be declared as a function with
+ no arguments and a return type of event_trigger.
@@ -768,7 +768,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
$TG_objectname
- The name of the objectthat caused the trigger procedure
+ The name of the object that caused the trigger procedure
to be invoked.
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 7e80265..4ef1fc1 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/alter_event_trigger.sgml b/doc/src/sgml/ref/alter_event_trigger.sgml
index d4af986..db4727b 100644
--- a/doc/src/sgml/ref/alter_event_trigger.sgml
+++ b/doc/src/sgml/ref/alter_event_trigger.sgml
@@ -93,12 +93,12 @@ ALTER EVENT TRIGGER name RENAME TO
-
+ Compatibility
- ALTER EVENT TRIGGER is a PostgreSQL
- extension of the SQL standard.
+ There is no ALTER EVENT TRIGGER statement in the
+ SQL standard.
diff --git a/doc/src/sgml/ref/create_event_trigger.sgml b/doc/src/sgml/ref/create_event_trigger.sgml
index 0e3b0f8..3b3d474 100644
--- a/doc/src/sgml/ref/create_event_trigger.sgml
+++ b/doc/src/sgml/ref/create_event_trigger.sgml
@@ -24,7 +24,7 @@ PostgreSQL documentation
CREATE EVENT TRIGGER name
ON event
[ WHEN filter_variable IN (filter_value [ , ... ] ) ]
- EXECUTE PROCEDURE function_name ()
+ EXECUTE PROCEDURE function_name()
@@ -33,35 +33,11 @@ CREATE EVENT TRIGGER nameCREATE EVENT TRIGGER creates a new event trigger.
- The trigger will be associated with the specified event and will
- execute the specified
- function function_name when
- that event occurs.
-
-
-
- The event trigger gives a procedure to fire before the event is
- executed. In some cases the procedure can be fired instead of the event
- code PostgreSQL would run itself. A event trigger's function must
- return event_trigger data type. It can then only
- abort the execution of the command by raising an exception.
-
-
-
- If multiple triggers of the same kind are defined for the same event,
- they will be fired in alphabetical order by name.
-
-
-
- Note that objects dropped by the effect of DROP
- CASCADE will not result in a event trigger firing, only the
- top-level event for the main object will fire a event trigger. That
- also applies to other dependencies following, as in DROP OWNED
- BY.
-
-
-
- Refer to for more information about triggers.
+ Whenever the designated event occurs and the WHEN condition
+ associated with the trigger, if any, is satisfied, the trigger function
+ will be executed. For a general introduction to event triggers, see
+ . The user who creates an event trigger
+ becomes its owner.
@@ -73,9 +49,8 @@ CREATE EVENT TRIGGER namename
- The name to give the new trigger. This must be distinct from the name
- of any other trigger for the same table. The name cannot be
- schema-qualified.
+ The name to give the new trigger. This name must be unique within
+ the database.
@@ -85,8 +60,8 @@ CREATE EVENT TRIGGER name
The name of the event that triggers a call to the given function.
- Currently only command_start is supported, that
- event is run before the specific command code takes control.
+ See for more information
+ on event names.
@@ -95,12 +70,11 @@ CREATE EVENT TRIGGER namefilter_variable
- The name of a variable used to filter events, allowing to control
- which cases must be handled by the trigger function. Currently the
- only
- provided filter_variable
- is named TAG and contains the command tag for which
- the trigger is about to fire.
+ 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 suppoted
+ filter_variable
+ is TAG.
@@ -109,364 +83,10 @@ CREATE EVENT TRIGGER namefilter_value
- A list of values that the
+ A list of values for the
associated filter_variable
- can have to allow for the trigger to fire.
-
-
- The TAG variable accepts the following values:
-
-
-
-
-
- command tag
- supported events, in order
-
-
-
-
- ALTER AGGREGATE
- command_start
-
-
- ALTER COLLATION
- command_start
-
-
- ALTER CONVERSION
- command_start
-
-
- ALTER DOMAIN
- command_start
-
-
- ALTER EXTENSION
- command_start
-
-
- ALTER FOREIGN DATA WRAPPER
- command_start
-
-
- ALTER FOREIGN TABLE
- command_start
-
-
- ALTER FUNCTION
- command_start
-
-
- ALTER LANGUAGE
- command_start
-
-
- ALTER OPERATOR
- command_start
-
-
- ALTER OPERATOR CLASS
- command_start
-
-
- ALTER OPERATOR FAMILY
- command_start
-
-
- ALTER SCHEMA
- command_start
-
-
- ALTER SEQUENCE
- command_start
-
-
- ALTER SERVER
- command_start
-
-
- ALTER TABLE
- command_start
-
-
- ALTER TEXT SEARCH CONFIGURATION
- command_start
-
-
- ALTER TEXT SEARCH DICTIONARY
- command_start
-
-
- ALTER TEXT SEARCH PARSER
- command_start
-
-
- ALTER TEXT SEARCH TEMPLATE
- command_start
-
-
- ALTER TRIGGER
- command_start
-
-
- ALTER TYPE
- command_start
-
-
- ALTER USER MAPPING
- command_start
-
-
- ALTER VIEW
- command_start
-
-
- CLUSTER
- command_start
-
-
- CREATE AGGREGATE
- command_start
-
-
- CREATE CAST
- command_start
-
-
- CREATE COLLATION
- command_start
-
-
- CREATE CONVERSION
- command_start
-
-
- CREATE DOMAIN
- command_start
-
-
- CREATE EXTENSION
- command_start
-
-
- CREATE FOREIGN DATA WRAPPER
- command_start
-
-
- CREATE FOREIGN TABLE
- command_start
-
-
- CREATE FUNCTION
- command_start
-
-
- CREATE INDEX
- command_start
-
-
- CREATE LANGUAGE
- command_start
-
-
- CREATE OPERATOR
- command_start
-
-
- CREATE OPERATOR CLASS
- command_start
-
-
- CREATE OPERATOR FAMILY
- command_start
-
-
- CREATE RULE
- command_start
-
-
- CREATE SCHEMA
- command_start
-
-
- CREATE SEQUENCE
- command_start
-
-
- CREATE SERVER
- command_start
-
-
- CREATE TABLE
- command_start
-
-
- CREATE TABLE AS
- command_start
-
-
- CREATE TEXT SEARCH CONFIGURATION
- command_start
-
-
- CREATE TEXT SEARCH DICTIONARY
- command_start
-
-
- CREATE TEXT SEARCH PARSER
- command_start
-
-
- CREATE TEXT SEARCH TEMPLATE
- command_start
-
-
- CREATE TRIGGER
- command_start
-
-
- CREATE TYPE
- command_start
-
-
- CREATE USER MAPPING
- command_start
-
-
- CREATE VIEW
- command_start
-
-
- DROP AGGREGATE
- command_start
-
-
- DROP CAST
- command_start
-
-
- DROP COLLATION
- command_start
-
-
- DROP CONVERSION
- command_start
-
-
- DROP DOMAIN
- command_start
-
-
- DROP EXTENSION
- command_start
-
-
- DROP FOREIGN DATA WRAPPER
- command_start
-
-
- DROP FOREIGN TABLE
- command_start
-
-
- DROP FUNCTION
- command_start
-
-
- DROP INDEX
- command_start
-
-
- DROP LANGUAGE
- command_start
-
-
- DROP OPERATOR
- command_start
-
-
- DROP OPERATOR CLASS
- command_start
-
-
- DROP OPERATOR FAMILY
- command_start
-
-
- DROP RULE
- command_start
-
-
- DROP SCHEMA
- command_start
-
-
- DROP SEQUENCE
- command_start
-
-
- DROP SERVER
- command_start
-
-
- DROP TABLE
- command_start
-
-
- DROP TEXT SEARCH CONFIGURATION
- command_start
-
-
- DROP TEXT SEARCH DICTIONARY
- command_start
-
-
- DROP TEXT SEARCH PARSER
- command_start
-
-
- DROP TEXT SEARCH TEMPLATE
- command_start
-
-
- DROP TRIGGER
- command_start
-
-
- DROP TYPE
- command_start
-
-
- DROP USER MAPPING
- command_start
-
-
- DROP VIEW
- command_start
-
-
- LOAD
- command_start
-
-
- REINDEX
- command_start
-
-
- SELECT INTO
- command_start
-
-
- VACUUM
- command_start
-
-
-
-
-
- That list is also the list of supported commands on which you can
- attach an event trigger.
+ for which the trigger should fire. For TAG, this means a
+ list of command tags (e.g. 'DROP FUNCTION').
@@ -476,7 +96,7 @@ CREATE EVENT TRIGGER name
A user-supplied function that is declared as taking no argument and
- returning type event trigger.
+ returning type event_trigger.
If your event trigger is implemented in C then it
@@ -490,24 +110,20 @@ CREATE EVENT TRIGGER name
-
+ Notes
To create a trigger on a event, the user must be superuser.
-
-
- Use to remove a event trigger.
-
-
+ Examples
- Forbids the execution of any command supported by the event trigger
- mechanism, which includes all commands listed above:
+ Forbid the execution of any command supported by the event trigger
+ mechanism:
CREATE OR REPLACE FUNCTION abort_any_command()
@@ -547,13 +163,12 @@ $$;
-
+ Compatibility
- CREATE EVENT TRIGGER is a
- PostgreSQL extension of the SQL
- standard.
+ There is no CREATE EVENT TRIGGER statement in the
+ SQL standard.
diff --git a/doc/src/sgml/ref/drop_event_trigger.sgml b/doc/src/sgml/ref/drop_event_trigger.sgml
index 6b30dd9..86f9628 100644
--- a/doc/src/sgml/ref/drop_event_trigger.sgml
+++ b/doc/src/sgml/ref/drop_event_trigger.sgml
@@ -29,8 +29,9 @@ DROP EVENT TRIGGER [ IF EXISTS ] nameDescription
- DROP EVENT TRIGGER removes an existing trigger definition.
- To execute this command, the current user must be superuser.
+ DROP EVENT TRIGGER removes an existing event trigger.
+ To execute this command, the current user must be the owner of the event
+ trigger.
@@ -79,7 +80,7 @@ DROP EVENT TRIGGER [ IF EXISTS ] name
-
+ Examples
@@ -90,13 +91,14 @@ DROP EVENT TRIGGER snitch;
-
+ Compatibility
- The DROP EVENT TRIGGER statement is a
- PostgreSQL extension.
+ There is no DROP EVENT TRIGGER statement in the
+ SQL standard.
+
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 32994b9..f579340 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -27,24 +27,6 @@
plain SQL function language.
-
- PostgreSQL offers both triggers on commands
- (see ) and triggers on data manipulation
- (see ).
-
-
-
- Overview of Event Trigger Behavior
-
-
- A trigger is a specification that the database should automatically
- execute a particular function whenever a certain command is performed.
- The whole set of PostgreSQL commands is not
- supported for triggers, see
- for details.
-
-
-
Overview of Trigger Behavior