SQLite: Fehlercodes

Der SQLITE_NOLFS-Fehler kann auf Systemen zurückgegeben werden, die keine großen Dateien unterstützen, wenn die Datenbank größer wird, als das Dateisystem verarbeiten kann. „NOLFS“ steht für „NO Large File Support“.

Der Ergebniscode SQLITE_NOMEM zeigt an, dass SQLite nicht den gesamten Speicher zuweisen konnte, der zum Abschließen des Vorgangs erforderlich war. Mit anderen Worten: Ein interner Aufruf von sqlite3_malloc() oder sqlite3_realloc() ist in einem Fall fehlgeschlagen, in dem der zugewiesene Speicher erforderlich war, um den Vorgang fortzusetzen.

Beim Versuch, eine Datei zu öffnen, weist der Fehler SQLITE_NOTADB darauf hin, dass es sich bei der geöffneten Datei offenbar nicht um eine SQLite-Datenbankdatei handelt.

Der SQLITE_NOTFOUND-Ergebniscode wird auf drei Arten verfügbar gemacht: Der SQLITE_NOTFOUND-Ergebniscode wird auch intern von der SQLite-Implementierung verwendet, diese internen Verwendungen werden der Anwendung jedoch nicht zugänglich gemacht.

Der SQLITE_NOTICE-Ergebniscode wird von keiner C/C++-Schnittstelle zurückgegeben. Allerdings wird SQLITE_NOTICE (oder besser gesagt einer seiner erweiterten Fehlercodes) manchmal als erstes Argument in einem sqlite3_log()-Rückruf verwendet, um anzuzeigen, dass ein ungewöhnlicher Vorgang stattfindet.

Der SQLITE_NOTICE_RECOVER_ROLLBACK-Ergebniscode wird an den Rückruf von sqlite3_log() übergeben, wenn ein Hot Journal zurückgesetzt wird.

Der SQLITE_NOTICE_RECOVER_WAL-Ergebniscode wird an den Rückruf von sqlite3_log() übergeben, wenn eine Datenbankdatei im WAL-Modus wiederhergestellt wird.

Der Ergebniscode SQLITE_PERM gibt an, dass der angeforderte Zugriffsmodus für eine neu erstellte Datenbank nicht bereitgestellt werden konnte.

Der Ergebniscode SQLITE_PROTOCOL weist auf ein Problem mit dem von SQLite verwendeten Dateisperrprotokoll hin. Der SQLITE_PROTOCOL-Fehler wird derzeit nur zurückgegeben, wenn der WAL-Modus verwendet wird und versucht wird, eine neue Transaktion zu starten. Es kann zu einer Race-Bedingung kommen, wenn zwei separate Datenbankverbindungen gleichzeitig versuchen, eine Transaktion im WAL-Modus zu starten. Der Verlierer des Rennens zieht sich zurück und versucht es nach einer kurzen Verzögerung erneut. Wenn dieselbe Verbindung über einen Zeitraum von mehreren Sekunden Dutzende Male den Locking Race verliert, wird sie schließlich aufgeben und SQLITE_PROTOCOL zurückgeben. Der SQLITE_PROTOCOL-Fehler sollte in der Praxis sehr, sehr selten und nur dann auftreten, wenn es viele separate Prozesse gibt, die alle intensiv darum konkurrieren, in dieselbe Datenbank zu schreiben.

Der SQLITE_RANGE-Fehler weist darauf hin, dass das Parameternummernargument für eine der sqlite3_bind-Routinen oder die Spaltennummer in einer der sqlite3_column-Routinen außerhalb des gültigen Bereichs liegt.

Der Ergebniscode SQLITE_READONLY wird zurückgegeben, wenn versucht wird, einige Daten zu ändern, für die die aktuelle Datenbankverbindung keine Schreibberechtigung hat.

Der SQLITE_READONLY_CANTINIT-Ergebniscode stammt aus der xShmMap-Methode eines VFS und zeigt an, dass der vom WAL-Modus verwendete gemeinsam genutzte Speicherbereich vorhanden ist, sein Inhalt jedoch unzuverlässig und für den aktuellen Prozess unbrauchbar ist, da der aktuelle Prozess keine Schreibberechtigung für den gemeinsam genutzten Speicherbereich hat. (Der gemeinsam genutzte Speicherbereich für den WAL-Modus ist normalerweise eine Datei mit dem Suffix „-wal“, die dem Prozessraum zugeordnet wird. Wenn der aktuelle Prozess keine Schreibberechtigung für diese Datei hat, kann er nicht in den gemeinsam genutzten Speicher schreiben.) Die übergeordnete Logik innerhalb von SQLite fängt normalerweise den Fehlercode ab und erstellt einen temporären gemeinsam genutzten Speicherbereich im Arbeitsspeicher, sodass der aktuelle Prozess zumindest den Inhalt der Datenbank lesen kann. Dieser Ergebniscode sollte die Anwendungsschnittstellenschicht nicht erreichen.

