Django Pgactivity

Warnings

• breaking Version 1.8.0 dropped support for Python 3.9. Users on Python 3.9 must upgrade their Python version to 3.10 or later before upgrading to django-pgactivity 1.8.0.
  Fix: Upgrade Python to 3.10 or higher. For example, `pyenv install 3.10.13 && pyenv local 3.10.13`.
• breaking Earlier versions dropped support for older environments: 1.7.0 dropped Python 3.8 support, and 1.5.0 dropped Django 3.2 and Postgres 12 support. Ensure your environment meets the compatibility requirements (Python 3.10+, Django 4.2+, Postgres 14+).
  Fix: Review the compatibility matrix (Python 3.10-3.14, Django 4.2-6.0, Psycopg 2-3, Postgres 14-18) and upgrade your dependencies accordingly.
• gotcha Forgetting to add 'pgactivity' to `INSTALLED_APPS` in your Django `settings.py` will result in `AppRegistryNotReady` or `ModuleNotFoundError` errors when trying to use its features like the `PGActivity` model or management commands.
  Fix: Add `'pgactivity'` to the `INSTALLED_APPS` list in your Django `settings.py` file.
• gotcha Effective use of `django-pgactivity` requires a correctly configured PostgreSQL database in Django's `settings.DATABASES`. Incorrect `ENGINE`, `NAME`, `USER`, `PASSWORD`, `HOST`, or `PORT` will prevent the library from connecting to and monitoring your database.
  Fix: Double-check your `DATABASES` configuration in `settings.py` to ensure all PostgreSQL connection details are accurate and the Django application can successfully connect to your PostgreSQL instance.
• gotcha The `pg_stat_activity` view (which `django-pgactivity` queries) provides extensive information about active queries, but it does not directly expose memory usage statistics. For memory monitoring, you would need to use operating-system level facilities or more specialized PostgreSQL monitoring tools.
  Fix: Be aware of the data available through `pg_stat_activity` and integrate with other monitoring solutions if detailed memory usage per query is required.

Install

• pip install django-pgactivity Install stable version

Imports

• PGActivity

  from pgactivity.models import PGActivity

  Used to query the Postgres pg_stat_activity view as a Django model.
• pgactivity.context

  import pgactivity
  # then use @pgactivity.context(...) or with pgactivity.context(...)

  Decorator/context manager for annotating SQL queries with application metadata.
• pgactivity.timeout

  import pgactivity
  # then use @pgactivity.timeout(...)

  Decorator for dynamically setting the SQL statement timeout for a block of code.
• ActivityMiddleware

  from pgactivity.middleware import ActivityMiddleware

  Middleware to automatically attach request URL and method as context to queries.

Quickstart

To get started, add 'pgactivity' to your Django project's `INSTALLED_APPS`. You can then use the `pgactivity` management command to view and filter active PostgreSQL queries, or integrate its features programmatically. The example demonstrates using the `@pgactivity.timeout` decorator to enforce a statement timeout on a view function. Make sure your Django project is correctly configured to use PostgreSQL as its database backend.

# settings.py
INSTALLED_APPS = [
    # ...
    'pgactivity',
    # ...
]

# myapp/views.py (example using timeout decorator)
import pgactivity
from django.db import connection, utils
from django.http import HttpResponse

@pgactivity.timeout(0.5) # Set a 500ms timeout for queries in this view
def my_slow_view(request):
    try:
        with connection.cursor() as cursor:
            cursor.execute("SELECT pg_sleep(1)") # This will likely time out
        return HttpResponse("Operation completed within timeout.")
    except utils.OperationalError as e:
        return HttpResponse(f"Operation timed out or failed: {e}", status=500)

# To view active queries from the command line:
# python manage.py pgactivity