QuerySense

Analyze PostgreSQL EXPLAIN plans and get actionable performance fixes.

pip install querysense

```bash
$ 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);

Install

pip install -e .

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. Apply the suggested fixes
psql -c "CREATE INDEX idx_orders_status ON orders(status);"

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)

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 at Scale

Stress-tested on 250,000 real-world query plans:

Metric	Value
Analysis throughput	652 plans/second
Issues detected	584,957 across 8 rule types
Peak memory	1.7GB
Error rate	0.00%

Top issues found:

• Sequential scans on large tables: 289,618
• Missing parallel execution: 218,195
• Row estimate errors (>100x off): 39,696
• Queries spilling to disk: 37,448

QuerySense handles fleet-scale databases.

Philosophy

• Deterministic - No AI, no API keys, works offline
• Actionable - Every issue includes copy-paste SQL to fix it
• Focused - 8 rules that catch real problems, not 50 that cause noise
• Honest - Only flags issues we're confident about. No false positives.

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.2.0 - 8 rules, smart index recommendations, tested on 250k plans