Skip to main content

QuerySense

Analyze PostgreSQL EXPLAIN plans and get actionable performance fixes.

QuerySense: 2.3s → 0.04s with one index

$ 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)

Source distribution for querysense 0.3.0
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)

Table of built distributions (wheels) for querysense 0.3.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page