diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0e1b7aa5..1aaa08f32 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,6 +128,44 @@ echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid cargo bench --bench benchmark -- --profile-time=5 ``` +## Debugging bugs + +### Query execution debugging + +Turso aims towards SQLite compatibility. If you find a query that has different behavior than SQLite, the first step is to check what the generated bytecode looks like. + +To do that, first run the `EXPLAIN` command in `sqlite3` shell: + +``` +sqlite> EXPLAIN SELECT first_name FROM users; +addr opcode p1 p2 p3 p4 p5 comment +---- ------------- ---- ---- ---- ------------- -- ------------- +0 Init 0 7 0 0 Start at 7 +1 OpenRead 0 2 0 2 0 root=2 iDb=0; users +2 Rewind 0 6 0 0 +3 Column 0 1 1 0 r[1]= cursor 0 column 1 +4 ResultRow 1 1 0 0 output=r[1] +5 Next 0 3 0 1 +6 Halt 0 0 0 0 +7 Transaction 0 0 1 0 1 usesStmtJournal=0 +8 Goto 0 1 0 0 +``` + +and then run the same command in Turso's shell. + +If the bytecode is different, that's the bug -- work towards fixing code generation. +If the bytecode is the same, but query results are different, then the bug is somewhere in the virtual machine interpreter or storage layer. + +### Stress testing with sanitizers + +If you suspect a multi-threading issue, you can run the stress test with ThreadSanitizer enabled as follows: + +```console +rustup toolchain install nightly +rustup override set nightly +cargo run -Zbuild-std --target x86_64-unknown-linux-gnu -p turso_stress -- --vfs syscall --nr-threads 4 --nr-iterations 1000 +``` + ## Finding things to work on The issue tracker has issues tagged with [good first issue](https://github.com/tursodatabase/limbo/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), @@ -155,33 +193,6 @@ To produce pull requests like this, you should learn how to use Git's interactiv For a longer discussion on good commits, see Al Tenhundfeld's [What makes a good git commit](https://www.simplethread.com/what-makes-a-good-git-commit/), for example. - -## Debugging query execution - -Turso aims towards SQLite compatibility. If you find a query that has different behavior than SQLite, the first step is to check what the generated bytecode looks like. - -To do that, first run the `EXPLAIN` command in `sqlite3` shell: - -``` -sqlite> EXPLAIN SELECT first_name FROM users; -addr opcode p1 p2 p3 p4 p5 comment ----- ------------- ---- ---- ---- ------------- -- ------------- -0 Init 0 7 0 0 Start at 7 -1 OpenRead 0 2 0 2 0 root=2 iDb=0; users -2 Rewind 0 6 0 0 -3 Column 0 1 1 0 r[1]= cursor 0 column 1 -4 ResultRow 1 1 0 0 output=r[1] -5 Next 0 3 0 1 -6 Halt 0 0 0 0 -7 Transaction 0 0 1 0 1 usesStmtJournal=0 -8 Goto 0 1 0 0 -``` - -and then run the same command in Turso's shell. - -If the bytecode is different, that's the bug -- work towards fixing code generation. -If the bytecode is the same, but query results are different, then the bug is somewhere in the virtual machine interpreter or storage layer. - ## Compatibility tests The `testing/test.all` is a starting point for adding functional tests using a similar syntax to SQLite.