Abstürze

DuckDB wird gründlich getestet anhand einer umfangreichen Testsuite. Dennoch können Fehler auftreten, die mitunter zu Abstürzen führen. Diese Seite enthält praktische Hinweise zur Fehlerbehebung bei DuckDB-Abstürzen.

Arten von Abstürzen

Es gibt einige wesentliche Arten von Abstürzen:

• Terminierungssignale: Der Prozess endet mit SIGSEGV (Segmentation Fault), SIGABRT usw.: Das sollte nie vorkommen. Bitte erstellen Sie ein Issue.

• Interne Fehler: Eine Operation kann zu einem Internal Error führen, z. B.:

  INTERNAL Error:
  Attempted to access index 3 within vector of size 3

  Nach einem internen Fehler wechselt DuckDB in einen eingeschränkten Modus, in dem weitere Operationen die folgende Fehlermeldung ergeben:

  FATAL Error:
  Failed: database has been invalidated because of a previous fatal error.
  The database must be restarted prior to being used again.

• Speicherfehler (Out of Memory): Ein DuckDB-Absturz kann auch darauf zurückgehen, dass das Betriebssystem den Prozess beendet. Beispielsweise führen viele Linux-Distributionen einen OOM-Reaper oder OOM-Killer-Prozess aus, der Prozesse beendet, um deren Speicher freizugeben und so zu verhindern, dass dem Betriebssystem der Speicher ausgeht. Wenn Ihre DuckDB-Sitzung vom OOM-Reaper beendet wurde, konsultieren Sie die Seite „OOM-Fehler“.

Daten wiederherstellen

Wenn Ihre DuckDB-Sitzung vor dem Absturz in eine persistente Datenbankdatei geschrieben hat, liegt möglicherweise eine WAL-Datei (Write-Ahead Log) neben Ihrer Datenbank mit dem Namen ⟨database_filename⟩.wal{:.language-sql .highlight}. Um Daten aus der WAL-Datei wiederherzustellen, starten Sie einfach eine neue DuckDB-Sitzung auf der persistenten Datenbank. DuckDB spielt dann das Write-Ahead Log erneut ab und führt eine Checkpoint-Operation aus, wodurch die Datenbank in den Zustand vor dem Absturz zurückgesetzt wird.

Den Absturz beheben

Die neuesten Stable- und Preview-Builds verwenden

DuckDB wird ständig weiterentwickelt, daher besteht die Chance, dass der Fehler, auf den Sie gestoßen sind, im Code bereits behoben wurde. Versuchen Sie zuerst ein Update auf den aktuellen Stable-Build. Wenn das das Problem nicht löst, versuchen Sie den Preview-Build (auch „Nightly Build“ genannt).

Wenn Sie DuckDB mit einem offenen Pull Request im Code verwenden möchten, können Sie versuchen, aus dem Quellcode zu bauen.

Nach vorhandenen Issues suchen

Es ist möglich, dass jemand anderes den Fehler, der den Absturz verursacht, bereits gemeldet hat. Bitte suchen Sie im GitHub-Issue-Tracker nach der Fehlermeldung, um möglicherweise verwandte Issues zu finden. DuckDB hat eine große Community, und es gibt möglicherweise Vorschläge für einen Workaround.

Den Query-Optimizer deaktivieren

Manche Abstürze werden durch die Query-Optimizer-Komponente von DuckDB verursacht. Um festzustellen, ob der Optimizer den Absturz verursacht, deaktivieren Sie ihn und führen Sie die Abfrage erneut aus:

PRAGMA disable_optimizer;

Läuft die Abfrage erfolgreich durch, wurde der Absturz durch eine oder mehrere Optimizer-Regeln verursacht. Um die konkreten Regeln einzugrenzen, die den Absturz verursacht haben, können Sie versuchen, Optimizer-Regeln gezielt zu deaktivieren. So kann Ihre Abfrage weiterhin von den übrigen Optimizer-Regeln profitieren.

Versuchen Sie, das Problem einzugrenzen

Manche Probleme entstehen durch das Zusammenspiel verschiedener Komponenten und Erweiterungen oder treten nur auf bestimmten Plattformen oder in bestimmten Client-Sprachen auf. Oft lässt sich das Problem auf ein kleineres Teilstück eingrenzen.

Reproduzieren in reinem SQL

Probleme können auch durch Unterschiede in den Client-Bibliotheken entstehen. Um festzustellen, ob das der Fall ist, versuchen Sie, das Problem mit reinen SQL-Abfragen im DuckDB-CLI-Client zu reproduzieren. Wenn Sie das Problem im Kommandozeilen-Client nicht reproduzieren können, hängt es wahrscheinlich mit der Client-Bibliothek zusammen.

Andere Hardware-Umgebung

Nach unserer Erfahrung entstehen mehrere Abstürze durch fehlerhafte Hardware (überhitzte Festplatten, übertaktete CPUs usw.). Es lohnt sich daher, dieselbe Workload auf einem anderen Rechner auszuführen.

Die Abfrage zerlegen

Es ist sinnvoll, die Abfrage in mehrere kleinere Abfragen zu zerlegen, die jeweils eine eigene DuckDB-Erweiterung und SQL-Funktion nutzen.

Wenn Sie beispielsweise eine Abfrage haben, die auf einen Datensatz in einem AWS-S3-Bucket zielt und zwei Joins darauf ausführt, versuchen Sie, sie wie folgt in eine Reihe kleinerer Schritte umzuschreiben. Laden Sie die Dateien des Datensatzes manuell herunter und laden Sie sie in DuckDB. Führen Sie dann den ersten Join und den zweiten Join getrennt aus. Tritt der Absturz beim mehrstufigen Ansatz in einem Schritt weiterhin auf, ist die auslösende Abfrage eine gute Grundlage für ein minimales reproduzierbares Beispiel. Funktioniert der mehrstufige Ansatz und stürzt der Prozess nicht mehr ab, rekonstruieren Sie die ursprüngliche Abfrage und beobachten Sie, welcher Schritt den Fehler wieder einführt. In beiden Fällen verstehen Sie die Ursache besser und haben möglicherweise auch einen Workaround, den Sie sofort nutzen können. In jedem Fall sollten Sie in Erwägung ziehen, ein Issue mit Ihren Erkenntnissen einzureichen.

Issue einreichen

Wenn Sie einen Absturz in DuckDB gefunden haben, sollten Sie ein Issue in unserem GitHub-Issue-Tracker mit einem minimalen reproduzierbaren Beispiel einreichen.