contrib-spi.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

<sect1 id="contrib-spi">
 <title>spi</title>

 <indexterm zone="contrib-spi">
  <primary>SPI</primary>
  <secondary>examples</secondary>
 </indexterm>

 <para>
  Le module <filename>contrib/spi</filename> fournit plusieurs exemples
  fonctionnels d'utilisation de SPI et des déclencheurs. Bien que ces fonctions aient un
  intérêt certain, elles sont encore plus utiles en tant qu'exemples
  à modifier pour atteindre ses propres buts. Les fonctions sont suffisamment
  généralistes pour être utilisées avec une table quelconque, mais la création d'un
  déclencheur impose que les noms des tables et des champs soient précisés
  (comme cela est décrit ci-dessous).
 </para>

 <sect2>
  <title>refint.c &mdash; fonctions de codage de l'intégrité
  référentielle</title>

  <para>
   <function>check_primary_key()</function> et
   <function>check_foreign_key()</function> sont utilisées pour vérifier les
   contraintes de clé étrangère. (Cette fonctionnalité est dépassée depuis
   longtemps par le mécanisme interne, mais le module conserve un rôle
   d'exemple.)
  </para>

  <para>
   <function>check_primary_key()</function> vérifie la table de référence.
   Pour l'utiliser, on crée un déclencheur <literal>BEFORE INSERT OR UPDATE</literal>
   qui utilise cette fonction sur une table référençant une autre table.
   En arguments du déclencheur, on trouve&nbsp;: le nom de la colonne
   de la table référençant qui forme la clé étrangère, le nom de la table
   référencée et le nom de la colonne de la table référencée qui forme la
   clé primaire/unique. Il peut y avoir plusieurs colonnes. Pour gérer
   plusieurs clés étrangères, on crée un déclencheur pour chaque référence.
  </para>

  <para>
   <function>check_foreign_key()</function> vérifie la table référencée.
   Pour l'utiliser, on crée un déclencheur <literal>BEFORE DELETE OR UPDATE</literal>
   qui utilise cette fonction sur une table référencée par d'autres tables.
   En arguments du déclencheur, on trouve&nbsp;: le nombre de tables référençant pour
   lesquelles la fonction réalise la vérification, l'action à exécuter si une clé
   de référence est trouvée (<literal>cascade</literal> &mdash; pour supprimer
   une ligne qui référence, <literal>restrict</literal> &mdash; pour annuler la
   transaction si des clés de référence existent, <literal>setnull</literal>
   &mdash; pour initialiser les champs des clés référençant à NULL), les noms
   des colonnes de la table surveillées par le déclencheur, colonnes qui
   forment la clé primaire/unique, puis le nom de la table référençant et les noms des
   colonnes (répétés pour autant de tables référençant que cela est précisé par
   le premier argument). Les colonnes de clé
   primaire/unique doivent être marquées NOT NULL et posséder un index
   d'unicité.
  </para>

  <para>
   Il y a des exemples dans <filename>refint.example</filename>.
  </para>
 </sect2>

 <sect2>
  <title>timetravel.c &mdash; fonctions de codage du voyage dans le
  temps</title>

  <para>
   Dans le passé, <productname>PostgreSQL</productname> disposait d'une fonctionnalité
   de voyage dans le temps, permettant de conserver l'heure d'insertion et
   de suppression de chaque ligne. Ce comportement peut être émulé en
   utilisant ces fonctions. Pour les utiliser, il faut ajouter deux champs
   de type <type>abstime</type> à la table pour stocker le moment où une
   ligne a été insérée (start_date) et le moment où elle a été
   modifiée/supprimée (stop_date)&nbsp;:

<programlisting>
CREATE TABLE mytab (
        ...             ...
        start_date      abstime,
        stop_date       abstime
        ...             ...
);
</programlisting>

   Le nom des colonnes n'a aucune importance, mais dans ce
   chapitre, elles sont nommées start_date et stop_date.
  </para>

  <para>
   À l'insertion d'une nouvelle ligne, start_date doit normalement
   être initialisée à l'heure courante et stop_date à
   <literal>infinity</literal>. Le déclencheur substitue automatiquement ces
   valeurs si les données insérées sont NULL pour ces colonnes.
   L'insertion de données explicitement non-NULL dans ces colonnes n'intervient
   qu'au rechargement de données sauvegardées.
  </para>

  <para>
   Les lignes pour lesquelles stop_date vaut <literal>infinity</literal> sont des
   lignes <quote>actuellement valides</quote>, et peuvent être modifiées.
   Les lignes dont stop_date est fini ne peuvent plus être modifiées &mdash;
   le déclencheur les protège. (Pour les modifier, il est nécessaire de
   désactiver le voyage dans le temps comme indiqué ci-dessous.)
  </para>

  <para>
   Pour une ligne modifiable en mise à jour, seul stop_date est
   modifié (positionné à l'heure courante) et une nouvelle ligne avec la donnée modifiée
   est insérée. Pour cette nouvelle ligne, start_date est positionné à
   l'heure courante et stop_date à <literal>infinity</literal>.
  </para>

  <para>
   Une suppression ne supprime pas réellement la ligne mais positionne
   stop_date à l'heure courante.
  </para>

  <para>
   Pour trouver les lignes <quote>actuellement valides</quote>, on ajoute la
   clause <literal>stop_date = 'infinity'</literal> dans la condition
   WHERE de la requête. (Cela peut se faire au travers d'une vue.) De façon
   similaire, une requête peut être exécutée sur les lignes valides à
   un moment du passé si des conditions adéquates sont posées sur
   start_date et stop_date.
  </para>

  <para>
   <function>timetravel()</function> est la fonction déclencheur générique
   associée à ce fonctionnement.
   On crée un déclencheur <literal>BEFORE INSERT OR UPDATE
   OR DELETE</literal> qui utilise cette fonction pour chaque table sur laquelle
   la fonctionnalité de voyage dans le temps est activée. Le déclencheur
   accepte deux arguments&nbsp;: les noms réels des colonnes start_date et
   stop_date. La fonction accepte jusqu'à trois arguments optionnels
   qui doivent faire référence à des colonnes de type
   <type>text</type>. Le déclencheur stocke le nom de l'utilisateur courant
   dans la première de ces colonnes lors d'un INSERT, dans la seconde lors
   d'un UPDATE et dans la troisième lors un DELETE.
  </para>

  <para>
   <function>set_timetravel()</function> permet d'activer et de
   désactiver la fonctionnalité de voyage dans le temps pour une table.
   <literal>set_timetravel('ma_table', 1)</literal> l'active pour la table
   ma_table.
   <literal>set_timetravel('ma_table', 0)</literal> la désactive pour la table
   ma_table.
   Dans les deux cas, l'ancien statut est rapporté. Quand elle est
   désactivée, les colonnes start_date et stop_date peuvent être librement
   modifiées. Le statut actif/inactif est local à la session
   courante &mdash; toute session commence avec cette
   fonctionnalité activée sur toutes les tables.
  </para>

  <para>
   <function>get_timetravel()</function> renvoie l'état de la fonctionnalité
   du voyage dans le temps pour une table sans le modifier.
  </para>

  <para>
   Il y a un exemple dans <filename>timetravel.example</filename>.
  </para>
 </sect2>

 <sect2>
  <title>autoinc.c &mdash; fonctions pour l'incrémentation automatique
  d'un champ</title>

  <para>
   <function>autoinc()</function> est un déclencheur qui stocke la prochaine valeur
   d'une séquence dans un champ de type integer. Cela recouvre quelque peu
   la fonctionnalité interne de la colonne <quote>serial</quote>, mais
   ce n'est pas strictement identique&nbsp;: <function>autoinc()</function>
   surcharge les tentatives de substitution d'une valeur différente pour ce
   champ lors des insertions et, optionnellement, peut aussi être utilisé pour
   incrémenter le champ lors des mises à jour.
  </para>

  <para>
   Pour l'utiliser, on crée un déclencheur <literal>BEFORE INSERT</literal> (ou
   en option <literal>BEFORE INSERT OR UPDATE</literal>) qui utilise cette
   fonction. Le déclencheur accepte deux arguments&nbsp;: le nom de la
   colonne de type integer à modifier et le nom de la séquence qui fournit
   les valeurs. (En fait, plusieurs paires de noms peuvent être indiquées pour 
   actualiser plusieurs colonnes.)
  </para>

  <para>
   Un exemple est fourni dans <filename>autoinc.example</filename>.
  </para>

 </sect2>

 <sect2>
  <title>insert_username.c &mdash; fonctions pour tracer les utilisateurs qui
  ont modifié une table</title>

  <para>
   <function>insert_username()</function> est un déclencheur qui stocke le
   nom de l'utilisateur courant dans un champ texte. C'est utile pour
   savoir quel est le dernier utilisateur à avoir modifié une ligne particulière d'une
   table.
  </para>

  <para>
   Pour l'utiliser, on crée un déclencheur <literal>BEFORE INSERT</literal> et/ou
   <literal>UPDATE</literal> qui utilise cette fonction. Le déclencheur prend
   pour seul argument le nom de la colonne texte à modifier.
  </para>

  <para>
   Un exemple est fourni dans <filename>insert_username.example</filename>.
  </para>

 </sect2>

 <sect2>
  <title>moddatetime.c &mdash; fonctions pour tracer la date et l'heure
  de la dernière modification</title>

  <para>
   <function>moddatetime()</function> est un déclencheur qui stocke la date et
   l'heure de la dernière modification dans un champ de type
   <type>timestamp</type>. C'est utile pour savoir quand a eu lieu la
   dernière modification sur une ligne particulière d'une table.
  </para>

  <para>
   Pour l'utiliser, on crée un déclencheur <literal>BEFORE UPDATE</literal> qui
   utilise cette fonction. Le déclencheur prend pour seul argument le
   nom de la colonne de type <type>timestamp</type> à modifier.
  </para>

  <para>
   Un exemple est fourni dans <filename>moddatetime.example</filename>.
  </para>

 </sect2>

</sect1>