SQLite: Fehlercodes

Der SQLITE_ABORT-Ergebniscode gibt an, dass ein Vorgang vor dem Abschluss abgebrochen wurde, normalerweise durch eine Anwendungsanforderung. Siehe auch: SQLITE_INTERRUPT. Wenn die Rückruffunktion für sqlite3_exec() einen Wert ungleich Null zurückgibt, gibt sqlite3_exec() SQLITE_ABORT zurück. Wenn ein ROLLBACK-Vorgang auf derselben Datenbankverbindung wie ein ausstehender Lese- oder Schreibvorgang ausgeführt wird, schlägt der ausstehende Lese- oder Schreibvorgang möglicherweise mit einem SQLITE_ABORT- oder SQLITE_ABORT_ROLLBACK-Fehler fehl. Der SQLITE_ABORT-Wert ist nicht nur ein Ergebniscode, sondern wird auch als Konfliktlösungsmodus verwendet, der von der Schnittstelle sqlite3_vtab_on_conflict() zurückgegeben wird.

Der Fehlercode SQLITE_ABORT_ROLLBACK ist ein erweiterter Fehlercode für SQLITE_ABORT, der angibt, dass eine SQL-Anweisung abgebrochen wurde, weil die Transaktion, die beim ersten Start der SQL-Anweisung aktiv war, zurückgesetzt wurde. Ausstehende Schreibvorgänge schlagen bei einem Rollback immer mit diesem Fehler fehl. Ein ROLLBACK führt nur dann dazu, dass ein ausstehender Lesevorgang fehlschlägt, wenn das Schema innerhalb der zurückgesetzten Transaktion geändert wurde.

Der SQLITE_AUTH-Fehler wird zurückgegeben, wenn der Autorisierungsrückruf angibt, dass eine vorbereitete SQL-Anweisung nicht autorisiert ist.

Der SQLITE_AUTH_USER-Fehlercode ist ein erweiterter Fehlercode für SQLITE_AUTH, der darauf hinweist, dass ein Vorgang in einer Datenbank versucht wurde, für den der angemeldete Benutzer nicht über ausreichende Berechtigungen verfügt.

Der Ergebniscode SQLITE_BUSY gibt an, dass die Datenbankdatei aufgrund gleichzeitiger Aktivität einer anderen Datenbankverbindung, normalerweise einer Datenbankverbindung in einem separaten Prozess, nicht geschrieben (oder in einigen Fällen gelesen) werden konnte. Wenn sich Prozess A beispielsweise mitten in einer großen Schreibtransaktion befindet und Prozess B gleichzeitig versucht, eine neue Schreibtransaktion zu starten, erhält Prozess B ein SQLITE_BUSY-Ergebnis zurück, da SQLite jeweils nur einen Writer unterstützt. Prozess B muss warten, bis Prozess A seine Transaktion abgeschlossen hat, bevor er eine neue Transaktion starten kann. Die Schnittstellen sqlite3_busy_timeout() und sqlite3_busy_handler() sowie das Busy_timeout-Pragma stehen Prozess B zur Verfügung, um ihn bei der Behandlung von SQLITE_BUSY-Fehlern zu unterstützen. Ein SQLITE_BUSY-Fehler kann zu jedem Zeitpunkt einer Transaktion auftreten: beim ersten Start der Transaktion, bei Schreib- oder Aktualisierungsvorgängen oder beim Commit der Transaktion. Um zu vermeiden, dass mitten in einer Transaktion SQLITE_BUSY-Fehler auftreten, kann die Anwendung BEGIN IMMEDIATE statt nur BEGIN verwenden, um eine Transaktion zu starten. Der Befehl BEGIN IMMEDIATE gibt möglicherweise selbst SQLITE_BUSY zurück, aber wenn er erfolgreich ist, garantiert SQLite, dass keine nachfolgenden Vorgänge in derselben Datenbank bis zum nächsten COMMIT SQLITE_BUSY zurückgeben. Siehe auch: SQLITE_BUSY_RECOVERY und SQLITE_BUSY_SNAPSHOT. Der Ergebniscode SQLITE_BUSY unterscheidet sich von SQLITE_LOCKED darin, dass SQLITE_BUSY auf einen Konflikt mit einer separaten Datenbankverbindung hinweist, wahrscheinlich in einem separaten Prozess, während SQLITE_LOCKED auf einen Konflikt innerhalb derselben Datenbankverbindung (oder manchmal einer Datenbankverbindung mit einem gemeinsam genutzten Cache) hinweist.

