Documentation PostgreSQL 14.22 » Référence » Commandes SQL » CREATE PROCEDURE

Précédent | Niveau supérieur | Suivant
CREATE POLICY | Sommaire | CREATE PUBLICATION

## CREATE PROCEDURE

CREATE PROCEDURE — définit une nouvelle procédure stockée

## Synopsis

    CREATE [ OR REPLACE ] PROCEDURE
        nom ( [ [ mode_argument ] [ nom_argument ] type_argument [ { DEFAULT | = } expr_defaut ] [, ...] ] )
      { LANGUAGE nom_langage
        | TRANSFORM { FOR TYPE nom_type } [, ... ]
        | [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
        | SET parametre_configuration { TO valeur | = valeur | FROM CURRENT }
        | AS 'definition'
        | AS 'fichier_objet', 'symbole_lien'
        | corps_sql
      } ...

## Description

`CREATE PROCEDURE` définit une nouvelle procédure. `CREATE OR REPLACE PROCEDURE` va définir une nouvelle procédure, ou remplacer une définition existante. Pour pouvoir définir une procédure, l'utilisateur doit avoir le privilège `USAGE` sur le langage.

Si le nom du schéma est inclus, alors la procédure est créée dans le schéma spécifié. Sinon elle est créée dans le schéma courant. Le nom de la nouvelle procédure ne doit correspondre à aucune procédure ou fonction existante possédant les mêmes types d'arguments dans le même schéma. Cependant, des procédures et fonctions avec des arguments de types différents peuvent partager le même nom (on appelle cela surcharge ou overloading).

Pour remplacer la définition en cours d'une procédure existante, utilisez `CREATE OR REPLACE PROCEDURE`. Il n'est pas possible de changer le nom ou les types d'arguments d'une procédure avec cette méthode (si vous le faites, vous créez en fait une nouvelle procédure distincte).

Si `CREATE OR REPLACE PROCEDURE` est utilisé pour remplacer une procédure existante, le propriétaire et les permissions sur la procédure ne changent pas. Toutes les autres propriétés de la procédure se voient assignées les valeurs spécifiées dans la commande. Vous devez être propriétaire de la procédure pour la remplacer (cela fonctionne aussi si vous êtes membre du rôle propriétaire).

L'utilisateur qui crée la procédure devient son propriétaire.

Pour pouvoir créer une procédure, vous devez avoir le privilège `USAGE` sur les types des arguments.

La lecture de Section 38.3 fournit des informations supplémentaires sur l'écriture de procédures.

## Paramètres

`nom`

  Le nom (éventuellement qualifié par un schéma) de la procédure à créer.

`mode_argument`

  Le mode d'un argument : `IN`, `OUT`, `INOUT` ou `VARIADIC`. Sans précision, le défaut est `IN`.

`nom_argument`

  Le nom d'un argument.

`type_argument`

  Le(s) type(s) des arguments de la procédure (éventuellement qualifiés par un schéma), s'il y en a. Ils peuvent être les types de base, des types composites, des domaines, ou des références à un type d'une colonne d'une table.

  Selon le langage d'implémentation, il peut être permis de spécifier des « pseudo-types » comme `cstring`. Les pseudo-types indiquent le type d'argument que est soit incomplètement spécifié, soit en dehors des types de données ordinaires.

  On fait référence au type d'une colonne en écrivant ``table_name`.`column_name`%TYPE`. Cette fonctionnalité permet parfois de rendre une procédure indépendante des changements de définition d'une table.

`expr_defaut`

  Une expression à utiliser comme valeur par défaut si le paramètre n'est pas spécifié. L'expression doit respecter le type d'argument du paramètre. Tous les paramètres en entrée suivant un paramètre avec une valeur par défaut doivent en avoir une également.

`nom_langage`

  Le nom du langage dans lequel la procédure est implémentée. Ce peut être `sql`, `c`, `internal` ou le nom d'un langage procédural défini par l'utilisateur, par exemple `plpgsql`. La valeur par défaut est `sql` si `corps_sql` est indiqué. Mettre le nom entre guillemets simples est obsolète et exige une casse identique.

`TRANSFORM { FOR TYPE `nom_type` } [, ... ] }`

  Liste les transformations qu'un appel à la procédure devrait appliquer. Les transformations opèrent des conversions entre les types SQL et les types de données spécifiques au langage ; voir CREATE TRANSFORM. D'habitude les implémentations des langages procéduraux connaissent d'entrée les types internes, ces derniers n'ont donc pas besoin d'être listés ici. Si une implémentation d'un langage procédural ne sait pas traiter un type et qu'aucune transformation n'est fournie, elle se rabattra sur un comportement par défaut pour convertir les données, mais cela dépend de l'implémentation.

`[EXTERNAL] SECURITY INVOKER`
`[EXTERNAL] SECURITY DEFINER`

  `SECURITY INVOKER` indique que la procédure doit être exécutée avec les privilèges de l'utilisateur qui l'appelle. C'est le défaut. `SECURITY DEFINER` spécifie que la procédure doit être exécutée avec les privilèges de l'utilisateur qui la possède.

  Le mot clé `EXTERNAL` est permis pour la conformité envers le standard SQL, mais il est optionnel puisque, contrairement au SQL, cette fonctionnalité concerne toutes les procédures, et pas seulement les externes.

  Une procédure `SECURITY DEFINER` ne peut exécuter des commandes de contrôle de transaction (par exemple `COMMIT` et `ROLLBACK`, selon le langage).

`parametre_configuration`
`valeur`

  Avec la clause `SET`, le paramètre de configuration indiqué sera positionné à la valeur spécifiée à l'entrée dans la procédure, puis restauré à la valeur précédente à la sortie. `SET FROM CURRENT` mémorise la valeur du paramètre en cours au moment où `CREATE PROCEDURE` a été exécuté comme la valeur à appliquer à l'entrée dans la procédure.

  Si une clause `SET` est attachée à une procédure, alors les effets d'une commande `SET LOCAL` exécutée au sein de la procédure pour la même variable sont restreints à cette procédure : l'ancienne valeur du paramètre est toujours restaurée à la sortie de la procédure. Cependant, une commande `SET` ordinaire (sans `LOCAL`) a priorité sur la clause `SET`, tout comme elle le ferait sur un ordre `SET LOCAL` précédent : les effets d'une telle commande persisteront après la sortie de la procédure, à moins que la transaction en cours ne soit annulée.

  Si une clause `SET` est attachée à une procédure, alors cette procédure ne peut exécuter d'ordres de contrôle de transaction (comme `COMMIT`et `ROLLBACK`, selon le langage).

  Voir SET et Chapitre 20 pour plus d'informations sur les noms et valeurs de paramètres autorisés.

`definition`

  Une chaîne de caractères constante définissant la procédure ; sa signification dépend du langage. Ce peut être un nom de procédure interne, le chemin d'un fichier objet, un ordre SQL, ou du texte dans un langage procédural.

  Le dollar quoting (voir Section 4.1.2.4) est souvent utile pour écrire la chaîne de définition de la fonction, plutôt que la syntaxe normale à simple guillemet. Sans dollar quoting, le moindre guillemet ou backslash dans la définition de la procédure doit être échappé et donc doublé.

``fichier_objet`, `symbole_lien``

  Cette forme de la clause `AS` est utilisée pour les procédures en C chargées dynamiquement, quand le nom de la procédure dans le code source en C n'est pas le même que le nom de la procédure SQL. La chaîne `fichier_objet` est le nom de la bibliothèque partagée contenant la procédure C compilée, et est interprétée comme dans la commande `LOAD`. La chaîne `symbole_lien` est le symbole de lien de la procédure, c'est-à-dire le nom de la procédure dans le code source en C. Si le symbole de lien est absent, on suppose qu'il est le même que le nom de la procédure en train d'être définie.

  Quand des commandes `CREATE PROCEDURE` répétées se réfèrent au même fichier objet, celui-ci n'est chargé d'une fois par session. Pour décharger et recharger le fichier (peut-être pendant le développement), démarrez une nouvelle session.

`corps_sql`

  Le corps d'une procédure `LANGUAGE SQL`. Cela devrait être un bloc

      BEGIN ATOMIC
        instruction;
        instruction;
        ...
        instruction;
      END

  Ceci est similaire à écrire le texte du corps de la procédure sous la forme d'une chaîne constante (voir `definition` ci-dessus), mais il existe quelques différences : Cette forme fonctionne seulement pour `LANGUAGE SQL`, la forme de chaîne constante fonctionne pour tous les langages. Cette forme est analysée au moment de la défintion de la procédure, la forme de chaîne constante est analysée au moment de l'exécution ; de ce fait, cette forme ne supporte pas les arguments de type polymorphique et les autres constructions qui ne sont pas analysables au moment de la définition. Cette forme traque les dépendances entres la procédure et les objets utilisés dans le corps de la procédure, donc un `DROP ... CASCADE` fonctionnera correctement, alors que la forme utilisant une chaîne pourrait laisser des procédures invalides. Enfin, cette forme est plus compatible avec le standard SQL et les autres implémentations SQL.

## Notes

voir CREATE FUNCTION pour plus de détails sur la création de fonctions, qui s'appliquent aussi aux procédures.

Utilisez CALL pour exécuter une procédure.

## Exemples

    CREATE PROCEDURE insert_data(a integer, b integer)
    LANGUAGE SQL
    AS $$
    INSERT INTO tbl VALUES (a);
    INSERT INTO tbl VALUES (b);
    $$;

ou

    CREATE PROCEDURE insert_data(a integer, b integer)
    LANGUAGE SQL
    BEGIN ATOMIC
      INSERT INTO tbl VALUES (a);
      INSERT INTO tbl VALUES (b);
    END;

et l'appeler ainsi :

    CALL insert_data(1, 2);

## Compatibilité

Une commande `CREATE PROCEDURE` est définie dans le standard SQL. L'implémentation de PostgreSQL peut être utilisée d'une façon compatible mais a de nombreuses extensions. Pour plus de détails, voir aussi CREATE FUNCTION.

## Voir aussi

ALTER PROCEDURE, DROP PROCEDURE, CALL, CREATE FUNCTION