slowquery-detective

Catch slow Postgres queries live. Fingerprint the pattern. Run EXPLAIN asynchronously. Suggest the index. A drop-in FastAPI + SQLAlchemy middleware.

What it does

1. Fingerprints every query via sqlglot — WHERE id=1 and WHERE id=2 collapse into one row, so you see the pattern that's slow.
2. Runs EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) asynchronously for queries that cross the p95 threshold, off the request path.
3. Suggests fixes via a deterministic rules engine (seq-scan on large tables, missing FK indexes, sort without index, function in WHERE, SELECT *, N+1). When no rule matches, an OpenRouter-backed LLM explains the plan in plain English.
4. Exposes a tiny dashboard API (optional router) so a frontend can render live p95 timelines and one-click index suggestions.

This repository is the PyPI package only. The demo service and dashboard live in:

• Abdul-Muizz1310/slowquery-demo-backend — feathers-generated FastAPI service with a seeded 1M-row dataset
• Abdul-Muizz1310/slowquery-dashboard-frontend — Next.js dashboard

3-line integration

from slowquery_detective import install

install(app, engine)

Optional: mount the dashboard API on the same app.

from slowquery_detective import install, dashboard_router

install(app, engine)
app.include_router(dashboard_router, prefix="/_slowquery")

Status: this repo is at Phase 4a S1 — Bootstrap. The install helper is defined by docs/specs/05-middleware.md and lands in S3. See docs/ARCHITECTURE.md for the component map and docs/DEMO.md for the reproduction script.

Install

pip install slowquery-detective[fastapi]
# or, to enable the LLM fallback:
pip install slowquery-detective[fastapi,llm]

Development

git clone https://github.com/Abdul-Muizz1310/slowquery-detective
cd slowquery-detective
uv sync --all-extras
uv run pytest
uv run ruff check .
uv run mypy src/

License

MIT — see LICENSE.