Django QueryGuard 🛡️

Zero-UI middleware for analyzing Django SQL performance right in your terminal or API responses.

📚 Full Documentation (Wiki)

---

🚀 Why QueryGuard?

• Catch performance issues early during development.
• Pinpoint the exact Python line causing N+1 or duplicate queries.
• API-native & CI-friendly — no browser toolbar needed.
• Lightweight and focused on SQL performance.
• Zero Data Leakage: 100% Thread-Safe, ensuring metrics stay isolated per request.

---

⚖️ QueryGuard vs. Django Debug Toolbar

While Django Debug Toolbar is a great visual tool, QueryGuard follows a different philosophy for modern backend workflows:

Feature	Django Debug Toolbar	QueryGuard
UI	Browser sidebar	Terminal + HTTP headers
APIs / JSON	Awkward	Native support
Culprit detection	Manual inspection	Automatic file + line reporting
CI/CD integration	Hard to automate	Easy to plug into tests / pipelines

---

🧵 Thread-Safety & Concurrency

QueryGuard is built for modern, high-traffic Django environments (Gunicorn, uWSGI, Daphne).

By leveraging asgiref.local.Local (or threading.local as fallback), it guarantees that:

• Metrics remain isolated: SQL counts for User A will never leak into the headers for User B.
• No Global State: Data is strictly scoped to the lifecycle of a single HTTP request.
• Minimal Overhead: The monitoring logic is lightweight and thread-contained

---

⚙️ Quick Start

# Clone & setup
pip install uv  # optional for fast dependency handling
git clone https://github.com/addonol/django-query-guard
cd django-query-guard
uv sync --all-extras --dev  # or your usual virtualenv + pip

Enable the middleware in settings.py:

MIDDLEWARE = [
    # ...
    "query_guard.middleware.SQLPerformanceMiddleware",
]

Run your server:

python manage.py runserver

Make a request and watch your terminal for QueryGuard output.

📊 Example Output

==================== EXECUTING VIEW ====================
08:34:31 [WARNING] query_guard:
┌───────────────────────────────────────────────┐
│ QUERYGUARD REPORT                             │
├───────────────────────────────────────────────┤
│ Status     : DUPLICATE SQL                    │
│ Path       : /demo-url/                       │
├───────────────────────────────────────────────┤
│ Queries    : 3                                │
│ Duplicates : 1                                │
│ Duration   : 0.0090s                          │
│ Culprit    : demo.py:111 (demo_view)          │
└───────────────────────────────────────────────┘

==================== INJECTED HEADERS ======================
X-QueryGuard-Count: 3
X-QueryGuard-Duplicates: 1
X-QueryGuard-Culprit: demo.py:111 (demo_view)
============================================================

Typical response headers:

• X-QueryGuard-Count
• X-QueryGuard-Duplicates
• X-QueryGuard-Culprit

You can inspect these via browser dev tools, curl -i, Postman, or in your Django tests.

---

📚 Full Documentation (Wiki)

Section	Description
Home	Overview, philosophy, key concepts
Getting Started	Installation and basic setup
Configuration	Settings and thresholds
Usage & Examples	N+1 and duplicate query examples
Development & Contributing	Local setup, tests, contribution guidelines
Roadmap & FAQ	Future plans and common questions

---

Quick demo

python demo.py

---

🤝 Contributing

Contributions are welcome!

• Read the Development & Contributing guide.
• Open issues here: https://github.com/addonol/django-query-guard/issues.

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.