root/traduc/branches/bv747/manuel/ref/create_function.sgml

<!--
$Header: /var/lib/cvs/pgsql-fr/sgml/ref/create_function.sgml,v 1.7.2.1 2005/03/20 22:34:41 guillaume Exp $
-->

<refentry id="SQL-CREATEFUNCTION">
 <refmeta>
  <refentrytitle id="SQL-CREATEFUNCTION-TITLE">CREATE FUNCTION</refentrytitle>
  <refmiscinfo>SQL - Instructions du langage</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE FUNCTION</refname>
  <refpurpose>définit une nouvelle fonction</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createfunction">
  <primary>CREATE FUNCTION</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">nom</replaceable>
( [ <replaceable class="parameter">type_arg</replaceable> [, ...] ] )
    RETURNS <replaceable class="parameter">type_ret</replaceable>
  { LANGUAGE <replaceable class="parameter">nomlang</replaceable>
    | IMMUTABLE | STABLE | VOLATILE
    | CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
    | [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER
    | AS '<replaceable class="parameter">definition</replaceable>'
    | AS '<replaceable class="parameter">fichier_obj</replaceable>', '<replaceable class="parameter">symbole_lien</replaceable>'
  } ...
    [ WITH ( <replaceable class="parameter">attribut</replaceable> [, ...] ) ]
</synopsis>
 </refsynopsisdiv>
  
 <refsect1 id="sql-createfunction-description">
  <title>Description</title>

  <para>
   <command>CREATE FUNCTION</command> définit une nouvelle fonction.
   <command>CREATE OR REPLACE FUNCTION</command> créera une nouvelle fonction
   ou remplacera une fonction existante.
  </para>

  <para>
   Si un nom de schéma est inclus, alors la fonction est créée dans le schéma
   spécifié. Sinon, elle est créée dans le schéma courant. Le nom de la nouvelle
   fonction ne doit pas correspondre à une autre fonction existante avec les
   mêmes types d'argument dans le même schéma. Néanmoins, les fonctions de types
   d'arguments différents pourraient partager un nom (ceci est appelé le
   <firstterm>surchargement</>).
  </para>

  <para>
   Pour mettre à jour la définition d'une fonction existante, utilisez
   <command>CREATE OR REPLACE FUNCTION</command>. Il n'est pas possible de
   changer le nom ou les types d'argument d'une fonction de cette façon (si vous
   avez essayé, vous devrez seulement créer une nouvelle fonction distincte). De
   même, <command>CREATE OR REPLACE FUNCTION</command> ne vous laissera pas
   modifier le type en retour d'une fonction existante. Pour cela, vous devez
   supprimer et recréer la fonction.
  </para>

  <para>
   Si vous supprimez, puis recréez une fonction, la nouvelle fonction n'est pas
   la même entité que l'ancienne&nbsp;; vous casserez les règles, vues,
   déclencheurs, etc. qui référençaient l'ancienne fonction. Utilisez
   <command>CREATE OR REPLACE FUNCTION</command> pour modifier la définition
   d'une fonction sans casser d'objets qui se réfèrent à la fonction.
  </para>

  <para>
   L'utilisateur qui crée la fonction devient le propriétaire de la fonction.
  </para>
 </refsect1>

 <refsect1>
  <title>Paramètres</title>

   <variablelist>

    <varlistentry>
     <term><replaceable class="parameter">nom</replaceable></term>

     <listitem>
      <para>
       Le nom d'une fonction à créer.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">typearg</replaceable></term>

     <listitem>
      <para>
       Le type de données des arguments de la fonction (qualifié ou non du nom
       du schéma), s'il y en a. Les types d'argument pourraient être de base,
       complexe ou des domaines ou copier le type d'une colonne existante.
      </para>
      <para>
       Le type d'une colonne est référencé en lançant
       <literal><replaceable
       class="parameter">nomtable</replaceable>.<replaceable
       class="parameter">nomcolonne</replaceable>%TYPE</literal>&nbsp;;
       utiliser ceci peut quelque fois vous aider à rendre la fonction
       indépendante des modifications de la définition d'une table.
      </para>
      <para>
       Suivant le langage d'implémentation, il pourrait aussi être autorisé de
       spécifier des <quote>pseudotypes</> plutôt que des <type>cstring</>. Les
       pseudotypes indiquent que le type d'argument réel est soit non
       complètement spécifié, soit en dehors de l'ensemble des types de données
       ordinaires SQL.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">typeret</replaceable></term>

     <listitem>
      <para>
       Le type de données en retour (pouvant être qualifié du nom du schéma).
       Le type de retour pourrait être un type de base, complexe ou un domaine,
       ou pourrait être spécifié pour copier le type d'une colonne existante.
       Voir la description sous <literal>typearg</literal> ci-dessus pour savoir
       comment référencer le type d'une colonne existante.
      </para>
      <para>
       Suivant le langage d'implémentation, il pourrait aussi être autorisé de
       spécifier un <quote>pseudotype</> tel que <type>cstring</>. Le
       modificateur <literal>SETOF</literal> indique que la fonction renverra un
       ensemble d'éléments plutôt qu'un seul élément.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">nomlang</replaceable></term>

     <listitem>
      <para>
       Le nom du langage dans laquelle la fonction est implémentée. Pourrait
       être <literal>SQL</literal>, <literal>C</literal>,
       <literal>internal</literal> ou le nom d'un langage de procédures défini
       par l'utilisateur. (Voir aussi <xref linkend="app-createlang"
       endterm="app-createlang-title">.) Pour une compatibilité ascendante, le
       nom peut être englobé avec des guillemets simples.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>IMMUTABLE</literal></term>
     <term><literal>STABLE</literal></term>
     <term><literal>VOLATILE</literal></term>

     <listitem>
      <para>
       Ces attributs informent le système s'il est sain de remplacer plusieurs
       évaluations de la fonction avec une seule évaluation pour une
       optimisation en exécution. Au plus un choix devra être donné. Si aucun
       n'apparaît, <literal>VOLATILE</literal> est la valeur par défaut.
      </para>

      <para>
       <literal>IMMUTABLE</literal> indique que la fonction renvoie toujours le
       même résultat si elle reçoit les mêmes valeurs en argument&nbsp;;
       c'est-à-dire qu'elle n'effectue pas de recherches dans la base de données
       ou, autrement, qu'elle utilise l'information non présente directement
       dans la liste d'arguments. Si cette option est donnée, tout appel de la
       fonction avec des arguments constants peut être immédiatement remplacé
       par la valeur de la fonction.
      </para>

      <para>
       <literal>STABLE</literal> indique qu'à l'intérieur d'un seul parcours de
       la table, la fonction renverra le même résultat pour les mêmes valeurs
       d'argument, mais son résultat pourrait varier au travers des
       instructions SQL. Ceci est la sélection appropriée pour les fonctions
       dont les résultats dépendent des recherches en base de données, des
       variables paramètres (tel que la zone horaire en cours), etc. Notez aussi
       que la famille de fonctions <function>current_timestamp</> est qualifiée
       de stable car leur valeur ne change pas à l'intérieur d'une transaction.
      </para>

      <para>
       <literal>VOLATILE</literal> indique que la valeur de la fonction peut
       changer même avec un seul parcours de table, donc aucune optimisation ne
       peut être réalisée. Relativement peu de fonctions de bases de données
       sont volatiles dans ce sens&nbsp;; quelques exemples sont
       <literal>random()</>, <literal>currval()</>, <literal>timeofday()</>.
       Notez que toute fonction qui a des effets de bord doit être classée
       comme volatile, même si son résultat est assez prévisible pour empêcher
       l'optimisation des appels&nbsp;; un exemple est <literal>setval()</>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>CALLED ON NULL INPUT</literal></term>
     <term><literal>RETURNS NULL ON NULL INPUT</literal></term>
     <term><literal>STRICT</literal></term>

     <listitem>
      <para>
       <literal>CALLED ON NULL INPUT</literal> (la valeur par défaut) indique
       que la fonction sera appelée normalement quand certains de ses arguments
       sont NULL. C'est alors de la responsabilité de l'auteur de la fonction de
       vérifier les valeurs NULL si nécessaire et de répondre en conséquence.
      </para>

      <para>
       <literal>RETURNS NULL ON NULL INPUT</literal> ou
       <literal>STRICT</literal> indiquent que la fonction renvoie toujours
       NULL si un de ces arguments est NULL. Si ce paramètre est spécifié, la
       fonction n'est pas exécutée quand il y a des arguments NULL&nbsp;; à la
       place, un résultat NULL est automatiquement renvoyé.
      </para>
     </listitem>
    </varlistentry>

   <varlistentry>
    <term><literal><optional>EXTERNAL</optional> SECURITY INVOKER</literal></term>
    <term><literal><optional>EXTERNAL</optional> SECURITY DEFINER</literal></term>

    <listitem>
     <para>
      <literal>SECURITY INVOKER</literal> indique que la fonction doit être
      exécutée avec les droits de l'utilisateur qui l'appelle. C'est la valeur
      par défaut. <literal>SECURITY DEFINER</literal> spécifie que la fonction
      doit être exécutée avec les droits de l'utilisateur qui l'a créé.
     </para>

     <para>
      Le mot clé <literal>EXTERNAL</literal> est présent pour la conformité SQL
      mais est optionnelle car, contrairement à SQL, cette fonctionnalité ne
      s'applique qu'aux fonctions externes.
     </para>
    </listitem>
   </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">definition</replaceable></term>

     <listitem>
      <para>
       Une chaîne définissant la fonction&nbsp;; la signification dépend du
       langage. Cela pourrait être un nom de fonction interne, le chemin vers un
       fichier objet, une commande SQL ou un texte dans un langage de
       procédures.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal><replaceable
        class="parameter">fichier_obj</replaceable>, <replaceable
        class="parameter">symbole_lien</replaceable></literal></term>

     <listitem>
      <para>
       Cette forme de clause <literal>AS</literal> est utilisée pour les
       fonctions en langage C chargeables dynamiquement quand le nom de la
       fonction dans le code source C n'est pas le même que celui de la fonction
       C. La chaîne <replaceable class="parameter">fichier_obj</replaceable> est
       le nom du fichier contenant l'objet chargeable dynamiquement et
       <replaceable class="parameter">symbole_lien</replaceable> est le symbole
       de lien de la fonction, c'est-à-dire le nom de la fonction dans le code
       source C. Si ce lien est omis, il est supposé être le même que le nom de
       la fonction en cours de définition.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">attribut</replaceable></term>

     <listitem>
      <para>
       La façon historique de spécifier les morceaux optionnels d'informations
       sur la fonction. Les attributs suivants pourraient apparaître ici&nbsp;:

      <variablelist>
       <varlistentry>
        <term><literal>isStrict</></term>
        <listitem>
         <para>
          Équivalent à <literal>STRICT</literal> ou <literal>RETURNS NULL ON
          NULL INPUT</literal>
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>isCachable</></term>
        <listitem>
         <para>
          <literal>isCachable</literal> est un équivalent obsolète de
          <literal>IMMUTABLE</literal>&nbsp;; il est toujours accepté pour des
          raisons de compatibilité ascendante.
         </para>
        </listitem>
       </varlistentry>

      </variablelist>

      Les noms d'attribut ne sont pas sensibles à la casse.
     </para>
    </listitem>
   </varlistentry>

   </variablelist>

 </refsect1>

 <refsect1 id="sql-createfunction-notes">
  <title>Notes</title>

   <para>
    Référez-vous à <xref linkend="xfunc"> pour plus d'informations sur
    l'écriture de fonctions.
   </para>

   <para>
    La syntaxe complète de type <acronym>SQL</acronym> est autorisée pour les
    arguments en entrée et pour la valeur de sortie. Néanmoins, quelques détails
    de spécification de type (c'est-à-dire le champ précision pour le type
    <type>numeric</type>) sont de la responsabilité de l'implémentation de la
    fonction sous-jacente et sont silencieusement avalés (c'est-à-dire non
    reconnus ou forcés) par la commande <command>CREATE FUNCTION</command>.
   </para>

   <para>
    <productname>PostgreSQL</productname> autorise le
    <firstterm>surchargement</firstterm> de fonctions&nbsp;; c'est-à-dire que
    le même nom peut être utilisé pour plusieurs fonctions différentes si tant
    est qu'elles ont des types d'arguments distincts. Néanmoins, les noms C de
    toutes les fonctions doivent être différents, donc vous devez donner des
    noms différentes aux fonctions C suchargées (par exemple, utilisez les
    types d'argument comme morceaux des noms des fonctions C).
   </para>

   <para>
    Lors d'appels répétés à <command>CREATE FUNCTION</command> et se référant
    au même fichier objet, le fichier est chargé une seule fois. Pour décharger
    et recharger le fichier (peut-être pendant le développement), utilisez la
    commande <xref linkend="sql-load" endterm="sql-load-title">.
   </para>

   <para>
    Utilisez <command>DROP FUNCTION</command> pour supprimer les fonctions
    définies par l'utilisateur.
   </para>

  <para>
   Tout guillemet simple ou antislash dans la définition de la fonction doit
   être échappé en le doublant.
  </para>

   <para>
    Pour être capable de définir une fonction, l'utilisateur doit avoir le droit
    <literal>USAGE</literal> sur le langage.
   </para>

 </refsect1>

 <refsect1 id="sql-createfunction-examples">
  <title>Exemples</title>

  <para>
   Voici un exemple trivial pour vous aider à commencer. Pour plus
   d'informations et d'exemples, voir <xref linkend="xfunc">.
<programlisting>
CREATE FUNCTION add(integer, integer) RETURNS integer
    AS 'select $1 + $2;'
    LANGUAGE SQL
    IMMUTABLE
    RETURNS NULL ON NULL INPUT;
</programlisting>
  </para>
 </refsect1>

 <refsect1 id="sql-createfunction-security">
  <title>Écrire des fonctions <literal>SECURITY DEFINER</literal> en toute
    sécurité</title>

   <para>
    Comme une fonction <literal>SECURITY DEFINER</literal> est exécutée
    avec les droits de l'utilisateur qui l'a créé, une certaine attention
    est nécessaire pour s'assurer que la fonction ne peut pas être
    utilisée de façon maline. Pour des raisons de sécurité,
    <xref linkend="guc-search-path"> doit être configuré pour exclure tout
    schéma où des utilisateurs qui ne sont pas de confiance pourraient
    écrire. Ceci empêche des utilisateurs malveillants de créer des
    objets qui masqueraient des objets utilisés par la fonction. Dans
    cette idée, le schéma des tables temporaires est particulièrement
    important car il est le premier schéma dans lequel a lieu la recherche
    et il est modifiable par tout utilisateur. Une solution est de forcer
    la recherche à ne prendre en condition ce schéma qu'en dernier lieu.
    Pour cela, écrire <literal>pg_temp</> en tant que dernière entrée de
    <varname>search_path</>. La fonction suivante illustre une utilisation
    sûre&nbsp;:
   </para>

<programlisting>
CREATE FUNCTION verifie_motdepasse(unom TEXT, motpasse TEXT)
RETURNS BOOLEAN AS $$
DECLARE ok BOOLEAN;
        ancien_path TEXT;
BEGIN
        -- Sauvegarder l'ancien search_path ;
        -- remarquez que nous devons qualifier current_setting
        -- pour nous assurer que nous appelons la bonne fonction
        ancien_path := pg_catalog.current_setting('search_path');

        -- Configurer un search_path sécurisé : schémas de confiance, puis 'pg_temp'.
        -- Nous initialisons is_local = true pour que l'ancienne valeur
        -- soit restaurée au cas où une erreur survienne avant que nous
        -- n'atteignons la fin de la fonction.
        PERFORM pg_catalog.set_config('search_path', 'admin, pg_temp', true);

        -- Effectuer le travail sécurisé de la fonction.
        SELECT  (motdepasse = $2) INTO ok
        FROM    motsdepasse
        WHERE   nomutilisateur = $1;

        -- Restaurer le search_path de l'appelant
        PERFORM pg_catalog.set_config('search_path', ancien_path, true);

        RETURN ok;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
</programlisting>

 </refsect1>

 <refsect1 id="sql-createfunction-compat">
  <title>Compatibilité</title>

  <para>
   Une commande <command>CREATE FUNCTION</command> est définie en SQL99.
   La version <productname>PostgreSQL</productname> est similaire mais pas
   entièrement compatible. Les attributs ne sont pas portables, pas plus que
   les différents langages disponibles.
  </para>
 </refsect1>


 <refsect1 id="sql-createfunction-seealso">
  <title>Voir aussi</title>

  <para>
   <xref linkend="sql-alterfunction" endterm="sql-alterfunction-title">,
   <xref linkend="sql-dropfunction" endterm="sql-dropfunction-title">,
   <xref linkend="sql-grant" endterm="sql-grant-title">,
   <xref linkend="sql-load" endterm="sql-load-title">,
   <xref linkend="sql-revoke" endterm="sql-revoke-title">,
   <xref linkend="app-createlang">
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->