Utilisez l'instruction RAISE
pour rapporter des messages et
lever des erreurs.
RAISE [niveau
] 'format
' [,expression
[, ...]] [ USINGoption
=expression
[, ... ] ]; RAISE [niveau
]nom_condition
[ USINGoption
=expression
[, ... ] ]; RAISE [niveau
] SQLSTATE 'état_sql
' [ USINGoption
=expression
[, ... ] ]; RAISE [niveau
] USINGoption
=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
et de placer
tout le reste dans la liste niveau
USINGUSING
.
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.
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
ERRCODE_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.
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.
L'instruction ASSERT
est un moyen pratique
d'insérer dans les fonctions PL/pgSQL
des vérifications d'assertions.
ASSERTcondition
[ ,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.