Un trigger sur événement se déclenche chaque fois que l'événement qui lui
est associé se déclenche sur la base qui lui est définie. Pour le moment,
les événements supportés sont
login
,
ddl_command_start
,
ddl_command_end
,
table_rewrite
et sql_drop
.
Le support pour des événements additionnels pourrait être ajouté dans
des versions ultérieures.
L'événement login
survient quand un utilisateur
authentifié se connecte au système. Tout bug dans la procédure du trigger
pour cet événement pourrait empêcher une connexion réussie au système. De
tels bugs peuvent être contournés en configurant event_triggers à false
, soit dans une
chaîne de connexion soit dans un fichier de configuration. Vous pouvez
aussi redémarrer le système en mode simple-utilisateur (les triggers sur
événement sont désactivés dans ce cas). Voir la page de référence de postgres pour des détails sur l'utilisation du mode
simple-utilisateur. L'événement login
se déclenchera
aussi sur les serveurs secondaires. Pour empêcher les serveurs de devenir
inaccessibles, de tels triggers doivent éviter d'écrire quoi que ce soit
dans la base s'ils sont exécutés sur un serveur secondaire. De plus, il
est recommandé d'éviter les requêtes longues à exécuter dans des triggers
sur événement login
. Notez que, par exemple, annuler
une connexion dans psql n'annulera pas le
trigger login
en cours d'exécution.
Pour un exemple sur la façon d'utiliser le trigger d'événement
login
, voir Section 38.5.
L'événement ddl_command_start
se déclenche juste avant
l'exécution d'une commande DDL. Les commandes DDL dans ce contexte sont :
CREATE
ALTER
DROP
COMMENT
GRANT
IMPORT FOREIGN SCHEMA
REINDEX
REFRESH MATERIALIZED VIEW
REVOKE
SECURITY LABEL
ddl_command_start
se produit également juste avant
l'exécution d'une commande SELECT INTO
, car cela est
équivalent à CREATE TABLE AS
.
À titre d'exception, cet événement ne se produit pas pour les commandes DDL ciblant des objets partagés :
bases de données
rôles (définitions de rôles et appartenances aux rôles)
tablespaces
droits sur les paramètres
ALTER SYSTEM
Cet événement ne se produit pas non plus pour les commandes ciblant les triggers d'événement eux-mêmes.
Aucune vérification de l'existence ou de l'inexistence de l'objet affecté n'est effectuée avant le déclenchement du trigger d'événement.
L'événement ddl_command_end
se déclenche juste après
l'exécution de ces même ensembles de commandes que ddl_command_start
. Pour obtenir
plus de détails sur les opérations DDL qui
interviennent, utilisez la fonction renvoyant un ensemble de lignes
pg_event_trigger_ddl_commands()
à partir du code du
trigger répondant à l'événement ddl_command_end
(voir Section 9.30). Notez que le trigger
est exécuté après les actions qui sont intervenues (mais avant
les validations de transactions), aussi les catalogues systèmes qui
peuvent être lus ont déjà été modifiés.
L'événement sql_drop
se déclenche juste avant le trigger
sur événement ddl_command_end
pour toute opération qui
supprime des objets de la base. Notez qu'outre les commandes
DROP
évidentes, certaines commandes
ALTER
peuvent également déclencher un événement
sql_drop
.
Pour lister les objets qui ont été supprimés,
utilisez la fonction retournant des ensembles d'objets pg_event_trigger_dropped_objects()
depuis le code du trigger sur événement sql_drop
(voir Section 9.30). Notez que le trigger est
exécuté après que les objets aient été supprimés du catalogue système, il
n'est donc plus possible de les examiner.
L'événement table_rewrite
se déclenche juste
avant qu'une table soit modifiée par certaines actions des commandes
ALTER TABLE
et ALTER TYPE
. Il
existe d'autres commandes qui permettent de modifier une table, tel
que CLUSTER
et VACUUM
, mais
l'événement table_rewrite
n'est pas déclenché
pour eux.
Pour trouver l'OID de la table qui a été réécrite, utilisez la fonction
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).
Les triggers sur événement (comme les autres fonctions) ne peuvent être
exécutés dans une transaction annulée. Ainsi, si une commande DDL échoue
avec une erreur, tout trigger ddl_command_end
associé
ne sera pas exécuté. Inversement, si un trigger ddl_command_start
échoue avec une erreur, aucun autre trigger sur événement ne se déclenchera,
et aucune tentative ne sera faite pour exécuter la commande elle-même. De
la même façon, si une commande ddl_command_end
échoue
avec une erreur, les effets de la commande DDL seront annulés, comme elles
l'auraient été dans n'importe quel autre cas où la transaction qui la contient
est annulée.
Les triggers sur événement sont créés en utilisant la commande CREATE EVENT TRIGGER.
Afin de créer un trigger sur événement, vous devez d'abord créer une
fonction avec le type de retour spécial event_trigger
.
Cette fonction n'a pas besoin (et ne devrait pas) retourner de valeur ; le
type de retour sert uniquement comme signal pour que la fonction soit
appelée comme un trigger sur événement.
Si plus d'un trigger sur événement est défini pour un événement particulier, ils seront déclenchés par ordre alphabétique de leur nom.
Une définition de trigger peut également spécifier une condition
WHEN
pour que, par exemple, un trigger
ddl_command_start
ne soit déclenché que pour des commandes
particulières que l'utilisateur souhaite intercepter. Une utilisation typique
de tels triggers serait de restreindre la portée des opérations DDL que les
utilisateurs peuvent exécuter.