43.2. Reporter les erreurs dans le serveur

Les messages d'erreurs, d'alertes et de traces générés à l'intérieur du code du serveur doivent être créés en utilisant ereport ou son ancien cousin elog. L'utilisation de cette fonction est assez complexe pour que cela requiert quelques explications.

Il y a deux éléments requis pour chaque message : un niveau de sévérité (allant de DEBUG à PANIC) et un message texte primaire. De plus, il y a des éléments optionnels, le plus commun d'entre eux est le code d'identifiant de l'erreur qui suit les conventions SQLSTATE des spécifications SQL. ereport en elle-même n'est qu'une fonction shell qui existe principalement pour des convenances syntaxiques faisant ressembler la génération de messages à l'appel d'une fonction dans un code source C. Le seul paramètre directement accepté par ereport est le niveau de sévérité. Le message texte primaire et les autres éléments de messages optionnels sont générés en appelant des fonctions auxiliaires, comme errmsg, à l'intérieur de l'appel à ereport.

Un appel typique à ereport peut ressembler à ceci :

    ereport(ERROR,
            (errcode(ERRCODE_DIVISION_BY_ZERO),
             errmsg("division by zero")));

Ceci met le niveau de sévérité de l'erreur à ERROR (une erreur banale). L'appel à errcode spécifie le code d'erreur SQLSTATE en utilisant une macro définie dans src/include/utils/errcodes.h. L'appel à errmsg fournit le message texte primaire. Notez l'ensemble supplémentaire de parenthèses entourant les appels aux fonctions auxiliaires (cela est ennuyeux mais syntaxiquement nécessaire).

Voici un exemple plus complexe :

    ereport(ERROR,
            (errcode(ERRCODE_AMBIGUOUS_FUNCTION),
             errmsg("function %s is not unique",
                    func_signature_string(funcname, nargs,
                                          actual_arg_types)),
             errhint("Unable to choose a best candidate function. "
                     "You may need to add explicit typecasts.")));

Ceci illustre l'utilisation des codes de formatage pour intégrer des valeurs d'exécution dans un message texte. Un message << conseil >>, optionnel, est également fourni.

Les routines auxiliaires disponibles pour ereport sont :

Il y a une plus ancienne fonction nommée elog, qui est toujours largement utilisée. Un appel à elog

    elog(niveau, "chaine format", ...);

est strictement équivalent à

    ereport(level, (errmsg_internal("chaine format", ...)));

Notez que le code d'erreur SQLSTATE est toujours par défaut et que la chaîne de caractères du message n'est pas sujet à une traduction. Par conséquent, elog devrait être utilisé seulement pour les erreurs internes et l'enregistrement de trace de débogage de bas niveau. N'importe quel message qui est susceptible d'être intéressant pour les utilisateurs ordinaires devrait passer par ereport. Néanmoins, il y a assez de contrôles d'erreurs internes qui << ne peuvent pas arriver >> dans le système, que elog est toujours largement utilisé ; pour ces messages, cela est préféré à cause de sa simplicité d'écriture.

Des conseils sur l'écriture de bons messages d'erreurs peuvent être trouvés dans la Section 43.3.

Notes

[1]

C'est-à-dire que la valeur qui était courante quand l'appel à ereport a été atteinte ; les changements d'errno dans les routines auxiliaires de rapports ne l'affecteront pas. Cela ne sera pas vrai si vous devez écrire explicitement strerror(errno) dans la liste de paramètres de errmsg ; en conséquence ne faites pas comme ça.