NAME
DBIO::Oracle::Util - Shared Oracle-specific helper functions for DBIO
VERSION
version 0.900007
SYNOPSIS
use DBIO::Oracle::Util qw(mask_error_details);
my $message = mask_error_details(
"ORA-00001: unique constraint (APP.UQ_EMAIL) violated on table APP.USERS columns (EMAIL)\n"
. "ORA-03301: (ORA-00001 details) row with column values (EMAIL:'a\@b.c') already exists"
);
# ... columns (EMAIL)
# ORA-03301: (ORA-00001 details) row with column values (EMAIL:***) already exists
DESCRIPTION
Helpers of the Oracle driver that do not belong to one class.
METHODS
mask_error_details
my $message = mask_error_details($message);
my $message = mask_error_details($message, \@binds);
my $message = mask_error_details($message, \@binds, $statement);
Oracle 23ai writes the offending value into its error text, also when the value was a bind: ORA-03302: (ORA-01722 details) invalid string value: x, row with column values (EMAIL:'x') already exists. The family's rule is that a message names keys, columns and options, never values; the server's text is the driver's to keep to it, and this is where the driver does.
Every value in the sentences of the server that quote one is replaced by ***, and what the caller needs to find the cause stays: the error code, the type, the column, the constraint, the table.
ORA-01722: unable to convert string value containing '***' to a number:
ORA-03302: (ORA-01722 details) invalid string value: ***
ORA-00001: unique constraint (APP.UQ) violated on table APP.USERS columns (A, B)
ORA-03301: (ORA-00001 details) row with column values (A:***, B:***) already exists
ORA-01438: value *** greater than specified precision (4, 1) for column
ORA-61800: invalid boolean literal: ***
ORA-01428: Argument *** is out of range.
The key of ORA-03301 is written COLUMN:value per column of the key. Oracle escapes nothing in it, so a value may hold , , :, a quote or a line break. The columns stay where the line of ORA-00001 before names them and the text reads as that list in one way only; any other key text is masked whole ((***)). A value of ORA-03302, ORA-61800 or ORA-03301 may span lines: it is masked up to the lines Oracle itself puts after it (the ORA-06512 stack, the Help: line, the DBD's tag), and, when the text ends otherwise, to its end.
The language of the session. Oracle writes its messages in the language of the session (NLS_LANGUAGE, taken from NLS_LANG or the environment), and the rules above are not tied to the English sentence. A message that quotes a value is recognised by its code (ORA-03302, ORA-03301, ORA-01722, ORA-01438, ORA-61800, ORA-01428) and read by its structure: the label of ORA-03302 and ORA-61800 ends at the first colon and the value follows; the key of ORA-03301 stands in the first brackets after the label, up to the last bracket that is followed by words (the columns are taken from the last brackets of the ORA-00001 line before it); the value of ORA-01722 stands between the first and the last quote of its line; the value of ORA-01438 and ORA-01428 is the number in the line (before the precision, for ORA-01438). The line with the link to the error help (Help:, Hilfe:, Aide :) and the ORA-06512 stack (at line 1, in Zeile 1, à la ligne 1) are recognised by the link and the code; the label of the link line is the language of the client (NLS_LANG), not of the session, so an English session under a French client has Aide : after English sentences. The brackets of the details (ORA-01722 details, ORA-01722-Details, Détails ORA-01722) are read as a parenthesis that holds an ORA- code. German, measured on Oracle 23ai Free:
ORA-01722: Zeichenfolgenwert mit 'g' kann nicht in eine Zahl konvertiert werden:
ORA-03302: (ORA-01722-Details) Ungültiger Zeichenfolgenwert: ***
ORA-00001: Unique Constraint (APP.UQ) für Tabelle APP.USERS mit Spalten (A, B) verletzt
ORA-03301: (ORA-00001-Details) Zeile mit Spaltenwerten (A:***, B:***) ist bereits vorhanden
ORA-01438: Wert *** ist größer als die angegebene Dezimalstellenanzahl (4, 1) für Spalte
ORA-61800: Ungültiges boolesches Literal: ***
ORA-01428: Argument *** befindet sich außerhalb des zulässigen Wertebereichs.
French, measured the same way:
ORA-01722: impossible de convertir une valeur de chaîne contenant '***' en un nombre :
ORA-03302: (Détails ORA-01722) valeur de chaîne non valide : ***
ORA-00001: violation de contrainte unique (APP.UQ) sur la table APP.USERS colonnes (A, B)
ORA-03301: (Détails ORA-00001) la ligne avec les valeurs de colonne (A:***, B:***) existe déjà
ORA-01438: valeur *** supérieure à la précision indiquée (4, 1) pour la colonne
ORA-61800: valeur littérale booléenne non valide : ***
ORA-01428: L'argument *** est hors limites.
Where the structure is not there -- a label with no colon, a key without brackets or without the details, a line of ORA-01438 or ORA-01428 with no number (and, for ORA-01438, no precision) -- the form is of a language or a build nobody has measured, and the text after the code is replaced by *** altogether (ORA-03302: ***). The code and, for ORA-03301, the line of ORA-00001 with the columns stay; nothing of the value does. A masked text is masked again to itself.
\@binds is optional: the values bound to the statement (a bind may be given as the pair [ \%attrs, $value ]). Each one of four characters or more that is found elsewhere in the message, in the form it was bound and in the form $dbh->quote gives it (a quote doubled), is replaced as well. Shorter values, undef and references are not looked for, since a letter or a number is part of any text; the sentences above hold those. A bound value that equals the name of a column or constraint is replaced there too.
$statement is the text of the statement that was run. The DBD appends it to a message ((DBD ERROR: error possibly near <*> indicator at char N in '...')) with its placeholders written :p1; it is the caller's own text and stays as it is, literals in it included -- but only when it is the DBD's: it must end the message and be the statement given (the marker taken out and the placeholders read as ?). Anything else that looks like it is part of the message, and so is a value that imitates it: all of the text is masked, the search for the bound values included. Without $statement there is no appendix.
A message of a code that quotes no value is returned as it is, and so is one without a value: ORA-12899: value too large for column "APP"."T"."S" (actual: 10, maximum: 5), ORA-02290: check constraint (APP.CK) violated, ORA-01400: cannot insert NULL into ("APP"."T"."NN"), a foreign key, a date or a JSON error of Oracle. Texts an application raises itself (ORA-20001) are the application's and are not touched.
SEE ALSO
DBIO::Oracle::Storage - the storage whose refused statements are masked
AUTHOR
DBIO & DBIx::Class Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.