django-pghistory

What it is and what it does

django-pghistory is a Django package that automatically records every change to your models by installing PostgreSQL triggers on the underlying tables. Instead of instrumenting your application code, it captures inserts, updates, and bulk operations—even raw SQL changes—at the database level and stores them in dynamically-created event models that mirror your original model's fields. You decorate a model with `@pghistory.track()`, run migrations, and the system handles the rest: every modification is logged with metadata fields like `pgh_obj` (the tracked object ID) and timestamps.

The package includes admin integration and middleware for attaching application context (such as the logged-in user) to events without extra database queries. It supports selective field tracking, conditional event storage based on field transitions, and aggregation across multiple event models. Since it relies on PostgreSQL triggers rather than application-level hooks, it captures changes regardless of how they reach the database—ORM saves, bulk updates, or direct SQL all get tracked.

Use it for

• Audit compliance: maintain a tamper-resistant record of all model changes for regulatory requirements.
• Soft deletes and recovery: revert models to previous versions or implement logical deletion with full history.
• User activity tracking: attach context like user ID to each change for accountability and debugging.
• Data debugging: trace the sequence of field changes to diagnose unexpected model states.
• Bulk operation auditing: capture changes from bulk operations or raw SQL that ORM hooks would miss.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

django-pghistory on PyPI

Before you install

Low friction install with a pure-Python wheel. Actively maintained as of 2026-02-17 with 540 repository stars. Requires only django and django-pgtrigger as runtime dependencies.

Requires PostgreSQL and Django; add pghistory and pgtrigger to INSTALLED_APPS after installation.

License in practice

BSD-3-Clause permissive license allows commercial and private use with minimal restrictions.

Quickstart

pip install django-pghistory

import pghistory
from django.db import models

@pghistory.track()
class TrackedModel(models.Model):
    int_field = models.IntegerField()
    text_field = models.TextField()

m = TrackedModel.objects.create(int_field=1, text_field="hello")
m.int_field = 2
m.save()
print(m.events.values("pgh_obj", "int_field"))

Package facts

Evidence: django_pghistory-3.9.2-py3-none-any.whl

Tags

More Database packages

See also django-easy-audit · django-pgtrigger · django-auditlog · django-reversion · django-dirtyfields · SQLAlchemy-Continuum · django-postgres-copy · django-crum · django-fsm-log · django-pgactivity