NAME
DBIx::SQLstate - message lookup and tokenization of SQL-State codes
SYNOPSIS
use DBI;
use DBIx::SQLstate;
my $dbh = DBI->connect($data_source, $username, $password,
{
HandleError => sub {
my $msg = shift;
my $h = shift;
my $state = $h->state;
my $message = sprintf("%s - %s",
$state, DBIx::SQLstate->token($state)
);
die $message;
}
}
);DESCRIPTION
Database Management Systems, and DBI have their own way of reporting errors. Very often, errors are quit expressive in what happened. Many SQL based systems do also include a SQL-State with each request. This module turns the SQL-State 5 byte code into human readable strings.
SQLSTATE Classes and Sub-Classes
Programs calling a database which accords to the SQL standard receive an indication about the success or failure of the call. This return code - which is called SQLSTATE - consists of 5 bytes. They are divided into two parts: the first and second bytes contain a class and the following three a subclass. Each class belongs to one of four categories: "S" denotes "Success" (class 00), "W" denotes "Warning" (class 01), "N" denotes "No data" (class 02) and "X" denotes "Exception" (all other classes).
CLASS METHODS
The following two class methods have been added for the programmer convenience:
message($sqlstate)
Returns a subclass-message or class-message for a given and exisitng SQLstate, or the default 'Unkown SQL-state'.
my $message = DBIx::SQLstate->message("25006");
#
# "read-only SQL-transaction"token($sqlstate)
Returns the tokenized (See tokenize) version of the message from above.
$sqlstate = "22XXX"; # non existing code
$LOG->error(DBIx::SQLstate->token $sqlstate)
#
# logs an error with "DataException"EXPORT_OK SUBROUTINES
sqlstate_message($sqlstate)
Returns the human readable message defined for the given SQL-State code.
my $sqlstate = '25006';
say sqlstate_message();
#
# prints "read-only SQL-transaction"sqlstate_class_message($sqlstate)
Returns the human readable message for the SQL-state class. This might be useful reduce the amount of variations of log-messages. But since not all SQLstate codes might be present in the current table, this will provide a decent fallback message.
my $sqlstate = '22X00'; # a madeup code
my $m = sqlstate_message($sqlstate) // sqlstate_class_message($sqlstate);
say $m;
#
# prints "data exception"sqlstate_default_message()
Returns a default message. The value can be set with our $DBIx::SQLstate::$DEFAULT_MESSAGE, and defaults to 'Unkown SQL-state'.
sqlstate_token($sqlstate)
Returns a tokenized string (See DBIx::SQLstate::tokenize).
my $sqlstate = '01007';
$LOG->warn sqlstate_token($sqlstate);
#
# logs a warning message with "PrivilegeNotGranted"sqlstate_class_token($sqlstate)
Returns the tokenized string for the above sqlstate_class_message. See tokenize.
sqlstate_default_token()
Returns the tokenized version of the default message.
sqlstate_class($sqlstate)
Returns the 2-byte SQL-state class code.
is_sqlstate_succes($sqlstate)
Returns true is the SQL-state class is 00.
is_sqlstate_warning($sqlstate)
Returns true is the SQL-state class is 01.
is_sqlstate_no_data($sqlstate)
Returns true is the SQL-state class is 02.
is_sqlstate_exception($sqlstate)
Returns true is the SQL-state class is any other than the above mentioned 00, 01, or 02.
Tokenization
The tokenized strings can be useful in logging, or for Throwable ( or Exception::Class) object creations etc. These are mostly camel-case. However, for some common abreviations, like 'SQL', 'XML' or 'XQuery' this module tries to correct the charactercase-folding.
For now, do not rely on the consitent case-folding, it may change in the future.
AUTHOR
Theo van Hoesel <tvanhoesel@perceptyx.com>
COPYRIGHT AND LICENSE
'DBIx::SQLstate' is Copyright (C) 2023, Perceptyx Inc
This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This package is distributed in the hope that it will be useful, but it is provided "as is" and without any express or implied warranties.
For details, see the full text of the license in the file LICENSE.