Implement MQL panel for Django Debug Toolbar

Author: aclark4life

README.md

@@ -1,3 +1,216 @@
-# django-mongodb-extensions
+# Django MongoDB Extensions
 
-Extensions for Django MongoDB Backend
+A collection of extensions for Django projects using
+[django-mongodb-backend](https://github.com/mongodb-labs/django-mongodb-backend).
+Inspired by
+[django-extensions](https://github.com/django-extensions/django-extensions),
+this package provides MongoDB-specific tools to enhance your development
+workflow.
+
+## Installation
+
+```bash
+pip install django-mongodb-extensions
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    'django_mongodb_extensions',
+    ...
+]
+```
+
+## Features
+
+### MQL Panel for Django Debug Toolbar
+
+The MQL (MongoDB Query Language) Panel provides detailed insights into MongoDB queries executed during a request, similar to the SQL panel for relational databases.
+
+#### Setup
+
+Add to Django Debug Toolbar panels:
+
+```python
+DEBUG_TOOLBAR_PANELS = [
+    ...
+    'django_mongodb_extensions.debug_toolbar.panels.MQLPanel',
+    ...
+]
+```
+
+#### Features
+
+- **Query Tracking**: Automatically tracks all MongoDB operations (find, aggregate, count, etc.)
+- **Query Timing**: Shows execution time for each query with visual timeline
+- **Query Grouping**: Groups similar and duplicate queries for easy identification
+- **Interactive Execution**: Re-execute read queries and view results directly in the panel
+- **Explain Plans**: View MongoDB explain output for queries
+- **BSON Support**: Proper handling of MongoDB-specific types (ObjectId, datetime, etc.)
+- **Thread-Safe**: Works correctly in multi-threaded environments
+
+#### Configuration
+
+You can customize the MQL panel behavior with these Django settings:
+
+```python
+# Maximum number of documents to return when re-executing queries (default: 100)
+DJDT_MQL_MAX_SELECT_RESULTS = 100
+```
+
+#### Usage
+
+Once configured, the MQL panel will automatically appear in the Django Debug Toolbar when MongoDB queries are executed. You can:
+
+1. **View Queries**: See all MongoDB operations with timing and parameters
+2. **Re-execute Queries**: Click "Sel" to re-execute read operations and view results
+3. **Explain Queries**: Click "Expl" to view MongoDB's query execution plan
+4. **Identify Issues**: Slow queries are highlighted, and duplicate queries are grouped
+
+## Performance Considerations
+
+### Query Result Limits
+
+When re-executing queries through the debug toolbar, results are limited to prevent memory issues:
+- Default limit: 100 documents
+- Configurable via `DJDT_MQL_MAX_SELECT_RESULTS`
+- Cursors are properly closed to free server resources
+
+### Memory Management
+
+The MQL panel uses `WeakSet` for tracking patched connections, ensuring that closed connections are garbage collected and don't cause memory leaks.
+
+### Thread Safety
+
+The panel is designed to work correctly in multi-threaded environments:
+- Connection patching is idempotent
+- Each request gets its own logger instance
+- Thread-local connection storage prevents cross-request contamination
+
+## Troubleshooting
+
+### Django Debug Toolbar Not Installed
+
+Before the MQL panel can work, you must have Django Debug Toolbar properly installed and configured. Follow the [official installation instructions](https://django-debug-toolbar.readthedocs.io/en/latest/installation.html):
+
+1. **Install the package**:
+   ```bash
+   pip install django-debug-toolbar
+   ```
+
+2. **Add to `INSTALLED_APPS`**:
+   ```python
+   INSTALLED_APPS = [
+       # ...
+       "debug_toolbar",
+       # ...
+   ]
+   ```
+
+3. **Add the URLs**:
+   ```python
+   from django.urls import include, path
+   from debug_toolbar.toolbar import debug_toolbar_urls
+
+   urlpatterns = [
+       # ... your URLconf ...
+   ] + debug_toolbar_urls()
+   ```
+
+4. **Add the middleware**:
+   ```python
+   MIDDLEWARE = [
+       # ...
+       "debug_toolbar.middleware.DebugToolbarMiddleware",
+       # ...
+   ]
+   ```
+
+5. **Configure `INTERNAL_IPS`**:
+   ```python
+   INTERNAL_IPS = [
+       "127.0.0.1",
+   ]
+   ```
+
+For complete setup instructions, including Docker configurations and troubleshooting, see the [Django Debug Toolbar documentation](https://django-debug-toolbar.readthedocs.io/en/latest/installation.html).
+
+### Panel Not Showing
+
+If the MQL panel doesn't appear:
+
+1. Verify Django Debug Toolbar is installed and working (see above)
+2. Verify `django_mongodb_extensions` is in `INSTALLED_APPS`
+3. Check that `MQLPanel` is in `DEBUG_TOOLBAR_PANELS`
+4. Ensure you're using `django-mongodb-backend` as your database engine
+5. Verify MongoDB queries are actually being executed in your view
+
+### Queries Not Tracked
+
+If queries aren't being tracked:
+
+1. Ensure Debug Toolbar is enabled (`DEBUG = True`)
+2. Check that the toolbar middleware is installed
+3. Verify your IP is in `INTERNAL_IPS`
+4. Check that queries are executed during the request (not in background tasks)
+
+### Re-execution Errors
+
+If you get errors when re-executing queries:
+
+- **"Query does not have structured data"**: The query was logged before security improvements. Only newly logged queries can be re-executed.
+- **"Unsupported operation"**: Write operations (insert, update, delete) cannot be re-executed for safety.
+- **Connection errors**: Check your MongoDB connection settings and ensure the server is accessible.
+
+## Security
+
+The MQL panel implements several security measures:
+
+- **Signed Forms**: All query re-execution requests use Django's signed data to prevent tampering
+- **Structured Data Only**: Only queries with validated structured data can be re-executed
+- **Read-Only Re-execution**: Write operations cannot be re-executed through the panel
+- **Server-Side Validation**: All query data is validated before execution
+
+## Development
+
+### Running Tests
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=django_mongodb_extensions --cov-report=html
+```
+
+### Code Quality
+
+```bash
+# Format code
+ruff format .
+
+# Lint code
+ruff check .
+
+# Type checking (if using mypy)
+mypy django_mongodb_extensions
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## License
+
+See [LICENSE](LICENSE) file for details.