jepsen-io/duckdbJepsen-basiertes Framework für transaktionale Korrektheitstests für DuckDB, das Isolationsanomalien wie G2-Item- und SSI-Verstöße durch randomisierte Workloads und den Elle-Checker erkennt.
Jepsen-Tests für die DuckDB-Datenbank. Läuft lokal, anstatt auf einem entfernten Cluster. Der Test startet eine Sammlung lokaler Prozesse, die eine DuckDB-Datei lokal öffnen, und interagiert mit ihnen über STDIN/STDOUT.
Dies ist ein früher Prototyp. Er schaltet sich ein, führt Transaktionen aus, überprüft sie auf Korrektheit und meldet Fehler, aber ich bin nicht sicher, ob diese Fehler echt sind.
Sie benötigen ein JDK (21+), Git, Gnuplot, Graphviz sowie Leiningen. Im Gegensatz zu den meisten Jepsen-Tests läuft dies vollständig lokal; Sie benötigen keinen Cluster von Maschinen, SSH-Schlüssel usw.
sudo apt install openjdk leiningen gnuplot graphviz
brew install openjdk leiningen gnuplot graphviz
Um einen Test auszuführen, versuchen Sie:
lein run test
DuckDB bietet (vermutlich) standardmäßig Strong SI, und das ist es, wonach der Test sucht. Es erlaubt jedoch G2-item, was eine Verletzung von Repeatable Read darstellt. Um dies zu demonstrieren, versuchen Sie:
lein run test --time-limit 10 --expected-consistency-model serializable --max-writes-per-key 8
Wir bitten darum, zehn Sekunden zu testen, um nach Verletzungen der Serialisierbarkeit zu suchen, und (um kleine, lesbare Beispiele zu erzeugen) nur 8 Elemente pro Schlüssel zu schreiben. Beispiele für G2-item sollten in store/latest/elle/G2-item verfügbar sein.
Es stehen mehrere Optimierungsoptionen zur Verfügung. Hilfe zu den verschiedenen Optionen erhalten Sie über lein run test --help.
Testergebnisse werden nach store/<test-name>/<date>/ geschrieben und als store/latest symbolisch verlinkt. Jedes dieser Testverzeichnisse ist in sich abgeschlossen; Sie können es kopieren, daraus ein Tar-Archiv erstellen, später analysieren, löschen usw. Sie können auch einen Webserver ausführen, um Ergebnisse zu durchsuchen.
lein run serve
Ein REPL ist verfügbar; siehe lein repl.
Das Test-Framework befindet sich in diesem Verzeichnis; seine Projektdatei ist project.clj, sein Quellcode liegt in src/ usw.
Das Test-Framework führt ein separates Programm aus, den "lokalen Knoten", der die DuckDB-Bibliothek einbettet und Transaktionen dagegen ausführt. Das Test-Framework generiert zufällige Transaktionen für eine gegebene Arbeitslast, sendet sie über HTTP an den lokalen Knoten und protokolliert die Ergebnisse dieser Transaktionen, wobei es am Ende auf verschiedene transaktionale Anomalien prüft. Wir suchen nach Strong Snapshot Isolation mit dem Elle-Checker (https://github.com/jepsen-io/elle).
Der lokale Knoten hat einen kleinen HTTP-Server, der abstrakte Transaktionen (z. B. "Schlüssel x lesen, dann y auf 5 setzen") vom Test-Framework empfängt und sie in Transaktionen übersetzt, die gegen den DuckDB-JDBC-Treiber ausgeführt werden.
Wir können eine Art von Fehler injizieren: Prozessabbrüche.
Wir haben zwei Arbeitslasten.
Die erste, append, führt Transaktionen aus, die eindeutige Ganzzahlen an Listen anhängen und die Inhalte dieser Listen lesen. Jede Liste lebt in einer einzelnen Zeile, verteilt auf mehrere Tabellen. Listen werden durch einen Primärschlüssel oder einen nicht indizierten Sekundärschlüssel identifiziert. Listen werden entweder als Textfelder oder als DuckDB-INTEGER[ ]-Listen codiert. Mutationen erfolgen entweder mit INSERT ON CONFLICT UPDATE oder MERGE INTO.
Die zweite, fkey-register, führt Lese- und Schreiboperationen auf Integer-Registern durch. In DuckDB speichern wir diese Register in zwei Tabellen. Eine logische Tabelle bildet Schlüssel auf physische IDs ab, mit einem Fremdschlüssel. Eine physische Tabelle bildet physische IDs auf Werte ab. Wir verwenden einen einfachen JOIN zwischen beiden zum Lesen. Schreibvorgänge werden entweder durch Aktualisieren der physischen Zeile oder durch Erstellen einer neuen physischen Zeile und Ändern des logischen Zeigers darauf durchgeführt. Ich habe diese Arbeitslast erst heute zum Laufen gebracht; sie läuft, ist aber noch nicht ausgereift.
Copyright © 2026 Jepens, LLC
Dieses Programm und die begleitenden Materialien werden unter den Bedingungen der Eclipse Public License 2.0 zur Verfügung gestellt, die unter https://www.eclipse.org/legal/epl-2.0 verfügbar ist.
Dieser Quellcode kann auch unter den folgenden sekundären Lizenzen zur Verfügung gestellt werden, wenn die Bedingungen für eine solche Verfügbarkeit in der Eclipse Public License v. 2.0 erfüllt sind: GNU General Public License, veröffentlicht von der Free Software Foundation, entweder Version 2 der Lizenz oder (nach Ihrer Wahl) eine spätere Version, mit der GNU Classpath Exception, die unter https://www.gnu.org/software/classpath/license.html verfügbar ist.