Debug & Error Handling

PDOdb provides an internal debug and error-handling system with structured exception logging, optional tracing, and support for both silent fail and full developer output. All errors throw real exceptions – but can be handled flexibly.

Debug Levels

Set the debug level using:

$db->debug = 0; // or 1, 2, 3
Level Logging Exceptions Behavior
0 ❌ none ✅ always (internally caught) Silent fail – use getLastError() to check
1 ✅ exception only ✅ always (internally caught) Errors are stored and logged – no output
2 ✅ full (query + bindings) ✅ thrown Immediate error with logs and full context
3 ✅ full + trace ✅ thrown Developer mode with full trace and last debug query
Exceptions are always thrown – regardless of debug level. Without try/catch, the script may exit with a fatal error.

Using try/catch (recommended)

All exceptions can be caught manually. This is the safest way to handle invalid inputs or failed operations: 

$db->debug = 2;

try {
  $db->whereInt('id', 'abc');
  $db->get('test_users');
} catch (Throwable $e) {
  echo "Error: " . $e->getMessage();
}

Without try/catch

In earlier versions or with $db->debug = 0, it was possible to handle query errors manually via getLastError() and getLastQuery().

However, in the current version of PDOdb, almost all query failures now throw real Exceptions. If you do not wrap your code in a try/catch block, your script may terminate with a fatal PHP error. 

// ⚠️ This will now throw a fatal exception:
$db->whereInt('id', 'abc');
$db->get('test_users');

// Not guaranteed to be reached:
if ($db->getLastErrno()) {
  echo $db->getLastError();
}
Important: Exception-based handling is now the default behavior. Use try/catch if you want to avoid fatal script interruption.

Error Inspection Methods

  • $db->getLastError() – last error message (string or null)
  • $db->getLastErrno() – last error code (usually 0 or PDO code)
  • $db->getLastQuery() – last executed query
These values are connection-specific and automatically cleared after each query.

Trace & Developer Logging

At debug level 3, detailed traces are available via the internal logException() method. Queries are logged via logQuery() and stored with bindings.

  • logException(Throwable $e, ?string $context) – logs exception context
  • logQuery(string $sql, ?array $bindings) – logs full query and bindings
  • logNotice(string $msg) – logs soft notices (deprecated, fallback, etc.)

If you want to override or redirect logs (e.g., to file, Redis, monitoring tools), you can extend these methods in your own class.

Internal method handleException() will always throw – even if logging is disabled.

See Also