Handling PDO Exceptions

PDOException indicates a failure during a connection or SQL operation.

The examples focus on the operation itself, including the important distinction: A SQLSTATE classification is more actionable than matching raw error-message text.

What It Does

Use the examples below to observe the behavior on a small dataset before extending it to application code.

Before You Start

The examples use PHP 8.2+ features where shown. Database snippets require the corresponding PDO driver, demo tables, and credentials configured outside source code.

Example 1: Basic Use

SQLSTATE is useful for classification. Do not expose driver exception details in production HTTP pages.

<?php
$pdo = new PDO(
    "mysql:host=" . (getenv("DB_HOST") ?: "127.0.0.1") . ";dbname=" . (getenv("DB_NAME") ?: "demo") . ";charset=utf8mb4",
    getenv("DB_USER") ?: "app",
    getenv("DB_PASSWORD") ?: "",
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, PDO::ATTR_EMULATE_PREPARES => false]
);
try {
$stmt = $pdo->prepare("SELECT id FROM users WHERE id = ?");
$stmt->execute([3]);
echo json_encode($stmt->fetch(PDO::FETCH_ASSOC));
} catch (PDOException $e) {
    error_log("SQLSTATE=" . $e->getCode());
    http_response_code(500);
    echo "Database operation failed";
}

This example is meant for a configured application environment; output depends on the installed extension, external service, or database contents.

Example 2: Checking Behavior

SQLSTATE is useful for classification. Do not expose driver exception details in production HTTP pages.

<?php
$pdo = new PDO(
    "mysql:host=" . (getenv("DB_HOST") ?: "127.0.0.1") . ";dbname=" . (getenv("DB_NAME") ?: "demo") . ";charset=utf8mb4",
    getenv("DB_USER") ?: "app",
    getenv("DB_PASSWORD") ?: "",
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, PDO::ATTR_EMULATE_PREPARES => false]
);
try {
$stmt = $pdo->prepare("SELECT id FROM users WHERE id = ?");
$stmt->execute([8]);
echo json_encode($stmt->fetch(PDO::FETCH_ASSOC));
} catch (PDOException $e) {
    error_log("SQLSTATE=" . $e->getCode());
    http_response_code(500);
    echo "Database operation failed";
}

This example is meant for a configured application environment; output depends on the installed extension, external service, or database contents.

Example 3: Practical Example

SQLSTATE is useful for classification. Do not expose driver exception details in production HTTP pages.

<?php
$pdo = new PDO(
    "mysql:host=" . (getenv("DB_HOST") ?: "127.0.0.1") . ";dbname=" . (getenv("DB_NAME") ?: "demo") . ";charset=utf8mb4",
    getenv("DB_USER") ?: "app",
    getenv("DB_PASSWORD") ?: "",
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, PDO::ATTR_EMULATE_PREPARES => false]
);
try {
$stmt = $pdo->prepare("SELECT id FROM users WHERE id = ?");
$stmt->execute([21]);
echo json_encode($stmt->fetch(PDO::FETCH_ASSOC));
} catch (PDOException $e) {
    error_log("SQLSTATE=" . $e->getCode());
    http_response_code(500);
    echo "Database operation failed";
}

This example is meant for a configured application environment; output depends on the installed extension, external service, or database contents.

Important Behavior and Edge Cases

Handle known SQLSTATE codes explicitly, log sanitized diagnostics and avoid echoing SQL credentials.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• PDOException indicates a failure during a connection or SQL operation.
• Handle known SQLSTATE codes explicitly, log sanitized diagnostics and avoid echoing SQL credentials.
• A SQLSTATE classification is more actionable than matching raw error-message text.

Use Handling PDO Exceptions when its documented behavior matches the problem. Test the relevant edge cases in your own runtime before deploying it.