GitHub - Alurith/sqlitewatch: A runtime profiler for SQLite applications · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
Alurith
sqlitewatch
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
master
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>12 Commits<br>12 Commits
fixtures
fixtures
src/sqlitewatch
src/sqlitewatch
tests
tests
.gitignore
.gitignore
.python-version
.python-version
LICENSE
LICENSE
README.md
README.md
pyproject.toml
pyproject.toml
uv.lock
uv.lock
View all files
Repository files navigation
SQLiteWatch
SQLiteWatch is a runtime profiler for SQLite applications on Linux. It observes the SQLite C API without requiring changes to your application, ORM, or database code.
It can:
capture SQL executed by an application and its child processes;
aggregate equivalent queries;
report full scans, sorts, automatic indexes, and SQLite VM work;
follow wrappers, workers, subprocesses, and development autoreloaders;
enforce optional performance limits in local development or CI;
verify SQLite compatibility with a dedicated Check command.
SQLiteWatch currently supports Linux x86_64 and Python 3.11–3.13.
Installation
Install a specific released version directly from its Git tag:
uv tool install "git+https://github.com/Alurith/sqlitewatch.git@v0.2.1"
This installs SQLiteWatch in an isolated environment and makes the sqlitewatch command available globally. To reinstall or switch to that exact version:
uv tool install --force "git+https://github.com/Alurith/sqlitewatch.git@v0.2.1"
You can also run SQLiteWatch from a source checkout:
[arguments...]">git clone https://github.com/Alurith/sqlitewatch.git<br>cd sqlitewatch<br>uv sync --locked<br>uv run sqlitewatch -- command> [arguments...]
The -- separator is required. Options before it belong to SQLiteWatch; everything after it is the command being observed.
Basic usage
Profile a Python application:
sqlitewatch -- python app.py
Profile a test suite:
sqlitewatch -- pytest
Profile a Django development server:
sqlitewatch -- python manage.py runserver
SQLiteWatch follows child processes by default, including Django's autoreloader. For a long-running server, exercise the application normally and press Ctrl-C when you want SQLiteWatch to produce the report.
When profiling a different project, run the SQLiteWatch executable while remaining in the target project's directory:
/path/to/sqlitewatch/.venv/bin/sqlitewatch -- uv run -m your_application
Understanding the report
The terminal report starts with a clear operational result:
WORKING: SQLite activity was measured successfully;
WORKING WITH WARNINGS: measurement worked, but some activity could not be evaluated completely;
PARTIAL: SQLite was observed with incomplete instrumentation or process coverage;
SQLITE NOT DETECTED: no SQLite activity was found;
FAILED: instrumentation could not complete.
The default terminal output is intentionally concise. It hides healthy queries and shows only query patterns with potential concerns:
FULL_SCAN;
SORT;
AUTO_INDEX;
configured rule violations.
Equivalent query patterns are grouped together. The report includes execution counts and aggregate metrics for each problem pattern.
A warning does not necessarily mean the application failed. For example, a data-quality warning means SQLiteWatch worked but could not evaluate every observed operation with full confidence.
Complete JSON report
Use JSON when you need every query, process, module, and metric:
sqlitewatch --format json -- python app.py
Write the report to a file:
sqlitewatch \<br>--format json \<br>--output sqlitewatch.json \<br>-- python app.py
The JSON report uses schema version 3 and includes process-tree and process-instance information.
Reports may contain SQL literals or other application data. Treat them as potentially sensitive artifacts.
Check
Check verifies whether SQLiteWatch can detect and instrument the SQLite implementation used by an application:
sqlitewatch check -- python app.py
For a server:
sqlitewatch...