Documentation PostgreSQL 15.15 » Programmation serveur » PL/Tcl -- Langage de procédures Tcl » Fonctions triggers en PL/Tcl

Précédent | Niveau supérieur | Suivant
44.5. Accès à la base de données depuis PL/Tcl | Sommaire | 44.7. Fonctions trigger sur événement en PL/Tcl

## 44.6. Fonctions triggers en PL/Tcl

Les fonctions trigger peuvent être écrites en PL/Tcl. PostgreSQL requiert qu'une fonction appelée en tant que trigger doit être déclarée comme une fonction sans arguments et retourner une valeur de type `trigger`.

L'information du gestionnaire du trigger est passée au corps de la fonction avec les variables suivantes :

`$TG_name`

  Nom du trigger provenant de l'instruction `CREATE TRIGGER`.

`$TG_relid`

  L'identifiant objet de la table qui est à la cause du lancement du trigger.

`$TG_table_name`

  Le nom de la table qui est à la cause du lancement du trigger.

`$TG_table_schema`

  Le schéma de la table qui est à la cause du lancement du trigger.

`$TG_relatts`

  Une liste Tcl des noms des colonnes de la table, préfixée avec un élément de liste vide. Donc, rechercher un nom de colonne dans la liste avec la commande `lsearch` de Tcl renvoie le numéro de l'élément, en commençant à 1 pour la première colonne, de la même façon que les colonnes sont numérotées personnellement avec PostgreSQL.

`$TG_when`

  La chaîne `BEFORE`, `AFTER` ou `INSTEAD OF` suivant le type de l'événement du trigger.

`$TG_level`

  La chaîne `ROW` ou `STATEMENT` suivant le type de l'événement du trigger.

`$TG_op`

  La chaîne `INSERT`, `UPDATE`, `DELETE` ou `TRUNCATE` suivant le type de l'événement du trigger.

`$NEW`

  Un tableau associatif contenant les valeurs de la nouvelle ligne de la table pour les actions `INSERT` ou `UPDATE` ou vide pour `DELETE`. Le tableau est indexé par nom de colonne. Les colonnes NULL n'apparaissent pas dans le tableau. Ce paramètre n'est pas initialisé pour les triggers de niveau instruction.

`$OLD`

  Un tableau associatif contenant les valeurs de l'ancienne ligne de la table pour les actions `UPDATE` or `DELETE` ou vide pour `INSERT`. Le tableau est indexé par nom de colonne. Les colonnes NULL n'apparaissent pas dans le tableau. Ce paramètre n'est pas initialisé pour les triggers de niveau instruction.

`$args`

  Une liste Tcl des arguments de la fonction ainsi que l'instruction `CREATE TRIGGER`. Ces arguments sont aussi accessibles par `$1` ... `$`n`` dans le corps de la fonction.

Le code de retour d'une fonction trigger peut être faite avec une des chaînes `OK` ou `SKIP` ou une liste de paires nom de colonne/valeur renvoyée par la commande Tcl `array get`. Si la valeur de retour est `OK`, l'opération (`INSERT`/`UP DATE`/`DELETE`) qui a lancé le trigger continuera normalement. `SKIP` indique au gestionnaire de triggers de supprimer silencieusement l'opération pour cette ligne. Si une liste est renvoyée, elle indique à PL/Tcl de renvoyer la ligne modifiée au gestionnaire de triggers ; le contenu de la ligne modifiée est spécifié par les noms de colonne et par les valeurs dans la liste. Toute colonne non mentionné dans la liste est configuré à NULL. Renvoyer une ligne modifiée n'a un intérêt que pour les triggers niveau ligne pour `BEFORE`, `INSERT` ou `UPDATE` pour laquelle la ligne modifiée sera insérée au lieu de celle donnée dans `$NEW` ; ou pour les triggers niveau ligne `INSTEAD OF`, `INSERT` ou `UPDATE` où la ligne renvoyée est utilisée comme données sources pour les clauses `INSERT RETURNING` ou `UPDATE RETURNING`. Dans les triggers `BEFORE` `DELETE` ou `INSTEAD OF` `DELETE` de niveau ligne, renvoyer une ligne modifiée a le même effet que renvoyer `OK`, autrement dit l'opération continue. La valeur de retour est ignorée pour les autres types de triggers.

### Astuce

La liste de résultats peut être réalisée à partir une représentation en tableau de la ligne modifiée avec la commande Tcl `array get`.

Voici un petit exemple de fonction trigger qui force une valeur entière dans une table pour garder trace du nombre de mises à jour réalisées sur la ligne. Pour les nouvelles lignes insérées, la valeur est initialisée à 0 puis incrémentée à chaque opération de mise à jour.

    CREATE FUNCTION trigfunc_modcount() RETURNS trigger AS $$
        switch $TG_op {
            INSERT {
                set NEW($1) 0
            }
            UPDATE {
                set NEW($1) $OLD($1)
                incr NEW($1)
            }
            default {
                return OK
            }
        }
        return [array get NEW]
    $$ LANGUAGE pltcl;

    CREATE TABLE mytab (num integer, description text, modcnt integer);

    CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
        FOR EACH ROW EXECUTE FUNCTION trigfunc_modcount('modcnt');

Notez que la fonction trigger elle-même ne connaît pas le nom de la colonne ; c'est fourni avec les arguments du trigger. Ceci permet à la fonction trigger d'être ré-utilisée avec différentes tables.