// SQLite-Fehlerreferenz

SQLITE_BUSY: Datenbank ist gesperrt

Eine andere Verbindung hält eine Sperre, die SQLite braucht, meist ein Schreiber in einem anderen Prozess. Stelle ein Busy-Timeout ein, halte Schreibtransaktionen kurz oder wechsle in den WAL-Modus.

Ergebniscode
SQLITE_BUSY
Name
5
Kategorie
Primäre Ergebniscodes
Fehlermeldung
database is locked

Was es bedeutet

SQLite lässt pro Datenbankdatei jeweils nur einen Schreiber zu. Wenn eine Verbindung eine Sperre benötigt, die eine andere Verbindung (im selben oder in einem anderen Prozess) hält, schlägt der Aufruf fehl mit SQLITE_BUSY und der Meldung database is locked, es sei denn, ein Busy-Handler ist eingestellt, in diesem Fall versucht SQLite zunächst bis zum Timeout einen erneuten Zugriff.

Standardmäßig gibt es keinen Busy-Handler, daher scheitert der Zugriff sofort. Im Rollback-Journal-Modus blockieren Leser auch das Committen eines Schreibers, und ein Schreiber blockiert neue Leser, während er committet; im WAL-Modus können Leser und ein Schreiber gleichzeitig arbeiten.

Häufige Ursachen

  • Zwei Prozesse oder Threads schreiben gleichzeitig in dieselbe Datenbank, ohne dass ein Busy-Timeout eingestellt ist.
  • Eine lange Schreibtransaktion (oder eine BEGIN die nie abgeschlossen wurde) hält die Sperre, während andere warten.
  • Eine Lese-Transaktion, die gestartet wurde mit BEGIN DEFERRED versucht, auf Schreiben umzustellen, während eine andere Verbindung schreibt; im WAL-Modus liefert das SQLITE_BUSY_SNAPSHOT und Warten hilft nicht.
  • Ein offener Cursor oder eine unvollendete Anweisung in deinem eigenen Programm hält eine Lesetransaktion offen.
  • Die Datenbankdatei befindet sich auf einem Netzwerkdateisystem, dessen Sperren nicht zuverlässig funktionieren.

Wie du es behebst

  1. Setze ein Busy-Timeout, damit SQLite wartet und es erneut versucht, statt sofort fehzuschlagen. Die meisten Bindings bieten das an (Pythons sqlite3 wartet standardmäßig 5 Sekunden; erhöhe es mit sqlite3.connect(path, timeout=30)). In SQL:

    PRAGMA busy_timeout = 5000;  -- milliseconds
  2. Stelle die Datenbank auf Write-Ahead Logging um, sodass Leser den Schreiber nicht mehr blockieren und der Schreiber die Leser nicht blockiert.

    PRAGMA journal_mode = WAL;
  3. Starte Schreibtransaktionen mit BEGIN IMMEDIATE, das die Schreibsperre vorab nimmt. Eine beschäftigte Verbindung wartet dann bei BEGIN (wo das Timeout gilt), anstatt mitten im Prozess zu scheitern.

    BEGIN IMMEDIATE;
    UPDATE counters SET n = n + 1 WHERE name = 'visits';
    COMMIT;
  4. Halte Transaktionen kurz, committe zügig und beende oder setze jede Anweisung zurück (Cursor schließen), damit keine Verbindung ein Lock länger hält als nötig.

  5. Halte die Datenbank auf einer lokalen Festplatte, nicht auf einer Netzwerkfreigabe.

Sicher reproduzieren

Verwende zwei separate Verbindungen zur selben Scratch-Datenbankdatei.

-- Connection 1 (for example the sqlite3 shell):
BEGIN IMMEDIATE;
INSERT INTO t VALUES (1);
-- Connection 2, same file, no busy timeout:
INSERT INTO t VALUES (2);   -- Runtime error: database is locked (5)

Fragen

Was ist der Unterschied zwischen SQLITE_BUSY und SQLITE_LOCKED?

SQLITE_BUSY bedeutet, dass eine andere Datenbankverbindung, meist in einem anderen Prozess, eine Sperre hält, die Konflikte verursacht. SQLITE_LOCKED bedeutet, dass der Konflikt innerhalb deiner eigenen Verbindung oder zwischen Verbindungen auftritt, die sich einen Cache teilen, zum Beispiel beim Löschen einer Tabelle, während eine Anweisung sie noch liest.

Beseitigt der WAL-Modus den Fehler database is locked?

Es beseitigt die meisten Konflikte zwischen Lesern und Schreibern, aber schreiben kann immer noch nur einer gleichzeitig, sodass gleichzeitige Schreiber weiterhin einen Busy-Timeout brauchen.

Zugehörige Fehler

Weitere Fehler bei primären Ergebniscodes

Der Code und der Meldungstext stammen aus der SQLite-Dokumentation zu Ergebnis- und Fehlercodes. Durchstöbere die vollständige SQLite-Fehlerliste oder Jeden Datenbankfehler durchsuchen.

// weniger Fehler, schnellere Korrekturen

Arbeiten mit SQLite in SQLly

Ein nativer SQL-Client für macOS, Windows und Linux mit schemabewusstem IntelliSense, Guardrails für riskante Anweisungen und klaren Fehlermeldungen, für SQLite und die anderen Datenbanken, mit denen du arbeitest.