42.9. Erreurs et messages

» » »

Précédent	Niveau supérieur	Suivant
42.8. Gestion des transactions	Sommaire	42.10. Fonctions trigger

42.9. Erreurs et messages

42.9.1. Rapporter des erreurs et messages
42.9.2. Vérification d'assertions

42.9.1. Rapporter des erreurs et messages

Utilisez l'instruction RAISE pour rapporter des messages et lever des erreurs.

RAISE [ niveau ] 'format' [, expression [, ...]] [ USING option = expression [, ... ] ];
RAISE [ niveau ] nom_condition [ USING option = expression [, ... ] ];
RAISE [ niveau ] SQLSTATE 'état_sql' [ USING option = expression [, ... ] ];
RAISE [ niveau ] USING option = expression [, ... ];
RAISE ;

L'option niveau indique la sévérité de l'erreur. Les niveaux autorisés sont DEBUG, LOG, INFO, NOTICE, WARNING et EXCEPTION, ce dernier étant la valeur par défaut. EXCEPTION lève une erreur (ce qui annule habituellement la transaction en cours). Les autres niveaux ne font que générer des messages aux différents niveaux de priorité. Les variables de configuration log_min_messages et client_min_messages contrôlent l'envoi de messages dans les traces, au client ou aux deux. Voir le Chapitre 19 pour plus d'informations.

Après niveau, vous pouvez écrire un format (qui doit être une chaîne litérale, pas une expression). La chaîne format indique le texte du message d'erreur à rapporter. Elle peut être suivie par des expressions optionnelles à insérer dans le message. Dans la chaîne, % est remplacé par la représentation de la valeur du prochain argument. Écrivez %% pour saisir un % litéral. Le nombre des arguments doit correspondre au nombre de % dans la chaîne format, sinon une erreur est levée durant la compilation de la fonction.

Dans cet exemple, la valeur de v_job_id remplace le % dans la chaîne.

RAISE NOTICE 'Appel de cs_creer_job(%)', v_job_id;

Vous pouvez attacher des informations supplémentaires au rapport d'erreur en écrivant USING suivi par des éléments option = expression. Chaque expression peut valoir n'importe quel expression sous forme de chaîne. Les mots clés autorisés option sont :

MESSAGE: Configure le texte du message d'erreur. Cette option ne peut pas être utilisée dans la forme d'un RAISE qui inclut une chaîne de format avec USING.
DETAIL: Fournit un message de détail sur l'erreur.
HINT: Fournit un message de conseil sur l'erreur.
ERRCODE: Spécifie le code d'erreur (SQLSTATE) à rapporter, soit par son nom de condition comme indiqué dans Annexe A, soit directement sous la forme d'un code SQLSTATE sur cinq caractères.
COLUMN CONSTRAINT DATATYPE TABLE SCHEMA: Fournit le nom de l'objet.

Cet exemple annulera la transaction avec le message d'erreur et l'astuce donnés :

RAISE EXCEPTION 'Nonexistent ID --> %', user_id
   USING HINT = 'Please check your user id';

Ces deux exemples affichent des façons équivalents pour initialiser SQLSTATE :

RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';

Il existe une deuxième syntaxe RAISE pour laquelle l'argument principale est le nom de la condition ou le SQLSTATE à rapporter, par exemple :

RAISE division_by_zero;
RAISE SQLSTATE '22012';

Dans cette syntaxe, USING peut être utilisé pour fournir un message d'erreur, un détail ou une astuce personnalisé. Voici une autre façon de faire l'exemple précédent :

RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;

Une autre variante est d'écrire RAISE USING ou RAISE niveau USING et de placer tout le reste dans la liste USING.

La dernière variante de RAISE n'a aucun paramètre. Cette forme peut seulement être utilisée dans un bloc BEGIN d'une clause EXCEPTION ; cela fait que l'erreur est renvoyée.

Note

Avant PostgreSQL 9.1, RAISE sans paramètres était interprété comme un renvoi de l'erreur à partir du bloc contenant le gestionnaire actif d'exceptions. Du coup, une clause EXCEPTION imbriquée dans ce gestionnaire ne la récupérerait pas, même si le RAISE était intégrée dans le bloc de la clause EXCEPTION. C'était très surprenant et incompatible avec PL/SQL d'Oracle.

Si aucun nom de condition ou SQLSTATE n'est indiqué dans une commande RAISE EXCEPTION, la valeur par défaut est d'utiliser raise_exception (P0001). Si aucun message texte n'est indiqué, la valeur par défaut est d'utiliser le nom de la condition ou le SQLSTATE comme texte de message.

Note

Lors de la spécification du code d'erreur par un code SQLSTATE, vous n'êtes pas limité aux codes d'erreur prédéfinis, mais pouvez sélectionner tout code d'erreur consistant en cinq chiffres et/ou des lettres ASCII majuscules, autre que 00000. Il est recommandé d'éviter d'envoyer des codes d'erreur qui se terminent avec trois zéros car il y a des codes de catégorie, et peuvent seulement être récupérés en filtrant la catégorie complète.

42.9.2. Vérification d'assertions

L'instruction ASSERT est un moyen pratique d'insérer dans les fonctions PL/pgSQL des vérifications d'assertions.

ASSERT condition [ , message ];

La condition est une expression booléenne qui est censée être toujours vraie. Si c'est le cas, l'instruction ASSERT ne fait rien. Si le résultat est faux ou NULL, alors une exception ASSERT_FAILURE est levée (si une erreur survient lors de l'évaluation de la condition, elle est rapportée normalement).

Si le message optionnel est fourni, cela doit être une expression dont le résultat (si non NULL) remplacera le message d'erreur (par défaut « assertion failed ») si la condition est fausse. L'expression message n'est pas évaluée dans le cas normal où l'assertion est vraie.

La vérification des assertions peut être activée ou désactivée via le paramètre de configuration plpgsql.check_asserts qui prend une valeur booléenne, par défaut à on. Si ce paramètre est à off alors l'instruction ASSERT ne fait rien.

Notez que l'instruction ASSERT sert à détecter des erreurs de programmation, pas à rapporter des erreurs ordinaires. Pour cela, veuillez utiliser l'instruction RAISE décrite ci-dessus.