PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 15.10 » Référence » Commandes SQL » CREATE PROCEDURE

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 COMMITet 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.