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

39.8. 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 18, Configuration du serveur 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.

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. Les mots clés autorisées pour option sont MESSAGE, DETAIL, HINT et ERRCODE, alors que chaque expression peut être une expression de type chaîne. MESSAGE configure le texte de l'erreur (cette option ne peut pas être utilisée sous la forme de RAISE qui inclut une chaîne de format avant USING). DETAIL fournit un message détaillé de l'erreur, HINT propose une astuce. ERRCODE indique le code d'erreur (SQLSTATE) à rapporter, soit par le nom de la condition comme indiquée dans Annexe A, Codes d'erreurs de PostgreSQL, soit directement sous la forme d'un code SQLSTATE à cinq caractères.

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 au prochain bloc englobant.

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]

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.