QuerySense
Analyze PostgreSQL EXPLAIN plans and get actionable performance fixes.
$ querysense analyze slow_query.json
[CRITICAL] Row estimation error on orders (5,000x off)
Planner estimated 50 rows, actually scanned 250,000.
Fix: ANALYZE orders;
[WARNING] Sequential scan on orders (250,000 rows)
Estimated improvement: 57x faster
Fix: CREATE INDEX idx_orders_status ON orders(status);
# Get ONLY the SQL fixes (copy-paste ready)
$ querysense fix slow_query.json > fixes.sql
$ psql < fixes.sql
Install
pip install querysense
Or with pipx (recommended for CLI tools):
pipx install querysense
Optional AI features (not required for core functionality):
pip install querysense[ai] # Adds Claude-based explanations
Usage
# 1. Export your slow query's plan
psql -c "EXPLAIN (ANALYZE, FORMAT JSON)
SELECT * FROM orders WHERE status = 'pending'" > plan.json
# 2. Analyze it
querysense analyze plan.json
# 3. Get copy-paste SQL fixes
querysense fix plan.json > fixes.sql
# 4. Apply the fixes
psql < fixes.sql
What It Catches
| Issue | Severity | Fix |
|---|---|---|
| Row estimation >1000x off | CRITICAL | ANALYZE table |
| Row estimation >100x off | WARNING | ANALYZE table |
| Sequential scan >10k rows | WARNING | CREATE INDEX |
| Nested loop with 1000+ scans | CRITICAL | Add join index |
| Hash/sort spilling to disk | WARNING | Increase work_mem |
| Parallel query not used | INFO | Check max_parallel_workers |
| Correlated subquery | WARNING | Rewrite as JOIN |
| Missing BUFFERS in EXPLAIN | INFO | Use EXPLAIN (ANALYZE, BUFFERS) |
| Foreign key without index | WARNING/CRITICAL | CREATE INDEX on FK column |
| Stale statistics | WARNING/CRITICAL | ANALYZE table |
| Table bloat | INFO/CRITICAL | VACUUM ANALYZE |
11 rules that catch real PostgreSQL performance problems.
Verify It Helped
# Before
querysense analyze before.json
[WARNING] Sequential scan on orders (250,000 rows)
# Apply fix
psql -c "CREATE INDEX idx_orders_status ON orders(status);"
# After
psql -c "EXPLAIN (ANALYZE, FORMAT JSON)
SELECT * FROM orders WHERE status = 'pending'" > after.json
querysense analyze after.json
# No performance issues found!
# Execution time: 2.3s → 0.02s (100x faster)
JSON Output
querysense analyze plan.json --json
Performance
Stress-tested on 250,000 query plans:
- 652 plans/second analysis throughput
- 1.7GB peak memory - production-viable footprint
- 0.00% error rate - deterministic rule engine
Why QuerySense?
| Feature | QuerySense | pgMustard | pganalyze | PEV2 |
|---|---|---|---|---|
| Price | Free | $29/mo | $499/mo | Free |
| CLI tool | Yes | No | No | No |
| Copy-paste SQL fixes | Yes | Partial | Yes | No |
| Works offline | Yes | No | No | Yes |
| No account required | Yes | No | No | Yes |
Philosophy
- Deterministic - No AI, no API keys, works offline
- Actionable - Every issue includes copy-paste SQL to fix it
- Focused - 11 rules that catch real problems
- Honest - Only flags issues we're confident about
Contributing
Have a slow query? Open an issue with the EXPLAIN JSON.
If it's a common pattern, we'll add a rule.
License
MIT
v0.3.0 - 11 PostgreSQL rules, 652 plans/sec
Metadata
Release files for querysense 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| querysense-0.3.0.tar.gz | 5.3 MB | Without provenance | Details for querysense-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| querysense-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for querysense-0.3.0-py3-none-any.whl |
Total release size: 5.4 MB
Release files / querysense-0.3.0.tar.gz
| Download URL | querysense-0.3.0.tar.gz |
|---|---|
| Size | 5.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
02dc9af7ea43a4597f637af3d811b5b95c8659f0ef3e45a2a57a3db572692cde
|
|
BLAKE2b-256 checksum How to use checksums |
a51cb1ff715c20fe9c5c4593282ec36194a2a294e61a62b622a3df87d61cf54e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / querysense-0.3.0-py3-none-any.whl
| Download URL | querysense-0.3.0-py3-none-any.whl |
|---|---|
| Size | 94.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
311d57f475f7f5a44f808533c195bd15ee9455447ca410fa4357c69a79fb170a
|
|
BLAKE2b-256 checksum How to use checksums |
983fe1eb5241507936c4c4ea801b31146333e024d240f2ba6520de5fde8ccd8f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for querysense 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.