Der Fehlercode SQLITE_READONLY_CANTLOCK ist ein erweiterter Fehlercode für SQLITE_READONLY. Der Fehlercode SQLITE_READONLY_CANTLOCK weist darauf hin, dass SQLite keine Lesesperre für eine Datenbank im WAL-Modus erhalten kann, da die dieser Datenbank zugeordnete Shared-Memory-Datei schreibgeschützt ist.

Der Fehlercode SQLITE_READONLY_DBMOVED ist ein erweiterter Fehlercode für SQLITE_READONLY. Der Fehlercode SQLITE_READONLY_DBMOVED weist darauf hin, dass eine Datenbank nicht geändert werden kann, da die Datenbankdatei seit dem Öffnen verschoben wurde. Daher kann jeder Versuch, die Datenbank zu ändern, zu einer Beschädigung der Datenbank führen, wenn die Prozesse abstürzen, weil das Rollback-Journal nicht korrekt benannt wird.

Der Ergebniscode SQLITE_READONLY_DIRECTORY gibt an, dass die Datenbank schreibgeschützt ist, da der Prozess keine Berechtigung zum Erstellen einer Journaldatei im selben Verzeichnis wie die Datenbank hat und die Erstellung einer Journaldatei eine Voraussetzung zum Schreiben ist.

Der Fehlercode SQLITE_READONLY_RECOVERY ist ein erweiterter Fehlercode für SQLITE_READONLY. Der Fehlercode SQLITE_READONLY_RECOVERY weist darauf hin, dass eine Datenbank im WAL-Modus nicht geöffnet werden kann, da die Datenbankdatei wiederhergestellt werden muss und für die Wiederherstellung Schreibzugriff erforderlich ist, aber nur Lesezugriff verfügbar ist.

Der Fehlercode SQLITE_READONLY_ROLLBACK ist ein erweiterter Fehlercode für SQLITE_READONLY. Der Fehlercode SQLITE_READONLY_ROLLBACK weist darauf hin, dass eine Datenbank nicht geöffnet werden kann, da sie über ein Hot-Journal verfügt, das zurückgesetzt werden muss, dies jedoch nicht möglich ist, da die Datenbank schreibgeschützt ist.

Der Ergebniscode SQLITE_SCHEMA zeigt an, dass sich das Datenbankschema geändert hat. Dieser Ergebniscode kann von sqlite3_step() für eine vorbereitete Anweisung zurückgegeben werden, die mit sqlite3_prepare() oder sqlite3_prepare16() generiert wurde. Wenn das Datenbankschema zwischen der Erstellung der Anweisung und der Ausführung der Anweisung durch einen anderen Prozess geändert wurde, kann dieser Fehler auftreten. Wenn eine vorbereitete Anweisung aus sqlite3_prepare_v2() generiert wird, wird die Anweisung automatisch neu vorbereitet, wenn sich das Schema ändert, bis zu SQLITE_MAX_SCHEMA_RETRY-Zeiten (Standard: 50). Die Schnittstelle sqlite3_step() gibt SQLITE_SCHEMA nur dann an die Anwendung zurück, wenn der Fehler nach so vielen Wiederholungsversuchen weiterhin besteht.

Der Fehlercode SQLITE_TOOBIG weist darauf hin, dass eine Zeichenfolge oder ein BLOB zu groß war. Die standardmäßige maximale Länge einer Zeichenfolge oder eines BLOBs in SQLite beträgt 1.000.000.000 Bytes. Diese maximale Länge kann zur Kompilierungszeit mit der Kompilierzeitoption SQLITE_MAX_LENGTH oder zur Laufzeit mit der Schnittstelle sqlite3_limit(db,SQLITE_LIMIT_LENGTH,...) geändert werden. Der SQLITE_TOOBIG-Fehler tritt auf, wenn SQLite auf eine Zeichenfolge oder ein BLOB stößt, die das Kompilierungszeit- oder Laufzeitlimit überschreitet. Der SQLITE_TOOBIG-Fehlercode kann auch auftreten, wenn eine übergroße SQL-Anweisung an eine der sqlite3_prepare_v2()-Schnittstellen übergeben wird. Die maximale Länge einer SQL-Anweisung beträgt standardmäßig einen ähnlichen Wert von 1.000.000.000 Bytes. Die maximale SQL-Anweisungslänge kann zur Kompilierungszeit mit SQLITE_MAX_SQL_LENGTH oder zur Laufzeit mit sqlite3_limit(db,SQLITE_LIMIT_SQL_LENGTH,...) festgelegt werden.

Der SQLITE_WARNING-Ergebniscode wird von keiner C/C++-Schnittstelle zurückgegeben. Allerdings wird SQLITE_WARNING (oder besser gesagt einer seiner erweiterten Fehlercodes) manchmal als erstes Argument in einem sqlite3_log()-Rückruf verwendet, um anzuzeigen, dass ein ungewöhnlicher und möglicherweise unüberlegter Vorgang stattfindet.

Der SQLITE_WARNING_AUTOINDEX-Ergebniscode wird an den Rückruf von sqlite3_log() übergeben, wenn die automatische Indizierung verwendet wird. Dies kann Anwendungsentwicklern als Warnung dienen, dass die Datenbank von zusätzlichen Indizes profitieren könnte.