42.1. Обзор механизма работы триггеров событий #
Триггер события срабатывает всякий раз, когда в базе данных, в которой он определён, происходит связанное с ним событие. В настоящий момент поддерживаются следующие события: login, ddl_command_start, ddl_command_end, table_rewrite и sql_drop. Поддержка дополнительных событий может быть добавлена в будущих выпусках.
42.1.1. login #
Событие login происходит, когда аутентифицированный пользователь входит в систему. Любые ошибки в процедуре триггера для этого события могут помешать успешному входу в систему. Таких ошибок можно избежать, задав для параметра event_triggers значение false в строке подключения или файле конфигурации. Кроме того, можно перезапустить сервер в однопользовательском режиме (поскольку триггеры событий в этом режиме отключены). За дополнительными сведениями об однопользовательском режиме обратитесь к справке по postgres. Событийный триггер login также срабатывает на резервных серверах. Во избежание проблем с подключением к серверам, работающие на них триггеры login не должны ничего записывать в базу данных. Кроме того, рекомендуется избегать длительных запросов в событийных триггерах login. Обратите внимание, что отмена подключения в psql не отменит текущий триггер login.
Пример использования триггера события login приведён в Разделе 42.5.
42.1.2. ddl_command_start #
Событие ddl_command_start происходит непосредственно перед выполнением команды DDL. В данном контексте командами DDL считаются:
CREATEALTERDROPCOMMENTGRANTIMPORT FOREIGN SCHEMAREINDEXREFRESH MATERIALIZED VIEWREVOKESECURITY LABEL
Событие ddl_command_start также происходит перед выполнением команды SELECT INTO, так как она равнозначна CREATE TABLE AS.
В качестве исключения это событие не срабатывает для команд DDL, направленных на общие объекты:
базы данных
роли (определения ролей и членство в ролях)
табличные пространства
права на параметры
ALTER SYSTEM
Оно также не срабатывает для команд, направленных на сами триггеры событий.
Проверка существования целевого объекта до срабатывания событийного триггера не выполняется.
42.1.3. ddl_command_end #
Событие ddl_command_end происходит непосредственно после выполнения того же набора команд, что и для ddl_command_start. Чтобы получить дополнительную информацию об операциях DDL, повлёкших произошедшее событие, вызовите функцию pg_event_trigger_ddl_commands(), возвращающую множество, из кода обработчика события ddl_command_end (см. Раздел 9.30). Заметьте, что этот триггер срабатывает после того, как эти действия имели место (но до фиксации транзакции), так что в системных каталогах можно увидеть уже изменённое состояние.
42.1.4. sql_drop #
Событие sql_drop происходит непосредственно перед событием ddl_command_end для любой операции, которая удаляет объекты базы данных. Обратите внимание, что кроме очевидных команд DROP некоторые команды ALTER также могут вызывать событие sql_drop.
Для получения списка удалённых объектов используйте возвращающую набор строк функцию pg_event_trigger_dropped_objects() в триггере события sql_drop (см. Раздел 9.30). Обратите внимание, что триггер выполняется после удаления объектов из таблиц системного каталога, поэтому их невозможно больше увидеть.
42.1.5. table_rewrite #
Событие table_rewrite происходит непосредственно перед тем, как таблица будет перезаписана в результате определённых действий команд ALTER TABLE и ALTER TYPE. Хотя перезапись таблицы может быть вызвана и другими управляющими операторами, в частности CLUSTER и VACUUM, событие table_rewrite для них не вызывается. Найти OID таблицы, которая была перезаписана, можно с помощью функции pg_event_trigger_table_rewrite_oid(). Чтобы узнать причину (причины) перезаписи, используйте функцию pg_event_trigger_table_rewrite_reason() (см. Раздел 9.30).
42.1.6. Событийные триггеры в прерванных транзакциях #
Триггеры событий (как и прочие функции) не могут выполняться в прерванной транзакции. Поэтому, если команда DDL завершается ошибкой, соответствующие триггеры ddl_command_end не сработают. И наоборот, если триггер ddl_command_end завершился с ошибкой, последующие триггеры событий не сработают, так же как и сама команда не будет выполняться. Похожим образом, если триггер ddl_command_end завершится ошибкой, действие команды DDL будет отменено, как это происходит при возникновении ошибки внутри транзакции.
42.1.7. Создание событийных триггеров #
Для создания триггера события используется команда CREATE EVENT TRIGGER. Предварительно нужно создать функцию, со специальным возвращаемым типом event_trigger. Данная функция не обязана возвращать значение (и может не возвращать). Возвращаемый тип служит лишь указанием на то, что функция будет вызываться из триггера события.
Если есть несколько триггеров на одно и то же событие, то они будут вызываться в алфавитном порядке по имени триггера.
В определении триггера можно использовать условие WHEN, чтобы, например, триггер ddl_command_start срабатывал только для отдельных команд, которые нужно перехватить. Триггеры событий часто используются для ограничения диапазона DDL-команд, доступных пользователям.
42.1. 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 supported events are login, ddl_command_start, ddl_command_end, table_rewrite and sql_drop. Support for additional events may be added in future releases.
42.1.1. login #
The login event occurs when an authenticated user logs into the system. Any bug in a trigger procedure for this event may prevent successful login to the system. Such bugs may be worked around by setting event_triggers to false either in a connection string or configuration file. Alternatively, you can restart the system in single-user mode (as event triggers are disabled in this mode). See the postgres reference page for details about using single-user mode. The login event will also fire on standby servers. To prevent servers from becoming inaccessible, such triggers must avoid writing anything to the database when running on a standby. Also, it's recommended to avoid long-running queries in login event triggers. Note that, for instance, canceling a connection in psql will not cancel the in-progress login trigger.
For an example on how to use the login event trigger, see Section 42.5.
42.1.2. ddl_command_start #
The ddl_command_start event occurs just before the execution of a DDL command. DDL commands in this context are:
CREATEALTERDROPCOMMENTGRANTIMPORT FOREIGN SCHEMAREINDEXREFRESH MATERIALIZED VIEWREVOKESECURITY 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.
42.1.3. ddl_command_end #
The ddl_command_end event occurs just after the execution of 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 Section 9.30). Note that the trigger fires after the actions have taken place (but before the transaction commits), and thus the system catalogs can be read as already changed.
42.1.4. sql_drop #
The sql_drop event occurs just before the ddl_command_end event trigger for any operation that drops 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 Section 9.30). 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.
42.1.5. table_rewrite #
The table_rewrite event occurs just before a table is rewritten by some actions of the commands ALTER TABLE and ALTER TYPE. While other control statements are available to rewrite a table, 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(), to discover the reason(s) for the rewrite, use the function pg_event_trigger_table_rewrite_reason() (see Section 9.30).
42.1.6. 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 ddl_command_end triggers will not be executed. Conversely, if a ddl_command_start trigger fails with an error, no further event triggers will fire, and no attempt will be made to execute the command itself. Similarly, if a ddl_command_end trigger fails with an error, the effects of the DDL statement will be rolled back, just as they would be in any other case where the containing transaction aborts.
42.1.7. Creating Event Triggers #
Event triggers are created using the command CREATE EVENT TRIGGER. 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 ddl_command_start 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.