Ein umfassender Leitfaden zur mysqli_sqlstate-Funktion in PHP

Wenn Sie in PHP über die mysqli-Erweiterung mit MySQL arbeiten, benötigen Sie eine zuverlässige Methode, um herauszufinden, warum eine Abfrage fehlgeschlagen ist. Die Funktion mysqli_sqlstate() gibt den SQLSTATE-Fehlercode für die zuletzt ausgeführte MySQL-Operation zurück — ein standardisierter, portabler Code, der Ihnen die Kategorie eines Fehlers mitteilt.

Dieser Leitfaden erklärt, was SQLSTATE ist, wie sich mysqli_sqlstate() vom MySQL-spezifischen mysqli_errno() unterscheidet, welche Codes am häufigsten vorkommen und wie Sie die Funktion korrekt einsetzen (einschließlich im modernen Exception-basierten Modus von PHP).

Was ist SQLSTATE?

SQLSTATE ist ein fünfstelliger Fehlercode, der durch den ANSI/ISO-SQL-Standard definiert wird. Da er Teil des Standards und keine MySQL-spezifische Erfindung ist, bedeutet derselbe Code bei verschiedenen Datenbank-Engines ungefähr dasselbe — was ihn portabler macht als herstellerspezifische Fehlernummern.

Die fünf Zeichen sind in zwei Teile aufgeteilt:

• Die ersten zwei Zeichen bilden die Klasse des Fehlers. Klasse 00 bedeutet Erfolg, 01 bedeutet eine Warnung und 42 bedeutet eine Syntaxfehler- oder Zugriffsverletzung.
• Die letzten drei Zeichen bilden die Unterklasse, die das Problem weiter eingrenzt.

So gehört 42S02 ("Basistabelle oder Ansicht nicht gefunden") zur Klasse 42 (Syntax-/Zugriffsverletzung) mit der Unterklasse S02.

Syntax

mysqli_sqlstate(mysqli $connection): string

mysqli_sqlstate() nimmt ein einziges Argument entgegen — das Verbindungsobjekt, das von mysqli_connect() zurückgegeben wird — und gibt einen string zurück:

• Einen leeren, aber nullgefüllten string "00000", wenn die letzte Operation erfolgreich war.
• Einen fünfstelligen Code wie "42S02", wenn ein Fehler aufgetreten ist.

Im objektorientierten Stil ist dies die Methode $connection->sqlstate.

SQLSTATE vs. mysqli_errno: Was sollten Sie verwenden?

Diese beiden Funktionen beantworten unterschiedliche Fragen, und oft benötigen Sie beide:

Faustregel: Verzweigen Sie Ihre Logik auf mysqli_sqlstate(), wenn Sie Code wollen, der eine Datenbankmigration übersteht, und greifen Sie auf mysqli_errno() zurück, wenn Sie eine MySQL-spezifische Unterscheidung benötigen. Verwenden Sie mysqli_error() für die Nachricht, die Sie protokollieren.

Ein vollständiges Beispiel

Der folgende Codeausschnitt stellt eine Verbindung her, führt eine Abfrage gegen eine nicht vorhandene Tabelle aus und gibt alle drei Diagnosewerte aus, damit Sie sehen können, wie sie zusammenhängen:

<?php

$connection = mysqli_connect('localhost', 'user', 'password', 'mydatabase');

if (!$connection) {
    die('Connection failed: ' . mysqli_connect_error());
}

$sql = "SELECT * FROM table_that_does_not_exist";

if (mysqli_query($connection, $sql)) {
    echo "Query executed successfully.";
} else {
    echo "SQLSTATE: " . mysqli_sqlstate($connection) . "\n";
    echo "Errno:    " . mysqli_errno($connection) . "\n";
    echo "Message:  " . mysqli_error($connection) . "\n";
}

// Typical output:
// SQLSTATE: 42S02
// Errno:    1146
// Message:  Table 'mydatabase.table_that_does_not_exist' doesn't exist

Beachten Sie, wie der portable SQLSTATE (42S02) und die MySQL-spezifische Fehlernummer (1146) dasselbe Problem auf zwei Detailebenen beschreiben.

Häufige SQLSTATE-Codes

Dies sind die Codes, die Sie im alltäglichen PHP/MySQL-Betrieb am wahrscheinlichsten behandeln werden:

Die Verzweigung auf diese Codes ermöglicht sinnvolle Reaktionen — zum Beispiel kann ein 23000-Doppelschlüssel-Fehler als "Dieser Datensatz existiert bereits" behandelt werden, anstatt als schwerwiegender Fehler:

<?php

$sql = "INSERT INTO users (email) VALUES ('[email protected]')";

if (!mysqli_query($connection, $sql)) {
    if (mysqli_sqlstate($connection) === '23000') {
        echo "That email address is already registered.";
    } else {
        echo "Unexpected database error: " . mysqli_error($connection);
    }
}

Verwendung im Exception-Modus

Modernes PHP (8.1+) aktiviert die MySQL-Fehlerberichterstattung standardmäßig, sodass eine fehlgeschlagene Abfrage eine mysqli_sql_exception auslöst, anstatt false zurückzugeben. In diesem Modus lesen Sie den SQLSTATE aus der getSqlState()-Methode der Exception, anstatt nachträglich mysqli_sqlstate() aufzurufen:

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

try {
    $connection = mysqli_connect('localhost', 'user', 'password', 'mydatabase');
    mysqli_query($connection, "SELECT * FROM missing_table");
} catch (mysqli_sql_exception $e) {
    echo "SQLSTATE: " . $e->getSqlState() . "\n"; // e.g. 42S02
    echo "Code:     " . $e->getCode() . "\n";     // e.g. 1146
    echo "Message:  " . $e->getMessage();
}

Wenn Sie mysqli_sqlstate() direkt nach dem Abfangen einer Exception aufrufen, funktioniert das noch immer — aber innerhalb eines try/catch-Blocks ist das Lesen des Codes aus dem Exception-Objekt sauberer und vermeidet ein erneutes Abfragen des Verbindungsstatus.

Fallstricke

• Es spiegelt nur die letzte Operation wider. Jede neue Abfrage überschreibt den vorherigen SQLSTATE. Lesen Sie ihn sofort nach dem betreffenden Aufruf — bevor Sie etwas anderes auf derselben Verbindung ausführen.
• "00000" bedeutet Erfolg, kein Fehler. Behandeln Sie eine nicht leere Rückgabe nicht als Fehler; eine erfolgreiche Operation gibt den Null-string zurück, nicht "".
• Eine fehlgeschlagene Verbindung hat keinen SQLSTATE. Wenn mysqli_connect() selbst fehlschlägt, gibt es kein Verbindungsobjekt zum Abfragen. Verwenden Sie in diesem Fall mysqli_connect_error() für Verbindungsprobleme.

Fazit

mysqli_sqlstate() liefert den portablen, standardbasierten SQLSTATE-Code für die letzte MySQL-Operation und ergänzt das MySQL-spezifische mysqli_errno() sowie das lesbare mysqli_error(). Verzweigen Sie auf SQLSTATE, wenn Sie datenbankagnostisches Fehlerhandling wünschen, wechseln Sie zur getSqlState()-Methode der Exception, wenn Sie im Standard-Exception-Modus von PHP arbeiten, und lesen Sie den Code stets unmittelbar nach der beschriebenen Operation.

Übungen