Der Fehlercode SQLITE_BUSY_RECOVERY ist ein erweiterter Fehlercode für SQLITE_BUSY, der angibt, dass ein Vorgang nicht fortgesetzt werden konnte, weil ein anderer Prozess nach einem Absturz damit beschäftigt ist, eine Datenbankdatei im WAL-Modus wiederherzustellen. Der Fehlercode SQLITE_BUSY_RECOVERY tritt nur bei Datenbanken im WAL-Modus auf.

Der SQLITE_BUSY_SNAPSHOT-Fehlercode ist ein erweiterter Fehlercode für SQLITE_BUSY, der bei Datenbanken im WAL-Modus auftritt, wenn eine Datenbankverbindung versucht, eine Lesetransaktion in eine Schreibtransaktion umzuwandeln, jedoch feststellt, dass eine andere Datenbankverbindung bereits in die Datenbank geschrieben und somit frühere Lesevorgänge ungültig gemacht hat. Das folgende Szenario veranschaulicht, wie ein SQLITE_BUSY_SNAPSHOT-Fehler auftreten kann:

Der Fehlercode SQLITE_BUSY_TIMEOUT weist darauf hin, dass eine blockierende Posix-Advisory-Dateisperranforderung in der VFS-Ebene aufgrund einer Zeitüberschreitung fehlgeschlagen ist. Das Blockieren von Posix-Advisory-Sperren ist nur als proprietäre SQLite-Erweiterung verfügbar und wird selbst dann nur unterstützt, wenn SQLite mit der Kompilierzeitoption SQLITE_ENABLE_SETLK_TIMEOUT kompiliert wird.

Der Ergebniscode SQLITE_CANTOPEN zeigt an, dass SQLite eine Datei nicht öffnen konnte. Bei der betreffenden Datei kann es sich um eine primäre Datenbankdatei oder eine von mehreren temporären Festplattendateien handeln.

Der Fehlercode SQLITE_CANTOPEN_CONVPATH ist ein erweiterter Fehlercode für SQLITE_CANTOPEN, der nur von Cygwin VFS verwendet wird und darauf hinweist, dass der Systemaufruf cygwin_conv_path() beim Versuch, eine Datei zu öffnen, fehlgeschlagen ist. Siehe auch: SQLITE_IOERR_CONVPATH

Der Ergebniscode SQLITE_CANTOPEN_DIRTYWAL wird derzeit nicht verwendet.

Der Fehlercode SQLITE_CANTOPEN_FULLPATH ist ein erweiterter Fehlercode für SQLITE_CANTOPEN, der darauf hinweist, dass ein Dateiöffnungsvorgang fehlgeschlagen ist, weil das Betriebssystem den Dateinamen nicht in einen vollständigen Pfadnamen umwandeln konnte.

Der Fehlercode SQLITE_CANTOPEN_ISDIR ist ein erweiterter Fehlercode für SQLITE_CANTOPEN, der darauf hinweist, dass ein Dateiöffnungsvorgang fehlgeschlagen ist, da es sich bei der Datei tatsächlich um ein Verzeichnis handelt.

Der Fehlercode SQLITE_CANTOPEN_NOTEMPDIR wird nicht mehr verwendet.

Der Ergebniscode SQLITE_CANTOPEN_SYMLINK wird von der Schnittstelle sqlite3_open() und ihren Geschwistern zurückgegeben, wenn das Flag SQLITE_OPEN_NOFOLLOW verwendet wird und die Datenbankdatei ein symbolischer Link ist.

