Database error codes and messages #

This page is for database administrators and developers who read Exponential's database errors, or write code that must react to them. It answers: which number a failed statement reports on each engine, how errors reach code, and what the drivers' own messages mean. Source: Operating a site, know your database driver and the drivers in lib/ezdb/classes/.

Contents #

1. The engine's own number
2. Two error handling modes
3. Exception classes
4. Messages and where they appear
5. Reading an error reference

The engine's own number #

A failed statement's error number is the database's own, in $db->errorNumber() and, with exception handling, as getCode() of the eZDBException thrown:

Upgrade note: PostgreSQL's errorNumber() was 1 for every error before and is the SQLSTATE now.

Two error handling modes #

$db = eZDB::instance();
$db->setErrorHandling( eZDB::ERROR_HANDLING_EXCEPTIONS );
try
{
    $db->query( "INSERT INTO my_table ( id ) VALUES ( 1 )" );
}
catch ( eZDBException $e )
{
    if ( $e->getCode() === 1062 || $e->getCode() === '23505' )   // MySQL, PostgreSQL
        { /* the row is there already */ }
}
$db->setErrorHandling( eZDB::ERROR_HANDLING_STANDARD );

• Standard (the default): a failed statement is logged and the call returns false; inside a transaction the kernel reports the failure.
• Exceptions: eZDBException with the engine's code. With it, MySQL on PHP 8.1 and later throws eZDBException instead of PHP's mysqli_sql_exception.
• The SQLite driver throws inside a transaction; outside one it answers false with errorNumber() set.

Compare codes per engine, never the message text, which differs by engine, version and language.

Exception classes #

Messages and where they appear #

Reading an error reference #

An error page shows a short reference. exp:logs finds the error by that reference and shows the lines of its request, with personal data masked by default (Finding an error by its reference).

Related pages #

• Troubleshooting database errors
• Reviewing extension SQL for every engine
• When something goes wrong
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.