aljaz/turso
1
0
Fork 0
mirror of https://github.com/aljazceru/turso.git synced 2025-12-17 00:24:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge 'Document ThreadSanitizer in CONTRIBUTING.md' from Pekka Enberg

Browse Source 
Closes #3739
This commit is contained in:
Pekka Enberg
2025-10-16 08:43:33 +03:00
committed by GitHub
parent 0ae53e6270 08f010b969
commit 012ac00e46
1 changed files with 38 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
CONTRIBUTING.md
View File

@@ -128,6 +128,44 @@ echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid
cargo bench --bench benchmark -- --profile-time=5 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 ## 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), 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. 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 ## Compatibility tests
The `testing/test.all` is a starting point for adding functional tests using a similar syntax to SQLite. The `testing/test.all` is a starting point for adding functional tests using a similar syntax to SQLite.