PostgreSQLLa base de données la plus sophistiquée au monde.

Version anglaise

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'
  } ...

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.

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, INOUT ou VARIADIC. Sans précision, le défaut est IN. (Les arguments OUT ne sont actuellement pas supportés pour les procédures. Utilisez à la place INOUT.)

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. 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(7). 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(7) et Chapitre 19, Configuration du serveur 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, « Constantes de chaînes avec guillemet dollar ») 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(7). 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.

Notes

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

Utilisez CALL(7) 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);
$$;

CALL insert_data(1, 2);

Compatibilité

Une commande CREATE PROCEDURE est définie dans le standard SQL. La version de PostgreSQL™ est similaire mais pas complètement compatible. Pour plus de détails, voir aussi CREATE FUNCTION(7).