django-pghistory

By default, django-pghistory uses row-level triggers. While this is highly efficient because it happens within the database instance without extra round-trips, a bulk update (e.g., Model.objects.update(...)) over many elements will result in many internal database operations.

To reduce the impact of bulk operations, use level=pghistory.Statement in the pghistory.track decorator to leverage statement-level triggers.

@pghistory.track(level=pghistory.Statement)
class MyModel(models.Model):
    ...

django-pghistory uses PostgreSQL set_config to propagate request/context to the database. If you use a connection pooler like PgBouncer (in transaction or statement mode) or RDS Proxy, this can cause session pinning.

Session pinning keeps a client bound to a single backend connection because the pooler assumes the set_config state might affect query results. While this does not pin read statements, it can significantly increase the number of backend connections required in write-heavy systems. Monitor your pooler's pinning metrics and backend connection counts after enabling pghistory.

When you use @pghistory.track() on a Django model, django-pghistory automatically generates a corresponding event model.

For example, tracking a model named TrackedModel will generate an event model named TrackedModelEvent. This event model contains:

• All fields from the original tracked model.
• Additional fields prefixed with pgh_ used to reference the tracked object, distinguish event types, and provide context.

Note: Event models are created dynamically and added to your models module. While you won't see them explicitly declared in your models.py file, they will appear in your Django migrations.

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

The pghistory.models.Events proxy model uses a Common Table Expression (CTE) to provide an aggregate view across all event tables.

Performance Notes:

• Postgres Version: Postgres 12+ optimizes filters on CTEs. On earlier versions, filtering Events directly may be slow.
• Scale: Aggregating many large event tables via the proxy model is inherently slow.
• Best Practice: For efficient filtering of large datasets, use the special model manager methods described in the Aggregating Events and Diffs guide instead of direct filtering on the Events model.

A tracker is a high-level abstraction used to monitor model events. It sits on top of database triggers.

• Trackers: These define what to watch for (e.g., inserts, updates, or deletes). For example, the standard @pghistory.track() decorator uses both an InsertEvent tracker and an UpdateEvent tracker.
• Events: An event is the actual historical record stored by a tracker. When a tracker detects a change, it saves a version of the model into an event model.

Users can customize tracking by:

1. Specifying trackers directly in @pghistory.track().
2. Overriding settings.PGHISTORY_DEFAULT_TRACKERS to change global behavior.
3. Adding conditions using pghistory.AnyChange or pghistory.Q to only track specific changes.

django-pghistory uses Postgres triggers to reliably capture historical changes. Because Django does not natively support triggers, the library uses django-pgtrigger to manage them.

Key characteristics of triggers in this system:

• Installation: Like database indices, triggers are installed via migrations and attached to specific database tables.
• Execution: They are functions that run directly within the database after INSERT, UPDATE, or DELETE operations.
• Data Access: Triggers have access to both the old and new versions of the rows being modified.
• Conditional Logic: Triggers can be configured to execute only when specific properties of the modified rows are met.

To track changes in many-to-many relationships (like adding or removing a user from a group), you must track the "through" model of that relationship.

When tracking through models, you often need to set obj_field=None because Django does not allow foreign keys to auto-generated through models. This tells pghistory to ignore creating a reference to the object in the event model, allowing you to capture the relationship changes via specific labels.

Example of tracking group additions and removals:

from django.contrib.auth.models import User
import pghistory

@pghistory.track(
    pghistory.AfterInsert("group.add"),
    pghistory.BeforeDelete("group.remove"),
    obj_field=None,
)
class UserGroups(User.groups.through):
    class Meta:
        proxy = True

To upgrade to version 2, most users can simply run python manage.py makemigrations to generate the necessary trigger migrations.

Important Requirements:

• Ensure django-pgtrigger>=4.5 is installed to avoid migration-related bugs.

Special Case: Third-party models If you are tracking third-party models (like Django's built-in User model), you must register trackers on proxy models. If you do not use proxy models for third-party tracking, trigger migrations may be created outside of your project's migration directory.

To create history records for existing data, you can use manual event tracking.

For large datasets, use bulk creation. You can access the correct event model via the pgh_event_model attribute on your tracked model class. If you have multiple trackers on a single model, use the dictionary syntax: model.pgh_event_models["label"].

# Example of accessing the event model for bulk creation
from myapp.models import MyModel

EventModel = MyModel.pgh_event_model
EventModel.objects.bulk_create([
    # ... event instances
])