Der Fehlercode SQLITE_CONSTRAINT bedeutet, dass beim Versuch, eine SQL-Anweisung zu verarbeiten, eine SQL-Einschränkungsverletzung aufgetreten ist. Weitere Informationen zur fehlgeschlagenen Einschränkung finden Sie in der begleitenden Fehlermeldung (zurückgegeben über sqlite3_errmsg() oder sqlite3_errmsg16()) oder indem Sie sich den erweiterten Fehlercode ansehen. Der SQLITE_CONSTRAINT-Code kann auch als Rückgabewert der xBestIndex()-Methode einer virtuellen Tabellenimplementierung verwendet werden. Wenn xBestIndex() SQLITE_CONSTRAINT zurückgibt, bedeutet dies, dass die bestimmte Kombination von Eingaben, die an xBestIndex() übermittelt werden, nicht zu einem verwendbaren Abfrageplan führen kann und nicht weiter berücksichtigt werden sollte.

Der SQLITE_CONSTRAINT_CHECK-Fehlercode ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der angibt, dass eine CHECK-Einschränkung fehlgeschlagen ist.

Der SQLITE_CONSTRAINT_COMMITHOOK-Fehlercode ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der darauf hinweist, dass ein Commit-Hook-Callback einen Wert ungleich Null zurückgegeben hat, was dazu führte, dass die SQL-Anweisung zurückgesetzt wurde.

Der SQLITE_CONSTRAINT_DATATYPE-Fehlercode ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der darauf hinweist, dass bei einer Einfügung oder Aktualisierung versucht wurde, einen Wert zu speichern, der nicht mit dem deklarierten Typ der Spalte in einer als STRICT definierten Tabelle übereinstimmt.

Der Fehlercode SQLITE_CONSTRAINT_FOREIGNKEY ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der angibt, dass eine Fremdschlüsseleinschränkung fehlgeschlagen ist.

Der Fehlercode SQLITE_CONSTRAINT_FUNCTION wird derzeit nicht vom SQLite-Kern verwendet. Dieser Fehlercode steht jedoch für die Verwendung durch Erweiterungsfunktionen zur Verfügung.

Der Fehlercode SQLITE_CONSTRAINT_NOTNULL ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der angibt, dass eine NOT NULL-Einschränkung fehlgeschlagen ist.

Der Fehlercode SQLITE_CONSTRAINT_PINNED ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der darauf hinweist, dass ein UPDATE-Trigger versucht hat, die Zeile zu löschen, die mitten in der Aktualisierung aktualisiert wurde.

Der SQLITE_CONSTRAINT_PRIMARYKEY-Fehlercode ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der angibt, dass eine PRIMARY KEY-Einschränkung fehlgeschlagen ist.

Der SQLITE_CONSTRAINT_ROWID-Fehlercode ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der angibt, dass eine Zeilen-ID nicht eindeutig ist.

Der SQLITE_CONSTRAINT_TRIGGER-Fehlercode ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der angibt, dass eine RAISE-Funktion innerhalb eines Triggers ausgelöst wurde, was zum Abbruch der SQL-Anweisung führte.

Der SQLITE_CONSTRAINT_UNIQUE-Fehlercode ist ein erweiterter Fehlercode für SQLITE_CONSTRAINT, der angibt, dass eine UNIQUE-Einschränkung fehlgeschlagen ist.

Der Fehlercode SQLITE_CONSTRAINT_VTAB wird derzeit vom SQLite-Kern nicht verwendet. Dieser Fehlercode steht jedoch für die Verwendung durch anwendungsdefinierte virtuelle Tabellen zur Verfügung.

Der Ergebniscode SQLITE_CORRUPT zeigt an, dass die Datenbankdatei beschädigt wurde. Weitere Erläuterungen dazu, wie es zu Beschädigungen kommen kann, finden Sie im Artikel So beschädigen Sie Ihre Datenbankdateien.

Der Ergebniscode SQLITE_CORRUPT_INDEX bedeutet, dass SQLite erkannt hat, dass ein Eintrag in einem Index fehlt oder fehlt. Dies ist ein Sonderfall des SQLITE_CORRUPT-Fehlercodes, der darauf hindeutet, dass das Problem durch Ausführen des REINDEX-Befehls behoben werden könnte, vorausgesetzt, dass an anderer Stelle in der Datenbankdatei keine anderen Probleme vorliegen.

