PHP PDO::errorCode Method

last modified April 19, 2025

The PDO::errorCode method retrieves the SQLSTATE error code for the last operation. It provides a standardized way to check for database operation errors in PDO.

Basic Definition

PDO::errorCode returns a five-character SQLSTATE code or null if no operation. SQLSTATE is an ANSI SQL standard for database error codes. The method applies to the database handle, not individual statements.

Syntax: public PDO::errorCode(): ?string. The method takes no parameters and returns a string or null. It doesn't throw exceptions.

Basic errorCode Example

This shows the simplest usage of errorCode to check for errors.

pdo_errorcode_basic.php

<?php

declare(strict_types=1);

try {
    $pdo = new PDO('mysql:host=localhost;dbname=testdb', 'user', 'password');
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);
    
    // Deliberate error - table doesn't exist
    $pdo->query("SELECT * FROM non_existent_table");
    
    $errorCode = $pdo->errorCode();
    if ($errorCode !== '00000') {
        echo "Error occurred: $errorCode";
    }
} catch (PDOException $e) {
    echo "Connection error: " . $e->getMessage();
}

This demonstrates basic error checking with errorCode. We set ERRMODE_SILENT to prevent exceptions. The code checks if errorCode differs from '00000' (success).

errorCode with Different Error Types

This example shows errorCode responses to different error conditions.

pdo_errorcode_types.php

<?php

declare(strict_types=1);

try {
    $pdo = new PDO('mysql:host=localhost;dbname=testdb', 'user', 'password');
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);
    
    // Syntax error
    $pdo->exec("SELECT FROM users");
    echo "Syntax error: " . $pdo->errorCode() . "\n";
    
    // Non-existent table
    $pdo->exec("SELECT * FROM no_such_table");
    echo "Table error: " . $pdo->errorCode() . "\n";
    
    // Valid query
    $pdo->exec("SELECT 1");
    echo "Success: " . $pdo->errorCode() . "\n";
} catch (PDOException $e) {
    echo "Error: " . $e->getMessage();
}

This shows different error codes for different error types. Syntax errors and missing tables return different SQLSTATE codes. Successful queries return '00000'.

errorCode vs errorInfo

This compares errorCode with the more detailed errorInfo method.

pdo_errorcode_vs_errorinfo.php

<?php

declare(strict_types=1);

try {
    $pdo = new PDO('mysql:host=localhost;dbname=testdb', 'user', 'password');
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);
    
    $pdo->exec("SELECT FROM users"); // Syntax error
    
    echo "errorCode: " . $pdo->errorCode() . "\n";
    
    $errorInfo = $pdo->errorInfo();
    echo "errorInfo: \n";
    print_r($errorInfo);
} catch (PDOException $e) {
    echo "Error: " . $e->getMessage();
}

errorCode returns just the SQLSTATE while errorInfo provides an array with the SQLSTATE, driver-specific error code, and error message. errorInfo is more detailed but errorCode is simpler for basic checks.

errorCode with Transactions

This demonstrates using errorCode to check transaction status.

pdo_errorcode_transaction.php

<?php

declare(strict_types=1);

try {
    $pdo = new PDO('mysql:host=localhost;dbname=testdb', 'user', 'password');
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);
    
    $pdo->beginTransaction();
    
    $pdo->exec("UPDATE accounts SET balance = balance - 100 WHERE user_id = 1");
    if ($pdo->errorCode() !== '00000') {
        $pdo->rollBack();
        echo "First update failed";
        exit;
    }
    
    $pdo->exec("UPDATE accounts SET balance = balance + 100 WHERE user_id = 999");
    if ($pdo->errorCode() !== '00000') {
        $pdo->rollBack();
        echo "Second update failed";
        exit;
    }
    
    $pdo->commit();
    echo "Transaction completed successfully";
} catch (PDOException $e) {
    $pdo->rollBack();
    echo "Error: " . $e->getMessage();
}

This uses errorCode to check each step in a transaction. If any operation fails, the transaction is rolled back. This ensures data consistency when errors occur.

Database-Specific Error Codes

This shows how errorCode works with different database systems.

pdo_errorcode_databases.php

<?php

declare(strict_types=1);

// MySQL error
try {
    $mysql = new PDO('mysql:host=localhost;dbname=testdb', 'user', 'password');
    $mysql->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);
    $mysql->exec("SELECT FROM users"); // Syntax error
    echo "MySQL error: " . $mysql->errorCode() . "\n";
} catch (PDOException $e) {}

// SQLite error
try {
    $sqlite = new PDO('sqlite::memory:');
    $sqlite->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);
    $sqlite->exec("SELECT FROM non_existent");
    echo "SQLite error: " . $sqlite->errorCode() . "\n";
} catch (PDOException $e) {}

Different database systems may return different SQLSTATE codes for similar errors. The errorCode method provides a standardized way to check these across databases.

errorCode in Prepared Statements

This shows errorCode usage with prepared statements.

pdo_errorcode_prepared.php

<?php

declare(strict_types=1);

try {
    $pdo = new PDO('mysql:host=localhost;dbname=testdb', 'user', 'password');
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);
    
    $stmt = $pdo->prepare("INSERT INTO users (name, email) VALUES (?, ?)");
    $stmt->execute(['John Doe']); // Missing second parameter
    
    if ($pdo->errorCode() !== '00000') {
        echo "Prepare/execute error: " . $pdo->errorCode() . "\n";
        print_r($pdo->errorInfo());
    }
} catch (PDOException $e) {
    echo "Error: " . $e->getMessage();
}

This demonstrates checking for errors in prepared statement execution. The example shows how to handle parameter count mismatches using errorCode and errorInfo.

Custom Error Handling with errorCode

This shows implementing custom error handling using errorCode.

pdo_errorcode_custom.php

<?php

declare(strict_types=1);

function handlePdoError(PDO $pdo): void {
    $errorCode = $pdo->errorCode();
    
    if ($errorCode === '00000') return;
    
    $errorMap = [
        '42S02' => 'Table not found',
        '42000' => 'Syntax error',
        '23000' => 'Integrity constraint violation'
    ];
    
    $message = $errorMap[$errorCode] ?? "Database error ($errorCode)";
    echo "Error: $message\n";
}

try {
    $pdo = new PDO('mysql:host=localhost;dbname=testdb', 'user', 'password');
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_SILENT);
    
    $pdo->exec("SELECT FROM users"); // Will trigger error
    
    handlePdoError($pdo);
} catch (PDOException $e) {
    echo "Connection error: " . $e->getMessage();
}

This implements a custom error handler that maps SQLSTATE codes to friendly messages. The handler checks errorCode and provides appropriate responses.

Best Practices

Combine with errorInfo: For detailed error diagnostics.
Check after operations: Verify success after each call.
Use constants: For common SQLSTATE codes in checks.
Document codes: Maintain a list of expected error codes.
Consider exceptions: ERRMODE_EXCEPTION may be simpler.

Source

PHP PDO::errorCode Documentation

This tutorial covered the PDO::errorCode method with practical examples showing how to implement error checking in different database operation scenarios.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all PHP PDO Functions.

Ebooks