Handling Database Connection Failures

Catch database connection failures without exposing secrets or DSN details to users.

The examples focus on the operation itself, including the important distinction: PDOException is diagnostic for operators; an HTTP user should see a safe error.

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

Do not publish detailed DSNs, SQL errors or passwords in an HTTP response.

<?php
try {
$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]
);
    echo "Connected";
} catch (PDOException $e) {
    error_log("Database connection failed, code=" . $e->getCode());
    http_response_code(503);
    echo "Service temporarily unavailable";
}

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

Example 2: Checking Behavior

Do not publish detailed DSNs, SQL errors or passwords in an HTTP response. Different public success messages remain separate from private diagnostic logging.

<?php
try {
$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]
);
    echo "Database available";
} catch (PDOException $e) {
    error_log("Database connection failed, code=" . $e->getCode());
    http_response_code(503);
    echo "Service temporarily unavailable";
}

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

Example 3: Practical Example

Do not publish detailed DSNs, SQL errors or passwords in an HTTP response. Different public success messages remain separate from private diagnostic logging.

<?php
try {
$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]
);
    echo "Connection check passed";
} catch (PDOException $e) {
    error_log("Database connection failed, code=" . $e->getCode());
    http_response_code(503);
    echo "Service temporarily unavailable";
}

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

Differentiate transient outages from authentication errors and avoid unbounded retries.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• Catch database connection failures without exposing secrets or DSN details to users.
• Differentiate transient outages from authentication errors and avoid unbounded retries.
• PDOException is diagnostic for operators; an HTTP user should see a safe error.

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