Der Ergebniscode SQLITE_CORRUPT_SEQUENCE bedeutet, dass das Schema der Tabelle sqlite_sequence beschädigt ist. Die Tabelle sqlite_sequence wird verwendet, um die Implementierung der AUTOINCREMENT-Funktion zu unterstützen. Die Tabelle sqlite_sequence sollte das folgende Format haben: Wenn SQLite feststellt, dass die Tabelle sqlite_sequence ein anderes Format hat, gibt es den Fehler SQLITE_CORRUPT_SEQUENCE zurück.

Der Fehlercode SQLITE_CORRUPT_VTAB ist ein erweiterter Fehlercode für SQLITE_CORRUPT, der von virtuellen Tabellen verwendet wird. Eine virtuelle Tabelle gibt möglicherweise SQLITE_CORRUPT_VTAB zurück, um anzuzeigen, dass der Inhalt der virtuellen Tabelle beschädigt ist.

Der SQLITE_EMPTY-Ergebniscode wird derzeit nicht verwendet.

Der Ergebniscode SQLITE_ERROR ist ein generischer Fehlercode, der verwendet wird, wenn kein anderer, spezifischerer Fehlercode verfügbar ist.

Der Ergebniscode SQLITE_ERROR_MISSING_COLLSEQ bedeutet, dass eine SQL-Anweisung nicht vorbereitet werden konnte, weil eine in dieser SQL-Anweisung genannte Sortiersequenz nicht gefunden werden konnte. Wenn dieser Fehlercode auftritt, konvertiert die Routine sqlite3_prepare_v2() manchmal den Fehler in SQLITE_ERROR_RETRY und versucht erneut, die SQL-Anweisung mit einem anderen Abfrageplan vorzubereiten, der die Verwendung der unbekannten Sortiersequenz nicht erfordert.

SQLITE_ERROR_RETRY wird intern verwendet, um sqlite3_prepare_v2() (oder eine seiner Geschwisterroutinen zum Erstellen vorbereiteter Anweisungen) zu provozieren, erneut zu versuchen, eine Anweisung vorzubereiten, die beim vorherigen Versuch mit einem Fehler fehlgeschlagen ist.

Der Ergebniscode SQLITE_ERROR_SNAPSHOT wird möglicherweise zurückgegeben, wenn versucht wird, eine Lesetransaktion für eine historische Version der Datenbank mithilfe der Schnittstelle sqlite3_snapshot_open() zu starten. Wenn der historische Snapshot nicht mehr verfügbar ist, schlägt die Lesetransaktion mit SQLITE_ERROR_SNAPSHOT fehl. Dieser Fehlercode ist nur möglich, wenn SQLite mit -DSQLITE_ENABLE_SNAPSHOT kompiliert wird.

Der SQLITE_FORMAT-Fehlercode wird derzeit von SQLite nicht verwendet.

Der Ergebniscode SQLITE_FULL zeigt an, dass ein Schreibvorgang nicht abgeschlossen werden konnte, da die Festplatte voll ist. Beachten Sie, dass dieser Fehler beim Versuch, Informationen in die Hauptdatenbankdatei zu schreiben, oder auch beim Schreiben in temporäre Festplattendateien auftreten kann. Manchmal tritt bei Anwendungen dieser Fehler auf, obwohl reichlich Speicherplatz auf der primären Festplatte vorhanden ist, da der Fehler beim Schreiben in temporäre Festplattendateien auf einem System auftritt, auf dem temporäre Dateien auf einer separaten Partition mit viel weniger Speicherplatz als auf der primären Festplatte gespeichert sind.

Der Ergebniscode SQLITE_INTERNAL weist auf eine interne Fehlfunktion hin. In einer funktionierenden Version von SQLite sollte eine Anwendung diesen Ergebniscode niemals sehen. Wenn die Anwendung auf diesen Ergebniscode stößt, weist dies darauf hin, dass ein Fehler in der Datenbank-Engine vorliegt. Dieser Ergebniscode könnte durch einen Fehler in SQLite verursacht werden. Allerdings können auch anwendungsdefinierte SQL-Funktionen oder virtuelle Tabellen oder VFSes oder andere Erweiterungen dazu führen, dass dieser Ergebniscode zurückgegeben wird, sodass das Problem möglicherweise nicht auf den Kern von SQLite zurückzuführen ist.